星战科技xingzhan.cloud
返回市场
MCP-高级版

MCP-高级版

作者：khshanovskyi7 星标更新：2025-11-16
安装使用来源：spider==github.com

项目介绍

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

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

🎯 任务概述

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

🎓 学习目标

通过完成本项目，您将学习：

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

🏗️ 架构

├── agent/                        # MCP客户端实现
│   ├── clients/
│   │   ├── custom_mcp_client.py    🚧 待办事项：纯Python MCP客户端
│   │   ├── mcp_client.py           ✅ 完成：基于框架的客户端
│   │   └── openai_client.py        ✅ 完成：AI模型集成
│   ├── models/           
│   │   └── message.py              ✅ 完成：消息结构
│   └── app.py                      🚧 待办事项：使用MCPClient和CustomMCPClient测试
└── mcp_server/                   # MCP服务器实现
    ├── models/
    │   ├── request.py              ✅ 完成：请求模型
    │   └── response.py             ✅ 完成：响应模型
    ├── services/
    │   └── mcp_server.py           🚧 待办事项：实现核心服务器逻辑
    ├── tools/
    │   ├── base.py                 ✅ 完成：抽象工具接口
    │   ├── create_user_tool.py     🚧 待办事项：实现网络搜索工具
    │   ├── delete_user_tool.py     🚧 待办事项：实现网络搜索工具
    │   ├── update_user_tool.py     🚧 待办事项：实现网络搜索工具
    │   ├── get_user_by_id_tool.py  🚧 待办事项：实现网络搜索工具
    │   └── search_users.py         🚧 待办事项：实现网络搜索工具
    └── server.py                   🚧 待办事项：实现FastAPI服务器

📋 要求

  • Python：3.11或更高版本
  • 依赖项：列在requirements.txt中
  • 可选：Postman用于API测试

🔧 设置说明

  1. 创建虚拟环境 
    python -m venv .venv
  2. 安装依赖项 
    pip install -r requirements.txt

🚀 任务：

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

创建MCP服务器：

  1. 运行docker desktop with UMS
  2. 打开mcp_server并查看MCP服务器结构：
    • 在models中持久化已实现的请求和响应模型，关于请求和响应的详细信息，请参阅官方文档
    • 在services/mcp_server.py中，你需要实现TODO部分描述的内容
    • 在tools中，你可以找到简单的工具
    • 最后，在server.py中提供TODO部分描述的实现
  3. 在本地运行MCP服务器
  4. 使用Postman进行测试。导入mcp.postman_collection.json到Postman。（init -> init-notification -> tools/list -> tools/call）
  5. 打开agent/app.py，并在本地使用MCPClient运行它，并实现它
  6. 使用以下查询测试代理👇
  7. 提供custom_mcp_client.py中TODO部分描述的实现
  8. 再次使用以下查询测试代理👇
检查Arkadiy Dobkin是否作为用户存在，如果不存在，则在网络上搜索他的信息并添加他

🔍 MCP协议细节

JSON-RPC结构

请求格式：

{
  "jsonrpc": "2.0",
  "id": "唯一请求ID",
  "method": "方法名称",
  "params": {
    "参数": "值"
  }
}

响应格式：

{
  "jsonrpc": "2.0",
  "id": "匹配请求ID",
  "result": {
    "数据": "响应数据"
  }
}

MCP会话流程

  1. 初始化：客户端发送initialize请求
  2. 通知：客户端发送notifications/initialized
  3. 发现：客户端调用tools/list以获取可用工具
  4. 操作：客户端调用tools/call，指定特定工具及其参数
  5. 关闭：DELETE, {主机}, 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

常见问题

  • 缺少Accept头部：服务器需要同时接受JSON和SSE类型
  • 会话ID缺失：大多数操作都需要有效的会话ID
  • 工具参数：参数必须根据工具模式正确格式化
  • 异步上下文：对于HTTP请求，使用正确的async/await模式

📚 额外资源