Canli Fundamentals

canli-fundamentals-mcp

SEC company fundamentals point in time, as an MCP server. For any value a company reported in XBRL, it tells your AI assistant three things: what was first reported, what the latest filing says, and what was known on a given date. Every value comes with the filing behind it.

That difference matters. Apple's diluted EPS for fiscal 2018 was 11.91 in the annual reports of 2018 and 2019, and 2.98 in the 2020 report, after its 4-for-1 split. A backtest that reads today's data for a 2018 decision uses a number nobody saw in 2018. Apple's accounts payable at the end of fiscal 2017 was first reported as $49.05B and changed to $44.24B a year later. Of 3,827 annual periods Apple has reported, 190 now read differently from their first report, not counting 35 per-share and share-count changes from its stock splits.

npx -y canli-fundamentals-mcp

Claude Code:

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

Hosted, no install (claude.ai connectors, ChatGPT, Cursor, or any client that takes a URL):

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

Claude Desktop, Cursor or any MCP client (mcpServers in its config):

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

Then ask things like "What did Apple report as of 31 December 2018?", "Which of Microsoft's annual numbers were restated?", "Show Toyota's revenue since 2015" or "Show every filing that reported Apple's 2017 accounts payable".

Tools

All eight tools are read-only.

A cross-section indexes only the measure asked for in each company's snapshot and keeps none of them in memory, so fifty companies cost about as much memory as one. Checked against an independent Python selection over the same SEC snapshots (scripts/research/fundamentals-pit-check/ in the canlicapital repository): 20 companies on 3 dates, NetIncomeLoss, annual, 60 of 60 identical in value, period, filed date, accession number and changed_after, including 5 where neither side had a value (Meta before its first 10-K, for example). Fiscal years end on different dates, so compare end before comparing values.

Naming a company

company takes a ticker (AAPL), an SEC CIK (320193) or a name (Exxon Mobil, Alphabet, Goldman Sachs). Names are compared without case, punctuation or trailing legal words (Inc, Corp, Holdings), and a result read by name says how it was resolved in company.matched. A name is used only when one company is clearly meant: the only company with that name or name start, or the only one of them with a current ticker (Alphabet Inc. rather than Alphabet Holding Company). Otherwise the error lists the candidates with their CIKs, and find_company shows them ranked.

Some tickers now belong to companies outside the reference. XOM is the SEC's ticker for ExxonMobil Holdings Corp (CIK 2115436), a new holding company; the server reads the covered filer with the same name, Exxon Mobil Corporation (CIK 34088), and says so. Former tickers are not listed: search by name (Twitter) or use the CIK.

Naming a measure

Use a plain name and the server follows the measure across the tags a company has used for it. Apple's revenue was SalesRevenueNet until fiscal 2017 and RevenueFromContractWithCustomerExcludingAssessedTax from 2018; Toyota's figures moved from us-gaap to IFRS. Each value names the tag it came from.

Common variants work too (sales, revenues, EPS, total_assets). Any XBRL tag also works (AccountsPayableCurrent), us-gaap by default; a tag that exists in two taxonomies is read from both, and a prefix picks one (us-gaap:Assets, dei:EntityCommonStockSharesOutstanding). A tag the company stopped using comes back with newer_series, naming the plain name that continues it.

Where the numbers come from, and how you can check them

For every company in its reference, canlicapital.com serves the SEC's XBRL companyfacts response byte for byte, as a gzip snapshot, and names the snapshot's SHA-256 in the company's record. This server:

1. resolves a ticker from https://canlicapital.com/api/v1/company-tickers.json, and a name from the company name index at /api/v1/company-names.json;
2. reads the company record at /company-data/{CIK}.json;
3. downloads the snapshot it names and refuses it unless its SHA-256 matches;
4. computes everything else on your machine.

Those GETs are the only network traffic. Each result names the snapshot (its date, hash, URL and the SEC URL it came from), so you can fetch the same file from the SEC and compare. Snapshots change when the company reference is released again; snapshot.age_days on every result says how old the one you read is.

The ticker list, the name index and company records are kept on disk and used for six hours without asking, then revalidated by their ETag; if the site cannot be reached, the copy on disk is used. With the disk warm, the first call for a company in a new process took 38 to 72 ms in our measurement (AAPL, JPM, MSFT).

How periods are handled:

• A period is its start and end date. A quarter and a year-to-date figure that end on the same day are different periods, and values are never merged across them.
• Durations of 350 to 380 days are annual (52- and 53-week years included). Durations of 80 to 125 days are quarterly, which covers 12- to 17-week quarters such as Kroger's 16-week first quarter. Anything else (six- and nine-month year-to-date figures) appears only under periods: "all".
• A balance (an instant) takes the kind of the report that first carried it: year-end balances are first reported in annual reports, interim balances in 10-Qs and 6-Ks.
• first_reported is the earliest filing by filed date, then accession number. With as_of, only filings made on or before that date exist, for every basis, so nothing filed later can leak in.
• When one filing reports a period under two tags of a plain name, the value comes from the tag that first reported the period, so a second definition in the same filing is not read as a revision.
• Filing-fee exhibits (the ffd taxonomy) and registration statements (424B prospectuses, S- and F- forms) are left out: they repeat facts that are not periodic results.
• A split is recognised when the change matches a split ratio the company reported (StockholdersEquityNoteStockSplitConversionRatio1). With no reported ratio, a per-share or share change by a whole ratio from 2 to 20 is marked split_likely. Both are left out of restatements unless include_splits is set. A value that changed and later went back to its first report is counted in changed_then_reverted, not listed.

Limits

• Values are as the SEC's companyfacts API reports them in the snapshot named with each result. Filings made after the snapshot date are missing: each result gives the snapshot's age_days, and snapshot_note says so when as_of is later than the snapshot.
• tag_change means the first and latest values come from different tags of a plain name. That can be a real restatement or two definitions of the measure; read both filings.
• Results are capped at 10,000 characters of rows, newest first; truncated says when rows were cut. list_concepts and restatements page with offset and give next_offset while rows remain.
• filed is the date a filing reached EDGAR. To avoid lookahead, treat a value as known from the next trading day after it was filed.
• A changed value can be a restatement, a reclassification or a correction; the accession number names the filing to read.
• Coverage is the 12,738 SEC filers in the Canli company reference, 5,277 of them with a current ticker (6,415 tickers). A company outside it returns an error naming its CIK.
• Company-reported data. Not investment advice.

Settings

Part of the Canli MCP family

• canli-validation-mcp: checks whether a backtest is real (deflated Sharpe, probability of overfitting, minimum track record).
• canli-research-mcp: Canli Capital's open research record.

Code MIT. The SEC filings and XBRL facts are U.S. government works in the public domain; Canli Capital's selection and derived data are CC BY 4.0 (credit "Canli Capital (canlicapital.com)").

Repository audit example (Unreleased)

Backtest developers can call the supplied-vintage audit core through the separate local stdio example. It reads the exact reference, usage and settings bytes supplied by the client, keeps every selected row, and makes missing or uncertain outcomes visible. The complete repository checkout and its pinned package dependencies are required. The canonical helper lives outside this npm package; npx canli-fundamentals-mcp and the hosted endpoint continue to expose the existing eight tools.

Opt-in package audit command (Unreleased)

The next substantial fundamentals release is preparing the separate canli-fundamentals-audit command. This candidate packages its own exact canonical helper, supplied-input core and stdio adapter, plus the input contract. It requires no repository checkout. The existing repository example above remains unchanged; its original helper location does not describe this new packaged copy.

After a reviewed candidate tarball has been placed in a private installation, configure an MCP client with the absolute path to node_modules/.bin/canli-fundamentals-audit, and supply the four exact input fields described in the contract. This command lists one audit_inputs tool. canli-fundamentals-mcp and hosted endpoints still list the existing eight tools. The new command has not been published to npm; version0.5.0 is unchanged while PRIMARY assembles the substantial release. Do not use a current npm download as evidence that this Unreleased command is available.

Unreleased: offline expert-submission audit

The repository candidate adds the separate opt-in canli-expert-submission-audit command. It audits supplied packet and review bytes while preserving the complete selected denominator, missing roles and unknown human/expert/rights outcomes. See the standalone packaged contract and synthetic SDK workflow. The command is not included in the already published 0.5.0 artifact. The default seven-tool server and canli-fundamentals-audit retain their existing behavior.

Unreleased supplied-file audit client

The candidate package adds canli-fundamentals-audit-files, an offline convenience command over the existing compact audit. It preserves all selected rows, exact supplied-byte bindings and unknown outcomes, and closes its one owned stdio child before success. See the complete fictional file workflow. This candidate is not an npm release or an installation/adoption measurement.

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

All paths must be absolute; PACKAGE_ROOT is this same admitted package and REFERENCE_SHA256 pins the exact reference bytes. The five flags occur once each. The default seven-tool command and existing audit commands keep their behavior.

Supplied-file expert reconciliation (Unreleased)

The candidate package command canli-expert-submission-files audits caller-owned local gold, intake, evidence and reviewer-return files through the unchanged expert-submission core. EXPERT_SUBMISSION_FILES.md provides six complete synthetic input blocks and a private exclusive-output workflow. The command preserves the full selected denominator, missing-role worklists, exact raw bindings and unknown human/expertise/independence/rights outcomes. It needs no SDK child or network. This is a source candidate; the unchanged 0.5.0 field is not evidence of npm availability or publication.

Supplied-file expert SDK client (Unreleased)

The opt-in canli-expert-submission-client captures explicitly supplied private files and calls the existing local expert stdio audit once through locked SDK2.1 legacy negotiation. EXPERT_SUBMISSION_CLIENT.md contains six complete synthetic inputs and the command. It saves the complete report privately while preserving raw bindings, all selected rows, missing roles and unknown human/expertise/independence/rights/label/adjudication outcomes.

Observed15s work and one5s closure/output/terminal reserve share an absolute clock; encoded request/report/tool/frame bounds are enforced before native effects. Known same-child closure and exclusive0600/fsync/readback output are required for success. The direct no-SDK expert file command remains unchanged. This repository candidate and its new cases are written until exact new-head automaticCI; no installation/publication/adoption or authenticated-source claim follows.

Supplied-file expert intake preparation (Unreleased)

The opt-in canli-expert-intake-files command prepares the complete expert-intake report from four explicit supplied files and zero to64 ordered opaque evidence files. The complete synthetic workflow uses package-local source and starts no SDK child. It preserves full selected-N, blank reviewer packets and adjudicator worklists; real humans, expertise, independence, rights, labels and admission remain unverified/NULL. Private exclusive output is fsynced and read back, with uncertainty refusing and retaining the artifact. This is a repository Unreleased source candidate; npm availability and installation are separate. Fixtures are WRITTEN_UNRUN before this signed source's remote CI.

Supplied-byte expert-intake preparation (Unreleased)

The opt-in canli-expert-intake-prepare command exposes one filingfacts_prepare_expert_intake tool over the supplied-byte preparation core. Use EXPERT_INTAKE_STDIO.md for the complete package SDK workflow and four marked synthetic input documents. The tool retains the entire preparation report, two blank same-gold reviewer packets, and the distinct adjudicator worklist. All selected items and missing-role/evidence coverage remain visible; authenticated humans, expertise, independence, rights, labels and admission remain unknown.

Original request keys and all bounded base64 metadata are admitted before payload decode. The complete report appears both as structured content and exact JSON text. The standalone endpoint uses the same absolute work clock through projection and serialization, followed by a fresh observation immediately before its native write. The guide documents bounded owned-child closure. This opt-in command is separate from the existing default tool surface and does not fetch sources, recruit reviewers, dispatch packets, or make rights/admission decisions.

Prompts and resources (Unreleased)

Three prompts do the common jobs in one step: known_on_date (company, as_of), restatement_review (company, optional concept) and peers_as_of (companies, concept, as_of). In clients that support completion, company completes from the SEC ticker list and concept from the plain names.

Resources: canli://concepts lists every plain name and the tags behind it; canli://limits gives the limits to quote; canli://schemas/{tool} gives a tool's exact JSON Schemas; canli://examples/{language}/{tool} gives a working call in python, javascript or curl.

Companies outside the reference

The reference covers the filers listed on its site. Set CANLI_SEC_LIVE=1 and a company outside it, such as TSMC or Shell, is read live from the SEC (data.sec.gov), with snapshot.read_live and a note saying so. SEC_USER_AGENT sets who the SEC sees. It is off by default, so this server alone contacts only CANLI_API_BASE. The canli-mcp flagship turns it on.

With it on, a company inside the reference is checked too: when the SEC's filing list (data.sec.gov/submissions) shows an annual or quarterly report filed on or after the day its reference snapshot was captured, the SEC's own company facts are read instead. The snapshot block then carries read_live, newer_filing (the form, date and accession number of that report), reference (the snapshot it replaced) and a note, so an answer is never quietly older than the company's latest report.