Sec Financial Statements

@pipeworx/sec-financial-statements

来自 SEC DERA“财务报表和附注”数据集的带维度 XBRL 事实和带标签的附注文本——这是 data.sec.gov 的 companyfacts/frames 之下的一层（edgar 和 sec-xbrl 调用的接口），后者仅提供不带维度的事实。分部级收入、地域细分、带脚注标签的套期名义金额——这些都无法通过 companyfacts/frames 获取；它们只存在于 SEC 的批量数据集中。托管服务，调用方无需密钥。

属于 Pipeworx——一个将 AI Agent 连接到 1686+ 个实时数据源的 MCP 网关。

**提交时的状态：架构、工具和加载器均已完成；目前尚未加载任何一期数据。**迁移文件（supabase/migrations/219_sec_financial_statements.sql）尚未应用到生产环境，此数据包也尚未部署。请参阅下文“为何在没有数据的情况下发布”——这是有意为之，并非疏忽，下一步也已在该处说明。

工具

• company_financial_facts(company?, cik?, tag?, limit?) — 查询某个申报主体的带维度事实（提供名称进行 ILIKE 匹配，或提供 CIK）。每条事实都包含所属期间、值、单位；如果带维度，还会包含它所属的分部／地域轴，而不是仅提供一个无从解读的哈希值。这项工具能回答 companyfacts/frames 在结构上无法回答的问题，例如“Flutter Entertainment 的跨货币利率互换名义金额”：这是一个按套期指定维度划分的 DerivativeNotionalAmount 事实，而非合并总额。
• tag_cross_company_screen(tag, version?, ddate?, dimensioned_only?, limit?) — 按排名列出某一期间所有申报主体的某个标签的值——与按公司查询相反（“本季度谁报告的 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 修复，fleet #2500，提交 7ab72cdca）会在申报文件的渲染文本中进行以竖线分隔的多短语正文搜索；如果短语对应某个财务概念，还会附上与该短语精确匹配的申报文件 accession 中的一条 XBRL 事实。此数据包则与之相反：它是一个结构化数据库，收录已加载期间内的每条带标签数值事实（包括带维度的事实）和每个带标签的附注文本块；无需猜测某个搜索短语是否会在渲染后的文档中原样出现，即可按标签／公司／期间查询。若要在某一份特定申报文件的正文中查找事实，请使用 edgar_filing_text；若要跨公司筛选、获取完整的维度细分，或一次搜索多份申报文件中的附注文本，请使用此数据包。

为什么此工具包尚未加载数据

提交此工具包时，大小明确标记为未经验证（fleet #2506）——“先测量”。已针对最新可用期间（2026_08_notes.zip，HTTP 200，content-length: 312,729,503，压缩后）进行了实时测量：此工具包加载的六张表解压后约为 2.46GB，其中 num.tsv 单独就有 5,563,767 行 / 1.14GB。即使只加载一个期间，也需要通过 SEC 共享的 fleet 出口流量进行数 GB 的实际批量操作（CLAUDE.md，fleet #1245）——这不是适合在构建会话中随意执行的操作。我们已在本地使用真实的 2026_08_notes.zip 验证了解析和行映射（确认了每张表的表头和列，正确区分了带维度和不带维度的事实，且注释文本和提交行均能正常读取）——加载器并非纸上谈兵；它已针对真实 SEC 数据运行过，只是尚未加载到生产环境。

要实际加载数据并上线此工具包，还需满足两项条件：

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……然后工具包才能上线”）。此构建的 fleet 任务（#2506）明确要求**“提交，但不要推送——向派发任务的 PM 报告 SHAs”**——因此，是否推送、应用和部署由派发任务的 PM 决定，而不是由本会话决定；本会话只负责报告，不会执行。（曾尝试通过 supabase db query --file … --linked 应用迁移，以进行本地验证；这是文档所述的临时测试路径，但会话自身的权限策略将其拒绝为受保护的基础设施应用操作。我们尊重了这一拒绝，没有绕过限制；遇到同样阻碍时，正确做法也是如此。）
2. 首次加载期间属于实际数据摄取操作，不是 CI 步骤： node scripts/ingest-sec-fsn.mjs --period 2026_08（或使用 --list-periods 查看 SEC 当前发布的内容）。请预留充足的实际运行时间——仅 num.tsv 就有 556 万行，批次大小为 3,000。

数据与刷新

来源：https://www.sec.gov/data-research/sec-markets-data/financial-statement-notes-data-sets——季度压缩包从 2009q1 到 2025q2，之后从 2025_08 起改为按月发布（如 2026_08 等）（SEC 于 2025 年年中更改了发布频率）。这是美国联邦政府数据，属于公有领域——无需考虑再利用许可。每个压缩包包含八个 TSV 文件，其中六个会被加载（sub、tag、dim、pre、num、txt）；不加载 cal（计算链接库）和 ren（渲染元数据）——它们用于报表渲染，而非此工具包提供服务的事实和注释查询。

• 加载器：node scripts/ingest-sec-fsn.mjs --period <YYYY_MM|YYYYqN>——每次运行处理一个期间，凭据解析和带重试的批量 upsert 方式与 scripts/ingest-sec-13f.mjs 相同。 --only sub,tag,dim,pre,num,txt 可加载部分表；--zip <path> 可跳过下载，直接使用本地或已获取的压缩包。
• 对已加载期间重复运行是安全的空操作 upsert：num/txt 以所有已加载列的内容哈希作为键（SEC 文档中 num.tsv 的自然键有 9 列，其中几列可为空——使用哈希可合并 SEC 端完全重复的行，同时保留真正不同的行；此做法与 leie_exclusions / csl_entries / ferc_eqr 相同，见迁移 211）。
• 回填计划：先加载最新期间（最快验证整个数据管道），然后根据预算，每次运行向前回溯一个期间。fsn_coverage() 始终准确报告已加载的内容——任何响应都不会暗示超出实际范围的覆盖情况。
• 架构和索引：supabase/migrations/219_sec_financial_statements.sql。六张表均已启用行级安全，并撤销了 anon / authenticated 的权限（采用迁移 211 中 ferc_eqr 的模式）——只有网关自身注入的数据凭据能够读取。

无法告诉你的内容

• 覆盖范围取决于实际加载的数据，而不是 SEC 发布的 2009 年至今的完整历史记录。 fsn_coverage() 是权威来源；查询已加载时段之外的数据时，不会返回结果，并会明确说明这一点， 而不是让人误以为“这项事实不存在”。
• 没有 ticker 列——SEC 的 DERA 数据集以 CIK/申报编号为键，而非 ticker。company_financial_facts 接受公司名称（ILIKE）或 CIK；如果名称匹配结果不唯一，会返回候选 CIK，而不是 默默选定其中一个。
• 标签是精确且区分大小写的 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 跨整个目录进行路由——无需添加第二个 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