MCP Census Server

MCP Census Server

HTTP 経由の JSON-RPC を使用して米国国勢調査局のデータにアクセスする、堅牢な Model Context Protocol（MCP）サーバーです。

機能

• JSON-RPC 2.0（単一リクエストとバッチリクエスト）
• リクエスト／レスポンスの検証に Pydantic モデルを使用
• Census API のレスポンスをキャッシュ（TTL 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
   # 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. ヘッダー X-API-Key: <SERVER_API_KEY> を指定して、http://localhost:8000/ に JSON-RPC リクエストを送信します。

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 リポジトリで、Settings > Pages に移動します。
2. Source で、main ブランチと /docs フォルダーを選択します。
3. Save をクリックします。

ドキュメントは次の場所で公開されます：

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

この URL をリポジトリの About セクションにプロジェクトのウェブサイトとして追加できます。

クライアントアプリケーション

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 サーバーとクライアントが同時に実行されます。