MCP 人口普查服务器

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

功能

• 支持 JSON-RPC 2.0（单次和批量请求）
• 使用 Pydantic 模型进行请求/响应验证
• 缓存人口普查 API 响应（过期时间：5 分钟）
• 结构化日志记录（通过 Python logging）
• 通过 X-API-Key 头进行 API 密钥身份验证
• 健康检查端点（/health）
• 交互式 API 文档（Swagger UI 可在 /docs 访问）
• 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
   # 编辑 .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. 使用 http://localhost:8000/ 发送 JSON-RPC 请求，带有头 X-API-Key: <SERVER_API_KEY>。

示例 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 .
• 代码检查：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 仓库中，转到 设置 > Pages。
2. 在 源 下，选择 主分支 和 /docs 文件夹。
3. 点击 保存。

文档将可用于：

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

您可以在仓库的 关于 部分将其设置为项目网站。

客户端应用程序

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

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

   cd client
   

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

   cp .env.example .env.local
   # 设置 OPENAI_API_KEY，MCP_SERVER_URL（例如 https://your-server），SERVER_API_KEY
   

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

   npm install
   npm run dev
   

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

快速开始脚本

您可以配置环境并同时运行服务器和客户端：

chmod +x start.sh
./start.sh

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