Sec Financial Statements

@pipeworx/sec-financial-statements

SEC の DERA「Financial Statement and Notes」データセットに含まれる、ディメンション付き XBRL ファクトとタグ付き注記テキストです。data.sec.gov の companyfacts/frames よりも下層にあたります。edgar や sec-xbrl が参照する companyfacts/frames で公開されるのは、ディメンションのないファクトのみです。セグメント別の売上高、地域別の内訳、脚注タグ付きのヘッジ想定元本などは、companyfacts/frames からは取得できず、SEC の一括データセットにのみ存在します。ホストされており、呼び出し側にキーは不要です。

Pipeworx の一部です。AI エージェントを 1686+ 件の稼働中のデータソースに接続する MCP ゲートウェイです。

コミット時点のステータス：スキーマ、ツール、ローダーはコード完成済みですが、まだデータを読み込んだ期間はありません。 マイグレーション（supabase/migrations/219_sec_financial_statements.sql）は本番環境に適用されておらず、このパックもデプロイされていません。以下の「データなしでリリースする理由」を参照してください。これは意図的なもので、次の手順もそこに記載されています。

ツール

• company_financial_facts(company?, cik?, tag?, limit?) — 1 社の提出者のディメンション付きファクトを取得します（名前を指定すると ILIKE で照合されます。または CIK を指定できます）。各ファクトには期間、値、単位が含まれ、ディメンションがある場合は、単なるハッシュ値のままにせず、所属するセグメント／地域の軸を sec_fsn_dimensions を通じて解決します。companyfacts/frames では構造上答えられない質問に答えるためのツールです。たとえば「Flutter Entertainment のクロスカレンシー金利スワップの想定元本」は、連結合計ではなく、ヘッジ指定でディメンション化された DerivativeNotionalAmount ファクトです。
• tag_cross_company_screen(tag, version?, ddate?, dimensioned_only?, limit?) — 1 期間における 1 つのタグについて、すべての提出者の値をランキング形式で取得します。企業ごとの検索とは逆の用途です（「今四半期、AccountsPayableCurrent の報告額が最も高かった企業はどこか」）。
• note_text_search(query, company?, tag?, limit?) — タグ付きの注記／脚注テキストブロック（数値の背後にある開示文）を Postgres の english tsvector で全文検索します。検索対象はタグ付き注記ブロックのみで、提出書類の全文ではありません。以下の「edgar_filing_text とこのパック」を参照してください。
• fsn_coverage() — 読み込み済みの期間と、各期間に含まれる提出書類、ファクト、注記ブロックの数を確認します。検索結果がない場合は、まずこれを呼び出してください。対象範囲は実際に存在する有限のもので、暗黙に想定されることはありません。

edgar_filing_text とこのパック — 重複ではなく、相互補完

edgar_filing_text（2026-09-29 修正、フリート #2500、コミット 7ab72cdca）は、提出書類をレンダリングしたテキストを対象に、パイプ区切りの複数語句による文章検索を行います。また、語句が財務概念を表す場合は、その語句に一致する XBRL ファクトを該当するアクセッション番号から紐付けます。このパックはこれとは逆の構成です。読み込み済みのすべての期間にわたる、タグ付き数値ファクト（ディメンション付きのものを含む）とタグ付き注記テキストブロックを網羅する構造化データベースであり、レンダリングされた文書にそのまま記載されている検索語句を推測する必要なく、タグ／企業／期間で検索できます。特定の提出書類の文章内からファクトを見つけるには edgar_filing_text を使います。企業横断のスクリーニング、完全なディメンション別内訳の取得、または多数の提出書類にわたる注記テキストの一括検索には、このパックを使います。

データを含めずにリリースする理由

このパックの申請時には、サイズは明示的に未検証とされていました（フリート #2506）——「まず測定する」。最新の入手可能な期間（2026_08_notes.zip、HTTP 200、content-length: 312,729,503 圧縮）を実測したところ、このパックが読み込む6つのテーブル全体で、展開後は約2.46GBです。num.tsvだけで5,563,767行／1.14GBあります。1期間分だけ読み込む場合でも、SECの共有フリートのエグレス（CLAUDE.md、フリート #1245）を介した実際の複数GB規模の一括処理となるため、ビルドセッション内で気軽に実行できるものではありません。解析と行のマッピングは、実際の2026_08_notes.zipを使ってローカルで検証済みです（各テーブルのヘッダーと列を確認し、ディメンション付きとディメンションなしのファクトを正しく区別し、注記テキストと提出行を問題なく読み取れることを確認しました）。ローダーは推測に基づくものではなく、本番環境にはまだ投入していませんが、SECの実データを使って実行済みです。

データの読み込みと、このパックを本番環境にリリースするには、次の2つの条件を満たす必要があります。

1. マイグレーションをmainにマージし、db-migrate.yml経由で適用する必要があります（workflow_dispatch、gh workflow run db-migrate.yml -f file=219_sec_financial_statements.sql——まず-f dry_run=trueでドライランを実行）。これはCLAUDE.mdのローカルコピーのルール（「マイグレーションを単独でmainにマージしてから……パックをリリースする」）に従うものです。このビルドに関連するフリートタスク（#2506）には、明確に**「コミットするが、プッシュはしない——SHAをディスパッチしたPMに報告する」**と記載されています。したがって、プッシュ／適用／デプロイの判断はこのセッションではなく、ディスパッチしたPMが行い、ここでは実行せずに報告します。（ローカルでの検証のために、ドキュメントに記載された臨時テスト手順であるsupabase db query --file … --linkedによる直接適用を試みましたが、セッション固有の権限ポリシーにより、保護対象のインフラへの適用操作として拒否されました。この拒否を尊重し、回避策を取らなかったことは、同じ問題に直面した場合の適切な対応です。）
2. 最初の期間の読み込みは、CIのステップではなく、実際の取り込み処理です： node scripts/ingest-sec-fsn.mjs --period 2026_08（SECが現在公開している期間を確認するには--list-periodsを指定）。実際の経過時間を見込んでください。num.tsvだけでも、1バッチ3,000行で556万行を処理します。

データと更新

ソース：https://www.sec.gov/data-research/sec-markets-data/financial-statement-notes-data-sets——四半期ごとのZIPは2009q1から2025q2まで、その後は2025_08以降、月次（2026_08など）です（SECは2025年半ばに公開頻度を変更しました）。米国連邦政府のデータであり、パブリックドメインのため、再利用許諾の確認は不要です。各ZIPに含まれる8つのTSVのうち、6つ（sub、tag、dim、pre、num、txt）を読み込みます。cal（計算リンクベース）とren（レンダリングメタデータ）は読み込みません。これらは財務諸表のレンダリング用であり、このパックが対応するファクト／注記の検索には使いません。

• ローダー：node scripts/ingest-sec-fsn.mjs --period <YYYY_MM|YYYYqN> — 1回の実行につき1期間を処理します。認証情報の解決方法と、再試行付きの一括アップサート方式はscripts/ingest-sec-13f.mjsと同じです。 --only sub,tag,dim,pre,num,txtを指定すると対象を限定して読み込みます。--zip <path>を指定すると、ダウンロードを省略し、ローカルまたは取得済みのアーカイブを使います。
• 読み込み済みの期間を再実行しても、安全なノーオップのアップサートになります。num／txtのキーには、読み込み対象の全列のコンテンツハッシュを使います（SECが公式に文書化しているnum.tsvの自然キーは9列で、そのうち複数はNULL許容です。ハッシュを使うことで、実際に異なる行を失うことなく、SEC側の完全一致する重複をまとめられます。マイグレーション211のleie_exclusions／csl_entries／ferc_eqrと同じ方式です）。
• バックフィル計画：まず最新の期間を読み込んで、パイプライン全体を最短で検証し、その後、予算に応じて1回の実行につき1期間ずつ遡ります。fsn_coverage()は、読み込み済みの範囲だけを常に正確に報告します。応答が実際の読み込み範囲を超えるカバレッジを示唆することはありません。
• スキーマとインデックス：supabase/migrations/219_sec_financial_statements.sql。6つすべてのテーブルで行レベルセキュリティが有効になっており、anon／authenticatedの権限は取り消されています（マイグレーション211のferc_eqr方式）。読み取りできるのは、ゲートウェイに注入されたデータ認証情報だけです。

この情報からは分からないこと

• 対象範囲は実際に読み込まれたデータのみであり、SEC が公開している 2009 年から現在までの全履歴ではありません。 fsn_coverage() が信頼できる情報源です。読み込み済みの期間外を検索すると、結果が空であることが示されます。これは「この事実は存在しない」という意味ではありません。
• ティッカー列はありません。SEC の DERA データセットでは、ティッカーではなく CIK／アクセッション番号をキーにしています。company_financial_facts は会社名（ILIKE）または CIK を受け取ります。名前が曖昧な場合は、候補の CIK を返し、無言で 1 つを選ぶことはありません。
• タグは大文字と小文字を区別する、正確な XBRL 要素名です（"Revenues" であり、"revenue" ではありません）。このパックはタグ名のあいまい検索を行いません。よく似たタグは誤字ではなく、別の会計概念を表すためです。
• これは提出者がタグ付けした内容であり、修正申告を考慮したビューではありません。 修正申告の事実は、異なるアクセッション番号の下で元の申告の事実と並んで記録されます。このパックでは、それらを統合しません（sec-13f の修正申告処理とは対照的です。XBRL の事実は保有ポジションではなく申告によってバージョン管理されるため、ここには同等の機能はありません）。

認証

呼び出し元にキーは不要です。データの認証情報はゲートウェイが注入し、決して公開されません。

クイックスタート

MCP クライアント（Claude Desktop、Cursor、Windsurf など）に追加します。

{
  "mcpServers": {
    "sec-financial-statements": {
      "url": "https://gateway.pipeworx.io/sec-financial-statements/mcp"
    }
  }
}

このエンドポイントが実際に提供するもの

https://gateway.pipeworx.io/sec-financial-statements/mcp の tools/list は、上の表のツールに加えて、共有 Pipeworx メタツール（ask_pipeworx、 discover_tools、search_within、remember／recall など、ゲートウェイ全体で使えるツール一式）も返します。そのため、表示されるツール数はこの表より多くなります。現在、単一パックのエンドポイントには、そのパック固有のツールに加えて、およそ 30 個の共有ツールが一覧表示されます。接続の initialize レスポンスには正確な範囲が記載されており、その日の状況を確認する際の確かな情報源です。

これは意図的な設計であり、偶然の多重化ではありません。メタツールを使えば、このパックの対象外の質問にも ask_pipeworx を通じてカタログ全体を検索して回答できるため、2 つ目の MCP サーバーを追加する必要がありません。現時点では、メタツールを使わずにパックのエンドポイントを接続する方法はありません。追加のスキーマがもたらすコンテキストコストに対してルーティングの利点が見合わない場合は、複数のパックのエンドポイントではなく、フルゲートウェイに一度だけ接続してください。

このパックだけでなく、すべてのパックのツールを直接一覧表示するには、Pipeworx のフルゲートウェイに接続します。

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

どちらの URL も、同じゲートウェイと同じ 1686 以上のデータソースに接続します。違いは、どのパックのツールが直接一覧表示されるかだけです。どちらからでも ask_pipeworx を使ってすべてのツールにアクセスできます。

MCP クライアントがない場合：HTTP で呼び出す

curl -X POST https://gateway.pipeworx.io/v1/tools/company_financial_facts \
  -H 'Content-Type: application/json' \
  -d '{"company":"Apple","tag":"Revenues"}'

最初の呼び出しにアカウントは不要です。任意のツールを確認するには、GET https://gateway.pipeworx.io/v1/tools/company_financial_facts を使います。ツールを検索するには、{"query":"..."} を指定して POST https://gateway.pipeworx.io/v1/tools/search_packs を使います。

スタンドアロン（ゲートウェイアカウント不要）

このパッケージは、ローカルの stdio MCP サーバーとしても実行できます。Pipeworx アカウントも、ゲートウェイへの往復通信も必要ありません。

{
  "mcpServers": {
    "sec-financial-statements": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-sec-financial-statements"]
    }
  }
}

または、次のコマンドを直接実行して起動を確認します。

npx -y @pipeworx/mcp-sec-financial-statements

stdin/stdout 経由で MCP を使用し、このパックのツールのみを対象に initialize／tools/list／tools/call に応答します。上記のゲートウェイ接続で追加される共有メタツールはありません。同じソース、同じツールであり、ask_pipeworx によるルーティングはありません。

ask_pipeworx の使用

ツールを直接呼び出す代わりに、自然な英語で質問できます。この方法は上記のパックのエンドポイントでも、フルゲートウェイでも使えます。

ask_pipeworx({ question: "your question about Sec Financial Statements data" })

ゲートウェイが適切なツールを選び、引数を自動的に入力します。

詳細

• ドキュメントとガイド
• pipeworx.io

ライセンス

MIT