mcp-example

# MCP Intelligent Chat Assistant Sample Project <p align="center"> <strong>Intelligent Dialogue System Example Based on Model Context Protocol</strong> </p> ## Project Introduction This project is an example of an intelligent chat assistant based on the MCP (Model Context Protocol) framework, demonstrating how to integrate large language models (LLM) with external data sources and tools to create a cross-modal, multi-capability intelligent dialogue system. ## Introduction to the MCP Framework MCP (Model Context Protocol) is an open protocol open-sourced by Anthropic, providing a standardized way for seamless integration between LLM applications and external data sources and tools. MCP can be understood as the "USB-C interface" for AI applications, just as USB-C provides a standard way for devices to connect with various peripherals and accessories, MCP provides a standard way for AI models to connect with different data sources and tools. ### Core Value of MCP: Connecting Users, Large Models, and Professional Services MCP is essentially a standardized connection protocol that elegantly connects three core components: 1. **Users** - Individuals or other input sources expressing needs through natural language 2. **Large Models** - AI systems that handle understanding and generation 3. **Professional Services** - Tools and data sources that provide capabilities in specific domains As a connector, MCP delivers the following key values: - **Lowering User Barriers**: Allows users to express complex needs in natural language without needing to understand underlying technical details - **Expanding Model Capabilities**: Enables large models to access real-time external data and professional functions, overcoming the limitations of model knowledge and the "hallucination" problem - **Activating Professional Services**: Allows existing professional services to be intelligently invoked by large models without the need for a complete overhaul of existing systems - **Standardizing Interactions**: Reduces integration complexity through a unified protocol, lowering development and maintenance costs The design of this standard protocol makes the entire AI application ecosystem more modular and scalable, allowing components to focus on their strengths while collaborating through standard interfaces to provide users with an integrated intelligent experience. ### Why Choose MCP? MCP helps you build intelligent agents and complex workflows on top of LLMs. Large language models often need to integrate with data and tools, and MCP provides: - A pre-built integration list that connects directly to your LLM - Flexibility to switch between different LLM providers and vendors - Best practices for protecting data within your infrastructure ### MCP Architecture At its core, MCP follows a client-server architecture, where the host application can connect to multiple servers: - **MCP Host**: Programs like Claude Desktop, IDEs, or AI tools that wish to access data via MCP - **MCP Client**: A protocol client that maintains a 1:1 connection with the server - **MCP Server**: Lightweight programs that expose specific functionalities through the standardized Model Context Protocol - **Local Data Sources**: Computer files, databases, and services that the MCP server can securely access - **Remote Services**: External systems (e.g., APIs) available over the internet that the MCP server can connect to ### MCP Workflow The actual workflow of MCP follows these steps: 1. **Service Preparation**: First, you need one or more MCP servers that comply with the MCP standard, each exposing a functional interface (tool) and data resources for a specific domain. These servers can be local or remote. 2. **User Application**: Users send requests through applications integrated with the MCP client (e.g., chat interfaces, IDE plugins), with the MCP client responsible for communicating with the MCP server. 3. **Request Processing**: - Users send natural language requests (e.g., "What's the weather in Beijing tomorrow?") - The application collects information about all registered MCP servers and their tool information - The application calls the large language model to analyze user intent and maps it to the appropriate MCP services and tools - The model returns structured call information (service name, tool name, parameters, etc.) 4. **Service Invocation**: - The application calls the relevant tools of the specified MCP server based on the model's decision - The MCP server processes the request and returns structured data 5. **Result Processing**: - The application receives professional data from the server - The model is called again to convert the professional data into user-friendly natural language responses - The final response is presented to the user The diagram below illustrates the workflow of MCP: ``` ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ │ │ │ │ │ │ User │───────▶│ Application │◀──────▶│ Large Model │ │ │ │ (MCP Client) │ │ │ └───────────────┘ └───────▲───────┘ └───────────────┘ │ │ ┌───────▼───────┐ │ MCP Service │ │ Registration │ │ and Discovery│ └───────┬───────┘ │ ┌───────────────┼───────────────┐ │ │ │ ┌───────▼───────┐┌──────▼────────┐┌─────▼─────────┐ │ ││ ││ │ │ MCP Server A ││ MCP Server B ││ MCP Server C │ │ (Weather Service)││ (Knowledge Base) ││ (Data Analysis)│ │ ││ ││ │ └───────────────┘└───────────────┘└────────────────┘ ``` This workflow demonstrates the core value of MCP: allowing large language models to seamlessly utilize various professional services through a standardized protocol while maintaining a consistent user experience. Users only need to express their needs in natural language without needing to understand the underlying technical details or service architecture. ### MCP Multi-Server Coordination Mechanism The MCP framework elegantly coordinates multiple servers to achieve complex functional integration. The specific coordination mechanisms include: 1. **Service Discovery and Registration**: - The MCP host scans and discovers local or networked MCP servers upon startup - Each server registers its capabilities (tools, resource types, etc.) with the host upon startup - The host maintains a mapping table of server capabilities for routing requests 2. **Capability Descriptions and Tool Lists**: - Each MCP server publishes its supported tool list, parameter specifications, and resource types - The host can retrieve each server's capabilities through APIs like `list_tools` and `list_resources` - The model decides which server's tool to call based on these capabilities 3. **Context Management**: - MCP maintains request context to ensure information consistency between multi-server calls - Context can include session information, user preferences, authentication tokens, etc. - Servers can read the context to provide personalized responses 4. **Request Routing**: - When an application or model needs a specific service, the MCP client is responsible for: - Identifying which server can handle the request - Formatting the request as a standard MCP protocol message - Establishing a connection with the target server - Transmitting the request and waiting for a response 5. **Parallel Processing**: - MCP supports sending requests to multiple servers simultaneously - Information can be retrieved from different data sources in parallel - Results from multiple servers can be aggregated into a single response 6. **Error Handling and Fallback**: - When a specific server is unavailable, MCP can automatically attempt to use a backup server - An error reporting mechanism helps the application diagnose issues - Fallback strategies can be defined for service interruptions 7. **Version Compatibility**: - The MCP protocol is designed to support coexistence of different server versions - Clients can handle version differences to ensure backward compatibility - New servers can provide enhanced functionalities without requiring updates to the entire environment In practice, for example, when a user asks, "Analyze last month's sales data and compare it with the weather," MCP will: 1. Identify the need for sales data analysis and weather query services 2. Call the data analysis MCP server to obtain sales statistics 3. Call the weather MCP server to retrieve historical weather data 4. Combine the two data sets and return them to the model 5. The model generates a comprehensive analysis based on the complete context This coordination mechanism allows MCP to seamlessly integrate the capabilities of multiple professional servers, providing an integrated experience while each server focuses on its area of expertise, greatly enhancing the modularity and scalability of the system. The core idea of the MCP framework is to provide structured contextual information for large language model applications, including: - **Resources**: Data provided to the model, such as file contents, API responses, etc. - **Tools**: Functions that the model can call to perform operations and retrieve information - **Prompts**: Reusable interaction templates to guide model responses ## Practical Applications of MCP Let's look at a few vivid examples of how MCP solves real-world problems: ### Example 1: Intelligent Code Assistant **Problem**: Traditional code assistants lack deep understanding of code repositories and cannot access local code structures and version control information. **MCP Solution**: - Developers install an MCP-supported IDE plugin - The IDE creates an MCP server that exposes the local file system, Git history, and code index - When a developer asks the AI, "What could be the cause of this bug?" via MCP, the AI can: - Read the content of the currently opened file - Query the error logs - Retrieve relevant code modules - Analyze Git commit history to find recent changes - Provide specific, context-based solutions **Effect**: Developers receive concrete suggestions based on the actual project situation rather than vague answers. ### Example 2: Private Knowledge Base Q&A **Problem**: Companies want employees to inquire about internal documents and data but are concerned about privacy breaches. **MCP Solution**: - The company deploys an MCP server on its infrastructure, connecting to the internal knowledge base - An employee asks in the chat interface, "What was our sales strategy for Q3 2023?" - The MCP server locally: - Retrieves relevant internal documents - Extracts the required information - Sends the content to the model for summarization - The employee receives an answer based on internal data **Effect**: Sensitive data remains within the company, but employees still enjoy an intelligent Q&A experience. ### Example 3: Personal Data Assistant **Problem**: Users want AI to help manage personal data but are concerned about privacy issues. **MCP Solution**: - Users install the MCP application on their devices - The application creates a local server that connects to personal photo libraries, calendars, and files - Users ask, "Help me find photos taken at the beach last summer and create an album" - The MCP server processes locally: - Searches for relevant images in the photo library - Only sends image thumbnails to the model for analysis - Creates an album on the local device based on the model's suggestions **Effect**: Users gain AI-assisted personal data management capabilities. ### Example 4: Multi-Source Research Assistant **Problem**: Researchers need to handle various data formats and switch tools, which is time-consuming. **MCP Solution**: - Researchers deploy multiple MCP servers, each connecting to: - Scientific literature databases - Data visualization tools - Statistical analysis software - Note-taking and citation management systems - Researchers can ask, "What is the correlation between this set of gene data and findings in recent papers?" - MCP coordinates multiple servers: - Retrieves and analyzes experimental data - Searches for the latest relevant papers - Runs statistical comparisons - Generates visual charts - Compiles everything into a comprehensive report **Effect**: Researchers complete complex workflows across data sources and tools through a unified interface. These examples illustrate how MCP addresses key challenges such as data integration, privacy protection, and tool interoperability, enabling AI applications to securely access and process various data sources while providing rich context for large language models to maximize their value. ## Project Architecture This project adopts a modular design, primarily consisting of the following components: 1. **Chat Service (Chat App)**: The core service component responsible for - User request handling - Large model API calls - User intent parsing - MCP service call coordination - Response formatting 2. **MCP Manager**: Responsible for - MCP service discovery and registration - Tool list management - Service call routing 3. **Weather MCP Service**: Provides weather information query functionality - Weather data retrieval - Temperature range queries - Precipitation forecasts - Weather chart generation 4. **Large Language Model Service (vLLM)**: Provides large model inference capabilities - Model hosting and optimized inference - User intent parsing and service selection - Structured data to natural language description conversion - OpenAI-compatible API interface Architecture diagram: ``` ┌─────────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ User/Client │◀─HTTP────▶│ mcp_chat_app/ │ │ │ │ chat_app.py │ └─────────────────────────┘ │ (Flask Application)│ └──────────┬───────────┘ │ │ ┌──────────────────────────────┼──────────────────────────────┐ │ │ │ ┌────────────▼─────────────┐ ┌────────────▼─────────────┐ ┌────────────▼─────────────┐ │ mcp_chat_app/ │ │ mcp_chat_app/ │ │ vllm_server/ │ │ mcp_manager.py │ │ mock_mcp_manager.py │ │ run.py │ │ (MCP Service Discovery │ │ (Test Mock MCP Manager)│ │ (Large Model Inference │ │ and Management) │ │ │ │ Service, can be │ └────────────┬─────────────┘ └──────────────────────────┘ │ replaced with remote API)│ │ └──────────┬───────────────┘ │ MCP Protocol │ │ │ ┌────────────▼─────────────┐ ┌───────────▼───────────────┐ │ weather_mcp_server/ │◀─────────────────────────────────┤ 1. Intent Parsing │ │ weather_server.py │ │ 2. Parameter Extraction and Validation │ │ (Weather Service MCP Implementation)│─────────────────────▶│ 3. Result Formatting and Refinement │ │ │ └───────────────────────────┘ └──────────────────────────┘ ▲ │ │ │ │ │ │ ┌────────────▼──┐ ┌───▼────────────┐ ┌───────────────────────────┐ │ │ utils.py │ │ chart_generator.py│ │ Bidirectional Interaction Flow │ │ │ (Data Processing) │ │ (Chart Generation) │ │ │ │ └───────────────┘ └────────────────┘ │ 1. User Query Intent Understanding │ │ │ 2. MCP Tool Selection │ │ │ 3. Parameter Parsing and Conversion │ │ │ 4. Result Data Natural Language Conversion │ │ │ 5. Multi-modal Content Processing │ │ └───────────────────────────┘ │ │ chat_app.py ──────────┘ ``` ### Key Interactions of the Large Model Service The large language model service (vLLM) plays the role of the "brain" in the entire system, with three key interaction points with other components: 1. **Interaction with Chat Service (chat_app.py)**: - Receives the user's raw query and analyzes user intent - Selects the most suitable MCP service and tool from the available tool list - Extracts and formats the call parameters - Converts the structured data returned by the MCP service into natural language responses - Handles error situations and provides friendly responses 2. **Indirect Interaction with MCP Services**: - The large model decides which MCP service to call through the chat service as an intermediary - Correctly constructs call parameters based on the tool documentation information of the MCP service - Understands the data structure returned by the MCP service for information extraction and integration 3. **Application of Model Capabilities**: - Semantic Understanding: Converts natural language into structured intent - Context Memory: Maintains coherence in multi-turn dialogues - Format Conversion: Transforms between natural language and structured data - Multi-modal Processing: Supports mixed content such as text, charts, and structured data The large model service uses vLLM for accelerated inference, providing an OpenAI-compatible API interface, allowing the system to easily replace underlying models while maintaining interface consistency. This service not only provides basic inference capabilities but also plays a decision-making and coordination role for the entire system, serving as a key bridge connecting user needs with professional services. It is worth noting that the vLLM server component in this architecture adopts a modular design, allowing for flexible replacement with: - **Local Deployment Mode**: Such as the current vllm_server deployment, suitable for development testing or scenarios with high data security requirements - **Cloud API Mode**: Can be directly replaced with commercial API services like OpenAI, Anthropic Claude, QianWen千问, etc. - **Self-hosted Remote Mode**: Can be deployed on dedicated GPU servers or cloud GPU instances, connected via API - **Hybrid Mode**: Different functionalities use model services from different sources, such as using lightweight models for intent understanding and more powerful models for content generation The system design ensures that regardless of which model service deployment method is used, the core functionality of the chat application and its interaction with MCP services remain consistent, requiring only configuration changes without altering the application code architecture. This flexibility allows developers to choose the most suitable deployment strategy based on actual needs, budget, and computing resources. System workflow: 1. The user sends an HTTP request to the chat service (chat_app.py) 2. The chat service uses the vLLM large model service to analyze user intent 3. Based on the analysis results, it calls the relevant tools of the weather MCP service through mcp_manager 4. The weather service processes the request, possibly using chart_generator to generate charts 5. The chat service receives professional data returned by the MCP service 6. Calls the large model service again to convert the data into natural language responses 7. Returns the final response to the user ### User Usage By calling the API, users can query weather information in natural language: - "What's the weather like in Beijing today?" - "What is the temperature trend in Shanghai for the next three days?" - "Will it rain in Guangzhou today?" - "Show me the precipitation chart for Hangzhou." The system will call the weather service to obtain relevant data and convert it into easy-to-understand responses through the large model. ## How to Develop Your Own MCP Service with Cursor (Using the Current Project, Weather Query Service as an Example) - Create a new folder - Copy the MCP's [readme](https://raw.githubusercontent.com/modelcontextprotocol/servers/refs/heads/main/README.md) and [python sdk readme](https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/refs/heads/main/README.md) to the root directory of the current project to inform Cursor about what MCP is and how to use it ### Generate MCP Server - Use the cursor agent to start the first project generation ``` Please create a project based on the MCP framework in the README, which is an MCP server that implements all the functionalities of an MCP server for weather queries. ``` This will generate the `weather_mcp_server` project. - Run MCP Create a venv for the entire project ```bash # Go back to the project root directory uv venv -p python3.12 .venv source .venv/bin/activate # Install MCP pip install mcp 'mcp[cli]' # Install dependencies pip install -r weather_mcp_server/requirements.txt # Run MCP server python weather_mcp_server/run.py --dev # Or use the MCP command mcp dev weather_mcp_server/weather_server.py # Output as follows Starting MCP inspector... Proxy server listening on port 3000 🔍 MCP Inspector is up and running at http://localhost:5173 🚀 ``` Now we can access the MCP server at http://localhost:5173 through the MCP proxy.  It can be used in both Claude and Cursor, for example, in Cursor:  Adding will help us create a file, and the file content needs to be filled in according to the MCP server we just created. ```json { "mcpServers": { "server-name": { "command": "python", "args": ["/yourpath/weather_mcp_server/weather_server.py"] } } } ```  After registering, the MCP server can be used through Cursor in the cursor agent.  ### Generate User Program Now the MCP server relies on Cursor, and the design of MCP itself is to serve as a connector between large models and applications. So can we write an application to connect large models and applications? The application is already available, and it needs: - A large model (whether locally launched, such as DeepSeek, Llama, or QianWen, performs poorly; using Alibaba Cloud's BaiLian `qwen-plus` is recommended) - You can use the vllm code in the project to launch it locally - Use an online large model - A user-facing program where users send requests, such as "How's the weather in Beijing?" This program analyzes user semantics through the large model and matches it with the services exposed by the MCP server, calling the corresponding service to get a return, which the large model processes before returning to the user. You can refer to [mcp_simple_chatbot](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/clients/simple-chatbot/mcp_simple_chatbot/main.py) - Needs to have MCP server registration functionality - Solve the above business process Send the above paragraph to the cursor agent, and it will generate the project `mcp_chat_app`, which is basically usable after debugging. ```bash curl -X POST "http://localhost:8081/chat/test_user" -H "Content-Type: application/json" -d '{"message": "Which cities have temperatures between 29 and 30 degrees tomorrow?", "use_tools": true}' {"response":"According to the weather forecast, the cities with temperatures between 29°C and 30°C tomorrow are:\n\n1. **Guangzhou**: Expected maximum temperature of 30°C, mainly hot weather.\n2. **Shenzhen**: Expected temperature of 29.5°C, mostly cloudy.\n\nIf you plan to go to either of these cities, remember to prepare according to the weather! 😊"}% ``` ```bash curl -X POST "http://localhost:8081/chat/test_user" -H "Content-Type: application/json" -d '{"message": "How's the weather in Xi'an today?", "use_tools": true}' {"response":"Hello! Regarding the weather in Xi'an today, the MCP service currently does not provide specific information directly, but it has given a weather overview for some cities over the next 7 days. From this data, we can see:\n\n- **The hottest cities** are Guangzhou and Shenzhen, reaching 30.0°C (hot) and 29.5°C (cloudy), respectively.\n- **Cities with rain** include Chengdu, forecasted for light rain.\n\nAlthough Xi'an's weather is not mentioned in the above list, it is usually dry and clear, so I recommend checking a local weather app or querying again later for more accurate information! If you need further assistance, please let me know! 😊"}% ``` ## Project Expansion This project can be expanded in the following ways: 1. **Add More MCP Services**: Develop new professional services, such as document processing, code generation, etc. 2. **Enhance Chat Experience**: Add context management and multi-turn dialogue support. 3. **Improve Large Model Capabilities**: Integrate more powerful models and optimize prompt engineering. 4. **Develop Web/Mobile Frontend**: Build user-friendly interfaces. 5. **Add Authentication**: Implement user management and access control. ## Current MCP Ecosystem As a relatively emerging technical standard, the MCP ecosystem is still in its early stages of development: - **Mature Applications**: - The Claude desktop application is currently the most comprehensive application integrating MCP, providing complete MCP service discovery, management, and invocation functionalities. - The Cursor IDE has implemented basic MCP support, allowing developers to leverage local context during coding. - **Ecosystem Status**: - Currently, applications and tools supporting MCP are relatively limited, mainly focused on development tools and professional domains. - The official SDK supports mainstream programming languages (Python, TypeScript, Java, Kotlin), but community-contributed MCP service libraries are still in their infancy. - Most MCP services require developers to build and deploy them themselves. - **Development Trends**: - As Anthropic continues to promote standard development and ecosystem construction, more applications are expected to add MCP support. - The vendor-neutral nature of MCP makes it a potential universal standard for connecting LLMs and professional services. - The developer community's demand for private deployment and data security is driving the application of MCP in enterprise environments. For developers, this is a favorable time to participate in the construction of the MCP ecosystem, either by building MCP services in professional domains to fill ecosystem gaps or by packaging existing tools and services through the MCP protocol for integration with large model applications. ## Related Resources - 📚 Read the [MCP Documentation](https://modelcontextprotocol.io) - 🔍 View the [MCP Specification](https://spec.modelcontextprotocol.io) - 💻 Build with SDKs: - [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [Java SDK](https://github.com/modelcontextprotocol/java-sdk) - [Kotlin SDK](https://github.com/modelcontextprotocol/kotlin-sdk) ## Contribution Guidelines Contributions to the project are welcome! You can participate in the following ways: 1. Submit issues and feature requests 2. Submit code improvements 3. Contribute new MCP services 4. Improve documentation ## License [Apache-2.0 License](LICENSE)