openstates-mcp-server

---

概要

Open States が提供する米国州議会の情報：全米50州、DC、米国の5つの準州に対応しています。法案、議員、委員会、イベントを検索し、任意の場所を代表する議員を確認できます。

ツール

ツール	説明
openstates_search_bills	全対象の米国管轄区域を対象に、全文検索、管轄区域／会期による絞り込み、主題タグ、提出者の検索を使って州議会法案を検索します
openstates_get_bill	OCD ID または3要素のパス（管轄区域＋会期＋bill_id）を指定して、特定の法案の詳細を取得します
openstates_search_people	管轄区域内の州議会議員や公職者を、名前、議院、選挙区で検索するか、OCD person ID を指定して特定の人物を取得します
openstates_get_legislators_by_location	地理座標（緯度／経度）を代表するすべての議員（州議会議員および連邦議会代表団）を検索します
openstates_search_committees	管轄区域の委員会を一覧表示します（実験的機能 — すべての州のデータが網羅されているわけではありません）
openstates_get_committee	OCD 組織 ID を指定して委員会の詳細を取得します。任意で委員名簿も取得できます
openstates_search_events	公聴会、本会議、委員会の会議を検索します（実験的機能）
openstates_get_event	議題、参加者、メディアリンクを含むイベントの詳細を取得します
openstates_list_jurisdictions	Open States が対象とする56の管轄区域（50州、DC、米国領土5か所）を、会期識別子と対象データのメタデータとともに一覧表示します
openstates_get_jurisdiction	特定の管轄区域について、すべての立法会期とその識別子を含むメタデータを取得します

リソース

リソース	説明
openstates://jurisdiction/{jurisdiction_id}	現在の会期、対象期間、法案／人物データの更新日時などの管轄区域メタデータ

すべてのリソースデータはツールからも取得できます。プログラムから管轄区域を検索する場合は openstates_get_jurisdiction を使用してください。リソースは、安定した参照資料として管轄区域のコンテキストを注入するのに便利です。

プロンプト

プロンプト	説明
openstates_bill_research	州法案を分析するための構造化されたフレームワークです。概要、提出者、委員会への付託、審議の経過、投票記録、関連法案を扱います
openstates_legislator_profile	議員のプロフィールを調査するためのフレームワークです。提出法案、委員会の所属、投票記録、連絡先を扱います

機能リファレンス

openstates_search_bills _tool

• スキーマ上、jurisdiction または q のいずれかが必須です。q のみの検索では56の管轄区域すべてが対象となり、一般的な検索語では上流のタイムアウト時間を超えるため、両方を指定する方法が確実です
• フィルター：session、chamber（upper／lower）、classification、subject タグ、sponsor、sponsor_classification、ISO 8601形式の日付フィルター action_since／updated_since／created_since
• include を指定すると、提出情報、アクション、投票、概要、バージョン、文書、関連法案がインラインで含まれます。これにより、後続の openstates_get_bill の呼び出しを避けられます
• sort のデフォルトは updated_desc です。sort=latest_action_desc を指定すると、現在審議中の法案が上位に表示されます。ページあたり最大20件（デフォルトは10件）までページネーションできます
• 結果がない場合の通知では、適用されたすべてのフィルターが表示され、認識されない管轄区域は名称で示されます

---

openstates_get_bill _tool

• openstates_id（検索結果に含まれるため推奨）または3要素のパス jurisdiction + session + bill_id で検索します。どちらも指定せずに呼び出すと missing_lookup_params エラーになります
• 議会で使われる形式の法案識別子（例：HB 1000、SB 42）を受け付けます
• include を指定すると、提出情報、アクション、投票、バージョン、文書、概要、その他のタイトル／識別子、関連法案がインラインで含まれます
• ID またはパスから対象が見つからない場合は not_found が返されます

---

openstates_search_people _tool

• jurisdiction または id（OCD の人物 ID）のいずれかが必須です。名前のみの検索でも、管轄を指定しない検索は上流のタイムアウト時間を超過します
• id には、法案の提案者や委員会のメンバーシップから返される任意の数の OCD 人物 ID を指定し、1 回の呼び出しで解決できます。併せて jurisdiction を指定する必要はありません
• org_classification：upper／lower／executive／legislature（上下両院を統合し、行政府の役職者を除外します）。省略すると、行政府の役職者を含むすべての役職者が返されます
• 大文字と小文字を区別しない部分一致の name 検索と、district に対応しています。include で offices、links、other_names、other_identifiers、sources を追加できます
• すべての結果で政党が報告されますが、政党による絞り込みはできません
• 1 ページあたり最大 20 件までページネーションできます

---

openstates_get_legislators_by_location _tool

• 10 進度の latitude／longitude を指定します。住所のジオコーディングには対応していません
• 1 回の呼び出しで両方の政府階層を返します。州議会議員に加え、その座標に対応する米国上院議員 2 名と米国下院議員 1 名が含まれます
• 階層の判別には jurisdiction.classification（state と country）を使用します。current_role.org_classification は、米国上院議員も州上院議員と同じく upper となるため、判別には使えません
• stateCount／federalCount の付加フィールドで階層ごとの件数を報告します
• 範囲外の座標は invalid_coordinate エラーとなります。対象範囲のデータがない場所では、結果が空である旨の通知が返されます

---

openstates_search_committees _tool

• jurisdiction は必須です。全州を対象とするリクエストはスキーマで拒否されます
• classification（committee／subcommittee）と chamber で絞り込みます。parent を指定すると、1 つの委員会の小委員会に絞り込めます
• include=memberships を指定すると、メンバーの役割を含む完全な名簿が返されます
• 試験運用中です。Open States は委員会のサポート復旧に取り組んでおり、すべての州のデータがそろっているわけではありません。出力の coverageNote フィールドには、常にこの点が記載されます
• 1 ページあたり最大 20 件までページネーションできます

---

openstates_get_committee _tool

• OCD の committee_id（openstates_search_committees から取得）でデータを取得します
• include=memberships を指定すると名簿が返されます。include=links／sources を指定すると参照 URL が追加されます
• 試験運用中です。委員会データがない州もあります。ID が存在しない場合は not_found になります

---

openstates_search_events _tool

• jurisdiction は必須です。イベントエンドポイントでは全州を対象にした検索はできません
• after／before で ISO 8601 の日付範囲を指定します。require_bills=true を指定すると、議題に法案が含まれるイベントに絞り込まれます
• include=agenda,participants を指定すると、会議の詳細情報がすべて返されます
• 試験運用中です。イベントデータを公開していない州が大半です。結果が空でも、イベントがないのではなく、データが提供されていない可能性があります
• 1 ページあたり最大 20 件までページネーションできます

---

openstates_get_event _tool

• OCD の event_id（openstates_search_events から取得）でデータを取得します
• include を指定すると、議題、参加者、リンク、メディア、文書が追加されます
• 試験運用中です。イベントのカバレッジは限定的です。ID が存在しない場合は not_found になります

---

openstates_list_jurisdictions _tool

• デフォルトの 1 回の呼び出しで、56 の管轄区域（50 州、DC、および米国の 5 つの準州）をすべて返します。上流の per_page 上限が 52 では全件を網羅できなくなったため、ページはサーバー側で統合されます
• classification フィルターのデフォルトは state です
• include=legislative_sessions を指定すると、過去および現在のすべての会期 ID が返されます。州によって形式（例：2025、2025-2026、2025rs、2025s1）が異なるため、会期で法案検索を絞り込む前にこの指定が必要です
• include=organizations／latest_runs を指定すると、議院・行政府機関の情報とスクレーパー実行メタデータが追加されます

---

openstates_get_jurisdiction _tool

• OCD-ID、州名、または 2 文字の略称で 1 つの管轄区域を取得します
• include=legislative_sessions を指定すると、日付範囲を含むすべての会期 ID が返されます
• 識別子を解決できない場合は not_found になります

---

openstates://jurisdiction/{jurisdiction_id} _リソース

• jurisdiction_id には OCD-ID、州名、または 2 文字の略称を指定できます
• 管轄区域のメタデータを application/json 形式で返します。現在の立法会期、対象期間、法案と議員の更新日時が含まれます
• 常に legislative_sessions が含まれます。ツールを呼び出さずに会期識別子を事前に取得するために使用してください
• 識別子を解決できない場合は not_found を返します

---

openstates_bill_research _{プロンプト}

• 引数：jurisdiction、session、bill_id。すべて必須です
• 概要、提案者、立法経緯、投票記録、関連法案、法案本文、可決可能性の評価を含む、構造化された調査概要を作成するよう指示するユーザーメッセージを 1 件返します

---

openstates_legislator_profile _{プロンプト}

• 引数：name、jurisdiction。どちらも必須です
• 身元・役職、提案した法案、委員会の所属、投票記録、概要を含む、構造化されたプロフィールを作成するよう指示するユーザーメッセージを 1 件返します

機能

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

Open States 固有の機能：

• Open States v3 API を全面的にカバー：法案、議員、委員会、イベント、管轄区域
• 法案および委員会の取得ツールで 2 種類の検索方法に対応（OCD ID または構造化パス）
• Open States の people-by-geo エンドポイントを使用した地理情報ベースの議員検索。州と連邦の両方の階層に対応
• サーバーレベルの指示により、ツール呼び出し前に会期の検出ワークフローと include パラメーターの使い方をエージェントに提示
• キーごとのリクエスト予算（OPENSTATES_DAILY_REQUEST_BUDGET）と 2 段階のタイムアウト設定により、共有アップストリームキーを保護

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

• 空の結果からの復旧：検索ツールは適用したフィルターを表示し、結果がない場合は検索範囲を広げる方法を提案します
• 委員会およびイベントのツールに実験的な対象範囲の注記（coverageNote）を付加し、空の結果を黙って返すのではなく制限事項を明示します
• すべての検索・取得ツールで include パラメーターのパターンに対応し、一般的な調査ワークフローでの N+1 回の追加呼び出しを回避します

はじめに

公開ホストインスタンス

https://openstates.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。Streamable HTTP 経由で任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "openstates-mcp-server": {
      "type": "streamable-http",
      "url": "https://openstates.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

Open States API キーが必要です。open.pluralpolicy.com で無料登録してください。

以下を MCP クライアントの設定ファイルに追加してください。

{
  "mcpServers": {
    "openstates-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/openstates-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OPENSTATES_API_KEY": "your-api-key"
      }
    }
  }
}

または npx を使用する場合（Bun は不要です）：

{
  "mcpServers": {
    "openstates-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openstates-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OPENSTATES_API_KEY": "your-api-key"
      }
    }
  }
}

または Docker を使用する場合：

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

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

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

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• Open States API キー。open.pluralpolicy.com で無料登録してください。

インストール

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

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

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

cd openstates-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set OPENSTATES_API_KEY

設定

設定はすべて、src/config/server-config.ts の Zod スキーマによって起動時に検証されます。主な環境変数は次のとおりです。

変数	説明	デフォルト
OPENSTATES_API_KEY	必須。 open.pluralpolicy.com から取得する Open States API キーです。	—
OPENSTATES_API_BASE_URL	Open States API のベース URL です。	https://v3.openstates.org
OPENSTATES_DAILY_REQUEST_BUDGET	直近 24 時間における上流リクエストの最大数です。上限に達すると、リクエストが送信される前に呼び出しが拒否されるため、上限超過による上流側の費用は発生しません。デフォルト値は v3 の無料プランの日次上限に合わせています。API キーのプランでより多くのリクエストが許可されている場合は、値を増やしてください。	250
OPENSTATES_REQUEST_TIMEOUT_MS	上流への各試行に適用される期限（ミリ秒単位）です（最小値は 1000）。期限切れは再試行されないため、完了できないリクエストは 4 回ではなく 1 回分の待ち時間で済みます。Open States のスコープ指定クエリの応答時間は 1 秒未満から約 57 秒まで幅があり、Open States のゲートウェイは約 60 秒でタイムアウトします。早く失敗させるには値を小さくし、時間のかかるクエリを待つには大きくしてください。	45000
OPENSTATES_TOTAL_REQUEST_BUDGET_MS	再試行の全試行とその間のバックオフを含む、1 回の呼び出しに対する実時間の上限（ミリ秒単位）です。各試行の期限は単一のリクエストを制限し、この値は一連の試行全体を制限します。そのため、再試行可能な失敗を繰り返す遅い上流によって、呼び出しが再試行シーケンス全体にわたって保留されることを防ぎます。OPENSTATES_REQUEST_TIMEOUT_MS 以上である必要があります。それより小さい値を設定すると、各試行の期限が適用される前にすべての試行が中断されるため、起動時に拒否されます。デフォルト値は期限の 2 倍なので、期限の直前に失敗した試行の後でも、ほぼ 1 回分の期限を使って再試行できます。	90000
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_SESSION_MODE	HTTP セッションモードです。auto、stateful、または stateless を指定します。src/index.ts は createApp({ sessionMode }) で stateless を宣言しています。呼び出し元からの入力待ちで中断するツールがないため、セッション状態は不要です。この設定を指定すると、その宣言が上書きされます。フレームワークのスキーマのデフォルトは auto で、これは stateful に解決されます。	stateless
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP エンドポイントのパスです。	/mcp
MCP_PUBLIC_URL	TLS を終端するリバースプロキシ環境で使用する、公開オリジンの上書き値です。	なし
MCP_AUTH_MODE	認証モードです。none、jwt、または oauth を指定します。	none
MCP_LOG_LEVEL	ログレベルです（debug、info、notice、warning、error）。	info
MCP_GC_PRESSURE_INTERVAL_MS	オプトインで有効にする Bun 専用の強制 GC 間隔（ミリ秒単位）です。HTTP 負荷が継続している間にヒープが増加する場合は、60000 を試してください。	0（無効）
LOGS_DIR	ログファイルの保存ディレクトリです（Node.js のみ）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンドです。in-memory、filesystem、supabase、cloudflare-kv/r2/d1 を指定します。	in-memory
OTEL_ENABLED	OpenTelemetry の計装を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP のベース URL です。トレースは /v1/traces に、メトリクスは /v1/metrics に送信されます。	なし
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	オプトインで有効にする OTLP ログエクスポート先です（例：http://localhost:4318/v1/logs）。ベースエンドポイントを設定しても、ログエクスポートは有効になりません。	なし
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果を、キー名のみに基づいて秘匿化し、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）を上限としてログに記録します。	false

任意の上書き設定の一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

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

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

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

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t openstates-mcp-server .
docker run --rm -e OPENSTATES_API_KEY=your-key -e MCP_TRANSPORT_TYPE=http -p 3010:3010 openstates-mcp-server

Dockerfile はデフォルトで HTTP トランスポートを使用し、MCP_SESSION_MODE=stateless を明示的に設定して、/var/log/openstates-mcp-server にログを記録します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツール、リソース、プロンプトを登録し、Open States サービスを初期化します。
src/config	サーバー固有の環境変数を Zod で解析・検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）です。法案、人物、委員会、イベント、管轄区域に関する 10 個のツールがあります。
src/mcp-server/resources	リソース定義です。管轄区域のメタデータリソースがあります。
src/mcp-server/prompts	プロンプト定義です。法案調査と議員プロフィールのプロンプトがあります。
src/services/openstates	Open States API v3 のサービスレイヤーです。HTTP クライアント、リクエスト処理、ドメイン型を扱います。
tests/	src/ に対応する単体テストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークがキャッチします。ツールのロジック内で try/catch は使いません。
• リクエスト単位のログには ctx.log、テナント単位のストレージには ctx.state を使います。
• 新しいツールとリソースは、src/index.ts の配列から登録します。
• 外部 API の呼び出しは、未加工データを検証し、ドメイン型に正規化してから出力スキーマに沿って返します。不足しているフィールドを捏造してはいけません。

貢献

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

bun run devcheck
bun run test

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。