人口普查数据服务器

MCP普查服务器

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

特性

• JSON-RPC 2.0（单次和批处理请求）
• 用于请求/响应验证的Pydantic模型
• 缓存人口普查API响应（生存时间5分钟）
• 结构化日志记录（通过Python） logging)
• API密钥认证通过 X-API-Key 头球
• 健康检查端点(/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
   # 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. 将JSON-RPC请求发送到 http://localhost:8000/ 带标题 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存储库中，转到 设置 > 页面.
2. 在...之下 源，选择 主要的 分支和 /docs 文件夹。
3. 点击 保存.

这些文件将在以下网址提供：

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

您可以在存储库中添加此URL 关于 部分作为项目网站。

客户端应用

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