MCP Census Server

🚀 MCP 人口普查サーバー

強力なモデルコンテキストプロトコル（MCP）サーバーで、HTTP 上の JSON - RPC を通じて米国国勢調査局のデータにアクセスできます。

✨ 主な機能

• JSON - RPC 2.0（単一およびバッチリクエスト）をサポート
• Pydantic モデルを使用したリクエスト/レスポンスの検証
• 国勢調査 API レスポンスのキャッシュ（有効期限：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
   # .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/ を使用して、X - API - Key: <SERVER_API_KEY> ヘッダー付きで 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 リポジトリで、設定 > Pages に移動します。
2. ソース で、メインブランチ と /docs フォルダを選択します。
3. 保存 をクリックします。

ドキュメントは以下の URL で利用可能になります。 https://.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 サーバーとクライアントが並行して実行されます。