pubrecords

Halverson IQ Data

一个付费的 MCP 服务，涵盖美国公共记录、联邦拨款和联邦合同。 公司、SEC 文件、法院案卷、支出拨款、许可证、Grants.gov 项目机会和 SAM.gov 合同公告共用一个 API 密钥和一张账单。

---

此服务包含的内容

此代码库是整合后的 Halverson IQ Data 服务。

来源	工具
OpenCorporates、SEC EDGAR、CourtListener、USASpending、NPPES、FCC	公共记录工具（公司、文件、法院、支出、许可证、实体验证）
Grants.gov	拨款搜索、详情、机构汇总、截止日期提醒
SAM.gov	合同搜索、公告详情、授予公告

此服务不包含：商业情报和户外数据集（单独提供或已退役），以及网页抓取（由另一条拥有独立抓取器和缓存的管线处理）。

每次调用工具时都会检查一个客户密钥。免费套餐每天可在整个服务中调用 30 次。Pro 套餐使用同一密钥，不限调用次数。升级：https://mcpize.com/pubrecords-mcp

---

定价

套餐	价格	限额
免费	$0	每天 30 次调用
Pro	$29/月	不限调用次数
按量计费	$0.03/次调用	按使用量付费

密钥按用户签发。请向运营方索取密钥，或让他们通过 POST /admin/keys 创建密钥。以下示例使用占位符 YOUR_API_KEY。

---

工具参考

公共记录

工具	参数	返回内容
search_companies	name、state?、status?、limit?	OpenCorporates 实体
get_company_details	company_id、jurisdiction	高管、注册代理人、文件
search_sec_filings	company_name、form_type?、date_from?、limit?	EDGAR 文件列表
get_sec_filing	accession_number	文件元数据 + 索引 URL
search_court_cases	party_name、court?、date_from?、limit?	RECAP 联邦法院案卷
lookup_federal_spending	recipient_name、agency?、year?、limit?	USASpending 拨款
lookup_npi	name?、specialty?、state?、limit?	NPPES 提供者
get_ucc_filings	debtor_name、state	UCC 留置权（路线图项目——参见“数据缺口”）
verify_entity	name、state?	跨来源 0–100 置信度评分
search_licenses	entity_name、license_type?、state?	NPI + FCC 许可证合集

拨款和联邦合同

工具	参数	返回内容
search_grants	keyword?、agency?、amount_min?、amount_max?、status?、limit?	Grants.gov 项目机会
get_grant_details	opportunity_id	完整的 Grants.gov 记录
search_contracts	keyword?、naics_code?、agency?、set_aside?、limit?	SAM.gov 招标公告
get_contract_details	notice_id	一条 SAM.gov 公告
search_awards	recipient_name?、agency?、year?	SAM.gov 授予公告
get_agencies	type?（grants、contracts 或 both）	有开放项目机会的机构
get_deadlines	days_ahead?	时间窗口内即将截止的拨款项目
match_opportunities	org_description、org_type?、focus_areas?、limit?	与组织资料最匹配的拨款和合同

REST 路由中的 focus_areas 是逗号分隔的字符串。MCP 工具接受列表。

只有设置了 SAM_API_KEY，合同工具才会调用 SAM.gov。如果未设置，则会返回 {"success": false, "error": "SAM_API_KEY is not configured"}，且不会发送请求。

---

在 Claude 中安装

claude mcp add --transport http halverson-iq-data https://mcp-pubrecords-production.up.railway.app/mcp/

注意 /mcp/ 末尾的斜杠。 如果没有斜杠，网关会发出 307 响应并丢弃 POST 请求正文，导致 JSON-RPC 握手失败。

然后在客户端中设置 API 密钥：

X-API-Key: YOUR_API_KEY

---

Python SDK

pubrecords-sdk/ 中提供了一个轻量级 Python 封装，适用于非 MCP 集成：

pip install pubrecords

from pubrecords import PubRecords

client = PubRecords(api_key="YOUR_API_KEY")
print(client.health())
print(client.search_companies(name="Apple", state="CA"))
print(client.search_grants(keyword="broadband"))

---

REST 接口

每个 MCP 工具也可通过普通 HTTP 使用。每次调用都发送相同的 X-API-Key。

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://mcp-pubrecords-production.up.railway.app/tools/search_companies?name=Apple&state=CA"

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://mcp-pubrecords-production.up.railway.app/tools/search_grants?keyword=broadband"

生产环境 URL：https://mcp-pubrecords-production.up.railway.app

GET  /health                          (no auth)
GET  /usage                           (X-API-Key)
GET  /tools/<tool_name>?...           (X-API-Key)
POST /admin/keys                      (X-Admin-Token; fails closed)
POST /billing/upgrade                 (X-Admin-Token; fails closed)
POST /mcp/                            (MCP streamable-http transport)

GET /usage 返回该密钥剩余的每日配额。GET /health 无需身份验证。

签发客户密钥

除非已设置 PUBRECORDS_ADMIN_TOKEN 且 X-Admin-Token 请求头与之匹配，否则 POST /admin/keys 和 POST /billing/upgrade 会返回 403。没有默认管理员令牌。

curl -X POST https://mcp-pubrecords-production.up.railway.app/admin/keys \
  -H "X-Admin-Token: $PUBRECORDS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_API_KEY","tier":"free"}'

将同一个密钥升级为付费层级（这是唯一的计费开关）：

curl -X POST https://mcp-pubrecords-production.up.railway.app/billing/upgrade \
  -H "X-Admin-Token: $PUBRECORDS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_API_KEY"}'

---

本地开发

git clone https://github.com/bch1212/mcp-pubrecords.git
cd mcp-pubrecords
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn server:app --reload --port 8000

运行测试：

pytest -v

环境变量（参见 .env.example）：

变量	必需	用途
PUBRECORDS_ADMIN_TOKEN	签发或升级密钥时必需	管理员密钥。缺失或为空时将默认拒绝（403）。
SAM_API_KEY	使用合同工具时必需	你的 SAM.gov 密钥。切勿提交真实值。
PUBRECORDS_SEC_USER_AGENT	生产环境必需	用于 SEC EDGAR 的标识性 User-Agent。
OPENCORPORATES_TOKEN	否	提高 OpenCorporates 匿名访问上限。
COURTLISTENER_TOKEN	否	提高 CourtListener 匿名访问上限。
PUBRECORDS_CACHE_TTL	否	缓存 TTL（秒），默认值为 86400。
PUBRECORDS_DB_PATH	否	用于缓存和 API 密钥的 SQLite 文件。
PORT	否	监听端口。Railway 会设置此项。

---

数据新鲜度

默认情况下，响应会缓存 24 小时。

数据源	刷新频率
OpenCorporates	每日／每周（因司法管辖区而异）
SEC EDGAR	提交后数分钟内出现备案文件
USASpending.gov	每月更新，并回填财政年度数据
CourtListener (RECAP)	每日更新，具体取决于上传情况
NPPES NPI	每周
FCC License-View	每日
Grants.gov	机构更新时发布机会
SAM.gov	合同办公室发布时公布合同通知

如需获取更新鲜的数据，请设置 PUBRECORDS_CACHE_TTL=300（5 分钟）。这会增加上游流量。

---

数据缺口和来源限制

当查询超出覆盖范围时，服务会返回结构化错误封套，而不会编造数据行。

1. UCC 备案 — 没有统一的联邦 UCC API。在各州适配器就绪之前，get_ucc_filings 会返回 {"error": "not_implemented"}。
2. 州级专业执照 — 覆盖医疗保健（NPI）和 FCC。律师、房地产、承包商和 CPA 执照按州分别管理。
3. OpenCorporates 速率限制 — 匿名访问流量设有上限。生产环境请设置 OPENCORPORATES_TOKEN。
4. SEC EDGAR 全文检索 — 宽泛的关键词会返回大量结果。请结合 form_type 使用。
5. CourtListener — 覆盖联邦 PACER/RECAP。无法保证覆盖州法院。
6. SAM.gov — 只有在环境中设置了 SAM_API_KEY 后，合同工具才会运行。请通过 https://sam.gov 申请。此代码库中不包含该密钥。
7. SAM 获奖历史 — search_awards 从机会 API 读取 Award Notice 行。更深入的受款方汇总请使用 lookup_federal_spending（USASpending）。
8. 匹配分数 — match_opportunities 根据标题和机构进行确定性的词元重叠计算，不会调用模型。
9. 不包含消费者个人身份信息 — 仅提供实体级别的公共记录。

---

许可证与合规

此服务代理并缓存联邦和公共来源中已可免费访问的公共记录。缓存的载荷会保留 24 小时，也可通过删除 SQLite 文件清除。客户 API 密钥和管理员令牌应存储在环境变量及 SQLite 密钥存储中。切勿提交这些凭据。