AI导哈

MCP客户端API学习模板

一个用于学习创建和集成MCP服务器和客户端的模板项目，遵循Python官方SDK和最佳实践。

  • by AdrianRico98
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 adrianrico98/mcp_server

使用说明

MCP客户端API-模板Educativo

一个模板项目，用于学习如何按照良好做法和官方Python SDK创建和集成MCP服务器和客户端。

教育目的

这个项目作为 学习模板 了解如何：

  • 使用FastMCP和pydantic创建带有工具的MCP服务器。
  • 实现通过HTTP Streamaliente连接的MCP客户端。
  • 使MCP工具适应语言模型SDK（Gemini）所需的格式。
  • 管理会议并保持对话环境。
  • 构建一个协调整个流程的后端API。

[！重要] 这是一个 小例子 出于教育目的。如果不在安全性、身份验证和状态管理方面进行额外改进，它就不是为生产而设计的。

模板建筑

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   FastAPI       │    │   MCP Client    │    │   MCP Server    │
│   Backend       │◄───┤   (Cliente)     │◄───┤  (FastMCP)      │
│   (Orchestador) │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
    ┌─────────┐              ┌─────────┐              ┌─────────┐
    │ Session │              │ Gemini  │              │ File    │
    │ Manager │              │ 2.5     │              │ Tools   │
    │(In-Mem) │              │ Flash   │              │(Pydantic)│
    └─────────┘              └─────────┘              └─────────┘

你会学到什么

1. 具有FastMCP的MCP服务器

  • 运输使用 streamable-http 跟随 官方SDK.
  • 定义带有pydantic模式的工具。
  • 通过日志和信息消息处理上下文。
  • 模拟“慢”过程 asyncio.sleep().

2.客户MCP Completo

  • 使用上下文管理器正确初始化。
  • 连接生命周期管理（连接/断开）。
  • MCP工具适应谷歌Gemini SDK格式。
  • 保持与上下文的对话历史。

3.与语言模型的整合

  • 将 MCP 方案转换为格式 Tool 双子座。
  • 为LLM构建会话上下文。
  • 处理混合响应（文本+函数调用）。
  • 工具执行和结果处理。

快速安装

[！注意] 需要Python 3.8+和Gemini API令牌

# 1. Crear y activar entorno
python -m venv venv
venv\Scripts\activate  # Windows

# 2. Instalar dependencias
pip install "mcp[cli]" google-genai fastapi uvicorn python-dotenv pydantic-settings

# 3. Configurar token
echo "GEMINI_TOKEN=tu_token_aqui" > .env

[！提示] 获取您的双子座代币 谷歌人工智能工作室

使用模板

执行组件

1号航站楼-服务MCP：

python server.py

终端2-API后端：

python backend.py

测试集成

# Crear sesión
curl -X POST "http://localhost:8080/session/new"

# Hacer consulta (usa el session_id devuelto)
curl -X POST "http://localhost:8080/session/{session_id}/query" \
  -H "Content-Type: application/json" \
  -d '{"query": "¿Qué directorios principales tiene el usuario adrian.rico?"}'

模板组件

伺服MCP(server.py)

遵循FastMCP实现两个示例工具

客户MCP(mcp_client.py)

通过遵循官方SDK演示正确的初始化

后端API(backend.py)

合同模板：

  • 内存会话管理。
  • 端点RESTful组合。
  • 错误处理和日志记录。
  • 配置的CORS（非常允许开发）。

工具示例

recuperar_directorios_principales

  • 输入: usuario: str
  • 输出: List[Directorio].
  • 证明类型化方案，上下文日志，延迟模拟。

recuperar_archivos_directorio

  • 输入多个参数带过滤器。
  • 输出: List[Archivo].
  • 证明：复杂的工具，错误处理，渐进式日志记录。

已知限制

[！小心] 这个模板对教育简单性有故意的限制

状态管理

  • 记忆中的会话：重新启动时丢失。
  • 没有坚持：历史不会自动保存。
  • 基本清洁：仅用于超时，没有高级度量。

安全

  • CORS放大器：允许任何来源(*)
  • 没有身份验证：没有保护的公共端点
  • 犯罪率限制：容易滥用资源
  • 日志verbosos：可以过滤敏感信息
  • 没有服务器安全性：一些工具可能意味着要在服务器上实现的额外安全性以及通话限制。

可扩展性

  • 单螺纹：每个MCP服务器一个实例
  • Sin负载平衡：不分配负载

建议的改进

[！提示] 转化为生产应用程序的改进领域

安全

  • 智威汤逊实施自给自足。
  • Redis的速率限制。
  • CORS对领土的限制。
  • 输入消毒。

持久性

  • 会话数据库（Redis/PostgreSQL）。
  • 存储对话。
  • 备份和状态恢复。

监视器

  • 公制。
  • 高级健康检查。
  • 追踪分布。
  • 自动警报

可扩展性

  • 多个实例的负载均衡器。
  • 重型工具排队系统。
  • 智能缓存。

档案结构

mcp-template/
├── server.py           # Servidor MCP con FastMCP
├── mcp_client.py       # Cliente MCP completo  
├── backend.py          # API FastAPI orchestador
├── session_manager.py  # Gestión de sesiones
├── models.py          # Schemas Pydantic
├── config.py          # Configuración centralizada
├── .env               # Variables de entorno
└── README.md          # Esta documentación

参考文献和资源

贡献到模板

该模板与社区一起改进：

  1. 叉库
  2. 改进实验
  3. 记录你的发现
  4. Comparte通过Pull Request

[！重要] 保持教育重点-明确优先于效率

基于Python的非模板教育辅助MCP协议

相关 MCP