disclosures

disclosures

面向 AI Agent 和 TypeScript 的公司披露研究工具——通过 21 条司法辖区路线（20 条国家路线及欧盟汇总路线）访问 26 个官方来源，查询申报文件、内部人士、所有者、财务信息和所有权链。

disclosures 是一款免费的开源 Model Context Protocol 服务，同时也是一个 TypeScript 库。它可以回答诸如 “NVIDIA 的董事有哪些？”、“谁持有 Samsung Electronics 5% 的股份？” 或 “给我看看 Vale 最近三年的年度业绩” 等问题，并为每个答案提供指向官方源文件的链接。

• 10 个稳定工具，21 条司法辖区路线——六个核心工具通过 jurisdiction 分发；OwnershipChain 为全球工具；另有三个专用工具用于查询已提交文件、担保债权和个人信息。随着覆盖范围扩大，工具名称保持稳定。
• 仅使用官方来源——SEC EDGAR、GLEIF、Companies House、FCA NSM、filings.xbrl.org、OpenDART、EDINET、cninfo、SZSE、BSE、TWSE、CVM、BaFin、info-financiere、recherche-entreprises、HKEXnews、ACRA、DBD、AFM、IDX、Bursa Malaysia、KAP、DFM、PSE EDGE、ASX 和 ASIC。
• 秉持诚实原则——仅提供真实来源链接；对于不支持的内容会明确说明，而不是返回空结果或捏造内容；并清晰列出注意事项（“没有申报记录不代表没有申报”）。
• 内置运行时——提供一个适用于 Node 18+ 的 JavaScript 文件。MCP SDK 和 Zod 是声明的程序包依赖项，因此 TypeScript 用户可以获得公共 API 所使用的类型。

快速开始

需要 Node 18+。通过 SEC 查询美国数据时，必须按照 EDGAR 的公平访问政策设置具有描述性的 User-Agent。无需密钥的非美国路线则不需要此设置。

npx -y disclosures

Claude Code

claude mcp add --transport stdio disclosures \
  --env DISCLOSURES_USER_AGENT="Your Organization [email protected]" \
  -- npx -y disclosures

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "disclosures": {
      "command": "npx",
      "args": ["-y", "disclosures"],
      "env": {
        "DISCLOSURES_USER_AGENT": "Your Organization [email protected]"
      }
    }
  }
}

Cursor

将与 Claude Desktop 相同的 mcpServers 配置块添加到 ~/.cursor/mcp.json（或项目专属的 .cursor/mcp.json）。

VS Code（Copilot / MCP）

添加到 .vscode/mcp.json：

{
  "servers": {
    "disclosures": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "disclosures"],
      "env": {
        "DISCLOSURES_USER_AGENT": "Your Organization [email protected]"
      }
    }
  }
}

[mcp_servers.disclosures]
command = "npx"
args = ["-y", "disclosures"]
env = { DISCLOSURES_USER_AGENT = "Your Organization [email protected]" }

同一服务器也支持 MCP streamable-HTTP 传输，适用于托管或联网部署。传入 --http（不带标志时仍默认为 stdio）：

disclosures --http --port 8080          # or: node dist/server.mjs --http

• 默认绑定到 127.0.0.1。端口取自 --port，否则取自 PORT 环境变量，再否则使用 8080。Host 和提供的 Origin 标头必须与服务器允许列表匹配。绑定到非环回地址时，必须提供 bearer token 并显式指定允许的主机。
• MCP 端点：POST /mcp（该传输也会响应 streamable-HTTP 的 GET/DELETE 握手）。以无状态方式运行——没有会话 ID，每个请求都会创建一个全新的服务器实例。
• 健康检查：GET /healthz → 200 {"name","version","tools"}。
• 诊断信息仅输出到 stderr，与 stdio 模式相同。

在任意 streamable-HTTP MCP 客户端中连接 http://127.0.0.1:8080/mcp。

对于托管服务，请通过部署的密钥配置提供 DISCLOSURES_HTTP_TOKEN，然后设置：

DISCLOSURES_HTTP_ALLOWED_HOSTS="disclosures.example.com" \
DISCLOSURES_HTTP_ALLOWED_ORIGINS="https://disclosures.example.com" \
DISCLOSURES_DOWNLOAD_DIR="/var/lib/disclosures/downloads" \
  disclosures --http --host 0.0.0.0 --port 8080

在反向代理处终止 TLS，保留已配置的 Host 标头，并让客户端发送 Authorization: Bearer <token>。允许的主机必须是完全匹配的 authority；如果客户端发送端口，则必须包含端口。支持以逗号分隔的值。Origin 默认使用允许主机对应的 http:// Origin；在 TLS 终止后，请显式设置 HTTPS Origin。支持不带 Origin 的请求，以供非浏览器客户端使用。健康检查端点会检查 Host/Origin，但不要求提供 token。

库部署可使用 runHttpServer({ bearerToken, allowedHosts, allowedOrigins, downloadDirectory }) 采用相同策略。HTTP 下载始终保存在由服务器控制的目录中（默认使用私有临时目录）；output_path 只能接受文件名。stdio/库下载可以使用显式的本地路径。所有模式都会拒绝覆盖现有文件或符号链接；省略路径时会生成唯一的私有临时文件。

更改配置后，请重启客户端，然后尝试：

“使用 disclosures 列出 Apple 的董事会成员及其最新的 Form 4 活动。” “谁持有 NVIDIA 5% 或以上的股份？请附上文件链接。” “解析韩国的 Samsung Electronics，并展示其最新年度财务数据。” “Apple Operations India 上游的 GLEIF 所有权链是什么？”

十个工具

六个核心工具通过 jurisdiction 在所有司法管辖区路由间分发；OwnershipChain 覆盖全球，不受司法管辖区限制。CompanyDocument 接受 US、GB（默认值）、JP、KR、FR、HK、CN、IN、TR、AE、PH 和 AU；PersonAppointments 接受 US、GB（默认值）、DE、FR 和 AU；CompanyCharges 专用于 Companies House，不接受 jurisdiction。

每个 company 输入都接受名称或本地标识符——股票代码、CIK、LEI 或 ISIN（US／全球）、Companies House 编号（GB——包括苏格兰和北爱尔兰的 SC／NI 前缀）、OpenDART 公司／股票代码（KR）、EDINET／证券／公司代码（JP）、A 股或 HK 代码（CN）、BSE 证券代码（IN）、TWSE 上市代码（TW）、CVM 注册代码（BR）、BaFin-Id 或 ISIN（DE）、SIREN／ISIN／LEI（FR）、4／5 位 HKEX 股票代码（HK）、新加坡 UEN（SG）、13 位法人注册号（TH）、AFM 登记册中的发行人名称或 LEI（NL）、4 字母 IDX 股票代码／kode emiten（ID）、4 位 Bursa 股票代码或发行人名称（MY）、BIST 股票代码（TR）、DFM 发行人代码（AE）、PSE 股票代码或数字形式的 PSE 公司 ID（PH）。传入 jurisdiction: "US" | "GB" | "EU" | "KR" | "JP" | "CN" | "IN" | "TW" | "BR" | "DE" | "FR" | "HK" | "SG" | "TH" | "NL" | "ID" | "MY" | "TR" | "AE" | "PH" | "AU"（默认值为 US）。

覆盖范围矩阵

✅ 支持 · ⚠️ 部分支持（FR CompanyOwners：提供跨越阈值的通知；尽力从通知 PDF 的文本层结构化提取持有人、方向、阈值和变动后的持股比例（针对最新的少数通知）；扫描版／非标准 PDF 和较早的通知仅提供链接列表 · HK CompanyOwners：无需密钥的 CCASS 持股查询返回参与者／托管人层级的持股（托管银行、经纪商、HKSCC Nominees、CSDC），不是受益所有人；SFO Part XV 权益披露登记册设有验证码，仅提供链接供手动查询 · HK CompanyFinancials：从发行人最新业绩公告 PDF 提取主要数据，仅限最新公告；标准发行人的数据可顺利提取，复杂的分部拆分／多栏报表仅能部分解析，页数不足或缺少报表时则退回提供 PDF 链接 · CN CompanyFinancials：从发行人最新定期报告 PDF 的主要会计数据表中提取主要数据，并根据报告注明的单位（元／千元／万元／百万元）统一换算为整元人民币；仅限最新报告；若报告存在乱码（对象流）、PDF 超出大小限制或缺少主要数据表，则退回提供 PDF 链接 · CN CompanyOwners：从发行人最新定期报告中解析前十名股东表；提供真实的大股东数据，但表格格式不规整，列顺序因发行人而异，因此仅输出通过值启发式解析器可靠匹配的行；这是报告发布时的时点快照，不是实时登记册，也不追踪最终受益所有人 · CN CompanyInsiders：不同交易所的处理方式不对称——SZSE 代码（0/3xxxxx）使用 SZSE 无需密钥的董监高持股变动结构化数据源；SSE 代码（6xxxxx）则退回使用最新年报中已发布的董监高名单，仅提供姓名和职位） · ID 通过 受反爬虫保护的主机（www.idx.co.id）提供服务：适配器会发送浏览器级请求头，在这些请求头有效时即可正常工作；如果边缘节点拒绝请求，则会明确提示“主机阻止了此请求——请注入浏览器支持的 fetchFn”，并说明这不代表该发行人的结果为空，绝不会静默漏报 · TR CompanyFilings 有意标记为不支持：KAP 的目录及每个披露页面／PDF 均可无需密钥访问，但其 Next.js 重建将数据层迁移到了 kapsitebackend.mkk.com.tr，该域名无法公开解析——按披露 ID 查询的内容均可正常使用，但无法枚举披露（公司通知页面返回 200，但服务端渲染的是空壳，且从该不可访问的主机获取通知条目），因此工具会说明原因并提供发行人的 KAP 页面，而不会伪造列表 · PH CompanyFinancials 为部分支持：PSE EDGE 提供其 17-A 表格所载的主要报表（资产负债表和损益表，币种为 PHP），不包含报告 PDF 附件中的完整审计报表 · — 返回明确诚实的不支持该司法管辖区的说明，绝不会返回空结果或编造结果 NL CompanyOwners/CompanyInsiders 已获得全面支持，但会读取整个文件的 AFM 登记册导出数据（不存在服务端筛选；重大持股导出文件约为 108 MB）：会话中的首次调用需要约 20–30 s，之后按发行方缓存 24 h 的摘要，其余调用均可在毫秒内完成。在按请求部署时，请提供 AdapterOptions.cache（例如 FileCache）。

⚠️ ASX 和 PSE EDGE 是受限数据源，默认会在访问网络前禁用。 它们的条款限制了使用和再分发，可能与自动披露服务相冲突。请查看 AU.md 和 PH.md，然后仅在你有权在当前场景中使用相应数据源时，设置 DISCLOSURES_ACKNOWLEDGE_ASX_TERMS=1 和/或 DISCLOSURES_ACKNOWLEDGE_PSE_TERMS=1。无需确认 ASX 条款，即可继续使用 ASIC 提供的 CC-BY 澳大利亚公司和取消资格登记册。启用后，响应中仍会保留数据源专属的条款声明。本内容不构成法律建议。

每个司法管辖区都有完整的参考页面，介绍数据源、凭据、可接受的标识符、各意图的行为以及注意事项，详见 docs/jurisdictions/。

数据源和凭据

美国和全球查询只需 User-Agent 即可使用。只要上游允许，非美国数据源均无需密钥；少数需要密钥的数据源也都是免费的。只需提供你要查询的司法管辖区所需的密钥——其他功能无需密钥也能正常使用；如果缺少凭据，系统会显示易读的错误，并指出需要设置的具体变量。

# Required (SEC fair-access policy — your name/org and contact email)
export DISCLOSURES_USER_AGENT="Your Organization [email protected]"

# Optional, per jurisdiction
export COMPANIES_HOUSE_API_KEY="..."   # GB
export OPENDART_API_KEY="..."          # KR
export EDINET_API_KEY="..."            # JP document search
export DBD_API_KEY="..."               # TH company-name search (by-number is keyless)

# Restricted sources: set only after reviewing the source terms.
export DISCLOSURES_ACKNOWLEDGE_ASX_TERMS=1
export DISCLOSURES_ACKNOWLEDGE_PSE_TERMS=1

SEC_EDGAR_USER_AGENT 可作为兼容性回退值；DISCLOSURES_USER_AGENT 优先。

作为 TypeScript 库使用

同一个软件包可以直接导入，无需启动 stdio —— 每个适配器都接受可注入的 { fetchFn?, env?, cache? }，因此可嵌入使用，也能进行确定性测试。

import { createTools } from "disclosures";

const tools = createTools({
  env: { DISCLOSURES_USER_AGENT: "Your Organization [email protected]" },
});

const resolve = tools.find((tool) => tool.name === "CompanyResolve")!;
const result = await resolve.handler({ company: "NVDA" });

处理程序绝不会抛出异常 —— 所有失败都会以易读的 MCP 风格结果返回。各个适配器也以命名空间形式导出（secEdgar、gleif、companiesHouse、openDart、edinet、cninfo、szse、bseIndia、fcaNsm、xbrlFilings、twseOpenApi、cvmOpenData），方便你获取原始的标准化记录，而不是 Markdown。

import { FileCache, createTools } from "disclosures";

const tools = createTools({
  env: { OPENDART_API_KEY: process.env.OPENDART_API_KEY },
  cache: new FileCache("/var/cache/disclosures"), // TTL-aware, survives restarts
});

import { gleif } from "disclosures";

gleif.isIsin("US0378331005");                               // true — validates the check digit
const issuer = await gleif.resolveLeiByIsin("US0378331005"); // → issuer's GLEIF Entity (with .lei)
const isins = await gleif.getIsinsForLei("HWUPKR0MPOU8FGXBT394"); // → every ISIN for that LEI

import { createDisclosuresServer } from "disclosures";

const server = createDisclosuresServer(); // McpServer with all ten tools registered

专为 AI 客户端打造

响应针对 MCP 客户端的实际使用方式而设计：

• 优先使用 Markdown 渲染。 每个结果都是一个 GitHub 风格的 Markdown 文本块 —— 包含标题、精简的管道表格（表头仅声明一次，不像 JSON 那样每行重复）、真实来源链接和内联注意事项。这是适合大模型读取的高效令牌格式。
• 为链式调用提供结构化输出。 含数据的工具还会返回与 Markdown 内容一致的 MCP structuredContent，让客户端无需解析散文即可链式调用：CompanyResolve 返回带完整标识符集合的排序候选项，CompanyFilings 和登记记录包含可直接使用的 transactionId，PersonAppointments 返回带 officerId 的人员，以及 CompanyInsiders、CompanyOwners、CompanyFinancials（按财年期末标注每项概念事实）、OwnershipChain、PrivateRaises 和 CompanyCharges —— 每项都带有 sourceJurisdiction 标签。OwnershipChain 还声明了 MCP outputSchema；多司法管辖区工具保留了如实报告未命中的纯文本路径，因此只会附加输出结构，而不声明架构。
• 下一步提示。 支持链式调用的输出会以一行 _Next: …_ 提示结尾，注明下一步要调用的工具和参数。
• 工具注解。 所有工具都声明 openWorldHint 和 idempotentHint；除 CompanyDocument（其 pdf 模式会写入本地文件）外，其他工具都声明 readOnlyHint，因此客户端可以并行执行，并跳过确认提示。
• 分页文档文本。 CompanyDocument 的 xhtml 模式通过 text_offset 按每段 50,000 个字符读取 —— 可以完整读取较长的申报文件，而不会仅截取开头部分。
• 隔离不可信内容。 提取的申报方编写文本会由固定的 <<<BEGIN/END UNTRUSTED DOCUMENT TEXT>>> 标记包围（文档内形似标记的内容也会被处理以消除歧义），让客户端可以通过程序隔离这些内容。
• 司法管辖区资源。 服务会公开 disclosures://jurisdictions 和 disclosures://jurisdictions/{code} MCP 资源，介绍各司法管辖区的数据来源、凭据、接受的标识符和注意事项 —— 无需因工具调用失败就能检查要求。

诚信与范围

这些工具忠实地报告公开披露信息，并非 KYC、UBO 或资本结构表产品：

• 没有记录不代表没有。 没有 Form D 不代表公司从未进行过非公开融资；缺少 PSC 不能证明不存在控制人；ECCTA 身份字段为空不能证明某位高管未经核实。
• GLEIF 母公司关系指的是会计合并关系，不代表投票控制权、市场披露中的所有权或最终受益所有权。
• Schedule 13D/13G 用于识别持股达到 5% 门槛的申报人；它不是完整或持续更新的资本结构表。
• Section 16 内部人信息基于近期的 Forms 3/4/5，可能并非完整的当前名册。
• 文件可能经过修订、重述、逾期提交，或使用其他 XBRL 概念标记——请对照链接的源文件进行核实。
• 本文内容不构成法律、投资、会计或财务建议。

未能匹配时会返回纯文本“Could not find…”；配置、上游服务和速率限制错误则会返回带标记的错误，并指出修复方法。每个链接都指向真实且可访问的来源 URL。

文档

开发

开发需要 Bun；已发布的制品可在 Node 18+ 上运行。

bun install --frozen-lockfile
bun audit                            # complete dependency graph
bun --no-env-file run typecheck       # pinned TypeScript compiler
bun --no-env-file run test            # full offline suite — no live HTTP
bun --no-env-file run build           # bundle and declarations
bun --no-env-file run test:stdio      # freshly built stdio integration
bun --no-env-file run test:runtime    # stdio and HTTP on the active Node runtime
bun --no-env-file run test:package    # isolated npm install and strict consumer compilation

对于不能加载本地环境文件的自动化任务，请在干净的检出目录中运行包管理器 命令：Bun 的安装／审计命令不会遵循运行时 --no-env-file 标志。PR 会在 Node 22 上 运行完整的离线门禁；发布验证还会检查 Node 18/20/22/24 和实时服务提供方。 版本、安全和发布门禁请参阅发布说明。

默认测试套件绝不访问网络：路由 fetch 存根会对任何未匹配的请求抛出错误。另有一个实时端到端测试套件，会构建真实的 Node 制品，通过 MCP stdio 驱动它，并使用 .env.local 中现有的凭据：

bun run test:live       # missing jurisdiction keys are reported as skips
bun run test:live:all   # strict: require User-Agent + GB/KR/JP keys

实时断言可容忍数据变化（检查身份、标识符格式、来源主机和响应结构，而非易变的数量或日期）；临时故障会重试一次；调用设有时间限制；诊断信息会对已配置的密钥脱敏。实时文件使用 .live.ts 后缀，因此裸运行 bun test 时不会发现这些文件。请参阅完整的测试规范。较小的 bun run smoke:live SEC/GLEIF 诊断仍可用于快速检查。

stdio 规则： 服务会保留 stdout 用于 JSON-RPC——贡献者的诊断信息必须写入 stderr，因为 console.log 会破坏 MCP 传输。

当前缺口

覆盖范围会在现有工具集的基础上逐步扩展。印度仍需深入支持的目标是从最新季度的 BSE 持股 iXBRL/XML 中获取 CompanyOwners。由于年度报告 PDF 中的所有权表差异过大，特意不对其进行解析。10 月 20 日的来源检查发现，目前的发现机制受阻，旧版端点提供的数据也已过时，因此在核实当前数据集之前，所有权信息仍不受支持。其他缺口均按司法管辖区记录，而不会以空数据表示。欢迎通过 GitHub 提交建议和问题。

许可证

Apache-2.0。版权所有 Carrotly AI。