Sec Beneficial Ownership

@pipeworx/sec-beneficial-ownership

SEC Schedule 13D / 13G 受益所有权申报——谁持有上市公司 5% 及以上的股份、持有方式（单独或共同拥有投票权／处置权），以及对于 13D，持有原因（Item 4「交易目的」，这是激进投资者的信号）。解析 SEC 自 2024 年规则起要求提交的结构化 XML；对于较早的纯文本申报，则如实回退（structured: false），而不是返回空结果。

这是 Pipeworx 的一部分——一个连接 AI Agent 与 1807+ 个实时数据源的 MCP 网关。这是独立、非官方的集成，与上游提供方无关联、未获其认可，也未由其发布。

工具

• sec_13d_filings(ticker_or_cik, form_type?, limit?) — 列出发行人的 Schedule 13D/13G 申报（及修订），按时间从新到旧排列。每行都会标明申报是结构化 XML 还是 2024 年之前的纯文本。
• sec_13d_filing(ticker_or_cik, accession_number) — 解析一份申报：列出每位申报所有者、持股比例、单独／共同投票权、单独／共同处置权及持有股份总数；对于 13D，还包括 Item 4 的目的文本。对于规则实施前的申报，回退到有长度限制的纯文本。
• sec_13d_amendment_diff(ticker_or_cik, accession_number) — 给定一份 13D/A 或 13G/A，查找该申报所属链条中同一申报群体之前提交的申报，并比较持股比例、投票权／处置权（按所有者分别比较），以及（对于 13D）Item 4 的目的文本是否发生变化。

认证

无需密钥。SEC EDGAR 免费、公开且无需 API 密钥——只需提供描述性 User-Agent；本工具包会根据 SEC 的开发者指南，在每次请求中发送该标头。

数据源

• https://data.sec.gov/submissions/CIK##########.json — 按发行人划分的申报索引（表格类型、accession number、申报日期、主文档名称）。与 mcps/edgar 共用此模式。
• https://www.sec.gov/Archives/edgar/data/{cik}/{accession}/primary_doc.xml — 申报的结构化 XML，适用于 SEC 2024 年结构化数据规则实施当日及之后提交的申报（SCHEDULE 13D / SCHEDULE 13G 表格类型）。
• https://www.sec.gov/Archives/edgar/data/{cik}/{accession}/{primary_document} — 申报的纯 HTML／文本文档，适用于规则实施前的申报（SC 13D / SC 13G 表格类型）。
• https://www.sec.gov/files/company_tickers.json — 通过共享的 resolveSecEntity 辅助函数，将股票代码／公司名称解析为 CIK（mcps/edgar 也使用该函数）。所有以 SEC 为数据源的工具包共用同一个解析器，而不在此处另行实现。

值得了解的陷阱

• 结构化申报文件的提交索引中的 primaryDocument 字段指向的是查看器路径，而非原始文件。 路径看起来像 xslSCHEDULE_13D_X01/primary_doc.xml——获取该确切 URL 会返回渲染后的 HTML（服务器端应用了供浏览器使用的 XSLT 转换），而不是机器可读的 XML，尽管文件名以 .xml 结尾。无论查看器路径指定的是哪个 XSLT 样式表变体（X01、X02……），实际的结构化 XML 文件始终位于 accession 档案根目录下的 primary_doc.xml。本套件获取结构化申报文件时始终使用根目录路径；mcps/sec-form-d 处理 Form D 时也遵循同一约定。
• SC 13D/SC 13G（规则实施前的纯文本）与 SCHEDULE 13D/SCHEDULE 13G（规则实施后的结构化 XML）是同一种表格，只是所属时期不同。 SEC 2024 年的结构化数据规则改变了提交类型字符串，而不仅仅是文件格式。本套件中的筛选逻辑会将两者规范为同一类别（13D/13G），因此调用方按表格类型筛选时可以获取所有时期的申报文件。
• previousAccessionNumber（如果存在）指向修订链中的原始申报文件，而非紧邻的上一份修订文件。 已通过实时数据确认：同一申报集团连续提交的三份修订文件都带有相同的 previousAccessionNumber（指向 2024 年的原始文件）。该字段也并非总是存在——较晚的 XSD 修订版（X0202，至少在一家大型机构申报者的数据中出现过）完全省略了该字段。sec_13d_amendment_diff 将它作为链成员关系的一个信号，与申报所有者身份重叠情况结合使用，而不会将其视为直接指向“上一份申报文件”的指针。
• 13D/A 或 13G/A 只会重述发生变更的条目。 如果某条目内容与上一份申报文件相比没有变化，修订文件的 items1To7（13D）或 items（13G）区块可能会直接省略 item2、item4 等条目——这不是解析失败，而是 SEC 架构允许申报修订文件的方式。sec_13d_filing 和 sec_13d_amendment_diff 会对缺失的条目返回 null，而不会凭空编造内容。
• Schedule 13G 没有“目的”字段。 13D 的 Item 4 是“交易目的”（自由文本）；13G 的 Item 4 是“持有情况”（金额／百分比／投票权，已由 reporting_owners 覆盖）。item4_purpose 仅会为 13D 填充；对于 13G，该字段为 null，并附有说明原因的 note。
• 所有 SEC/EDGAR 套件共用覆盖整个集群的 SEC 出口（一个出站 IP）。 此处的每个工具只读取范围有限且明确的一组申报文件，从不会对某发行人的历史记录进行批量爬取。sec_13d_amendment_diff 向前回溯查找上一份申报文件时设有上限（最多获取 MAX_CHAIN_SCAN = 6 份申报文件）。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "sec-beneficial-ownership": {
      "url": "https://gateway.pipeworx.io/sec-beneficial-ownership/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/sec-beneficial-ownership/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 都会连接到同一个网关和相同的 1807+ 个数据源。唯一的区别是哪个工具包的工具会被直接列出；从任一端点都可以通过 ask_pipeworx 访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/sec_13d_filings \
  -H 'Content-Type: application/json' \
  -d '{"ticker_or_cik":"IMXI","form_type":"all","limit":10}'

首次调用无需账户。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/sec_13d_filings。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账户）

此软件包也可作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需往返网关：

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

或者直接运行，确认它能正常启动：

npx -y @pipeworx/mcp-sec-beneficial-ownership

它通过 stdin/stdout 使用 MCP，并针对仅此工具包的工具响应 initialize/tools/list/tools/call——不含上文网关连接额外提供的任何共享元工具。使用相同的源代码和工具，但不提供 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用通俗英语提问，而不是直接调用工具——这既适用于上文的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Sec Beneficial Ownership data" })

网关会选择合适的工具并自动填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT