MCP Census Server

🚀 MCP 人口普查服务器

MCP 人口普查服务器是一个功能强大的模型上下文协议（MCP）服务器，可通过 HTTP 上的 JSON - RPC 访问美国人口普查局的数据，为用户提供便捷、高效的数据获取途径。

✨ 主要特性

• JSON - RPC 2.0 支持：支持单次和批量请求，满足不同场景下的数据交互需求。
• 请求/响应验证：利用 Pydantic 模型进行请求和响应验证，确保数据的准确性和完整性。
• 响应缓存：对人口普查 API 响应进行缓存，过期时间为 5 分钟，减少重复请求，提高性能。
• 结构化日志记录：通过 Python logging 实现结构化日志记录，便于问题排查和系统监控。
• API 密钥身份验证：通过 X - API - Key 头进行 API 密钥身份验证，保障系统安全。
• 健康检查端点：提供 /health 健康检查端点，方便监控服务器状态。
• 交互式 API 文档：Swagger UI 可在 /docs 访问，方便开发者查看和测试 API。
• MCP 方法丰富：
  • initialize：用于协商协议版本和功能。
  • notifications/initialized：客户端就绪通知。
  • tools/list：列出可用工具 (census/get)。
  • tools/call：调用 census/get 以检索人口普查局数据。

🚀 快速开始

克隆与进入项目目录

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

复制环境变量模板并设置密钥

cp .env.example .env
# 编辑 .env：
# CENSUS_API_KEY=<your_census_api_key>
# SERVER_API_KEY=<your_mcp_server_secret_key>

安装依赖项

pip install -r requirements.txt

启动服务器

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

发送请求

使用 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 管道配置：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 服务器和客户端。