Congress.gov API MCP Server

Congress.gov API MCP サーバー

これは、ハイブリッド方式を使用して公式の Congress.gov API（v3）へのアクセスを提供する Model Context Protocol（MCP）サーバーです。

• MCP リソース： 標準化された URI を使用して、主要な立法関連エンティティ（法案、議員、議会、委員会、一般情報）を直接検索します。
• MCP ツール： コレクション全体の検索（congress_search）や、関連データのリスト取得（congress_getSubResource）など、より複雑な操作を行います。

このサーバーはブリッジとして機能し、MCP クライアント（AI アシスタントや開発ツールなど）が米国の立法データを簡単に検索、活用できるようにします。

プロジェクト構成

• /src：すべてのソースコードが含まれています。
  • /config：構成管理（ConfigurationManager.ts）。
  • /services：Congress.gov API との通信を行うコアロジック（CongressApiService.ts、RateLimitService.ts）。
  • /tools：MCP ツールの定義（search/、subresource/、index.ts）。
  • /types：TypeScript インターフェースと Zod スキーマ。
  • /utils：共有ユーティリティ関数（ログ、エラーなど）。
  • resourceHandlers.ts：主要エンティティのリソースリクエストを処理するロジック。
  • createServer.ts：サーバーインスタンスの作成、リソースとツールの登録。
  • server.ts：アプリケーションのメインエントリーポイント。
• /dist：コンパイル済み JavaScript の出力先（npm run build で生成）。
• /docs：プロジェクトドキュメント（PRD、機能仕様、RFC）。
• package.json：プロジェクトのメタデータと依存関係。
• tsconfig.json：TypeScript コンパイラーのオプション。
• .eslintrc.json、.prettierrc.json：Lint とフォーマットのルール。
• .env：（コミット対象外）CONGRESS_GOV_API_KEY の保存先。

はじめに

1. 依存関係をインストールします：

   npm install
   

2. API キーを設定します： プロジェクトのルートに .env ファイルを作成し、Congress.gov API キーを追加します。

   CONGRESS_GOV_API_KEY=YOUR_API_KEY_HERE
   

   （https://api.data.gov/signup/ からキーを取得してください）

3. サーバーをビルドします：

   npm run build
   

4. サーバーを実行します：

   npm start
   

   （node dist/server.js を実行します）

または、npm run dev を使用して開発モードで実行します（ts-node と nodemon を使用）。

MCP クライアントでの使用方法

実行中のサーバーに MCP クライアントを接続します（ローカルで実行する場合は、stdio 経由など）。

リソースへのアクセス

適切な URI を指定して、access_mcp_resource コマンド／メソッドを使用します。

例：

• 第117議会の法案 H.R. 3076 を取得する：

  <access_mcp_resource>
  <server_name>congress-server</server_name>
  <uri>congress-gov://bill/117/hr/3076</uri>
  </access_mcp_resource>
  

• 議員 Pelosi を取得する：

  <access_mcp_resource>
  <server_name>congress-server</server_name>
  <uri>congress-gov://member/P000197</uri>
  </access_mcp_resource>
  

• 第118議会の情報を取得する：

  <access_mcp_resource>
  <server_name>congress-server</server_name>
  <uri>congress-gov://congress/118</uri>
  </access_mcp_resource>
  

• API の概要を取得する：

  <access_mcp_resource>
  <server_name>congress-server</server_name>
  <uri>congress-gov://info/overview</uri>
  </access_mcp_resource>
  

ツールの使用

use_mcp_tool コマンド／メソッドを使用します。

!!! 重要なツールのワークフロー：エンティティの検索と関連データの取得 !!!

よくある多くのタスクでは、両方のツールを使った必須の2段階プロセスが必要です。

1. ステップ1：congress_search を使ってエンティティ ID を検索します

   • 目的： 必要な特定の法案、議員、委員会などを特定し、一意の識別子（例：memberId、または法案 URI 用の congress、billType、billNumber）を取得します。

   • ツール： congress_search

   • 例： 議員「John Kennedy」を検索します（選択が必要な複数の結果が返される場合があります）。

     <use_mcp_tool>
       <server_name>congress-server</server_name>
       <tool_name>congress_search</tool_name>
       <arguments>
         {
           "collection": "member",
           "query": "John Kennedy"
         }
       </arguments>
     </use_mcp_tool>
     

   • 出力： 結果から memberId（例：K000393）またはその他の必要な識別子を探します。

   • !!! 警告 !!! 検索結果に複数の候補が含まれる場合があります。次の手順では、必ず該当するエンティティを特定し、その固有の ID を使用してください。

   • !!! API の制限 !!! filters パラメーターを使用して一般的な検索を congress で絞り込むことは、基盤となる API ではサポートされていません（例：/v3/bill や /v3/member）。指定しても無視されます。通常、議会ごとの絞り込みには特定の API パス（例：/v3/bill/117）を使用する必要がありますが、このツールではそのパスを構築しません。

2. ステップ 2：congress_getSubResource を使用して関連データを取得する

   • 目的： ステップ 1 で見つけた識別子を使用して parentUri を構築し、関連する詳細情報（議事、提案者、本文など）を取得します。

   • ツール： congress_getSubResource

   • 前提条件： ステップ 1 で正しい parentUri（例：congress-gov://member/K000393）を取得している必要があります。

   • 例： メンバー K000393 が提案した法案を取得します。

     <use_mcp_tool>
       <server_name>congress-server</server_name>
       <tool_name>congress_getSubResource</tool_name>
       <arguments>
         {
           "parentUri": "congress-gov://member/K000393",
           "subResource": "sponsored-legislation",
           "limit": 5
         }
       </arguments>
     </use_mcp_tool>
     

   • !!! エラーが確実に発生する場合の警告 !!! parentUri の種類に対して厳密に有効な subResource 文字列を使用する必要があります（例：メンバーには 'sponsored-legislation'、法案には 'actions'）。無効な組み合わせを指定すると、必ずエラーになります。有効な組み合わせについては、ツールの説明を確認してください。

関連情報を確実に取得するには、この 2 ステップの手順に従うことが不可欠です。

ツールの使用例：

• 「climate」を含む法案を検索（上限 5 件）：

  <use_mcp_tool>
  <server_name>congress-server</server_name>
  <tool_name>congress_search</tool_name>
  <arguments>
  {
    "collection": "bill",
    "query": "climate",
    "limit": 5
  }
  </arguments>
  </use_mcp_tool>
  

• メンバーを一覧表示（ここでは議会による絞り込みはできません）：

  • 注：前述のとおり、congress_search で congress を直接指定して絞り込むことは、「member」コレクションでは API によってサポートされていません。

    <use_mcp_tool>
    <server_name>congress-server</server_name>
    <tool_name>congress_search</tool_name>
    <arguments>
    {
      "collection": "member",
      "limit": 10 
      // 必要に応じて "query" や "type" などのフィルターを追加します
    }
    </arguments>
    </use_mcp_tool>
    

• 法案 H.R. 3076（第 117 議会）の議事を取得（検索結果または既知の情報から URI を取得する必要があります）：

  <use_mcp_tool>
  <server_name>congress-server</server_name>
  <tool_name>congress_getSubResource</tool_name>
  <arguments>
  {
    "parentUri": "congress-gov://bill/117/hr/3076",
    "subResource": "actions",
    "limit": 10
  }
  </arguments>
  </use_mcp_tool>
  

• メンバー P000197 が提案した法案を取得：

  <use_mcp_tool>
  <server_name>congress-server</server_name>
  <tool_name>congress_getSubResource</tool_name>
  <arguments>
  {
    "parentUri": "congress-gov://member/P000197",
    "subResource": "sponsored-legislation",
    "limit": 5
  }
  </arguments>
  </use_mcp_tool>
  

リントとフォーマット

• リント： npm run lint
• フォーマット： npm run format

コミット時に、Husky と lint-staged によってコードが自動的にリントおよびフォーマットされます。