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	契約の検索、公告の詳細、契約受注公告

このサーバーには含まれないもの：ビジネスインテリジェンスおよびアウトドア関連のデータセット（別サービスまたは提供終了）、ウェブページの取得（独自の取得機能とキャッシュを備えた別のパイプライン）。

すべてのツールで、利用者のキーを確認します。無料プランでは、サーバー全体で1日あたり30回まで呼び出せます。Pro は同じキーで無制限に利用できます。アップグレード先：https://mcpize.com/pubrecords-mcp

---

料金

プラン	料金	上限
Free	$0	1日あたり30回
Pro	$29/mo	無制限
従量課金	$0.03/call	従量制

キーはユーザーごとに発行されます。運営者にキーを問い合わせるか、運営者に 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 の公告1件
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.gov を呼び出すのは、SAM_API_KEY が設定されている場合のみです。設定されていない場合は {"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

MCP 以外の統合向けのシンプルな Python ラッパーは、pubrecords-sdk/ にあります。

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 は、そのキーの1日あたりの残りクォータを返します。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 のキーストアに保管してください。これらをコミットしないでください。