MCP Framework

🚀 MCP開發指南

本指南將為您詳細介紹MCP（可能是某個特定框架或項目）的開發流程，包括工具模板示例、部署方法、配置說明、工具開發以及常見問題解答等內容，幫助您快速上手MCP開發。

🚀 快速開始

您可以參考以下工具模板示例，快速瞭解如何開發一個基本的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部署（推薦）

按照以下步驟，您可以使用Docker快速部署MCP服務。

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部署

如果您不想使用Docker，也可以使用傳統的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

📚 詳細文檔

配置

環境變量

以下是一些常用的環境變量及其默認值：

日誌

默認情況下，日誌輸出到控制檯。您可以通過配置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