使用说明
JSONPlaceholder MCP服务器-生产就绪
一个用Python实现的生产级模型上下文协议（MCP）服务器，它封装了公共JSONPlaceholder API。此服务器提供结构化的MCP工具，用于访问帖子、评论和用户数据，并进行适当的错误处理、验证和日志记录。
特性
- 5结构化MCP工具 --get_post、list_post、get_comments_for_post、get_user、list_users
- 全类型安全 --在整个代码库中键入提示，在所有工具上进行输入验证
- 稳健的错误处理 --网络错误、超时、HTTP错误通过结构化响应得到妥善处理
- 生产测井 --调试、信息、警告和错误级别的全面日志记录
- 整洁架构 --关注点分离：服务层（HTTP）、工具层（MCP定义）和服务器层
- 管理平台就绪 --环境变量配置，无硬编码端口，0.0.0.0绑定
- 健康检查端点 --内置健康验证方法
- 请求超时 -所有API请求超时10秒以防止挂起
- 异步/等待 --完全异步支持可扩展性
项目结构
app/
├── main.py # Entry point with environment configuration
└── server/
├── __init__.py # Server package initialization
├── mcp_server.py # MCP server implementation with tool registration
├── services/
│ ├── __init__.py
│ └── jsonplaceholder_client.py # HTTP client with error handling
└── tools/
├── __init__.py
├── posts.py # Post-related MCP tools
└── users.py # User-related MCP tools
requirements.txt # Python dependencies
Procfile # Deployment start command
README.md # This file
.gitignore # Git ignore rules
安装
先决条件
- Python 3.8+
- pip或诗歌
本地设置
-
克隆存储库：
cd /path/to/sample-mcp-server -
创建虚拟环境（推荐）：
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate -
安装依赖项：
pip install -r requirements.txt
本地运行
默认配置
python -m app.main
服务器将于启动 0.0.0.0:8000 默认情况下。
自定义主机/端口
# Set environment variables before running
export HOST=127.0.0.1
export PORT=3000
python -m app.main
使用.env文件
创建一个 .env 项目根目录中的文件：
HOST=0.0.0.0
PORT=8000
然后运行：
python -m app.main
可用的MCP工具
帖子工具
get_post
按ID获取单个帖子。
输入：
{
"post_id": 1
}
输出：
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat provident...",
"body": "quia et suscipit..."
}
list_posts
获取所有帖子，可选择按用户筛选。
输入：
{
"user_id": 1
}
输出：
{
"data": [
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat provident...",
"body": "quia et suscipit..."
}
],
"count": 10
}
get_comments_for_post
获取特定帖子的所有评论。
输入：
{
"post_id": 1
}
输出：
{
"data": [
{
"postId": 1,
"id": 1,
"name": "id labore ex et quam laborum",
"email": "Eliseo@gardner.biz",
"body": "laudantium enim quasi est quidem magnam..."
}
],
"count": 5
}
用户工具
get_user
按ID获取单个用户。
输入：
{
"user_id": 1
}
输出：
{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "Sincere@april.biz",
"address": {
"street": "Kulas Light",
"suite": "Apt. 556",
"city": "Gwenborough",
"zipcode": "92998-3874",
"geo": {
"lat": "-37.3159",
"lng": "81.1496"
}
},
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
"name": "Romaguera-Crona",
"catchPhrase": "Multi-layered client-server neural-net",
"bs": "harness real-time e-markets"
}
}
list_users
获取所有用户。
输入：
{}
输出：
{
"data": [
{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "Sincere@april.biz",
...
}
],
"count": 10
}
错误处理
所有工具都返回带有状态代码和消息的结构化错误响应：
{
"error": "Invalid post_id. Must be integer between 1 and 100",
"status": 404
}
常见错误场景：
- 无效输入 --帖子/用户ID超出有效范围（帖子1-100，用户1-10）
- 未找到 --请求的资源不存在（HTTP 404）
- 网络错误 --连接失败或超时
- 解析错误 -API的JSON响应无效
建筑与设计决策
服务层(services/jsonplaceholder_client.py)
HTTP客户端与MCP工具定义是分开的，允许：
- 轻松独立测试API调用
- 跨多个工具的可重用HTTP逻辑
- 集中错误处理和日志记录
- 请求超时管理（10秒）
设计模式： 上下文管理器支持资源清理
工具层(tools/posts.py, tools/users.py)
工具定义如下：
- JSON模式验证 --根据MCP模式验证所有输入
- 键入提示 --IDE支持的完整类型注释
- 文档字符串 --每个工具的全面文档
- 异步支持 --为高并发场景做好准备
- 结构化响应 --JSON格式的输出，不是原始文本
设计模式： 工具定义和执行处理程序分开
服务器层(server/mcp_server.py)
MCP服务器：
- 启动时注册所有工具
- 将工具调用路由到适当的处理程序
- 提供健康检查功能
- 管理客户端生命周期
设计模式： 用于工具执行的处理程序注册表模式
配置(main.py)
- 环境变量 --环境中的端口和主机
- 日志记录设置 --结构化日志记录到stdout
- 异步运行时 --asyncio.run（）用于服务器执行
- 错误处理 --优雅的关机和错误报告
Natoma安全平台上的部署
此服务器与Natoma托管主机要求兼容：
- 绑定到
0.0.0.0默认情况下 - 荣誉注入
PORT环境变量 - 暴露
/health活性检查的终点 - 同时支持MCP JSON-RPC
/和/mcp端点 - 使用stdout日志记录进行平台日志收集
步骤
- 配置服务运行时：
- 运行时：Python 3.11+
- 构建命令：
pip install -r requirements.txt - 启动命令：
python -m app.main
- 设置环境变量（如果您的工作区需要）：
PORT--通常平台注入HOST--保持未设置（默认为0.0.0.0)或明确设置LOG_LEVEL--可选(INFO,DEBUG,WARNING,ERROR)
- 设置健康检查路径：
/health
渲染部署
步骤
-
在渲染时创建新的Web服务：
- 仓库：您的Git仓库URL
- 运行时：Python 3.11
- 构建命令：
pip install -r requirements.txt - 启动命令：使用Procfile（自动检测）
-
设置环境变量（可选）：
PORT--由Render自动设置，无需配置HOST--保持原样0.0.0.0用于渲染- 其他自定义变量（如果需要）
-
部署：
- 渲染将自动使用Procfile
- 服务将于启动
web: python -m app.main
健康检查
Render可以通过调用内置的健康检查来验证服务器的健康状况：
# Server includes async health_check() method
# Returns: {"status": "healthy", "server": "online", "api": "connected"}
开发与测试
运行测试（手动）
# Test a single tool via Python
python -c "
from app.server.services import JSONPlaceholderClient
client = JSONPlaceholderClient()
post = client.get_post(1)
print(post)
"
调试
将日志级别设置为DEBUG：
# In main.py or your test script
logging.basicConfig(level=logging.DEBUG)
代码质量
- 类型检查： 使用
mypy用于静态类型检查 - Linting： 使用
pylint或flake8 - 代码格式： 使用
black风格一致
# Example type check
mypy app/
API 参考
JSON占位符客户端方法
所有方法包括：
- 参数和返回值的类型提示
- 全面的文档字符串
- 日志记录错误处理
- 超时支持（默认10秒）
from app.server.services import JSONPlaceholderClient
client = JSONPlaceholderClient()
# Posts
post = client.get_post(1) # Returns dict or None
posts = client.list_posts(user_id=1) # Returns list
comments = client.get_comments_for_post(1) # Returns list
# Users
user = client.get_user(1) # Returns dict or None
users = client.list_users() # Returns list
生产注意事项
✅ 安全：
- 没有硬编码凭据
- 所有参数的输入验证
- 类型提示可防止许多注入攻击
✅ 可靠性：
- 全面的错误处理
- 请求超时防止挂起
- API故障的优雅降级
- 监测健康检查
✅ 可扩展性：
- 异步/等待支持
- 清晰地分离关注点
- 可观察性日志记录
- 标准HTTP传输
✅ 可维护性：
- 完整类型提示
- 详细文档字符串
- 干净的代码结构
- 对设计决策的在线评论
故障排除
服务器无法启动
- 检查端口是否未使用：
lsof -i :8000 - 验证Python 3.8+：
python --version - 检查依赖关系：
pip list | grep mcp
API调用失败
- 验证JSONPlaceholder是否可访问：
curl https://jsonplaceholder.typicode.com/posts/1 - 检查防火墙/网络设置
- 查看日志中的超时消息
工具响应无效
- 验证工具输入是否与架构匹配（post_id 1-100，user_id 1-10）
- 检查日志中的验证错误
- 确保JSON占位符API响应格式未更改
许可证
MIT许可证-有关详细信息，请参阅许可证文件
支持
对于问题或疑问：
- 检查日志：
python -m app.main显示所有操作 - 直接测试API：
curl https://jsonplaceholder.typicode.com/posts/1 - 验证配置
echo $PORT $HOST
