racemodel

racemodel

racemodel は、米国の選挙区をモデリングするサービスである ElectionsMCP のホスト型 MCP サーバーへの、シンプルなローカルブリッジです。上流サービスでは、場所や候補者を特定し、シナリオを作成して、候補者の得票率や投票率の前提を設定し、スイングを適用したうえで、得票数、逆転した議席、地図、グラフ、選挙区ごとの集計として選挙区の結果を取得できます。予備選挙についても、個別に処理します。

このブリッジは選挙データを保持せず、独自の予測も行いません。ライブエンドポイントから取得したとおりの上流サーバーのツール一覧をローカルで提供し、各ツール呼び出しを上流に転送して、結果を変更せずに返します。シナリオとシミュレーションの状態は上流に保存されるため、シナリオの作成や得票率の設定といった書き込みは、サービス独自のモデリング処理であり、ほかの呼び出しと同様に転送されます。billing_status は読み取り専用です。利用可能な機能に、支払い、寄付、購入のツールはありません。

ツール

地理情報、候補者、選挙：

• resolve_geography — 地名または略称を正式な地理 ID に変換します（query、必須）。
• resolve_candidate — 人名から、議席の現職者または立候補者を検索します（name、必須）。
• search_candidates — 名前を指定せず、フィルターを使って候補者登録簿を検索します。
• lookup_address — 住所（address、必須）を地理情報に変換します。
• list_contests — 地理情報に対応する選挙を一覧表示します（geo_id、必須）。
• election_calendar — 選挙日程を取得します。必須の引数はありません。

シナリオとシミュレーション：

• create_scenario — 新しいシナリオを開始します（name、必須）。
• list_scenarios、get_scenario（scenario_id）、commit_version（scenario_id）、diff_versions（scenario_id、version_a、version_b）— 保存済みシナリオのバージョンを管理、比較します。
• set_performance — シナリオ内の地理情報に対する得票率を設定します（scenario_id、geo_id、shares）。
• target_precincts — シナリオの選挙区をターゲットに設定します（scenario_id、必須）。
• set_candidates — シミュレーションの候補者リストを設定します（simulation_id、level、candidates）。
• set_turnout — 投票率の想定値を設定します（simulation_id、必須）。
• set_race_scope — シミュレーションの選挙範囲を設定します（simulation_id、必須）。
• list_simulations と get_simulation（simulation_id、必須）— シミュレーションを列挙して読み取ります。
• share_simulation — シミュレーションを共有します（simulation_id、必須）。

ビュー、変動、集計：

• get_view、render_view、set_view — シミュレーションのビューを読み取り、描画、または設定します（いずれもsimulation_idを指定します）。
• render_chart — チャートを描画します（type、必須）。
• add_map_comment（simulation_id、body）とlist_map_comments（simulation_id）— シミュレーションの地図に注釈を付け、注釈を読み取ります。
• apply_uniform_swing — 全体に一律の変動をパーセントポイントで適用します（simulation_id、level、swing_pp）。
• apply_swing_to_query — クエリで範囲を指定して変動を適用します（simulation_id、state、filter）。
• get_tally — 指定したレベルの集計結果を取得します（simulation_id、level）。
• list_flipped — 指定したレベルで議席を奪取した候補者を一覧表示します（simulation_id、level）。
• compare_simulations — 指定したレベルで2つのシミュレーションを比較します（simulation_id_a、simulation_id_b、level）。
• roll_up_race — シミュレーションを選挙全体のレベルに集計します（simulation_id、必須）。

投票率、開票結果、参照データ：

• get_early_voting_turnout — 州の期日前投票率を取得します（state、必須）。
• get_county_voter_turnout_and_registration、get_state_historical_turnout、get_live_early_vote_returns、get_precinct_election_returns — 投票率、登録情報、過去のデータ、開票結果を取得します。必須の引数はありません。
• get_county_officials とget_county_economic_and_wealth_profile — 郡の参照プロファイルを取得します。必須の引数はありません。
• billing_status とconnection_status — アカウントと接続の状態を取得します。必須の引数はありません。
• get_campaign_onboarding、help、get_catalog — オンボーディング情報、ヘルプ、カタログを取得します。必須の引数はありません。

予備選挙：

• list_primary_calendar — 政党の予備選挙日程を取得します（party、必須）。
• set_primary_shares — 予備選挙の得票率を設定します（simulation_id、party）。
• roll_up_primary — 予備選挙の結果を集計します（simulation_id、party）。
• primary_batch_edit — 予備選挙を一括編集します（simulation_id、edits）。

メタ：

• call_tool — 上流を通じて、名前で別のツールを呼び出します（name、必須）。

設定

• ELECTIONSMCP_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://www.electionsmcp.com/mcp です。（この上書きフックは、この再構築版独自の明示的な再現です。）
• ELECTIONSMCP_API_KEY（任意）— 設定すると、その値はこのリモートに対してレジストリレコードで指定されているヘッダー名 x-electionsmcp-key で、すべての上流リクエストに送信されます。未設定の場合、認証ヘッダーは送信されません。（この転送は明示的な再現です。元のキャプチャにはキーがありませんでした。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーミング可能な HTTP セッションを開始します。JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、 clientInfo name racemodel）、続いて notifications/initialized 通知を送り、その後、呼び出し元の引数を 変更せずに含む tools/call リクエストを送信します。上流が initialize に Mcp-Session-Id ヘッダーを付けて応答した場合、その値は セッション内の以降のすべてのリクエストに付与され、プロセスの稼働中は セッションが再利用されます。応答は通常の JSON またはサーバー送信イベントとして 届く場合があり、どちらも読み取られます。

上流からの成功結果は、上流が設定した isError フラグを含め、 そのまま渡されます。JSON-RPC エラー、2xx 以外のステータス、 読み取り不能な応答、または完了できないリクエストなどの失敗は、 テキストが racemodel error: で始まる isError 結果として返されます （この表示方法は、この再構築版独自の明示的な再現です）。

CLI

各ツールは、JSON 引数文字列を 1 つ受け取るサブコマンドとしても利用できます （引数を取らないツールでは省略します）。

npx @reneturcios/racemodel resolve_geography '{"query":"CA-03"}'
npx @reneturcios/racemodel create_scenario '{"name":"Baseline 2026"}'
npx @reneturcios/racemodel get_catalog
npx @reneturcios/racemodel --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法の誤りの場合は 2 です。

MCP サーバー

npx -y @reneturcios/racemodel mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "racemodel": {
      "command": "npx",
      "args": ["-y", "@reneturcios/racemodel", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/racemodel
docker run --rm ghcr.io/cloudcorprecords/racemodel --version

コンテナのデフォルトコマンドは mcp なので、最初の形式は stdio MCP サーバーとして動作し、それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化された JSON-RPC 上流に対して実行されます。実際のネットワーク呼び出しはありません。

ライセンス

MIT — LICENSE を参照してください。