AI导哈

MCP协议实现工具

一个用于构建基于MCP（Model Context Protocol）协议的AI代理和服务器/客户端架构的Python实现工具，支持自定义工具开发、会话管理和实时通信。

  • by khshanovskyi
  • Python
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 Codeus-Community/mcp-advanced

使用说明

高级MCP（服务器和客户端）实践任务

使用MCP（模型上下文协议）工具和MCP服务器/客户端架构构建AI代理的Python实现。

🎯 任务概述

使用自定义工具创建并运行MCP服务器，然后使用MCP客户端实现AI代理，该代理利用创建的服务器中的工具。此任务演示了从服务器实现到客户端集成的完整MCP工作流程。

🎓 学习目标

通过完成这个项目，你将学习：

  • MCP协议实现：了解模型上下文协议规范和JSON-RPC通信
  • 服务器端工具开发：创建符合MCP标准的自定义工具
  • 客户端集成：将AI代理连接到MCP服务器并处理工具执行
  • 会话管理：实施适当的会话处理和状态管理
  • 流媒体响应：使用服务器发送事件（SSE）进行实时通信
  • 错误处理：在分布式系统中实施稳健的错误处理

🏗️ 建筑

├── agent/                        # MCP Client Implementation
│   ├── clients/
│   │   ├── custom_mcp_client.py    🚧 TODO: Pure Python MCP client
│   │   ├── mcp_client.py           ✅ Complete: Framework-based client
│   │   └── openai_client.py          ✅ Complete: AI model integration
│   ├── models/           
│   │   └── message.py              ✅ Complete: Message structures
│   └── app.py                      🚧 TODO: Test it with MCPClient and CustomMCPClient
└── mcp_server/                   # MCP Server Implementation
    ├── models/
    │   ├── request.py              ✅ Complete: Request model
    │   └── response.py             ✅ Complete: Response model
    ├── services/
    │   └── mcp_server.py           🚧 TODO: Implement core server logic
    ├── tools/
    │   ├── base.py                 ✅ Complete: Abstract tool interface
    │   ├── create_user_tool.py     🚧 TODO: Implement web search tool
    │   ├── delete_user_tool.py     🚧 TODO: Implement web search tool
    │   ├── update_user_tool.py     🚧 TODO: Implement web search tool
    │   ├── get_user_by_id_tool.py  🚧 TODO: Implement web search tool
    │   └── search_users.py         🚧 TODO: Implement web search tool
    └── server.py                   🚧 TODO: Implement FastAPI server

📋 需求

  • python：3.11或更高
  • 依赖项：列在 requirements.txt
  • 可选的：API测试邮差

🔧 安装说明

  1. 创建虚拟环境
    python -m venv .venv
  2. 再进行
    pip install -r requirements.txt

🚀 任务：

如果主分支中的任务对你来说很难，那么切换到 with-detailed-description 分支

创建MCP服务器：

  1. 跑 使用UMS的docker去中心化
  2. 打开 mcp服务器 并回顾mcp服务器结构：
  3. 在本地运行MCP服务器
  4. 用Postman测试一下。导入 mcp.postman_collection.json 成为邮递员。 (init -> init-notification -> tools/list -> tools/call)
  5. 打开 agent/app.py 并使用MCPClient在本地运行它并实现它
  6. 测试代理有以下疑问👇
  7. 提供中所述的实现 TODO 部分为 custom_mcp_client.py
  8. 使用以下查询再次测试代理👇
Check if Arkadiy Dobkin present as a user, if not then search info about him in the web and add him

🔍 MCP协议详细信息

JSON-RPC结构

请求格式：

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "method_name",
  "params": {
    "parameter": "value"
  }
}

响应格式：

{
  "jsonrpc": "2.0",
  "id": "matching-request-id",
  "result": {
    "data": "response_data"
  }
}

MCP会话流

  1. 初始化：客户端发送 initialize 请求
  2. 通知：客户端发送 notifications/initialized
  3. 发现：客户电话 tools/list 获取可用工具
  4. 行动：客户电话 tools/call 使用特定的工具和论据
  5. 关机: DELETE, {host}, Mcp-Session-Id: {Mcp-Session-Id}，关机不在本实践中，但它是简单的REST请求

标头

  • Content-Type: application/json
  • Accept: application/json, text/event-stream
  • Mcp-Session-Id：会话标识符（初始化后）

🎯 实施技巧

自定义MCP客户端实现

  1. 错误处理：始终检查HTTP会话初始化
  2. 会话管理：正确存储和重用会话ID
  3. SSE解析：寻找 data: 前缀行，忽略 [DONE]
  4. JSON-RPC错误：检查 error 响应中的字段
  5. 内容提取：工具结果在 result.content[0].text

常见问题

  • 缺少接受标头：服务器需要JSON和SSE接受类型
  • 会话ID丢失：大多数操作都需要有效的会话ID
  • 工具参数：参数必须按照工具架构正确格式化
  • 异步上下文：对HTTP请求使用适当的异步/等待模式

📚 其他资源

相关 MCP