Canli Fundamentals

canli-fundamentals-mcp

以 MCP 服务的形式提供 SEC 公司基本面数据的时点快照。对于公司在 XBRL 中报告的任何数值，它都会告诉你的 AI 助手三件事：首次报告的数值、最新申报文件中的数值，以及截至指定日期已知的数值。每个数值都附有对应的申报文件。

这种差异很重要。Apple 2018 财年摊薄后每股收益在 2018 和 2019 年的年度报告中为 11.91，在 2020 年报告中则为 2.98，这是因为进行了 4 比 1 拆股。如果回测使用今天的数据来做出 2018 年的决策，就会用到一个当时无人见过的数字。Apple 2017 财年末的应付账款最初报告为 490.5 亿美元，一年后改为 442.4 亿美元。在 Apple 报告的 3,827 个年度期间中，如今有 190 个期间的数据与首次报告时不同，这还不包括股票拆分造成的每股数据和股数变化，共 35 处。

npx -y canli-fundamentals-mcp

Claude Code：

claude mcp add canli-fundamentals -- npx -y canli-fundamentals-mcp

托管服务，无需安装（claude.ai connectors、ChatGPT、Cursor，或任何支持 URL 的客户端）：

claude mcp add --transport http canli-fundamentals https://canlicapital.com/mcp/fundamentals

Claude Desktop、Cursor 或任何 MCP 客户端（在其配置中使用 mcpServers）：

{
  "mcpServers": {
    "canli-fundamentals": { "command": "npx", "args": ["-y", "canli-fundamentals-mcp"] }
  }
}

然后可以询问：“Apple 截至 2018 年 12 月 31 日报告了什么？”、“Microsoft 哪些年度数据被重述了？”、“显示 Toyota 自 2015 年以来的收入”，或“显示报告 Apple 2017 年应付账款的所有申报文件”。

工具

工具	返回内容
known_as_of	对每项指标，返回截至某日期已提交申报的最近期间及当时的数值。标记后来被重述的数值（changed_after）以及公司已停止报告的指标（stale）。默认返回十项常见指标。设置 ratios: true 后，会添加仅根据这些申报文件计算的利润率、股本回报率和资产回报率、负债权益比及自由现金流，每项均列出其输入数据及对应申报文件。这是回测的时点数据基础工具。
history	按时间展示一项指标，最新的期间排在最前：first_reported（默认）、latest，或截至 as_of 日期已知的数值。可选择年度、季度或所有期间。
restatements	列出最新数值与首次报告数值不同的期间，并提供两个数值、变化百分比及原因：split、split_likely、tag_change 或无（即重述、重新分类或更正）。未指定概念时，会扫描所有概念。
vintages	按时间从早到晚，列出报告某项指标在一个期间数值的每份申报文件。
list_concepts	列出公司报告的概念及支持的通俗名称，并提供单位、期间数量、日期范围和重述期间数量。
find_company	按名称、股票代码或 CIK 查找匹配的公司，按匹配度从高到低排列，并列出其 CIK 和股票代码，以及其他工具会读取哪家公司。
cross_section	按申报日期返回最多 50 家公司（股票代码、CIK 或名称）的一项指标：每家公司的最新期间、当时的数值、申报文件，以及之后是否被重述。这是进行同行比较或构建因子的时点数据基础工具。

全部七种工具均为只读。

横截面查询仅为每家公司快照中所请求的指标建立索引，不会将其保留在内存中，因此查询 50 家公司的内存开销与查询一家大致相同。已使用对相同 SEC 快照进行独立 Python 筛选的结果进行核对（canlicapital 仓库中的 scripts/research/fundamentals-pit-check/）：在 3 个日期查询 20 家公司的年度 NetIncomeLoss，60 项结果在数值、期间、申报日期、accession number 和 changed_after 方面全部一致；其中有 5 项双方均无数值（例如 Meta 首次提交 10-K 之前的期间）。各公司的财年结束日期不同，因此比较数值前应先比较 end。

为公司指定名称

company 接受股票代码（AAPL）、SEC CIK（320193）或名称（Exxon Mobil、Alphabet、 Goldman Sachs）。名称匹配时不区分大小写、不考虑标点，也会忽略末尾的法律实体类型词（Inc、Corp、 Holdings）；按名称查询得到的结果会在 company.matched 中说明匹配方式。只有在能明确确定所指公司时才使用名称：名称或名称开头对应的公司只有一家，或者其中只有一家有当前股票代码（Alphabet Inc.，而非 Alphabet Holding Company）。否则，错误会列出候选公司及其 CIK，find_company 会按匹配程度排列候选项。

现在有些股票代码属于参考范围以外的公司。XOM 是 SEC 为 ExxonMobil Holdings Corp（CIK 2115436）指定的股票代码，这是一家新的控股公司；服务会读取名称相同且在覆盖范围内的申报公司 Exxon Mobil Corporation（CIK 34088），并说明这一点。不会列出曾用股票代码：请按名称搜索（Twitter）或使用 CIK。

为指标指定名称

使用普通名称，服务会跨公司曾用于该指标的标签追踪数据。Apple 的收入在 2017 财年以前使用 SalesRevenueNet，从 2018 年起使用 RevenueFromContractWithCustomerExcludingAssessedTax；Toyota 的数据则从 us-gaap 转为 IFRS。每个值都会标明其来源标签。

普通名称	标签，按优先顺序排列
revenue	Revenues, RevenueFromContractWithCustomerExcludingAssessedTax, RevenueFromContractWithCustomerIncludingAssessedTax, SalesRevenueNet, ifrs-full:Revenue, ifrs-full:RevenueFromContractsWithCustomers
net_income	NetIncomeLoss, ifrs-full:ProfitLossAttributableToOwnersOfParent, ProfitLoss, ifrs-full:ProfitLoss
operating_income	OperatingIncomeLoss, ifrs-full:ProfitLossFromOperatingActivities
gross_profit	GrossProfit, ifrs-full:GrossProfit
eps_diluted, eps_basic	EarningsPerShareDiluted 或 Basic, ifrs-full:DilutedEarningsLossPerShare 或 BasicEarningsLossPerShare
assets, liabilities	Assets 或 Liabilities，以及同名的 ifrs-full 标签
equity	StockholdersEquity, ifrs-full:EquityAttributableToOwnersOfParent, StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest, ifrs-full:Equity
cash	CashAndCashEquivalentsAtCarryingValue, ifrs-full:CashAndCashEquivalents, CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents
operating_cash_flow	NetCashProvidedByUsedInOperatingActivities, ifrs-full:CashFlowsFromUsedInOperatingActivities
diluted_shares	WeightedAverageNumberOfDilutedSharesOutstanding, ifrs-full:AdjustedWeightedAverageShares
shares_outstanding	dei:EntityCommonStockSharesOutstanding, CommonStockSharesOutstanding
capex	PaymentsToAcquirePropertyPlantAndEquipment, ifrs-full:PurchaseOfPropertyPlantAndEquipmentClassifiedAsInvestingActivities, PaymentsToAcquireProductiveAssets

常见变体也可用（sales、revenues、EPS、total_assets）。任何 XBRL 标签也可用 （AccountsPayableCurrent），默认使用 us-gaap；如果某个标签同时存在于两个分类体系中，服务会同时读取两者；使用前缀可指定其中一个（us-gaap:Assets、dei:EntityCommonStockSharesOutstanding）。公司停止使用的标签会返回 newer_series，并标明承接该标签的普通名称。

数字的来源，以及如何核验

对于参考资料中的每家公司，canlicapital.com 都会逐字节提供 SEC 的 XBRL companyfacts 响应，并以 gzip 快照的形式保存，同时在公司的记录中列出该快照的 SHA-256 值。该服务会：

1. 从 https://canlicapital.com/api/v1/company-tickers.json 解析股票代码，并从 /api/v1/company-names.json 的公司名称索引中解析名称；
2. 读取 /company-data/{CIK}.json 中的公司记录；
3. 下载该记录所指向的快照，并在 SHA-256 值不匹配时拒绝使用；
4. 在你的计算机上计算其他所有内容。

这些 GET 请求是唯一的网络流量。每个结果都会列出快照的信息（日期、哈希值、URL，以及它所来自的 SEC URL），因此你可以从 SEC 获取同一文件并进行比较。公司参考资料重新发布时，快照会更新；每个结果中的 snapshot.age_days 表示所读取快照的历史天数。

股票代码列表、名称索引和公司记录都会保存在磁盘上，并在六小时内直接使用，之后再通过 ETag 重新验证；如果无法访问该网站，则使用磁盘上的副本。在磁盘缓存已预热的情况下，我们测得新进程对某家公司的首次调用耗时为 38 至 72 ms（AAPL、JPM、MSFT）。

期间的处理方式：

• 一个期间由起始日期和结束日期构成。结束日期相同的季度数据和年初至今数据属于不同期间，数值绝不会跨期间合并。
• 350 至 380 天的时长视为年度期间（包括 52 周和 53 周的年度）。80 至 125 天的时长视为季度期间，涵盖 Kroger 这类 16 周的第一季度等 12 至 17 周的季度。其他期间（六个月和九个月的年初至今数据）仅会出现在 periods: "all" 中。
• 余额（时点数据）沿用首次报告该数据的报告类型：年末余额最初在年度报告中报告，中期余额最初在 10-Q 和 6-K 中报告。
• first_reported 按提交日期排序，其次按 accession number 排序，以确定最早的申报。使用 as_of 时，对于所有口径，仅纳入在该日期或之前提交的申报，因此之后提交的内容不会被纳入。
• 当一份申报在两个同名普通标签下报告某个期间时，取首次报告该期间的标签所对应的数值，因此不会将同一份申报中的第二个定义视为修订。
• 不纳入申报费用附件（ffd 分类体系）和注册声明（424B 招股说明书、S- 和 F- 表格）：它们会重复记录并非定期业绩的数据。
• 当变动符合公司报告的拆股比例（StockholdersEquityNoteStockSplitConversionRatio1）时，系统会识别为拆股。如果没有报告比例，但每股数据或股份数的变动是 2 到 20 之间的整数倍，则标记为 split_likely。除非设置了 include_splits，否则这两类变动都不会纳入 restatements。若某项数值发生变化后又恢复为首次报告时的数值，则计入 changed_then_reverted，而不列出。

限制

• 数值以 SEC 的 companyfacts API 在各结果所标注的快照中报告的内容为准。快照日期之后提交的文件不会包含在内：每个结果都会给出快照的 age_days，如果 as_of 晚于快照日期，snapshot_note 会说明这一点。
• tag_change 表示首个值和最新值来自同一个普通名称下的不同标签。这可能是实际重述，也可能是对该指标的两种定义；请阅读这两份文件。
• 结果最多包含 10,000 个字符的行，按时间从新到旧排列；如果行被截断，truncated 会说明。list_concepts 和 restatements 会通过 offset 分页，并在还有行时提供 next_offset。
• filed 是文件提交至 EDGAR 的日期。为避免前视偏差，请将某个值视为从提交后的下一个交易日起已知。
• 数值发生变化可能是因为重述、重新分类或更正；accession number 标明了应阅读的文件。
• 覆盖范围为 Canli 公司参考数据中的 12,738 家 SEC 申报公司，其中 5,277 家拥有当前 ticker（共 6,415 个 ticker）。不在其中的公司会返回一条指出其 CIK 的错误。
• 数据由公司报告。非投资建议。

设置

变量	默认值	作用
CANLI_CACHE_DIR	~/.cache/canli-fundamentals	快照（以其 SHA-256 命名，因此缓存文件永远不会过期）以及 ticker 列表、名称索引和记录（每六小时重新验证）缓存的位置；仅所有者可访问。设为空值即可不在磁盘上保存任何内容。内存中会保留最近使用的八家公司。
CANLI_API_BASE	https://canlicapital.com	要读取的网站。

属于 Canli MCP 系列

• canli-validation-mcp：检查回测是否可靠（Deflated Sharpe、过拟合概率、最低记录期限）。
• canli-research-mcp：Canli Capital 的开源研究记录。

代码采用 MIT 许可证。SEC 文件和 XBRL 事实属于美国政府作品，处于公有领域；Canli Capital 的筛选和衍生数据采用 CC BY 4.0 许可（注明“Canli Capital (canlicapital.com)”）。

仓库审计示例（尚未发布）

回测开发者可以通过单独的本地 stdio 示例调用提供版本审计核心。 它会读取客户端提供的精确参考、用量和设置字节， 保留每一行选中数据，并明确显示缺失或不确定的结果。 此操作需要完整的仓库检出副本和固定版本的包依赖。 规范辅助程序位于此 npm 包之外；npx canli-fundamentals-mcp 和托管端点仍会提供现有的七个工具。

可选启用的包审计命令（尚未发布）

下一次重要的 fundamentals 版本正在准备单独的 canli-fundamentals-audit 命令。此候选版本打包了自己的精确规范 辅助程序、输入核心和 stdio 适配器，以及输入约定。 无需检出仓库。上文现有的仓库示例保持不变；其原有辅助程序位置并不适用于这个新打包的副本。

将经过审核的候选 tarball 放入私有安装后， 使用绝对路径 node_modules/.bin/canli-fundamentals-audit 配置 MCP 客户端， 并提供约定中说明的四个精确输入字段。此命令会列出一个 audit_inputs 工具。 canli-fundamentals-mcp 和托管端点仍会列出已有的七个工具。 新命令尚未发布至 npm；PRIMARY 正在准备重要版本，因此 version0.5.0 保持不变。不要将当前 npm 下载作为此尚未发布命令已可用的证据。

未发布：离线专家提交审计

该仓库候选版本新增了独立的可选命令 canli-expert-submission-audit。 它会审计提供的数据包和评审字节，同时保留完整的已选分母、缺失角色以及未知的人类/专家/权利结果。 请参阅独立打包契约和合成 SDK 工作流。 该命令未包含在已发布的 0.5.0 制品中。默认的七工具服务和 canli-fundamentals-audit 保持现有行为。

未发布：提供文件审计客户端

候选版本新增了 canli-fundamentals-audit-files，这是一个基于现有精简审计的离线便捷命令。它会保留所有已选行、精确的提供字节绑定和未知结果，并在成功前关闭其拥有的唯一 stdio 子进程。请参阅完整的虚构文件工作流。此候选版本不是 npm 发布版本，也不代表安装/采用情况的测量。

canli-fundamentals-audit-files --root "$PACKAGE_ROOT" --reference "$REFERENCE" --expected-reference-sha256 "$REFERENCE_SHA256" --usage "$USAGE" --settings "$SETTINGS"

所有路径都必须是绝对路径；PACKAGE_ROOT 是同一个获准包，REFERENCE_SHA256 固定指向精确的参考字节。五个标志各出现一次。默认的七工具命令和现有审计命令保持原有行为。

提供文件的专家核对（未发布）

候选包命令 canli-expert-submission-files 通过未更改的专家提交核心，审计调用方拥有的本地 gold、受理、证据和评审返回文件。EXPERT_SUBMISSION_FILES.md 提供六个完整的合成输入块和一个私有独占输出工作流。该命令会保留完整的已选分母、缺失角色工作清单、精确的原始绑定，以及未知的人类/专业能力/独立性/权利结果。它不需要 SDK 子进程或网络。这是一个源代码候选版本；未更改的 0.5.0 字段不能证明其已在 npm 上可用或已发布。

提供文件的专家 SDK 客户端（未发布）

可选的 canli-expert-submission-client 会捕获明确提供的私有文件，并通过锁定的 SDK2.1 legacy 协商调用一次现有的本地专家 stdio 审计。EXPERT_SUBMISSION_CLIENT.md 包含六个完整的合成输入和该命令。它会将完整报告私下保存，同时保留原始绑定、所有已选行、缺失角色，以及未知的人类/专业能力/独立性/权利/标签/裁定结果。

观测到的 15s 工作时间与 5s 的关闭/输出/终端预留时间共用一个绝对时钟； 编码后的请求/报告/工具/帧上限会在产生原生影响前强制执行。 成功必须完成已知的同子进程关闭，以及独占的 0600/fsync/回读输出。直接的无 SDK 专家文件命令保持不变。在针对确切新头提交运行自动 CI 之前，此仓库候选版本及其新用例均为已编写但未运行；这不构成任何安装/发布/采用情况或经认证来源的声明。

提供文件的专家受理准备（未发布）

可选的 canli-expert-intake-files 命令会根据四个明确提供的文件和零至 64 个按顺序排列的不透明证据文件，准备完整的专家受理报告。完整的合成工作流 使用包内源代码，且不会启动 SDK 子进程。它会保留完整的已选 N、空白评审数据包和裁定者工作清单；真实人员、专业能力、独立性、权利、标签和准入仍未经验证/为 NULL。私有独占输出会执行 fsync 并回读；如有不确定性，则拒绝操作并保留制品。这是一个仓库中的未发布源代码候选版本；npm 可用性与安装情况是两回事。在此签名源代码的远程 CI 运行之前，夹具为已编写但未运行。

提供字节专家接收准备（未发布）

可选的 canli-expert-intake-prepare 命令通过提供字节准备核心公开一个 filingfacts_prepare_expert_intake 工具。 完整的软件包 SDK 工作流和四份带标记的合成输入文档，请参阅 EXPERT_INTAKE_STDIO.md。 该工具会保留完整的准备报告、两份空白且依据相同金标准的审阅者资料包，以及单独的裁定者工作清单。所有选定项目以及缺失角色／证据的覆盖情况仍然可见；经身份验证的人类、专业知识、独立性、权利、标签和准入状态仍然未知。

原始请求键和所有有界 base64 元数据均会在载荷解码前接收。完整报告会同时以结构化内容和精确 JSON 文本的形式呈现。独立端点在投影和序列化过程中使用同一绝对工作时钟，并在本机写入前立即进行新一轮观察。指南记录了有界自有子进程的关闭方式。此可选命令与现有默认工具表面分离，不会获取来源、招募审阅者、分发资料包，也不会作出权利／准入决定。

提示词和资源（未发布）

三个提示词可一步完成常见任务：known_on_date（company、as_of）、restatement_review（company、可选的 concept）和 peers_as_of（companies、concept、as_of）。在支持补全的客户端中，company 会根据 SEC 股票代码列表补全，concept 会根据纯名称补全。

资源：canli://concepts 列出所有纯名称及其背后的标签；canli://limits 给出需要引用的限制；canli://schemas/{tool} 提供工具的精确 JSON Schemas；canli://examples/{language}/{tool} 提供可运行的调用示例，支持 python、javascript 或 curl。