MCP Census Server

MCP Census Server

一个功能强大的模型上下文协议（MCP）服务，通过 HTTP 上的 JSON-RPC 访问美国人口普查局数据。

功能

• JSON-RPC 2.0（单个和批量请求）
• 使用 Pydantic 模型验证请求和响应
• 缓存 Census API 响应（TTL 为 5 分钟）
• 结构化日志记录（通过 Python logging）
• 通过 X-API-Key 标头进行 API 密钥身份验证
• 健康检查端点（/health）
• 交互式 API 文档（可在 /docs 使用 Swagger UI）
• MCP 方法：
  • initialize：协商协议版本和功能
  • notifications/initialized：客户端就绪通知
  • tools/list：列出可用工具（census/get）
  • tools/call：调用 census/get 获取美国人口普查局数据

快速开始

1. 克隆仓库并进入目录：

   git clone https://github.com/kaman1/mcp_census_server.git
   cd mcp_census_server
   

2. 复制环境模板并设置密钥：

   cp .env.example .env
   # Edit .env:
   # CENSUS_API_KEY=<your_census_api_key>
   # SERVER_API_KEY=<your_mcp_server_secret_key>
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 启动服务：

   uvicorn app:app --host 0.0.0.0 --port 8000 --reload
   

5. 使用标头 X-API-Key: <SERVER_API_KEY> 向 http://localhost:8000/ 发送 JSON-RPC 请求。

tools/list 调用示例：

curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SERVER_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

开发

• 测试：pytest
• 格式化：black .
• 导入排序：isort .
• Lint 检查：flake8 .
• CI 流水线配置位于 .github/workflows/ci.yml

文档

• 架构：docs/architecture.md
• 使用示例：docs/usage.md
• 身份验证：docs/authentication.md
• 样式化文档（MDX + Mintlify）：

  npm install
  npm run serve:docs
  

托管文档

你可以通过 GitHub Pages 发布这些文档：

1. 在 GitHub 仓库中，前往 Settings > Pages。
2. 在 Source 下，选择 main 分支和 /docs 文件夹。
3. 点击 Save。

文档将在以下地址提供：

https://<username>.github.io/mcp_census_server/

你可以将此 URL 添加到仓库的 About 部分，作为项目网站。

客户端应用

client/ 目录包含一个基于 Next.js 的 MCP 客户端，可与此服务交互。

1. 切换到客户端文件夹：

   cd client
   

2. 复制示例环境文件，并填写密钥和服务 URL：

   cp .env.example .env.local
   # Set OPENAI_API_KEY, MCP_SERVER_URL (e.g. https://your-server), SERVER_API_KEY
   

3. 安装依赖项并启动开发服务：

   npm install
   npm run dev
   

4. 打开 http://localhost:3000 使用客户端 UI。

快速启动脚本

你可以通过一个步骤配置环境并启动服务和客户端：

chmod +x start.sh
./start.sh

这将提示你输入所有必需的密钥，并同时运行 MCP 服务和客户端。