mcp-tutorial

# MCP End-to-End Tutorial | Understanding It from a Developer's Perspective [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/hztBUAA/mcp-tutorial/actions) [](https://github.com/hztBUAA/mcp-tutorial/blob/master/MCP_GUIDE.md) [](https://github.com/hztBUAA/mcp-tutorial/issues) ## 📖 Project Overview This project implements a complete system based on the **MCP (Model Context Protocol)** protocol, including end-to-end implementations for both client and server. It encapsulates the **Bohrium OpenAPI** into a standardized toolkit, enabling large language models to naturally invoke these API capabilities. The MCP protocol is a context-enhanced protocol specifically designed for large models, significantly improving their ability to utilize external tools through standardized discovery and invocation mechanisms. ✨ **Core Features** ✨ - Converts HTTP APIs into tools that can be directly invoked by large models - Supports two transport layer implementations: SSE and stdio - Provides a standardized tool discovery and invocation mechanism - Implements the ReAct reasoning framework for iterative thinking --- ## 🚀 Core Components This project consists of three core components that together form a complete MCP ecosystem: - **MCP Server** (`src/openapi_mcp_server/`): - Server-side implementation of the protocol, encapsulating Bohrium OpenAPI into standardized tools - Offers a rich set of academic tools, including: - Paper search (Standard, Enhanced, Pro versions) - Scholar information queries - Knowledge base management - Requires a Bohrium OpenAPI key for authentication - Supports SSE transport method - **MCP Host** (`src/mcp_host/`): - Acts as a bridge layer integrating MCP Client with LLM - Internally includes: - MCP Client: Establishes a 1:1 connection with the Server, handling session requests and responses - LLM integration: Supports Azure OpenAI or Mock implementations - Supports two running modes: 1. Mock mode: Uses built-in mock responses, suitable for development testing 2. Azure OpenAI mode: Connects to a real GPT model for production environments - Implements the ReAct reasoning framework, capable of iteratively invoking tools to solve complex problems - **Command Line Tool** (`src/cli/`): - Serves as the entry point for user interaction - Instantiates and manages the MCP Host - Provides a command-line interface, supporting: - Single query mode - Interactive session mode - Responsible for formatting and displaying results Workflow of these three components: 1. MCP Server starts and exposes standardized tool interfaces 2. Client in MCP Host connects with the Server to retrieve the list of available tools 3. Command line tool receives user input and passes it to the Host for processing 4. Host uses LLM to analyze the request and invokes tools provided by the Server through its internal Client 5. Results are returned to the user via the command line interface --- ## ⚙️ System Requirements - **Python**: Version 3.11 or higher - **Bohrium OpenAPI Key** (required): 1. Visit the [Bohrium official website](https://bohrium.com) 2. Register and log in to your account 3. Go to "Personal Settings" > "API Keys" 4. Create a new access key > ⚠️ Note: Whether for development testing or production environments, configuring the Bohrium API key is necessary to start the MCP Server. A mock version of the server will be developed later. - **Azure OpenAI API Key** (optional): - Development testing environment: - You can use Mock mode without needing an Azure OpenAI API key - Production environment: 1. Visit the [Azure Portal](https://portal.azure.com) 2. Create an Azure OpenAI service instance 3. Obtain the API key and endpoint from "Keys and Endpoints" - **Python Dependencies**: All dependencies are managed in `pyproject.toml`, follow the installation steps to set them up --- ## 🛠️ Installation Steps > 💡 Quick Start Tips: > - You must configure the Bohrium API key to use the MCP Server > - You can quickly start using Mock mode (no Azure OpenAI key required) > - For production environments, it is recommended to use Azure OpenAI mode for better results 1. **Clone the Repository**: ```bash git clone https://github.com/hztBUAA/mcp-tutorial.git cd mcp-tutorial ``` 2. **Create a Virtual Environment**: ```bash # Recommended to use conda (requires Python >= 3.11) conda create -n mcp_env python=3.11 -y conda activate mcp_env # Or use venv python -m venv venv source venv/bin/activate # Linux/macOS .\venv\Scripts\activate # Windows ``` 3. **Install the Project**: ```bash # For regular users pip install . # For developers (editable source mode) pip install -e . # If a development environment is needed (including jupyter support, etc.) pip install -e ".[dev]" # If testing tools are needed pip install -e ".[test]" ``` > 💡 Note: > - Regular users can simply use `pip install .`, which will install a stable version based on the pyproject.toml file in the project root > - Developers should use the `-e` option for installation, so modifications to the source code do not require reinstallation > - All dependencies are managed in `pyproject.toml`, no need to manually install other dependencies 4. **Environment Configuration**: ```bash # Create .env file cp .env.example .env ``` Choose one of the following configuration methods: A. Use Mock mode (quick start): ```bash # Set in .env MOCK=True ``` This mode does not require an API key and uses a mock OpenAI class developed in this project, suitable for quick experience and development testing. B. Production Environment: ```bash # Azure OpenAI Configuration MOCK=False # or remove this line AZURE_OPENAI_API_KEY=your_api_key AZURE_OPENAI_ENDPOINT=your_endpoint ``` > 💡 Tips: > - It is recommended to use Mock mode during development and testing, no API key configuration is needed > - Mock mode provides mock responses, helping you quickly understand how the system works > - For production environments, please use actual Azure OpenAI configurations 5. **Verify Installation**: ```bash # Test if imports are working correctly python -c "from openapi_mcp_server import __version__; print(__version__)" python -c "from cli import __version__; print(__version__)" python -c "from mcp_host import __version__; print(__version__)" ``` ## Frequently Asked Questions 1. If you encounter a "ModuleNotFoundError": - Check if you are using the correct conda environment, as new terminals reset to the base conda environment; you need to re-run `conda activate mcp_env`. - This indicates that the package or its dependencies were not installed correctly - Ensure you executed the `pip install .` command (for regular users) or `pip install -e .` (for developers) - Check if the Python version is >= 3.11 2. If you encounter dependency conflicts: ```bash # Clean the environment pip uninstall -y -r <(pip freeze) # Reinstall pip install . # Regular users # Or pip install -e . # Developers ``` --- ## 🚀 Usage Instructions ### Start the MCP Server ```bash # Start the server with default configuration python start_server.py ``` ### Use the MCP Client #### Single Query Mode ```bash # Use SSE transport (default) python mcp_demo.py "Find the latest papers on quantum computing" # Use stdio transport (not tested, as the server currently only supports SSE) # MCP_TRANSPORT=stdio python mcp_demo.py "Find the latest papers on quantum computing" ``` #### Interactive Mode ```bash # Start an interactive session python mcp_demo.py --interactive ``` --- ## 📊 Example Run Here is a practical example of using the MCP system for paper search, demonstrating how the system uses ReAct-style reasoning: ### Query Example: Find papers related to machine learning **User Query**: `Find papers about machine learning` **System Thinking Process**:  The system first analyzes the query, determines that it needs to use the enhanced paper search tool, and constructs appropriate query parameters. **Tool Invocation and Results**:  The system invokes the `search_papers_enhanced` tool to retrieve a list of relevant papers and analyzes the results to extract key information such as topic distribution, metadata features, and availability. **Final Answer**:   The system generates a structured final answer, including a curated list of papers, each containing key information such as title, authors, DOI links, etc., covering various aspects of machine learning. This example demonstrates how the MCP system: 1. Understands user intent and plans query strategies 2. Invokes appropriate tools and processes returned results 3. Analyzes and synthesizes information to generate coherent answers 4. Maintains a transparent reasoning chain throughout the process --- ## 🏗️ Code Structure ``` mcp-tutorial/ ├── src/ │ ├── mcp_client/ # MCP client implementation │ │ └── cli_client.py # Command line client │ ├── mcp_host/ # MCP host implementation │ │ ├── azure_openai_host.py # Azure OpenAI integration │ │ └── prompts.py # System prompt templates │ └── openapi_mcp_server/ # MCP server implementation │ ├── server.py # Core server logic │ ├── scholar/ # Scholar API module │ ├── paper/ # Paper API module │ └── knowledge/ # Knowledge base API module ├── mcp_demo.py # Demo script ├── MCP_GUIDE.md # MCP Development Guide ├── GUIDE.md # API Module Development Guide ├── requirements.txt # Project dependencies └── README.md # Project description ``` --- ## 💡 Core Concepts of MCP Protocol ### Tools Tools are executable functions provided by the server, allowing large models to perform operations. Each tool has: - Name (e.g., `search-papers`) - Description (e.g., "Search for related papers") - Input schema (in JSON Schema format) - Output type (text, image, etc.) ### Resources Resources are data or content provided by the server that can be accessed by large models. Resources include: - URI (e.g., `tables://analytics`) - Content type - Content ### Prompts Prompts are reusable templates that can be used with specific inputs to generate input for large models. --- ## 🔄 Transport Layer Implementations The MCP protocol supports two main transport layer implementations: ### SSE (Server-Sent Events) Suitable for network environments, it enables one-way communication from the server to the client via HTTP long connections. ```python # Server-side @app.route("/sse") async def handle_sse(request): async with sse.connect_sse(request.scope, request.receive, request._send) as streams: await server.run(streams[0], streams[1]) # Client-side async with sse_client(server_url) as streams: async with ClientSession(*streams) as session: # Communicate using session ``` ### stdio (Standard Input/Output) Suitable for local environments, it communicates through standard input/output streams. ```python # Server-side async def main(): await stdio_server(server) # Client-side async with stdio_client(server_command) as streams: async with ClientSession(*streams) as session: # Communicate using session ``` --- ## 📊 Bohrium OpenAPI Capabilities This project encapsulates various capabilities of the Bohrium OpenAPI, including: ### Scholar-related APIs - Scholar personal information queries - Scholar co-author relationships - Scholar paper lists - Follow and subscription lists ### Paper Search Engine - Standard search - Enhanced search - Corpus Pro version ### Parsing and Recognition - PDF file parsing - Image recognition - Formatted output ### Task Management - Task creation and submission - Task status queries - Task group management ...and so on~ --- ## 🔍 REST API vs MCP: Why MCP? ### Limitations of REST API REST APIs perform well in traditional web applications but have some limitations in large model application scenarios: 1. **Lack of Self-describing Capability**: REST APIs often require additional documentation to describe their functions and parameters 2. **Lack of Standardized Discovery Mechanism**: Clients find it difficult to automatically discover available API endpoints 3. **Not Suitable for Complex Interactions**: Cannot naturally support multi-turn dialogues and context retention ### Advantages of MCP The MCP protocol is designed specifically for large models, offering the following advantages: 1. **Standardized Tool Discovery**: Large models can automatically discover available tools and resources 2. **Self-describing Input Schemas**: Tool definitions include complete parameter descriptions and type information 3. **Unified Content Representation**: Standardized response formats facilitate processing by large models 4. **Suitable for Large Model Interactions**: The design philosophy aligns naturally with the tool invocation mechanisms of large models --- ## 🔮 Future Improvement Directions 1. **Support for More API and TOOL Modules**: Expand support for more Bohrium OpenAPI modules and tools, including RAG, Websearch, and CodeExecute, etc. 2. **Multi-model Support**: Extend support for more large models (e.g., Claude, GLM, etc.) 3. **Security Enhancements**: Implement more robust authentication and authorization mechanisms 4. **Monitoring and Logging**: Add detailed monitoring and logging features --- ## 📚 Reference Resources - [MCP Official Documentation](https://modelcontextprotocol.io/) - [OpenAI Function Calling Documentation](https://platform.openai.com/docs/guides/function-calling) - [MCP Protocol Discussion](https://github.com/orgs/modelcontextprotocol/discussions/209) - [OpenAI Tools & Remote MCP Guide](https://platform.openai.com/docs/guides/tools-remote-mcp) - [MCP vs REST Discussion](https://zhuanlan.zhihu.com/p/29001189476) --- ## 🤝 How to Contribute Contributions of any form are welcome! Please: 1. Report issues or suggestions via [Issues](https://github.com/hztBUAA/mcp-tutorial/issues) 2. Submit improvements through [Pull Requests](https://github.com/hztBUAA/mcp-tutorial/pulls) --- ## 📄 License This project is open-sourced under the [MIT License](https://opensource.org/licenses/MIT).