us-lobbying-mcp-server

---

概要

上院の LDA API による米国連邦政府のロビー活動開示情報と、司法省の FARA 記録による外国代理人登録情報を扱います。届出を検索し、クライアントとの関係を特定し、ロビイストや献金の開示情報を調査し、必要に応じてローカル SQL で報告金額を分析できます。API キーは不要です。

ツール

ツール	説明
uslobbying_search_filings	登録届出と活動報告を検索し、原本と修正届出を保持します
uslobbying_get_client_profile	クライアントとの関係を特定し、明示的に選択した ID と年を分析します
uslobbying_get_issue_spending	特定の問題に言及する四半期届出の報告金額を分析します
uslobbying_search_lobbyists	ロビイストを検索し、届出ごとの活動と対象職位の根拠情報を取得します
uslobbying_get_contributions	LD-203 報告書を、完全な献金一覧、PAC 開示情報、証明とともに取得します
uslobbying_search_foreign_agents	FARA スナップショットを検索するか、登録の選択したライブ詳細コレクションを取得します
uslobbying_list_reference	公式コード、識別子、方法論、情報源の制約を確認します
uslobbying_dataframe_query	読み取り専用 SQL クエリの結果を実体化し、すべての行をページ分割して取得します
uslobbying_dataframe_describe	ステージングされたテーブルのスキーマ、件数、ライフサイクル、出所を調べます
uslobbying_dataframe_drop	ステージングされたテーブルを削除します。オプトイン

機能リファレンス

uslobbying_search_filings _ツール

• 上流フィルターを少なくとも1つ指定してください：filing_year（1999～現在のUTC年）、client_id、registrant_id、lobbyist_id、client_name、registrant_name、filing_type、filing_period、またはいspecific_issues。任意のissue_codeはローカルで適用され、上流へのリクエストを絞り込むことはできません。
• amendment_policy: "all_versions"を指定した完全なfilings、個別のNULL許容USD小数文字列であるincome／expenses、文書リンク、ネストされた開示情報を返します。共通の取得ルールとレコードウィンドウのルールはFeaturesに記載されています。

---

uslobbying_get_client_profile _ツール

• mode: "resolve"（デフォルト）ではclient_nameが必要です。mode: "profile"では明示的なclient_idsとyears（1999～現在のUTC年）が必要です。IDは登録者との関係を識別するもので、候補が企業としての同一性に自動的に統合されることはありません。
• 取得が完了するまでは、プロファイルはstatus: "collecting"を返します。完了後は、出力ウィンドウ全体にわたる型付きのannual_ledgers、selections、firms、issue_codes、targeted_entities、selected_filings、activities、raw_filingsを返します。row_set_totals／row_set_offsetsは各リストの配信状況を示します。
• CANVAS_PROVIDER_TYPE=duckdbの場合、分析の完了時に、取得したすべての申告書、選択された申告書、選択された活動を含むdatasetも返します。任意のcanvas_idを指定すると既存のキャンバスを再利用できます。トークンの有効期限が切れている場合はcanvas_not_foundエラーになります。

---

uslobbying_get_issue_spending _ツール

• issue_codeと明示的なyearsが必要です。任意のclient_id／registrant_idを指定すると、上流での取得対象を絞り込めます。すべてのバージョンを取得してから、最新期間の選択とローカルでの課題フィルタリングを行います。広範囲のスキャンには数時間かかる場合があります。
• プロファイルモードと同じ、取得中／最終分析用リストおよび任意のdatasetを返します。attribution_basis: "whole_filing_mentions_issue"も返します。申告書全体の金額は課題別の区分間で重複し、課題別の支出額に割り当てられるものではありません。

---

uslobbying_search_lobbyists _ツール

• mode: "search"（デフォルト）ではname、registrant_name、またはregistrant_idが必要です。mode: "activity"ではlobbyist_idとfiling_yearが必要で、任意でclient_idとcovered_positions_onlyを指定できます。
• ロビイストの身元情報を示すlobbyists、または申告書単位のevidenceを返します。これには、一致した参加者、完全な活動情報、元のインデックス、申告書のUUID／文書が含まれます。対象職位は開示されたテキストであり、現在の雇用状況が確認済みであることを示すものではありません。

---

uslobbying_get_contributions _ツール

• filing_year（2008～現在のUTC年）が必要です。任意でfiling_period（mid_year／year_end）、登録者／ロビイストのセレクター、contribution_type、contributor、payee、honoree、および両端を含むcontribution_date_after／contribution_date_beforeを指定できます。
• 親レコードである完全なreports、完全なcontribution_items、すべての子レコードの条件が同じ項目に一致した場合のmatched_item_indexesを返します。原本と修正版は別々に保持されます。report_count_in_batchとitem_count_in_batchは寄付総額を示すものではありません。

---

uslobbying_search_foreign_agents _ツール

• mode: "search"（デフォルト）では日次XMLスナップショットを検索します。entity: "registrants"（デフォルト）または"foreign_principals"を選択し、任意で文字列どおりのトークンAND検索を行うname_containsを指定できます。countryの完全一致ラベルを指定できるのは外国関係者のみです。statusはactive（デフォルト）、terminated、またはallです。外国関係者のステータスは登録者のステータスとは独立しています。
• mode: "detail"では数字のみの文字列であるregistration_numberが必要で、選択したライブコレクションのみを取得します。選択肢はforeign_principals（デフォルト）、short_forms、またはdocumentsです。文書を取得するにはstatus: "all"が必要です（文書の場合、実質的なデフォルト値です）。コレクションが空であっても、その登録が一度も存在しなかった証拠にはなりません。
• page_sizeの範囲は1～25（デフォルトは25）で、固定された結果に対するローカルウィンドウを制御します。next_cursorを使って次のページに進んでください。レスポンスには、該当する場合、ソースフィールド、公式リンク、スナップショットの取得メタデータが保持されます。

---

uslobbying_list_reference _ツール

• topicには、issue_codes、filing_types、government_entities、contribution_types、countries、identifiers、methodology、fara_rulesのいずれかを指定します。省略可能なfilterでは、大文字と小文字を区別せず、トークンがすべて一致するものをリテラル検索します。
• 帰属情報付きのentries、total_entries、matched_entriesを返します。最大125件の固定ウィンドウにはnext_cursorを、サイズ超過のエントリにはrecord_handlesを使用して続きを取得します。国については、LDAコードとFARAラベルがそれぞれ個別の帰属情報付きで保持され、推測によるISOマッピングは行われません。

---

uslobbying_dataframe_query _ツール

• canvas_idに加え、sqlで読み取り専用のSELECT文を1つ（任意で新しいregister_asを指定）実行するか、任意でoffsetを指定して保存済みのresult_tableを指定する必要があります。row_limitは1～100で、デフォルトは25です。フレームワークの設定またはレスポンスのバイト数上限により、これより小さくなる場合があります。
• 新しいSQLでは、結果全体がマテリアライズされます。続きを取得するにはresult_table／next_offsetを使用します。row_countは正確な行数を示し、row_order: "canonical_values"は返却順序を示します。書き込み、複数のステートメント、外部データの読み取り、禁止されているプラン演算子は、型付きの理由とともに失敗します。
• 1行が上限内に収まらない場合、マテリアライズされた結果は保持されたままquery_row_too_largeで失敗します。列を減らすか、明示的なSUBSTRウィンドウを指定してください。テーブルが存在しないか期限切れの場合はmissing_tableで失敗します。有効なキャンバスがない場合、SQLは利用できません。

---

uslobbying_dataframe_describe _ツール

• 返されたcanvas_idが必要です。任意のtable_nameを指定すると、対象のテーブルを選択できます。SQLを実行する前に、信頼できる列と型を確認してください。
• 該当する場合、正確な行数、粒度、作成日時／有効期限、ソースツール、取得の来歴、マテリアライズに使用したSQLを返します。他のキャンバスは列挙しません。

---

uslobbying_dataframe_drop _ツール

• canvas_idとtable_nameが必要です。べき等であり、テーブルが存在しない場合はdropped: falseを返します。
• USLOBBYING_DATAFRAME_DROP_ENABLED=trueでない場合は無効で、tools/listにも表示されません。これはローカルにステージングされたデータのみを削除します。

特徴

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、切り替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを提供します。

LDA/FARA 固有の機能：

• ソースごとのリクエスト間隔を共有します。匿名の LDA アクセスは送信元 IP あたり毎分 15 リクエストで、オプションの登録済みトークンでは毎分 120 リクエストです。FARA リクエストは少なくとも 4.1 秒間隔で開始されます。別々のプロセス間では、上流の共有リクエスト枠を調整する必要があります。
• 分析上の選定では、登録者／クライアント／年／四半期ごとに最新の提出を使用します。最新の提出が同じ候補には曖昧フラグを付け、合計から除外します。これは分析上のルールであり、法的な修正履歴を検証したものではありません。
• 収入と支出は分けて扱い、金額が欠けている場合は不明のままとし、支出方法ごとに個別の台帳を維持します。開示記録は、不正行為、政策上の成果、影響力のいずれも立証するものではありません。
• FARA 検索では、公式の完全な日次 XML スナップショットを 24 時間キャッシュします。選択した登録の詳細にはライブ API を使用します。LDA のページネーションはライブであり、変更されない過去のスナップショットを保証するものではありません。

エージェントに適した出力：

• 完了状態を明示します。LDA の page_size は 1～25（デフォルトは 25）、max_pages は 1～5（検出時はデフォルトで 1、分析時は 5）です。取得の coverage.complete に達するまで next_cursor をたどり、その後 output_complete になるまで最後のウィンドウを続けてください。record_handles には引き続き取得が必要な場合があります。継続時にはフィルターを省略するか、変更せずに再指定できます。
• レコードを完全に取得できます。両方の出力面で、応答サイズは UTF-8 で 24,000 バイトを目標とします。サイズ超過した親レコードには、同じツールで record_handle、JSON Pointer の record_path、record_offset / record_limit（オブジェクトのエントリーまたは配列の項目を 1～25 件、デフォルトは 25）を指定して引き続きアクセスできます。文字列のウィンドウはバイト数に上限のある断片を使用し、オフセットは Unicode コードポイント単位です。子パスと next_offset をたどって値を再構成してください。
• 進行状況を復元できます。継続情報と保持された親レコードは、取得開始から 24 時間後に有効期限が切れます。直前のカーソルでは応答が再生されますが、それより古いカーソルや期限切れのカーソルは cursor_invalid エラーになります。インメモリの再起動では進行状況が失われます。明示的なファイルシステムストレージでは、有効期限まで公開レコードとチェックポイントが保持されます。広範囲のスキャンでは、デフォルトの 128 MiB の取得予算を使い切ったり、有効期間を超えたりする可能性があるため、対象を年／クライアント／登録者に絞ってください。
• 応答面の内容は一致します。structuredContent と content[] 内の JSON テキストには同じフィールドが含まれ、クリック可能なソースリンクも付いています。オプションの分析用 dataset 応答では正確なテーブル名が示され、describe/query ツールへ案内されます。SQL は、インラインで提供される完全な分析結果の代わりにはなりません。

はじめに

MCP クライアントの設定ファイルに以下を追加します。

{
  "mcpServers": {
    "us-lobbying-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/us-lobbying-mcp-server@latest"],
      "env": { "MCP_TRANSPORT_TYPE": "stdio" }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "us-lobbying-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/us-lobbying-mcp-server@latest"],
      "env": { "MCP_TRANSPORT_TYPE": "stdio" }
    }
  }
}

または Docker を使用します。

{
  "mcpServers": {
    "us-lobbying-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/us-lobbying-mcp-server:latest"]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以降）。
• 匿名アクセスにアカウントやキーは不要です。オプションの登録済み LDA トークンは、USLOBBYING_LDA_API_KEY として設定できます。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/us-lobbying-mcp-server.git

2. ディレクトリに移動します：

cd us-lobbying-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env for optional overrides

設定

変数	説明	デフォルト
USLOBBYING_LDA_API_KEY	認証済みリクエストの許可枠に使用する、任意の登録済み LDA トークンです。	—
USLOBBYING_DATAFRAME_DROP_ENABLED	ローカルのステージ済みテーブルを削除する uslobbying_dataframe_drop を公開します。	false
CANVAS_PROVIDER_TYPE	none または duckdb です。npm/Docker インストールではローカル SQL を有効にできます。MCPB では none に固定され、完全なインライン配信が維持されます。	none
STORAGE_PROVIDER_TYPE	取得チェックポイントのストレージです。filesystem を選択すると、公開記録を永続的に保持できます。	in-memory
STORAGE_FILESYSTEM_PATH	ファイルシステムストレージを選択する場合に指定する、書き込み可能なディレクトリです。チェックポイントは取得開始から24時間後に期限切れになります。	—
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_HOST	HTTP のバインドアドレスです。Docker のデフォルトは 0.0.0.0 です。	127.0.0.1
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_HTTP_ENDPOINT_PATH	MCP エンドポイントのパスです。	/mcp
MCP_AUTH_MODE	認証方式です。none、jwt、または oauth を指定します。	none
MCP_LOG_LEVEL	ログレベルです（debug、info、warning、error など）。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗したツールの引数と結果をログに記録します。キー名による編集が行われ、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で上限が設定されます。自由形式のシークレットは編集されません。	false
OTEL_ENABLED	OpenTelemetry インストルメンテーションを有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースとメトリクス用の OTLP ベース URL です。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	任意で指定する OTLP ログエクスポートのエンドポイントです。	—

任意のオーバーライドの全一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行する：

  bun run rebuild
  bun run start:http   # or start:stdio
  

• チェックとテストを実行する：

  bun run devcheck     # Lints, formats, type-checks
  bun run test         # Runs test suite
  

Docker

docker build -t us-lobbying-mcp-server .
docker run -p 3010:3010 us-lobbying-mcp-server

イメージはデフォルトでポート3010の HTTP を使用します。-e CANVAS_PROVIDER_TYPE=duckdb で SQL を有効にしてください。取得ロックとペーシングはプロセス内で管理されるため、ストレージ／上流の予算ごとにサーバープロセスを1つ使用してください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイント、ツールの直接登録、サービス／キャンバスのライフサイクルです。
src/config	サーバー環境の検証と、ツール共通のタイムアウトです。
src/domain	検証済み開示記録、来歴、配信契約、損失のないフォーマット処理です。
src/mcp-server/tools/definitions	LDA、FARA、参照、データフレームのツールです。
src/services/lda	ペーシングの共有と検証済みページネーションを備えた、ホスト固定の LDA クライアントです。
src/services/fara	日次 XML スナップショットと、登録ごとの詳細を取得するライブコレクションです。
src/services/acquisition	再開可能な取得、リプレイ、ストレージ受け入れ、保持記録の期間管理です。
src/services/lobbying	四半期ごとのバージョン選択、正確な会計、提出書類固有の証拠です。
src/services/canvas	分析テーブル全体のステージングと、安定した SQL 結果の配信です。
scripts	ビルド、開発チェック、パッケージ化、リリース用ツールです。
tests	ソース構成に対応した単体テストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md と AGENTS.md を参照してください。要点は以下のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch は使用しません。
• ログには ctx.log を、ストレージには ctx.state を使用します。
• src/index.ts の createApp() 配列にツールを直接登録します。
• 上流の完全なレコードを検証し、疎なフィールドや未知のフィールドを保持します。また、収入、支出、関係 ID、取得／出力の完了状態はそれぞれ区別して扱います。

貢献

課題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。