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 _工具

• 至少提供一个上游筛选条件：filing_year（1999 年至当前 UTC 年）、client_id、registrant_id、lobbyist_id、client_name、registrant_name、filing_type、filing_period 或 specific_issues。可选的 issue_code 在本地应用，不能缩小上游请求范围。
• 返回完整的 filings，其中 amendment_policy: "all_versions"，包含分别可空的 USD 十进制字符串 income / expenses、文档链接和嵌套披露信息。通用的数据获取和记录窗口规则见 Features。

---

uslobbying_get_client_profile _工具

• mode: "resolve"（默认）需要 client_name；mode: "profile" 需要明确提供 client_ids 和 years（1999 年至当前 UTC 年）。ID 用于标识与注册人的关系；候选对象不会自动合并为同一企业身份。
• 数据获取完成前，Profile 会返回 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；令牌过期时会返回错误 canvas_not_found。

---

uslobbying_get_issue_spending _工具

• 需要 issue_code 和明确提供的 years；可选的 client_id / registrant_id 用于缩小上游数据获取范围。会先获取所有版本，再筛选最新期间并在本地按议题过滤；大范围扫描可能需要数小时。
• 返回与 Profile 模式相同的 collecting / 最终分析列表和可选的 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，并且仅对外国委托人接受精确的国家标签。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 会按不区分大小写的字面词元执行 AND 匹配。
• 返回带有归属信息的 entries、total_entries 和 matched_entries；使用 next_cursor 获取最多包含 125 条目的固定窗口，或使用 record_handles 获取超大条目。国家会分别保留带有归属信息的 LDA 代码和 FARA 标签，不会猜测 ISO 映射。

---

uslobbying_dataframe_query _工具

• 需要 canvas_id，并且需要在 sql 中提供一条只读 SELECT（可选填写新的 register_as），或提供一个已存储的 result_table（可选填写 offset）。row_limit 范围为 1–100，默认值为 25；框架配置或响应字节预算可能会调低该值。
• 新 SQL 会物化完整结果。使用 result_table / next_offset 继续获取；row_count 是精确值，row_order: "canonical_values" 表示交付顺序。写入、多条语句、外部读取以及禁止的计划运算符都会因指定原因而失败。
• 无法容纳的行会导致 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 分页为实时查询，不保证提供不可变的历史快照。

便于 Agent 使用的输出：

• 明确的完成状态：LDA 的 page_size 为 1–25（默认 25）；max_pages 为 1–5（发现时默认为 1，分析时默认为 5）。持续跟进 next_cursor，直到获取状态 coverage.complete，然后继续获取最终窗口，直到 output_complete；仍可能需要通过 record_handles 获取记录。续传时可以省略筛选条件，也可以原样重复。
• 完整记录检索：两个接口返回的数据目标均为 24,000 UTF-8 字节。过大的父记录仍可通过同一工具访问，使用 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 响应会列出确切的表，并指向描述/查询工具；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

镜像默认通过 HTTP 在端口 3010 上运行。使用 -e CANVAS_PROVIDER_TYPE=duckdb 启用 SQL；每个存储/上游额度使用一个服务进程，因为获取锁和请求节流都是进程级的。

项目结构

目录	用途
src/index.ts	createApp() 入口、直接注册工具、服务/Canvas 生命周期管理。
src/config	服务环境验证和共享的工具截止时间。
src/domain	经过验证的披露记录、来源信息、交付约定和无损格式化。
src/mcp-server/tools/definitions	LDA、FARA、参考资料和 dataframe 工具。
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 文件。