EDGAR + Entity: US Company Research

edgar-entity-mcp

ソース：https://github.com/pgeneralpl/edgar-entity-mcp · 課題：https://github.com/pgeneralpl/edgar-entity-mcp/issues · npm：https://www.npmjs.com/package/edgar-entity-mcp · MCP レジストリ：io.github.pgeneralpl/edgar-entity-mcp

公式公開データを活用した、AI エージェント向けの米国企業調査ツールです。 SEC EDGAR（提出書類、XBRL 財務データ、Form 4 のインサイダー取引、企業間比較）と、州務長官の事業体登録簿（NY、CO、OR、CT、PA）を網羅する MCP サーバーです。レスポンスはソース URL を含む簡潔な JSON で、トークン使用量を抑えられるよう設計されています。

• アナリスト：「TSLA、F、GM の CY2023 の売上高を比較して」「今月、Apple のインサイダーは何を売却した？」「最新の 10-K のリスク要因を要約して」
• 創業者／営業／デューデリジェンス担当者：「Acme Widgets LLC はコロラド州で有効な事業体ですか？ 登録代理人は誰ですか？」
• 研究者：テキスト形式の整理された 10-K／10-Q のセクション、各指標に使用された XBRL タグを明記した正規化済み財務時系列データ。

データの利用に API キーは不要です。SEC では、User-Agent で利用者を明示する必要があります（SEC の User-Agent を参照）。

npx -y edgar-entity-mcp        # stdio MCP server

---

ツール

ツール	内容	ソース
search_company	ティッカー／名称から CIK の候補を検索し、あいまい検索で順位付けします（株式クラスは統合されます）	company_tickers_exchange.json
get_company_profile	名称、ティッカー、取引所、SIC と業種、設立州、会計年度末、EIN、住所、旧社名、最新の 10-K／10-Q	data.sec.gov/submissions
list_filings	フォームの種類と日付範囲で提出書類を検索します。アクセス番号、日付、主要文書とインデックスの URL を含みます。必要に応じて過去の履歴ページも読み込みます	data.sec.gov/submissions
get_filing_document	主要文書を読みやすいテキストに変換します（表は行形式で保持）。10-K／10-Q の項目抽出（1、1A、7、7A、8…）に対応し、max_chars／offset でページ分割できます	www.sec.gov/Archives
get_financials	正規化済みの売上高、売上総利益、営業利益、純利益、EPS（基本／希薄化後）、資産、負債、純資産、現金、長期債務、営業キャッシュフロー、設備投資、FCF、発行済み株式数を取得します。年次または四半期、会計期間ごとに重複を除去し、使用したタグを報告します	XBRL companyfacts
get_xbrl_concept	1 社について、任意の XBRL コンセプト／単位の全履歴を取得します	XBRL companyconcept
compare_companies	暦年期間について、すべての提出企業を対象に 1 つのコンセプトを比較します（順位付け、またはティッカーで絞り込み）	XBRL frames
get_insider_trades	Form 4／4A を解析します：報告者、役職、コードとその平易な意味、株数、価格、金額、A／D、取引後の保有数、デリバティブの詳細、買い／売りの概要	Form 4 XML
lookup_business_entity	名称または事業体 ID で州務長官の登録簿を検索し、ステータス、種類、設立日、管轄区域、住所、登録代理人を正規化して表示します	州のオープンデータ（Socrata）：NY／CO／OR／CT／PA
list_supported_states	州ごとの対象範囲、データセット ID、更新頻度、ライセンス	—

さらに、ワークフロー全体を実行する company_research_brief プロンプトと、ライセンス情報を含む edgar-entity://data-sources リソースも利用できます。

すべてのツールで、company にはティッカー（AAPL）、CIK（320193）、または曖昧さのない社名を指定します。エラーは {"error":{"code","message","hint"}} として返され、isError: true が設定されます。名称が曖昧な場合は、候補となる CIK が返されます。

呼び出し例と実際の出力（ライブデータ、一部抜粋）

get_financials {"company":"AAPL","limit":1}

{"cik":"0000320193","name":"Apple Inc.","period_type":"annual","currency":"USD",
 "periods":[{"fy":2025,"fp":"FY","period_end":"2025-09-27","period_start":"2024-09-29","form":"10-K","filed":"2025-10-31",
   "accession":"0000320193-25-000079","revenue":416161000000,"gross_profit":195201000000,"operating_income":133050000000,
   "net_income":112010000000,"eps_basic":7.49,"eps_diluted":7.46,"operating_cash_flow":111482000000,"capex":12715000000,
   "total_assets":359241000000,"total_liabilities":285508000000,"stockholders_equity":73733000000,"cash":35934000000,
   "long_term_debt":78328000000,"shares_outstanding":14776353000,"free_cash_flow":98767000000}],
 "tags_used":{"revenue":["us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax"],"net_income":["us-gaap:NetIncomeLoss"],"...":[]},
 "source_url":"https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json"}

period_type:"quarterly" は3か月分の値を返します。10-Qのキャッシュフロー項目は年初来の値であるため、四半期の値は差分から算出し、Q4はFYから9Mを差し引いて算出します。たとえば、MSFTのFY25 Q4の売上高は76.441Bドルとなり、報告された数値と一致します。算出された値はそれぞれ notes に記載されています。

get_insider_trades {"company":"TSLA","limit":5}

{"cik":"0001318605","name":"Tesla, Inc.","filings_returned":5,
 "summary":{"open_market_buys":{"count":0,"shares":0,"value":0},"open_market_sales":{"count":19,"shares":34620.25,"value":13321733}},
 "code_legend":{"F":"Shares withheld to pay exercise price or taxes","M":"Exercise or conversion of derivative (exempt)","S":"Open market or private sale"},
 "filings":[{"form":"4","filed":"2026-09-09","accession":"0001104659-26-106432","reporter":"Taneja Vaibhav","roles":"Officer",
   "officer_title":"Chief Financial Officer","transactions":[
     {"security":"Common Stock","date":"2026-09-08","code":"S","shares":2605.75,"price":360.134,"value":938419.17,
      "acquired_disposed":"D","shares_owned_after":25972.25,"ownership":"D"}],
   "url":"https://www.sec.gov/Archives/edgar/data/1318605/000110465926106432/tm2625055d1_4seq1.xml"}],"has_more":true}

get_filing_document {"url":"https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm","section":"1A","max_chars":3000}

{"url":"…/aapl-20250927.htm","kind":"html","section":{"id":"1A","title":"Risk Factors"},"total_chars":68118,"offset":0,"next_offset":3000,
 "text":"Item 1A.  Risk Factors\nThe following summarizes factors that could have a material adverse effect on the Company’s business…"}

compare_companies {"tag":"Revenues","period":"CY2023","companies":["TSLA","F","GM"]}

{"concept":"us-gaap:Revenues","unit":"USD","period":"CY2023","companies_reporting":2679,"results":[
 {"rank":12,"cik":"0000037996","name":"Ford Motor Co","val":176191000000,"end":"2023-12-31"},
 {"rank":13,"cik":"0001467858","name":"GENERAL MOTORS COMPANY","val":171842000000,"end":"2023-12-31"},
 {"rank":23,"cik":"0001318605","name":"Tesla, Inc.","val":96773000000,"end":"2023-12-31"}],
 "source_url":"https://data.sec.gov/api/xbrl/frames/us-gaap/Revenues/USD/CY2023.json"}

貸借対照表（時点）の概念には、I サフィックスが必要です。例：{"tag":"Assets","period":"CY2024Q4I"}

lookup_business_entity {"name":"Newmont Corporation","states":["CO"]}

{"results":[{"state":"CO","entity_id":"20021056790","name":"Newmont Corporation","status":"Good Standing",
  "type":"Foreign Profit Corporation (FPC)","formed":"2002-03-08","jurisdiction":"DE",
  "principal_address":"6900 East Layton Ave, Suite 700, Denver, CO, 80237, US",
  "registered_agent":{"name":"CORPORATION SERVICE COMPANY","address":"1900 W Littleton Blvd, Littleton, CO, 80120"},
  "details_url":"https://www.coloradosos.gov/biz/BusinessEntityDetail.do?masterFileId=20021056790",
  "source_url":"https://data.colorado.gov/resource/4ykn-tg5h.json?entityid=20021056790"}],
 "by_state":{"CO":{"count":1,"query_url":"…"}}}

その他の簡単な例：

• search_company {"query":"berkshire"} → BERKSHIRE HATHAWAY INC、CIK 0001067983、ティッカー BRK-B, BRK-A
• list_filings {"company":"AAPL","forms":["10-K"],"date_to":"2010-12-31","limit":2} → 古い履歴ページから取得した2010年の10-Kと10-K/A
• get_xbrl_concept {"company":"TSLA","tag":"ResearchAndDevelopmentExpense","forms":["10-K"],"framed_only":true}
• lookup_business_entity {"entity_id":"0783036","states":["CT"]} → THE TRAVELERS COMPANIES, INC.（有効、外国法人、MN）

---

インストール

接続方法は3つあります。ホスト型エンドポイント https://edgar-entity-mcp.vercel.app/mcp（インストール不要。下記の リモート を参照）、stdio経由のnpmパッケージ edgar-entity-mcp（Node.js ≥ 22.23.4 または ≥ 24.22.1）、または公式のMCP Registryのエントリー io.github.pgeneralpl/edgar-entity-mcp からインストールするクライアントを利用できます。

簡単な確認：npx -y edgar-entity-mcp --version

Node.jsのバージョン（stdioユーザー向け）： パッチ適用済みのNode.jsでパッケージを実行してください — 22.23.4以上（22.x）または24.22.1以上（24.x、推奨）、あるいは26.12.1以上です。これらのリリース（2026-10-21）では、fetch() でデコードされた悪意あるサーバー応答によって引き起こされる可能性のある、Brotliデコーダーの範囲外書き込みCVE-2026-111497と、TLSホスト名検証のバイパスが修正されています。Node.js 20はサポート終了となっており、この修正は提供されません。node -v で確認してください。パッチ未適用のNode.jsで起動すると、サーバーはstderrに警告を出力します。ホスト型エンドポイントは、Vercelが管理するNode.js 24.xランタイム上で動作し、Vercel自身がパッチを適用します。engines.node は 24.x（Vercelランタイムを固定するため）なので、npmは22.xで EBADENGINE の通知を表示します — 22.23.4以上であれば想定どおりで、問題ありません。

Claude Desktop / Claude Code / Cursor / Windsurf / VS Code（npx経由のstdio）

{
  "mcpServers": {
    "edgar-entity": {
      "command": "npx",
      "args": ["-y", "edgar-entity-mcp"],
      "env": { "SEC_USER_AGENT": "Your Name or Company [email protected]" }
    }
  }
}

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）。
• Cursor：~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）。
• Claude Code：claude mcp add edgar-entity -e SEC_USER_AGENT="Your Name [email protected]" -- npx -y edgar-entity-mcp
• VS Code："mcpServers" の代わりに "servers" を使う .vscode/mcp.json。

リモート（Streamable HTTP）

ホスト型エンドポイント（無料、キー不要）：https://edgar-entity-mcp.vercel.app/mcp · ヘルスチェック：https://edgar-entity-mcp.vercel.app/health。ホスト型インスタンスは、共有キャッシュ用のUpstash Redis、全インスタンス共通のSEC予算6 req/s、クライアントごとのクォータを使用します（ホスト型クォータを参照）。

{ "mcpServers": { "edgar-entity": { "url": "https://edgar-entity-mcp.vercel.app/mcp" } } }

stdioのみをサポートするクライアントの場合："command": "npx", "args": ["-y", "mcp-remote", "https://edgar-entity-mcp.vercel.app/mcp"]。APIキーを使う場合は、Authorization: Bearer <key> または x-api-key: <key> を送信します（mcp-remoteの場合：--header "Authorization: Bearer <key>"）。

HTTP サーバーをセルフホストする

npm run build && PORT=3000 SEC_USER_AGENT="Acme [email protected]" npm run start:http   # → http://127.0.0.1:3000/mcp

node サーバーはデフォルトで 127.0.0.1 にバインドされ、Host が localhost のリクエスト（DNS リバインディング対策）と、Origin が指定されている場合はそれがローカルのリクエストにのみ応答します。公開するには、HOST=0.0.0.0、ALLOWED_HOSTS=mcp.example.com、必要に応じて ALLOWED_ORIGINS を設定してください。TRUST_PROXY=1 を設定するのは、リバースプロキシが X-Forwarded-For／X-Real-IP を設定する場合に限ります。

Vercel にデプロイする

リポジトリにはすでに api/mcp.ts と api/health.ts（mcp-handler を基盤とする Web 標準ハンドラーを備えた Vercel Functions）、および vercel.json が含まれています。vercel.json は npm run build を実行し、/mcp を /api/mcp に、/health を /api/health に書き換えます。npm run smoke:remote -- https://<project>.vercel.app/mcp を実行すると、デプロイ先に対してライブチェックを行えます。

1. vercel link を実行し、続けて vercel env add SEC_USER_AGENT を実行します（さらに HEALTH_SECRET、IP_HASH_SALT、必要に応じて SOCRATA_APP_TOKEN／MCP_API_KEYS も設定します）。
2. Upstash Redis インテグレーションの追加を強くおすすめします。追加すると、キャッシュ、SEC／state のレート制限枠、クライアントごとのクォータがフリート全体で共有されます。追加しない場合は、インスタンスごとになります。Upstash コンソールでエビクション（allkeys-lru）と使用量アラートを有効にしてください。
3. vercel deploy --prod を実行します。クライアントの接続先を https://<project>.vercel.app/mcp に設定してください。

---

環境変数

変数	デフォルト	用途
SEC_USER_AGENT	–（必須）	独自の "<Name or Company> <email>"（例："Acme Research [email protected]"）を設定してください。未設定またはプレースホルダーの場合、SEC ツールは実行を拒否します（CONFIG_ERROR）。州の登記ツールは引き続き利用できます。
SEC_MAX_RPS	6（最大 8）	SEC リクエストの秒間数。プロセス単位で適用され、Redis を設定している場合はフリート全体にも適用されます
SOCRATA_MAX_RPS	5	州ポータルへのリクエストの秒間数（同じ 2 段階のリミッター）
DISTRIBUTED_RATE_LIMIT	1	0 にすると Redis トークンバケットを無効にします（プロセス単位の制限のみ）
SOCRATA_APP_TOKEN	–	州ポータル用のアプリトークン（より高いスロットリング上限を利用可能。各ポータルの開発者設定から無料で取得できます）
UPSTASH_REDIS_REST_URL / UPSTASH_REDIS_REST_TOKEN	–	Redis を有効にします（Vercel の KV_REST_API_URL / KV_REST_API_TOKEN も使用できます）。設定しない場合、キャッシュとクォータはメモリ内に保持されます。
QUOTA_ANON_PER_MINUTE / QUOTA_ANON_PER_DAY	30 / 60	匿名クライアント向けの HTTP クォータ。ハッシュ化された IP ごとの単位数（毎分の上限はインスタンスごとにメモリ内で適用されます）
QUOTA_ANON_NETWORK_PER_DAY	グローバル上限（60）の 10%	アドレスローテーション対策として、1 つの /24（IPv6 /48）内のすべての匿名クライアントに適用される共有日次上限。QUOTA_ANON_GLOBAL_PER_DAY の 10% を超えることはありません
QUOTA_ANON_GLOBAL_PER_DAY / QUOTA_ANON_GLOBAL_HARD_PER_DAY / QUOTA_ANON_TRICKLE_PER_DAY	600 / 900 / 10	すべての匿名クライアント全体に適用されるソフト日次上限。超過後も各 IP にはハード上限まで少量の利用枠が与えられます。API キーを使う呼び出しには影響しません。
QUOTA_KEY_PER_MINUTE / QUOTA_KEY_PER_DAY	120 / 500	API キーごとの HTTP クォータ（scripts/create-key.ts でキーごとに上書き可能）
SEC_KEYED_RESERVED_RPS	2	SEC_MAX_RPS のうち、API キーを使う呼び出し向けに確保される分（匿名トラフィックは残りを共有します）
MAX_CONCURRENT_UPSTREAM_PER_CLIENT	4	クライアント（ハッシュ化された IP またはキー）ごとの同時上流フェッチ数。超過分は待機し、その後 RATE_LIMITED になります
DEGRADED_SEC_RPS	0.2（最大 2）	Redis が利用できない、またはプラン上限を超えた場合の、API キーを使う呼び出しに対するインスタンスごとの SEC レート。0 は SEC 呼び出しを拒否します。この状態では匿名の呼び出しはキャッシュのみを利用できます。
MCP_API_KEYS	–	カンマ区切りの静的キー（Redis に保存されたハッシュ化キーと併せて受け付けます）
MCP_REQUIRE_API_KEY	–	1 にすると、匿名の HTTP 呼び出しを 401 で拒否します（0.1.x では MCP_API_KEYS が設定されている場合、常にキーが必要でした）
KEY_REQUEST_URL	GitHub issue のリンク	無料キーの申請先として、RATE_LIMITED のヒントに表示されます
IP_HASH_SALT	–（Redis 使用時は必須）	IP ハッシュ用のシークレット（32 文字以上のランダムな文字列。例：openssl rand -hex 32）。実際に使用されるソルトは HMAC-SHA256(IP_HASH_SALT, UTC date) であり、毎日ローテーションされます。Redis を設定している状態でこの値が未設定、古いデフォルト値の edgar-entity-mcp、または 32 文字未満の場合、サーバーは起動を拒否します（node：終了コード 1、Vercel：すべてのリクエストが 503 となり、/health は misconfigured を返します）。
API_KEY_SECRET	–（Redis 使用時は必須）	API キー（eem_<id>_<HMAC>）への署名に使うシークレット（32 文字以上のランダムな文字列で、IP_HASH_SALT とは異なるもの）。ローテーションすると、発行済みのすべてのキーがただちに無効になります。Redis がない場合、発行済みキーは無効になります。
REVOKED_KEY_IDS	–	ただちにすべてのインスタンスで拒否する、カンマ区切りのキー ID（または完全なキー）。Redis がなくても使用でき、縮退モード中の緊急失効にも使えます
HEALTH_SECRET	–	x-health-secret: <value> を送信するリクエストに対し、Redis の ping を行う /health?deep=1 を有効にします
SUPPRESSION_FILE	–	抑制エントリの JSON 配列（プライバシーを参照）
MAX_BODY_BYTES / MAX_DOCUMENT_BYTES	65536 / 15 MB	HTTP リクエスト本文の上限 / 提出書類の最大サイズ
USAGE_LOG	–	1 にすると、呼び出しごとの使用状況 JSON（ツール、レイテンシー、成功可否、レスポンスサイズ、ハッシュ化された主体）を stderr に記録します
MEMORY_CACHE_MB / REDIS_MAX_VALUE_BYTES / HTTP_TIMEOUT_MS	128 / 900000 / 25000	チューニング
HOST / ALLOWED_HOSTS / ALLOWED_ORIGINS / TRUST_PROXY	127.0.0.1 / – / – / –	セルフホストの node サーバーのみ

ホスト型サービスのクォータと API キー

ホスト型エンドポイントでは、各ツール呼び出しに、発生する可能性のある上流リクエスト数の概算を示す単位が課金されます。

ツール	単位
list_supported_states	0
search_company、get_company_profile、get_xbrl_concept	1
list_filings	1（日付フィルターまたはオフセットを指定した場合は6。この場合、過去のファイルを最大4件までページングすることがあります）
get_financials	2
compare_companies	3
get_filing_document	url で4、company + accession で10
get_insider_trades	6 + limit（ファイルは最大20件のため、最大26）
lookup_business_entity	州の数（最大5）

クライアント	1分あたり	1日あたり（UTC）
匿名（IPごと、IPv6は/64ごと）	30（インスタンスごと）	60
1つのネットワーク内のすべての匿名クライアント（IPv4 /24、IPv6 /48）	–	60（全体上限の10%）
すべての匿名クライアントの合計	–	ソフト上限600。その後はIPごとに10、ハード上限は900
無料 API キー	120（インスタンスごと）	500

予約してから返金します。 上の表の値は、呼び出し前に予約される見積もりです。呼び出し後、サーバーは実際のコスト（実行した上流リクエストの数。最低1）を課金し、残りを返金します。キャッシュから応答した呼び出しのコストは1単位なので、安価なキャッシュ済み呼び出しで共有の匿名クォータを使い切ることはありません。返金分はローカルに保持され、次のカウンター更新に織り込まれるため、Redis コマンドを消費しません。

クォータ超過時の呼び出しは、retry_after_seconds、スコープ（minute、day、network、global）、上限、およびキーの取得方法を含む RATE_LIMITED ツールエラーを返します。npx -y edgar-entity-mcp を使ってローカルで実行する場合、クォータはありません。

上流予算の公平な配分：デフォルトでは、SEC_KEYED_RESERVED_RPS（SEC リクエスト6件/秒のうち2件）が API キー利用者用に予約され、各クライアントが同時に実行できる上流フェッチは最大 MAX_CONCURRENT_UPSTREAM_PER_CLIENT（4件）です。SEC トークンバケットは滑らかに補充されます（6 rps の場合、約167ミリ秒ごとにトークン1個、バーストは2）。

API キー

無料キーを取得するには、github.com/pgeneralpl/edgar-entity-mcp で Issue を作成してください。キーは eem_<12-char id>_<24-hex HMAC> の形式で、自己検証型です。サーバーは API_KEY_SECRET を使った HMAC をローカルで検証するため、ランダムなキーや偽造されたキーは Redis にアクセスすることなく拒否されます。また、10分間に無効なキーを10回を超えて送信したクライアントには HTTP 429 が返されます。有効なキーはその後、一度だけ照会され（eem:v1:apikey:<id>。削除とキーごとの上限を反映するため）、5分間記憶されます。

• 発行：npx tsx scripts/create-key.ts [--per-day N] [--per-minute N]。キーは一度だけ表示されます。レコードには作成日と任意の上限のみが保存されます。所有者名、メールアドレス、その他の連絡先情報は収集されません（キーのリクエストは Issue トラッカーに記録されます。後で必要になる可能性がある場合は、そこでキー ID をメモしてください）。
• 削除：npx tsx scripts/delete-key.ts <key-or-id> を実行すると、レコードとキーの稼働中のカウンターがすべて削除されます。実行中のインスタンスがそのキーを受け付けなくなるまで、最大5分かかります。Redis が利用できない場合も含め、すべての環境で直ちに無効化するには、ID を REVOKED_KEY_IDS に追加してください。API_KEY_SECRET をローテーションすると、すべてのキーが一度に無効になります。
• どちらのスクリプトにも、デプロイ環境の UPSTASH_REDIS_REST_*、IP_HASH_SALT、API_KEY_SECRET が必要です。
• lookup_business_entity の include_agent_details は、API キー利用者にのみ適用されます（プライバシーを参照してください）。

Upstash の無料プランに合わせる（上限に達した場合の動作）

Upstash では、Lua スクリプト内の各 redis.call も含め、すべてのコマンドが課金対象です。以下の件数は、tests/budget.test.ts のスクリプトを正確に再現するエミュレーターで計測した課金対象コマンド数です（REST から確認できる部分は scripts/live-upstash.ts で実際の Upstash を使って検証しています）。

イベント	課金対象コマンド数
クォータチェック、匿名、許可（EVALSHA + IP-day、/24-day、global-day に対する INCRBY）	4（その日に各カウンターを初めて作成する際はカウンターごとに EXPIRE が 1 件追加：最大 7）
クォータチェック、API キー、許可（EVALSHA + INCRBY）	2（その日の初回呼び出しでは 1 件追加）
この呼び出しのコストをまかなう余裕が既知のカウンター（個別の日次、/24、グローバル）にないため拒否	0
スクリプト内で拒否（別のインスタンスによってカウンターが満杯になった場合）：匿名 7、キー 3（INCRBY + DECRBY によるロールバック）、その後 0	0
未使用の見積もり分を返金	0（次の INCRBY に統合）
1 分あたりの上限	0（メモリ内）
ランダムな API キー、偽造された API キー、または REVOKED_KEY_IDS 内のキー	0
MAC が有効なキーの初回使用（その後 5 分間メモ化）	1（GET）
SEC / state-portal リクエスト、フリートークンを取得（EVALSHA + HMGET + HSET + PEXPIRE）	上流へのリクエストごとに 4 件、予約済みバケットが空のキー認証済み呼び出し元の場合は 2 + 4 件
共有キャッシュ：L1（プロセスメモリ）ヒット / Redis ヒット / ミス + 保存	0 / 1 / 2
劣化モード中のすべての呼び出し	0
呼び出し全体：キャッシュが温まった search_company（プロセスキャッシュ）	4
呼び出し全体：SEC リクエストが 1 件のコールド呼び出し（クォータ 4、キャッシュの GET + SET が 2、SEC トークンが 4）	10（その日の初回呼び出しでは 13）

デフォルト設定での UTC 日あたりの最悪ケース：匿名トラフィックは 900 ユニットのハード上限に制限されます（呼び出しは ≤ 900 件、上流へのリクエストは約 ≤ 900 件）。コマンド数は約 900 × 4 + 900 × 6 ≈ 9K です。API キーごとに 1 日 500 ユニットを追加すると、最大約 4K 増えます。Upstash の無料枠（1 か月あたり約 500K コマンド、1 日あたり約 16K）は、匿名枠とアクティブなキー数個をカバーできます。プランに合わせて QUOTA_ANON_GLOBAL_PER_DAY と QUOTA_KEY_PER_DAY を設定してください。プランの上限に達しても、サーバーは失敗するのではなく、劣化モードに切り替わります。

劣化モード。 Redis がエラーになる、タイムアウトする、またはプラン上限（max requests limit）を報告した場合、インスタンスは 60 秒単位で次の動作に切り替わります。

• ローカルのインメモリクォータ（インスタンスごとに同じ日次上限）を使用します。
• 匿名の呼び出し元：キャッシュのみ — このインスタンスのメモリにすでにないものは、明確な RATE_LIMITED（scope: "degraded"）メッセージとともに拒否されます。
• API キーの呼び出し元： インスタンスごとに DEGRADED_SEC_RPS（0.2/秒）で SEC を利用します（0 = 拒否）。MAC が有効なキーは Redis による照会なしで受け入れますが、未検証として扱われるため、include_agent_details は利用できません。REVOKED_KEY_IDS 内のキーは引き続き拒否されます。
• インスタンスで抑制リストが一度も読み込まれていない場合、州のレジストリ検索は拒否されます。

/health は理由とともに status: "degraded" を返します。

HTTP エンドポイントには、ほかにも次の制限があります。リクエスト本文は 64 KB まで、JSON-RPC バッチには対応せず（1 リクエストにつき 1 メッセージ）、インサイダー呼び出しごとの Form 4 提出書類は最大 20 件、エンティティ検索ごとに州は 5 件まで、州ごとの結果は 25 件まで、提出書類は最大 15 MB です。

プライバシーと個人データ

• 登録代理人および送達受領代理人は、氏名の末尾に法人格を示す接尾辞（Inc、Corp、LLC、LLP、LP、Ltd、Company、「& Co」、Bank、N.A.、…）が付く場合、または既知の登録代理人サービス（CT Corporation、CSC、Cogency Global、…）である場合を除き、個人として扱われます。「JOHN CHURCH」「JUDE LAW」「DAVID CO」「JOHN SMITH PA」は個人です。CO／PA／PCで終わる曖昧な名称も個人として扱われます。
• 個人の代理人は { "kind": "individual", "withheld": true } として返されます。また、一人事業では自宅住所である場合が多いため、法人の主たる住所／郵送先住所（およびNY所在地名）も非表示になります（addresses_withheld: true）。include_agent_details: true を指定すると、APIキーを使用する呼び出し元（およびローカルのstdio利用）に限り、これらが表示されます。匿名のHTTP呼び出し元には、代わりにプライバシーに関する注記が返されます。組織の代理人は常に表示されます。
• 消去／異議申し立てのリクエストには、npx tsx scripts/suppress.ts add ...（Redisセット、10分以内に反映）、SUPPRESSION_FILE、または src/states/suppression-list.ts を使って entity:<STATE>:<id> または agent:<name> を追加します。法人IDは正規化されます（大文字・小文字、句読点、先頭のゼロ）。非表示対象の氏名は、代理人名と住所、および法人名、NY所在地名、主たる住所／郵送先住所の中から単語全体として照合されます。一致があれば、そのレコードの個人情報フィールドがすべて削除されます。法人名に一致した場合（「JANEDOE HOLDINGS LLC」のように、スペースを除いた形でも照合されます）、名称は [withheld] に置き換えられます。Redisが設定されているにもかかわらず、コールドインスタンスで非表示リストを読み込めない場合、リストなしでデータを返すのではなく、レジストリへのリクエストを行う前に州の情報検索が拒否されます。
• Form 4の報告対象所有者名は法令上の公開情報であり、get_insider_trades によって返されます。

ホスト型サーバーが保存するデータと保存期間

レート制限では、ハッシュ化された識別子をキーとして、Redis に整数カウンターのみを保存します。TTL は適用される期間と同じです。

Redis key	Value	TTL
eem:v1:q:d:ip:<hash>:<YYYYMMDD>	1 つの IP（IPv6：/64）による本日（UTC）の使用単位数	25 h（1 日＋1 h の猶予）
eem:v1:q:d:net:<hash>:<YYYYMMDD>	1 つの /24（IPv6：/48）の匿名クライアント全体による本日（UTC）の使用単位数	25 h
eem:v1:q:d:anon:<YYYYMMDD>	すべての匿名クライアントを合わせた本日（UTC）の使用単位数	25 h
eem:v1:q:d:key:<id>:<YYYYMMDD>	1 つの API キーによる本日（UTC）の使用単位数	25 h

• IP の <hash> は、HMAC-SHA256(daily salt, IP or prefix) を 80 ビットに切り詰めた値です。daily salt は HMAC-SHA256(IP_HASH_SALT, YYYYMMDD) です。日付が異なるハッシュ同士は関連付けられません。また、その日のカウンターが期限切れになると、その日の IP から導出された情報は残りません。リクエストは同じ UTC 日付でハッシュ化され、カウントされるため、午前 0 時をまたぐリクエストも一貫してカウントされます。IP ごとの分単位カウンターは午前 0 時にリセットされます。これはハッシュが変わるためで、その時点でクライアントが追加で利用できるクォータは、最大でも 1 分分です。
• キーの場合、<id> はキーの公開 ID です（シークレット部分が Redis に送られることはありません）。API キーのレコード（eem:v1:apikey:<id>）には作成日と、任意でキーごとの制限のみが保存されます。これは scripts/delete-key.ts で削除されるまで保持されます（キーのカウンターも削除されます）。抑制セット（eem:v1:suppress）には、消去リクエストのエントリが保存されます。
• Redis のどこにも保存されないもの：生の IP、ユーザーエージェント、リクエストパス、ツールの引数、ツールごとの利用履歴。公開 SEC データおよび州データの共有キャッシュエントリは、eem:v1:c:<sha256 of the upstream request> のキーで保存されるため、キー名から検索内容が分かることはありません。上流へのファンアウト予算（eem:rl:*）は、クライアントごとのデータを含まないグローバルなトークンバケットです。
• ログ：エラー（および USAGE_LOG=1 の場合は、ツール名、レイテンシ、結果、レスポンスサイズ、日ごとにローテーションするプリンシパルのハッシュを含む、呼び出しごとに 1 行のログ）が stderr に出力され、その後 Vercel のランタイムログに送られます。ログは Vercel のプランに定められた保持期間で期限切れになります（制限）。エラーテキストに含まれる URL のクエリ文字列、IP アドレス、メールアドレス、認証情報と思われる値はマスクされます。このサーバーがツールの引数、API キー、生の IP をログに記録することはありません。このコードの外部にある Vercel 独自のプラットフォームリクエストログには、Vercel の保持期間に従って、パスやクライアント IP などのリクエストメタデータが記録されます。
• 分単位の制限はプロセスメモリ内にのみ保持され（70 s）、Redis に書き込まれることはありません。
• /health は、この設定を quotas.state で報告します。

ホスト型デプロイを再開する前に必要な設定

デプロイの一時停止を解除する前に、Vercel プロジェクトの Production と Preview で、以下を設定してください。Redis が設定されている場合、IP_HASH_SALT と API_KEY_SECRET が有効になるまで、サーバーはリクエストを処理せず（HTTP 503、/health → misconfigured）、サービスを拒否します。

変数	値
SEC_USER_AGENT	"<Operator name> <contact email>"（SEC の公正利用ポリシー）
UPSTASH_REDIS_REST_URL + UPSTASH_REDIS_REST_TOKEN（または Vercel の KV_REST_API_URL + KV_REST_API_TOKEN）	Upstash データベース
IP_HASH_SALT	32 文字以上のランダムな文字列（openssl rand -hex 32）
API_KEY_SECRET	32 文字以上のランダムな文字列。IP_HASH_SALT とは異なるもの
HEALTH_SECRET	ランダムな値。/health?deep=1 を有効にします
SOCRATA_APP_TOKEN	州のポータルから取得した無料のアプリトークン（スロットリング制限が緩和されます）
KEY_REQUEST_URL	ユーザーが無料キーをリクエストする URL（デフォルト：GitHub の issue リンク）
DEGRADED_SEC_RPS	0.2（または Redis の停止中に SEC への呼び出しを完全に止める場合は 0）
MCP_REQUIRE_API_KEY	任意：匿名利用を無効にする場合は 1

あわせて、Upstash の使用量アラートを設定し、必要な場合を除き REVOKED_KEY_IDS は空にしておくことをおすすめします。キーの発行は、API_KEY_SECRET が確定してから行ってください（これをローテーションすると、発行済みのキーが無効になります）。

セキュリティに関する注意事項

• get_filing_document の提出書類のテキストは信頼できない、提出者が作成したコンテンツです。<<<BEGIN UNTRUSTED SEC FILING TEXT id=<nonce>>>> / <<<END UNTRUSTED SEC FILING TEXT id=<nonce>>>> マーカーで囲んで返されます。nonce はレスポンスごとにランダムに生成され、untrusted_marker_id にも同じ値が含まれるため、提出書類のテキストで終了マーカーを偽装することはできません。ゼロ幅文字、双方向制御文字、Unicode タグ文字（U+E0000–E007F）、異体字セレクター（U+FE00–FE0F、U+E0100–E01EF）は除去されます。その他のサードパーティのテキスト（企業名と住所、Form 4 の報告者名、備考と脚注、XBRL のラベルと説明）も同じ方法でクリーニングされ、各レスポンスの untrusted_fields に列挙されます。エージェントはこれらすべてを指示ではなく、データとして扱う必要があります。
• ドキュメント入力として受け付けるのは https://www.sec.gov/Archives/edgar/data/<CIK>/<accession>/<file> URL のみです。リダイレクトは手動でたどり、許可されたホストのリストと照合し直します。
• クライアントに返されるエラーメッセージは汎用的なものです。詳細は参照 ID とともにサーバーログに記録されます。

SEC の User-Agent とレート制限

SEC の公平なアクセスに関するポリシーでは、クライアントのリクエスト数は毎秒 10 件に制限され、User-Agent の申告が必須です。User-Agent を申告しないクライアントは SEC にブロックされる場合があります（HTTP 403「Undeclared Automated Tool」）。このサーバーは次のように動作します。

• SEC へのすべてのリクエストで SEC_USER_AGENT を送信します。
• 2 段階のリミッターでリクエスト間隔を調整します。プロセスごとの間隔制御に加え、Redis がある場合は、原子的な全インスタンス共通のトークンバケットを使用します（デフォルトは毎秒 6 件、そのうち 2 件は API キー利用者用に確保。滑らかに補充され、バースト数は 2）。約 5 秒以内にトークンが付与されない場合、呼び出しは RATE_LIMITED で失敗します。Redis が利用できない場合、またはプランの上限を超えた場合は、匿名利用者にはキャッシュからのみ応答し、API キー利用者には縮退モードでインスタンスごとに毎秒 0.2 件のレートを適用します。
• 429/5xx は指数バックオフで再試行し、Retry-After に従います。
• 同一の処理中リクエストは重複排除し、TTL を設定してキャッシュします。ティッカーは 24 時間、提出データは 10 分、companyfacts/concepts は 6 時間、frames は 12 時間、提出書類のドキュメントはプロセスメモリ内で 30 日間です（生のドキュメントが Redis に書き込まれることはありません。256 KB 未満の処理済みテキストと解析済みの Form 4 は 7 日間共有されます）。州の検索結果は 1 時間です。

収益化のための仕組み（課金機能はまだありません）

• HTTP ゲート：Redis に登録する自己検証型キー（scripts/create-key.ts / scripts/delete-key.ts）、MCP_API_KEYS の静的キー、または他の場所に保存されたキー用の createHttpHandler({ verifyKey: async (k) => principalOrNull }) が利用できます。無効なキーには 401 が返されます。
• 呼び出しごとの利用量計測：setUsageHooks({ beforeCall, afterCall })（パッケージからエクスポートされています）。beforeCall は {tool, transport, apiKey, clientId, principal, args} を受け取ります。ToolError をスローすると、そのコードで呼び出しが拒否されます（それ以外は UNAUTHORIZED になります）。組み込みのクォータフックは最初に実行されます。afterCall は {ok, ms, errorCode, responseChars} を受け取るため、呼び出し単位またはトークン単位の課金に十分な情報が得られます。
• 推奨ティア：無料（stdio またはキーなしの HTTP、キャッシュ利用）、Pro（API キー、上限の引き上げ、一括／ページネーション対応のエクスポート）、Team（新しい提出書類またはインサイダー取引の Webhook）。

データソースとライセンス

コードはMITライセンスです。サーバーにはデータが含まれておらず、すべてのデータをリアルタイムで取得します。詳細については、DATA_SOURCES.mdおよびLICENSES/をご覧ください。

ソース	データセット	対象範囲	ライセンス（商用利用）
SEC EDGAR	submissions、XBRL APIs、Archives	すべてのEDGAR提出者	米国政府の公開情報。SECのポリシー（可）
New York DOS	n9v6-gdp6 Active Corporations	現存する法人のみ、月次	OPEN-NYの利用規約（可）
Colorado SOS	4ykn-tg5h Business Entities	すべての法人とステータス、日次	パブリックドメイン＋CO利用規約の免責事項（可）
Oregon SOS	tckn-sxa6 Active Businesses	現存する法人のみ、週次	法令に基づくパブリックドメイン。ORS 276A.368（可）
Connecticut SOTS	n7gp-d28j Business Master	すべての法人とステータス、日次	パブリックドメイン。CT利用規約（可）
Pennsylvania DOS	xvd7-5r2c Registered Businesses	現在の登録情報、月次	米国政府のパブリックドメイン（可）

Coloradoの免責事項： ここで提供されるデータは、元の提供元であるコロラド州のデータを利用目的に合わせて変更したものです。コロラド州は、本サイトを通じて提供されるデータの完全性、正確性、適時性、内容について、いかなる表明も保証も行いません。コロラド州は、明示または黙示を問わず、商品性または特定目的への適合性に関する黙示の保証を含むすべての保証を明示的に否認します。変更や更新が完了すると、データが変更される場合があります。Webフィードに含まれる情報は、利用者自身の責任で使用するものとします。

設立州として最も一般的なDelawareには、公開されている一括データセットがないため、対象外です。CAとFLはロードマップに含まれています（list_supported_statesを参照）。このサーバーが提供するのは情報目的のデータのみであり、投資、法律、信用に関する助言ではありません。消費者信用情報機関ではなく、その出力をFCRAの規制対象となる判断に使用してはなりません。

アーキテクチャ

src/
  core/      config, cache (memory LRU | Upstash | tiered), rate limiter, fetch+retry, usage hooks, errors
  sec/       tickers (fuzzy), submissions, documents (HTML→text, item extraction), financials, xbrl (concept/frames), insider (Form 4)
  states/    registry (per-state dataset config + normalizers), socrata (SoQL builder, ranking)
  tools.ts   zod schemas + tool handlers (transport-agnostic)
  server.ts  registers tools/prompt/resource on an McpServer (shared by both transports)
  stdio.ts   npm bin  → serveStdio()
  http/      handler.ts (mcp-handler + API-key auth) · node-server.ts (local/self-host)
api/mcp.ts   Vercel Function

公式のMCP TypeScript SDK v2（@modelcontextprotocol/server。@modelcontextprotocol/sdk v1パッケージの後継であり、mcp-handler 2.xの要件）を基盤としています。2026-07-28プロトコルを提供し、stdioとHTTPの両方で、2025年当時のクライアントにも自動的にフォールバックします。

開発

npm install
npm run check        # typecheck + eslint + vitest (offline unit tests)
npm run smoke:e2e    # build + live smoke over stdio (all tools, real SEC/state data) + HTTP + Vercel-function e2e
npm run validate:registry   # validate server.json against the MCP Registry schema
npx @modelcontextprotocol/inspector --cli node dist/stdio.js --method tools/list

ロードマップ

• 対象州の拡大：FL（Sunbizの一括ファイル）、CA（bizfile API、キーが必要）、オープンデータが利用可能なWA/TX、NYの現存しない法人（「All Filings」データセット）
• 役員／取締役（CTの主要人物データセット、PAの役員レコード、DEF 14A）
• EDGAR全文検索（efts.sec.gov）および8-Kの項目単位のイベントフィード
• 13F保有情報、13D/G所有権、S-1／IPOの追跡
• 新規提出書類やインサイダー取引のWebhook／サブスクリプション（MCPイベント）
• セグメント別および地域別の売上高（Financial Statementデータセット経由のXBRLディメンション）
• ワンクリックでClaude DesktopにインストールできるMCPBバンドル（manifest.jsonを同梱し、検証済み）
• ホスト型プラン：APIキー、利用枠、使用状況ダッシュボード（フックはすでに実装済み）

ライセンス

コードはMITライセンスです（LICENSEを参照）。データには各ソースの利用規約が適用されます（DATA_SOURCES.mdを参照）。