AI导哈

MCP集成示例

一个简单的教育项目，展示如何通过STDIO和HTTP/SSE传输方式与Anthropic模型上下文协议（MCP）集成。

  • by dondetir
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 dondetir/simpleMCP

使用说明

SimpleMCP - 基本的MCP集成示例

一个简单且具有教育意义的项目，展示了如何与（某系统/平台）进行集成 人类模型上下文协议（MCP） 同时使用两者 STDIO（标准输入输出） 并且 HTTP/SSE（服务器发送事件） 交通。

📖 这是什么？

SimpleMCP 是一个最小示例，展示了如何构建一个与任何MCP兼容客户端都能协同工作的MCP服务器。它实现了一个简单的讲故事服务，通过 两种运输方式:

  1. STDIO（标准输入输出） (stdin/stdout) - 用于本地MCP客户端
  2. HTTP/SSE（服务器发送事件） （服务器发送事件）- 用于远程MCP客户端和Web应用程序

非常适合学习如何构建MCP服务器并将其与任何MCP客户端集成！

🎯 你将学到的内容

  • 如何使用官方的Anthropic MCP SDK
  • 实现带有STDIO传输的MCP服务器
  • 使用HTTP/SSE传输实现MCP服务器
  • 业务逻辑与协议层之间的清晰分离
  • 测试MCP服务器

⚡ 快速启动

1. 安装

# Clone the repository
git clone https://github.com/dondetir/simpleMCP.git
cd simpleMCP

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. 运行测试

pytest tests/

3. 试一试

选项A：STDIO客户端（例如，Claude桌面版）

# See CLIENT_SETUP.md for full instructions
# Add to your MCP client configuration and restart

选项B：HTTP服务器

# Start the HTTP server
python mcp_http_server.py

# Server runs on http://localhost:8000/sse

选项C：测试客户端

# Use the example test client
python examples/test_mcp_client.py --stdio
python examples/test_mcp_client.py --http

🏗️ 项目结构

SimpleMCP/
├── mcp_server.py              # STDIO transport server
├── mcp_http_server.py         # HTTP/SSE transport server
├── story_manager.py           # Core business logic (transport-independent)
├── stories/stories.json       # Sample data
├── tests/                     # Unit and integration tests
├── examples/                  # Example clients and configs
└── requirements.txt           # Python dependencies

🔧 它的工作原理

建筑

┌─────────────────────────┐
│   Any MCP Client        │
│ (Desktop/CLI/Web/etc)   │
└──────────┬──────────────┘
           │
           │ MCP Protocol (JSON-RPC 2.0)
           │
    ┌──────▼───────┐
    │  Transport   │
    │ STDIO or SSE │
    └──────┬───────┘
           │
    ┌──────▼────────┐
    │  MCP Server   │
    │ (this project)│
    └──────┬────────┘
           │
    ┌──────▼─────────┐
    │ Business Logic │
    │story_manager.py│
    └────────────────┘

可用工具

两台服务器都提供了相同的两个MCP工具：

  1. list_stories - 返回所有可用的故事（ID和标题）
  2. get_story - 通过ID返回完整故事

示例故事

服务器包含5个示例故事：

  • squirrel_and_owl 《好奇的小松鼠和智慧的猫头鹰》
  • bear_loses_roar - 失去咆哮的熊
  • turtle_wants_to_fly 《想飞的乌龟》
  • lonely_firefly - 孤独的萤火虫
  • rabbit_and_carrot - 兔子与神奇的胡萝卜

📚 文档

🧪 测试

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=. --cov-report=term-missing

# Run specific test file
pytest tests/test_mcp_servers.py -v

💡 扩展这个例子

想搭建自己的MCP服务器吗？方法如下：

  1. 定义你的业务逻辑 （像 story_manager.py)
  2. 创建工具函数 （与）……一起/带着 @mcp.tool() 装饰器
  3. 选择您的交通工具 （本地使用STDIO，远程使用HTTP/SSE）
  4. 使用MCP Inspector进行测试 或者例如客户

请参阅代码注释以获取详细解释！

🛠️ 技术栈

  • Python 3.8或更高版本
  • MCP SDK（MCP软件开发工具包） （mcp>=1.17.0) - 官方Anthropic软件开发工具包（SDK）
  • FastAPI（快速API） & Uvicorn（通常指一个用于Python的异步ASGI服务器，全称可能是“Uvicorn Hypercorn”等，但直接翻译为“乌维康”并不常见，一般直接使用其英文名或根据上下文解释其功能） - 对于HTTP/SSE服务器
  • pytest - 测试框架

🤝 贡献

这是一个教育性质的示例项目。欢迎贡献！

  • 通过 GitHub Issues 报告错误
  • 提交包含改进的拉取请求
  • 分享您自己的MCP服务器示例

看 `CONTRIBUTING.md` 翻译成中文是：“贡献指南/贡献规范文件”。这个文件通常用于说明如何为某个项目或组织做出贡献，包括贡献的流程、规范、注意事项等 作为指南。

📄 许可证

MIT 许可证 - 详见 许可证 详情请查阅文件。

🔗 资源

🙋 常见问题解答 (FAQ)

问：使用这个我需要特定的MCP客户端吗？ A: 不！这适用于任何与MCP兼容的客户端，包括Claude Desktop、Claude Code或自定义实现。

问：我可以添加自己的工具吗？ A: 是的！用……添加新功能 @mcp.tool() 装饰器。请参阅现有工具以获取示例。

问：STDIO 和 HTTP/SSE 之间有什么区别？ A: STDIO 用于本地 MCP 客户端（如桌面应用程序），HTTP/SSE 用于基于网络的客户端（如网页应用或远程集成）。

问：我要如何添加更多故事？ A: 编辑 stories/stories.json 并添加新的故事对象 id， title，和 text 领域。

构建用于展示人类中心模型上下文协议 🚀 表情符号“🚀”在中文中通常被理解为“火箭”或“快速前进”的意思，但直接翻译时，由于它是一个图形符号，没有固定的中文文字对应，所以可以简单地描述为“火箭”或根据上下文意译为“快速进展”、“飞速发展”等。如果仅作为表情使用，可以保留原符号或用“火箭”来示意。

有问题吗？请在GitHub上提交一个议题！

相关 MCP