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 服務器和客戶端。