MCP开发指南

工具模板示例

import mcp.types as types
from . import BaseTool, ToolRegistry

@ToolRegistry.register
class YourTool(BaseTool):
    """您的工具描述"""
    name = "your_tool_name"  # 工具的唯一标识符
    description = "您的工具描述"  # 工具的描述信息，将显示给用户
    input_schema = {
        "type": "object",
        "required": ["param1"],  # 必需的参数
        "properties": {
            "param1": {
                "type": "string",
                "description": "参数1的描述",
            },
            "param2": {
                "type": "integer",
                "description": "参数2的描述（可选）",
            }
        },
    }
  
    async def execute(self, arguments: dict) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
        """执行工具逻辑"""
        # 参数验证
        if "param1" not in arguments:
            return [types.TextContent(
                type="text",
                text="Error: Missing required argument 'param1'"
            )]
          
        # 获取参数
        param1 = arguments["param1"]
        param2 = arguments.get("param2", 0)  # 获取可选参数，提供默认值
      
        # 执行工具逻辑
        result = f"处理参数: {param1}, {param2}"
      
        # 返回结果
        return [types.TextContent(
            type="text",
            text=result
        )]

部署指南

Docker部署（推荐）

1. 初始设置：

# 克隆仓库
git clone https://github.com/your-username/mcp-framework.git
cd mcp-framework

# 创建环境文件
cp .env.example .env

2. 使用Docker Compose：

# 构建并启动
docker compose up --build -d

# 查看日志
docker compose logs -f

# 管理容器
docker compose ps
docker compose pause
docker compose unpause
docker compose down

3. 访问服务：

• SSE端点: http://localhost:8000/sse

4. Cursor IDE配置：

• 设置 → 功能 → 添加MCP服务器
• 类型: "sse"
• URL: http://localhost:8000/sse

传统Python部署

1. 安装系统依赖：

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y poppler-utils tesseract-ocr tesseract-ocr-chi-sim

# macOS
brew install poppler tesseract tesseract-lang

# Windows
# 1. 下载并安装Tesseract: https://github.com/UB-Mannheim/tesseract/wiki
# 2. 将Tesseract添加到系统PATH

2. 安装Python依赖：

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

3. 运行服务：

uvicorn mcp_server:app --reload

配置

环境变量

以下是一些常用的环境变量：

• MCP_HOST: 服务绑定的主机，默认为0.0.0.0
• MCP_PORT: 服务绑定的端口，默认为8000
• MCP_DEBUG: 是否启用调试模式，默认为False

日志

默认情况下，日志输出到控制台。您可以通过配置logging模块来更改日志输出方式。

工具开发

工具模板

以下是一个工具的基本模板：

from typing import Dict, Any
import mcp.types as types
from . import BaseTool, ToolRegistry

@ToolRegistry.register
class MyTool(BaseTool):
    name = "my_tool"
    description = "这是一个示例工具"

    async def execute(self, arguments: Dict[str, Any]) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
        # 在此处实现逻辑
        return []

事件处理

您可以通过订阅事件来扩展功能：

from .events import EventManager

class MyEventListener:
    def on_event(self, event: str, data: Dict[str, Any]):
        if event == "my_event":
            print(f"收到自定义事件：{data}")

附录

常见问题

1. 如何调试服务？

   • 启用调试模式：MCP_DEBUG=True
   • 使用IDE的调试功能

2. 如何查看日志？

   • 默认输出到控制台
   • 配置logging模块输出到文件或数据库

3. 如何处理错误？

   • 在工具中捕获异常并返回友好的错误信息

参考文献

• MCP官方文档
• Python类型提示
• Uvicorn文档

联系方式

如有任何问题，请联系support@mcp.com