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 — 比较两个模拟在某个级别的结果（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 状态码、 无法读取的响应或无法完成的请求——会以 isError 结果返回， 其文本以 racemodel error: 开头（此呈现方式是本次重建自行标注的复原内容）。

CLI

每个工具也可作为子命令使用，并接受一个 JSON 参数字符串（无参数的工具可省略）：

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。