MCP Census Server

🚀 MCP 人口普查服务器

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

🚀 快速开始

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"}'

✨ 主要特性

• 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 以检索人口普查局数据。

📦 安装指南

依赖安装

pip install -r requirements.txt

环境变量配置

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

启动服务器

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

💻 使用示例

基础用法

使用 curl 发送 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"}'

📚 详细文档

• 架构：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/

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

🔧 技术细节

开发

• 测试：使用 pytest 进行测试。
• 格式化：使用 black . 进行代码格式化。
• 导入排序：使用 isort . 进行导入排序。
• 代码检查：使用 flake8 . 进行代码检查。
• CI 管道配置在 .github/workflows/ci.yml

客户端应用程序

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 服务器和客户端。