MCP服务器和插件
这个项目是一个模块化的MCP（模型上下文协议）服务器，使用FastAPI支持包括天气功能在内的多个客户端。它同时提供HTTP REST API和原生MCP协议支持，以便与Claude Desktop和其他MCP兼容客户端进行集成。
架构概述
*完整的系统架构，展示了HTTP桥接和原生MCP集成路径*
选项1：HTTP桥接集成
Claude Desktop → MCP HTTP Bridge → HTTP API Server → Weather Client → OpenWeatherMap API
↓ ↓ ↓ ↓ ↓
User asks Converts MCP Validates API Processes Returns weather
"weather?" to HTTP requests key & routes request data to user选项2：原生MCP集成
Claude Desktop → Native MCP Server → Weather Client → OpenWeatherMap API
↓ ↓ ↓ ↓
User asks Direct stdio Processes Returns weather
"weather?" protocol comm. request data to user主要区别：
- HTTP桥接器兼容Python 3.9+，通过HTTP层进行API密钥验证
- 原生MCP（多点触控处理器）要求：Python 3.10+，直接协议通信，可选API密钥
详细流程示例
用户请求: *“伦敦的天气怎么样？”*
HTTP桥接流：
1. Claude Desktop → "get_current_weather(location: 'London')" → MCP HTTP Bridge
2. MCP HTTP Bridge → POST /tools/get_current_weather + API Key → HTTP Server
3. HTTP Server → Validates "api_http_bridge_***" → Weather Client
4. Weather Client → GET weather?q=London → OpenWeatherMap API
5. OpenWeatherMap → Weather Data → Weather Client → HTTP Server
6. HTTP Server → Logs "Claude Desktop HTTP Bridge executed tool" → MCP Bridge
7. MCP Bridge → Weather Response → Claude Desktop → User原生MCP流
1. Claude Desktop → "get_current_weather(location: 'London')" → Native MCP Server
2. Native MCP Server → Logs "Claude Desktop MCP Native executed tool" → Weather Client
3. Weather Client → GET weather?q=London → OpenWeatherMap API
4. OpenWeatherMap → Weather Data → Weather Client → Native MCP Server
5. Native MCP Server → Weather Response → Claude Desktop → User特点/功能
- 天气工具使用OpenWeatherMap API查看当前天气状况和5天天气预报
- 双协议支持以下是原文内容的翻译：“HTTP REST API”和“native MCP stdio protocol”
- API密钥认证使用安全API密钥进行客户端识别和使用追踪
- 客户追踪客户端API访问和工具使用的全面日志记录
- Claude 桌面集成即开即用的配置文件，实现无缝集成
- 模块化架构可扩展的客户端系统，用于添加新工具
- 热重载带有自动代码重新加载功能的开发服务器
- 集中式缓存Python字节码缓存组织在
.cache/pycache/ - 全面日志记录用于调试、监控和客户端分析的详细日志记录
快速入门
1. 安装依赖项
pip install -e .2. 配置环境
复制 .env.example 到；向；对于；为了；由 .env 并添加您的OpenWeatherMap API密钥：
OPENWEATHERMAP_API_KEY=your_api_key_here
LOG_LEVEL=INFO
PYTHONPYCACHEPREFIX=.cache/pycache3. 启动服务器
./scripts/start.sh4. 测试API
# Test HTTP API with authentication
./test/check_endpoints.sh
# Test Native MCP server authentication (optional)
./test/check_native_mcp.sh5. 停止服务器
./scripts/stop.shClaude桌面集成
这个项目支持两种与Claude Desktop的集成方法，两者都 API密钥认证 用于客户追踪：
选项1：HTTP桥接（推荐用于Python 3.9+）
使用将MCP协议转换为HTTP REST调用的HTTP桥接器：
{
"mcpServers": {
"weather-server": {
"command": "
/mcp-server-env/bin/python",
"args": ["
/mcp_http_bridge.py"],
"env": {
"SERVER_URL": "http://localhost:8008",
"API_KEY": "api_http_bridge_3f8a2c9d1e6b4f7a8c5d2e9f1a3b6c8d"
}
}
}
}复制 claude-desktop-config-http-bridge.json.example 并更新路径。
选项2：原生MCP（需要Python 3.10+）
使用原生的MCP stdio协议：
{
"mcpServers": {
"weather-server": {
"command": "
/mcp-server-env/bin/python",
"args": ["-m", "src.mcp_server"],
"env": {
"API_KEY": "api_mcp_native_3f8a2c9d1e6b4f7a8c5d2e9f1a3b6c8d"
}
}
}
}复制 claude-desktop-config-native-mcp.json.example 并更新路径。
身份验证与客户端追踪
API密钥认证
两种集成方法均支持使用API密钥进行客户端身份验证和使用追踪：
可用的API密钥：
api_mcp_native_3f8a2c9d1e6b4f7a8c5d2e9f1a3b6c8d→ Claude Desktop MCP 本机（或：原生）api_http_bridge_3f8a2c9d1e6b4f7a8c5d2e9f1a3b6c8d→ Claude Desktop HTTP 桥接器
使用追踪
所有API调用均记录有客户端标识：
2025-09-09 14:42:30,882 - src.middleware.auth - INFO - API access: Claude Desktop MCP Native - Key: api_mcp_***
2025-09-09 14:42:30,883 - __main__ - INFO - Client 'Claude Desktop MCP Native' executing tool: get_current_weather日志位置： logs/mcp-server.log
认证行为
HTTP API（端口8008）：
- ✅ 公共终端节点：
/，/health，/docs，/openapi.json - 🔐 受保护的端点：
/tools，/tools/{tool_name}(需要X-API-Key头球 - 无效/缺失API密钥：HTTP 401错误
原生MCP服务器：
- ✅ 有效的API密钥：已识别客户端，使用情况已记录
- ⚠️ 无API密钥：已记录警告，以“匿名MCP客户端”模式运行
- 无效的API密钥：服务器启动失败
API 端点
服务器信息
根端点
GET http://localhost:8008/返回服务器信息和已加载的客户端
健康检查
GET http://localhost:8008/health返回服务器健康状态和客户端状态
列出所有工具 🔐（锁形符号，常用于表示密码、保密或安全）
GET http://localhost:8008/tools
X-API-Key: api_http_bridge_3f8a2c9d1e6b4f7a8c5d2e9f1a3b6c8d返回所有可用工具及其模式
天气工具
获取当前天气 🔐（锁形符号，常用于表示安全、保密或密码等含义）
POST http://localhost:8008/tools/get_current_weather
Content-Type: application/json
X-API-Key: api_http_bridge_3f8a2c9d1e6b4f7a8c5d2e9f1a3b6c8d
{
"location": "London"
}获取天气预报 🔐（锁形符号，常用于表示密码或保密）
POST http://localhost:8008/tools/get_weather_forecast
Content-Type: application/json
X-API-Key: api_http_bridge_3f8a2c9d1e6b4f7a8c5d2e9f1a3b6c8d
{
"location": "New York",
"days": 3
}可用的天气工具
- 获取当前位置天气（单位默认为公制）
- 获取任意地点的当前天气状况 - 位置可以是城市名、“城市,国家”，或者坐标 - 温度始终以摄氏度表示
- 获取天气预报（地点，天数=3，单位=公制）
- 获取1-5天的天气预报 - 与当前天气相同的位置选项 - 温度一律以摄氏度表示
测试
交互式测试
- 参观
http://localhost:8008/docs用于 Swagger UI - 使用不同参数测试所有端点
- 查看各城市的实时天气数据
命令行测试
# Test current weather (with API key)
curl -X POST "http://localhost:8008/tools/get_current_weather" \
-H "Content-Type: application/json" \
-H "X-API-Key: api_http_bridge_3f8a2c9d1e6b4f7a8c5d2e9f1a3b6c8d" \
-d '{"location": "Paris"}'
# Test weather forecast (with API key)
curl -X POST "http://localhost:8008/tools/get_weather_forecast" \
-H "Content-Type: application/json" \
-H "X-API-Key: api_http_bridge_3f8a2c9d1e6b4f7a8c5d2e9f1a3b6c8d" \
-d '{"location": "Tokyo", "days": 5}'
# Test without API key (will return 401 error)
curl -X POST "http://localhost:8008/tools/get_current_weather" \
-H "Content-Type: application/json" \
-d '{"location": "London"}'Claude桌面端测试
配置完成后，请询问Claude Desktop：
- “伦敦现在的天气怎么样？”
- “给我一份纽约5天的天气预报”
- “比较悉尼和温哥华的天气”
项目结构
├── src/
│ ├── app.py # FastAPI HTTP server
│ ├── mcp_server.py # Native MCP stdio server
│ ├── clients/
│ │ └── weather/ # Weather client implementation
│ ├── core/ # Base client classes
│ ├── types/ # Common type definitions
│ └── utils/ # Utilities and config
├── scripts/
│ ├── start.sh # Server startup script
│ └── stop.sh # Server stop script
├── test/
│ └── check_endpoints.sh # API testing script
├── mcp_http_bridge.py # MCP to HTTP bridge
├── run.py # Server entry point
└── claude-desktop-config-*.json.example # Claude Desktop configs发展
添加新客户
- 在（指定位置）创建一个新的客户端目录
src/clients/ - 实现一个扩展自（某基类的）客户端类
BaseClient - 定义工具及其架构
- 在加载器中注册客户端
环境变量
OPENWEATHERMAP_API_KEY天气功能所需的（条件/设置）LOG_LEVEL日志级别（INFO，DEBUG，WARNING，ERROR）PYTHONPYCACHEPREFIX集中式的Python缓存位置
虚拟环境
该项目使用了一个虚拟环境 mcp-server-env/ 使用 Python 3.12+ 以获得完整的 MCP 支持。
要求
- Python 3.10及以上版本
- OpenWeatherMap API密钥 （支持免费层级）
- FastAPI 以及依赖项（通过
pip install -e .)
故障排除
常见问题
- “工具执行失败”检查API密钥是否已设置
.env文件 - “缺少API密钥”（HTTP 401）确保
API_KEY在Claude Desktop配置中设置 - 无效的API密钥使用身份验证部分中的正确API密钥进行验证
- “服务器已断开连接”在Claude Desktop配置中验证Python路径
- 导入错误确保已激活虚拟环境并安装了依赖项
- 端口冲突确保端口8008可用
日志
- HTTP服务器检查控制台输出
./scripts/start.sh - 客户跟踪见
logs/mcp-server.logAPI访问日志 - MCP桥见
logs/mcp-bridge.log - MCP服务器见
logs/mcp-server.log - Claude Desktop（可译为“克劳德桌面版”或根据具体语境简化为“克劳德桌面”）检查Claude Desktop的MCP日志
监控客户端使用情况：
# Real-time client tracking
tail -f logs/mcp-server.log | grep "API access"
# Search specific client
grep "Claude Desktop MCP Native" logs/mcp-server.log