@pipeworx/sec-financial-statements

Dimensioned XBRL facts and tagged note text from SEC's DERA "Financial Statement and Notes" data sets — the layer beneath data.sec.gov companyfacts/frames (what edgar and sec-xbrl call), which expose undimensioned facts only. A segment-level revenue number, a geography breakdown, a footnote-tagged hedge notional — none of that is reachable through companyfacts/frames at all; it only exists in SEC's bulk data sets. Hosted, keyless to the caller.

Part of Pipeworx — an MCP gateway connecting AI agents to 1686+ live data sources.

Status at commit time: schema + tools + loader are code-complete; NO PERIOD IS LOADED YET. The migration (supabase/migrations/219_sec_financial_statements.sql) has not been applied to production and this pack has not been deployed. See "Why this ships without data" below — this is deliberate, not an oversight, and the next step is written down there.

Tools

• company_financial_facts(company?, cik?, tag?, limit?) — dimensioned facts for one filer (give a name, ILIKE-matched, or a CIK). Each fact carries its period, value, unit and — when dimensioned — the segment/geography axis it belongs to, resolved through sec_fsn_dimensions rather than left as a bare hash. This is the tool that answers what companyfacts/frames structurally cannot: "Flutter Entertainment's cross-currency interest rate swap notional" is a DerivativeNotionalAmount fact dimensioned by hedge designation, not a consolidated total.

• tag_cross_company_screen(tag, version?, ddate?, dimensioned_only?, limit?) — every filer's value for ONE tag in one period, ranked — the inverse of a per-company lookup ("who reported the highest AccountsPayableCurrent this quarter").

• note_text_search(query, company?, tag?, limit?) — full-text search (Postgres english tsvector) over tagged note/footnote text blocks — the disclosure prose behind the numbers. Searches tagged note blocks only, not full filing text; see "edgar_filing_text vs. this pack" below.

• fsn_coverage() — which periods are loaded and how many submissions/facts/note blocks each holds. Call this first when a lookup returns nothing — coverage is real and finite, never silently assumed.

Related MCP server: XBRL-US MCP Server

edgar_filing_text vs. this pack — complementary, not duplicative

edgar_filing_text (fixed 2026-09-29, fleet #2500, commit 7ab72cdca) does pipe-separated multi-phrase prose search over a filing's rendered text and attaches the one XBRL fact matched to that exact accession when a phrase reads as a financial concept. This pack is the opposite shape: a structured database of every tagged numeric fact (dimensioned included) and every tagged note text block across whichever periods are loaded, queryable by tag/company/period without needing to guess a search phrase that happens to appear verbatim in the rendered document. Use edgar_filing_text to find a fact inside one specific filing's prose; use this pack to screen across companies, pull a full dimensional breakdown, or search note text across many filings at once.

Why this ships without data

Sizes were explicitly UNVERIFIED when this pack was filed (fleet #2506) — "measure first." Measured live against the newest available period (2026_08_notes.zip, HTTP 200, content-length: 312,729,503 compressed): ~2.46GB uncompressed across the six tables this pack loads, num.tsv alone 5,563,767 rows / 1.14GB. Loading even one period is a real, multi-GB bulk operation over SEC's shared fleet egress (CLAUDE.md, fleet #1245) — not something to run casually inside a build session. Parsing and row-mapping were validated locally against the real 2026_08_notes.zip (every table's header/columns confirmed, dimensioned vs. undimensioned facts correctly distinguished, note text and submission rows read cleanly) — the loader is not speculative, it has been run against real SEC bytes, just not into production yet.

Two things gate actually loading data and shipping this pack live:

1. The migration has to land on main and be applied via db-migrate.yml (workflow_dispatch, gh workflow run db-migrate.yml -f file=219_sec_financial_statements.sql — dry-run first with -f dry_run=true), per CLAUDE.md's local-copy rule ("migration lands ALONE on main… before the pack ships"). This build's own fleet task (#2506) explicitly says "Commit, do NOT push — report SHAs to the dispatching PM" — so the push/apply/deploy decision is the dispatching PM's, not this session's, and is reported rather than executed here. (A direct supabase db query --file … --linked apply — the documented ad-hoc testing path — was attempted for local verification and was refused by the session's own permission policy as a protected infrastructure-apply action; that refusal was respected rather than routed around, which is the correct behavior for anyone hitting the same wall.)

2. The first period load is a real ingest run, not a CI step: node scripts/ingest-sec-fsn.mjs --period 2026_08 (or --list-periods to see what SEC currently publishes). Budget real wall time — num.tsv alone is 5.56M rows at 3,000/batch.

Data + refresh

Source: https://www.sec.gov/data-research/sec-markets-data/financial-statement-notes-data-sets — quarterly zips 2009q1 through 2025q2, then monthly (2026_08, etc.) from 2025_08 onward (SEC changed cadence mid-2025). US federal government data, public domain — no reuse-grant question. Six of the eight TSVs each zip carries are loaded (sub, tag, dim, pre, num, txt); cal (calculation linkbase) and ren (rendering metadata) are not — they serve statement rendering, not the fact/note lookups this pack answers.

• Loader: node scripts/ingest-sec-fsn.mjs --period <YYYY_MM|YYYYqN> — one period per run, same credential resolution and batched-upsert-with-retry shape as scripts/ingest-sec-13f.mjs. --only sub,tag,dim,pre,num,txt loads a subset; --zip <path> skips the download for a local/already-fetched archive.

• Re-running an already-loaded period is a safe no-op upsert: num/txt key on a content hash of every loaded column (SEC's own documented natural key for num.tsv is 9 columns, several nullable — a hash collapses exact SEC-side duplicates without losing genuinely distinct rows, same pattern as leie_exclusions / csl_entries / ferc_eqr, migration 211).

• Backfill plan: load the newest period first (proves the pipeline end-to-end fastest), then step backward one period per run as budget allows. fsn_coverage() always reports exactly what's loaded — no response ever implies coverage beyond that.

• Schema and indexes: supabase/migrations/219_sec_financial_statements.sql. Row-level security is enabled on all six tables, anon/authenticated revoked (migration 211's ferc_eqr pattern) — only the gateway's own injected data credential can read.

What this cannot tell you

• Coverage is whatever has actually been loaded, not the full 2009-present history SEC publishes. fsn_coverage() is the source of truth; a lookup outside loaded periods returns nothing and says so rather than reading as "this fact doesn't exist."

• No ticker column — SEC's DERA data sets key on CIK/accession, not ticker. company_financial_facts takes a company name (ILIKE) or a CIK; an ambiguous name match returns the candidate CIKs instead of silently picking one.

• Tags are exact, case-sensitive XBRL element names ("Revenues", not "revenue") — this pack does not fuzzy-match tag names, because a near-miss tag is a different accounting concept, not a typo.

• This is what filers tagged, not a restatement-aware view. An amended filing's facts sit alongside the original's under different accessions; this pack does not collapse them (contrast sec-13f's amendment handling, which has no analog here since XBRL facts are versioned by filing, not by position).

Auth

Keyless to the caller — the data credentials are injected by the gateway, never exposed.

Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

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

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/sec-financial-statements/mcp returns the tools in the table above plus the shared Pipeworx meta-tools — ask_pipeworx, discover_tools, search_within, remember/recall and the rest of the gateway-wide set. So the tool count you see is larger than this table: a single-pack endpoint currently lists roughly 30 shared tools alongside the pack's own. The connection's initialize response states its exact scope, and is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a scoped connection answer a question this pack does not cover — via ask_pipeworx, which routes across the whole catalog — without you adding a second MCP server. There is currently no way to mount a pack endpoint without them; if the extra schemas cost you more context than the routing is worth, connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed directly, instead of just this one's:

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

Both URLs reach the same gateway and the same 1686+ data sources. The only difference is which pack's tools are listed directly; ask_pipeworx reaches all of them from either one.

No MCP client? Call it over HTTP

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

No account needed for the first calls. Inspect any tool: GET https://gateway.pipeworx.io/v1/tools/company_financial_facts. Find one: POST https://gateway.pipeworx.io/v1/tools/search_packs with {"query":"..."}.

Standalone (no gateway account)

This package also runs as a local stdio MCP server — no Pipeworx account, no gateway round-trip:

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

Or run it directly to confirm it starts:

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

It speaks MCP over stdin/stdout and answers initialize/tools/list/tools/call for only this pack's tools — none of the shared meta-tools the gateway connection above adds. Same source, same tools, no ask_pipeworx routing.

Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English — this works on the pack endpoint above as well as on the full gateway:

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

The gateway picks the right tool and fills the arguments automatically.

More

• Docs and guides

• pipeworx.io

License

MIT