Content
# Tool List
[](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)
## <a href="#project-overview">Project Overview</a>
This project implements a complete end-to-end system based on the **MCP (Model Context Protocol)** protocol, including client and server implementations. It encapsulates **Bohrium OpenAPI** into a standardized toolset, enabling large language models to naturally call these API capabilities. The MCP protocol is a context enhancement protocol specifically designed for large models, significantly improving the external tool usage capabilities of large models through standardized tool discovery and calling mechanisms.
✨ **Core Features** ✨
- Convert HTTP APIs into tools directly callable by large models
- Support SSE and stdio transport layer implementations
- Provide standardized tool discovery and calling mechanisms
- Implement ReAct inference framework for iterative thinking
## <a href="#core-components">Core Components</a>
This project consists of three core components that form a complete MCP ecosystem:
- **MCP Server** (`src/openapi_mcp_server/`):
- Server-side implementation of the protocol, encapsulating Bohrium OpenAPI into standardized tools
- Provides a rich set of academic tools, including:
- Paper search (regular, enhanced, and Pro versions)
- Scholar information query
- Knowledge base management
- Requires Bohrium OpenAPI key for authentication
- Supports SSE transport
- **MCP Host** (`src/mcp_host/`):
- Integrates the bridge layer between MCP Client and LLM
- Internally contains:
- MCP Client: establishes a 1:1 connection with the Server, handling session requests and responses
- LLM integration: supports Azure OpenAI or Mock implementation
- Supports two operating modes:
1. Mock mode: uses built-in simulated responses, suitable for development and testing
2. Azure OpenAI mode: connects to real GPT models, used in production environments
- Implements ReAct inference framework, capable of iteratively calling tools to solve complex problems
- **Command Line Tool** (`src/cli/`):
- Serves as the user interaction entry point
- Instantiates and manages MCP Host
- Provides a command-line interface, supporting:
- Single query mode
- Interactive session mode
- Responsible for formatting and displaying results
The workflow of these three components:
1. MCP Server starts and exposes standardized tool interfaces
2. MCP Host's Client establishes a connection with the Server, obtaining available tool lists
3. Command line tool receives user input, passes it to Host for processing
4. Host uses LLM to analyze requests, calls tools provided by Server through internal Client
5. Results are returned to the user through the command line interface
## <a href="#system-requirements">System Requirements</a>
- **Python**: 3.11 or higher
- **Bohrium OpenAPI Key** (required):
1. Visit [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 in development or production, you need to configure the Bohrium API key to start the MCP Server. A mock version of the server will be developed later.
- **Azure OpenAI API Key** (optional):
- Development and testing environment:
- Can use Mock mode without Azure OpenAI API key
- Production environment:
1. Visit [Azure Portal](https://portal.azure.com)
2. Create an Azure OpenAI service instance
3. Obtain API key and endpoint in "Keys and Endpoints"
- **Python Dependencies**: all dependencies are managed in `pyproject.toml`, follow the installation steps
## <a href="#installation-steps">Installation Steps</a>
> 💡 Quick Start Tips:
> - Must configure Bohrium API key to use MCP Server
> - Can use Mock mode (without Azure OpenAI key) for quick start
> - Production environment recommended to use Azure OpenAI mode for better results
1. **Clone Repository**:
```bash
git clone https://github.com/hztBUAA/mcp-tutorial.git
cd mcp-tutorial
```
2. **Create Virtual Environment**:
```bash
# Recommended to use conda (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 Project**:
```bash
# Install as ordinary user
pip install .
# Install as developer (editable mode)
pip install -e .
# If you need a development environment (including jupyter support, etc.)
pip install -e ".[dev]"
# If you need test tools
pip install -e ".[test]"
```
> 💡 Note:
> - Ordinary users can use `pip install .` to install a stable version based on the pyproject.toml file in the project root directory
> - Developers use `-e` parameter to install, so that 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 API keys but uses a simulated OpenAI class developed in this project, suitable for quick experience and development testing.
B. Production environment:
```bash
# Azure OpenAI configuration
MOCK=False # or delete this line
AZURE_OPENAI_API_KEY=your_api_key
AZURE_OPENAI_ENDPOINT=your_endpoint
```
> 💡 Tips:
> - Recommended to use Mock mode for development and testing without API keys
> - Mock mode provides simulated responses to help you quickly understand the system workflow
> - Production environment recommended to use actual Azure OpenAI configuration
5. **Verify Installation**:
```bash
# Test import is normal
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__)"
```
## <a href="#frequently-asked-questions">Frequently Asked Questions</a>
1. If you encounter "ModuleNotFoundError":
- Check if you are using the correct conda environment, as a new terminal will reset to the base conda environment, requiring reactivation of `conda activate mcp_env`.
- This indicates that the package or its dependencies were not installed correctly
- Ensure that `pip install .` was executed (ordinary users) or `pip install -e .` (developers)
- Check if the Python version is >= 3.11
2. If you encounter dependency conflicts:
```bash
# Clean up environment
pip uninstall -y -r <(pip freeze)
# Reinstall
pip install . # Ordinary users
# Or
pip install -e . # Developers
```
## <a href="#usage-methods">Usage Methods</a>
### Start MCP Server
```bash
# Start server with default configuration
python start_server.py
```
### Use MCP Client
#### Single Query Mode
```bash
# Use SSE transport (default)
python mcp_demo.py "Find the latest papers about quantum computing"
# Use stdio transport (not tested, as server currently only supports SSE)
# MCP_TRANSPORT=stdio python mcp_demo.py "Find the latest papers about quantum computing"
```
#### Interactive Mode
```bash
# Start interactive session
python mcp_demo.py --interactive
```
## <a href="#example-operation">Example Operation</a>
The following is an actual operation 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 the need to use the enhanced paper search tool, and constructs appropriate query parameters.
**Tool Calls and Results**:
The system calls the `search_papers_enhanced` tool to obtain a list of related 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, author, DOI link, etc., covering multiple aspects of machine learning.
This example demonstrates how the MCP system:
1. Understands user intent and plans query strategies
2. Calls appropriate tools and processes returned results
3. Analyzes and synthesizes information to generate well-structured answers
4. Maintains a transparent reasoning chain throughout
## <a href="#code-structure">Code Structure</a>
```
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
```
## <a href="#mcp-protocol-core-concepts">MCP Protocol Core Concepts</a>
### 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 related papers")
- Input schema (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 have:
- URI (e.g., `tables://analytics`)
- Content type
- Content
### Prompts
Prompts are reusable templates that can be used with specific inputs to generate large model inputs.
## <a href="#transport-layer-implementation">Transport Layer Implementation</a>
The MCP protocol supports two main transport layer implementations:
### SSE (Server-Sent Events)
Suitable for network environments, implementing one-way communication from server to client through 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:
# Use session for communication
```
### stdio (Standard Input/Output)
Suitable for local environments, communicating 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:
# Use session for communication
```
## <a href="#bohrium-openapi-capabilities">Bohrium OpenAPI Capabilities</a>
This project encapsulates various capabilities of Bohrium OpenAPI, including:
### Scholar-related APIs
- Scholar personal information query
- Scholar co-author relationship
- Scholar paper list
- Follow and subscribe lists
### Paper Search Engine
- Regular search
- Enhanced search
- Pro version
### Parsing and Recognition
- PDF file parsing
- Image recognition
- Formatted output
### Task Management
- Task creation and submission
- Task status query
- Task group management
...and so on~
## <a href="#rest-api-vs-mcp-why-mcp">REST API vs MCP: Why MCP?</a>
### Limitations of REST API
REST API performs well in traditional web applications but has some limitations in large model application scenarios:
1. **Lack of self-description**: REST API usually requires additional documentation to describe its functions and parameters
2. **Lack of standardized discovery mechanism**: clients have difficulty automatically discovering available API endpoints
3. **Not suitable for complex interactions**: cannot naturally support multi-round dialogue and context maintenance
### Advantages of MCP
MCP protocol is specifically designed for large models, with the following advantages:
1. **Standardized tool discovery**: large models can automatically discover available tools and resources
2. **Self-descriptive input schema**: tool definitions include complete parameter descriptions and type information
3. **Unified content representation**: standardized response format facilitates large model processing
4. **Suitable for large model interaction**: design concept naturally aligns with large model's tool calling mechanism
## <a href="#future-improvement-directions">Future Improvement Directions</a>
1. **More API and TOOL module support**: expand support for more Bohrium OpenAPI modules and tools, including RAG, Websearch, CodeExecute, etc.
2. **Multi-model support**: expand support for more large models (e.g., Claude, GLM, etc.)
3. **Security enhancement**: implement more complete authentication and authorization mechanisms
4. **Monitoring and logging**: add detailed monitoring and logging functions
## <a href="#reference-resources">Reference Resources</a>
- [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)
## <a href="#how-to-contribute">How to Contribute</a>
Welcome any form of contribution! Please:
1. Report issues or suggestions via [Issues](https://github.com/hztBUAA/mcp-tutorial/issues)
2. Submit improvements via [Pull Requests](https://github.com/hztBUAA/mcp-tutorial/pulls)
## <a href="#license">License</a>
This project is open-sourced under the [MIT License](https://opensource.org/licenses/MIT).
