@pipeworx/mcp-edgar 0.3.0 → 0.3.2

package/README.md

@@ -2,7 +2,7 @@
 
 EDGAR MCP — SEC EDGAR public APIs (free, no auth)
 
-Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 884+ live data sources.
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1337+ live data sources.
 
 ## Tools
 
@@ -23,7 +23,7 @@ Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
 }
 ```
 
-Or connect to the full Pipeworx gateway for access to all 884+ data sources:
+Or connect to the full Pipeworx gateway for access to all 1337+ data sources:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipeworx/mcp-edgar",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "EDGAR MCP — SEC EDGAR public APIs (free, no auth)",
   "type": "module",
   "main": "src/index.ts",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.pipeworx-io/edgar",
   "title": "Edgar",
   "description": "EDGAR MCP — SEC EDGAR public APIs (free, no auth)",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "websiteUrl": "https://pipeworx.io/packs/edgar",
   "repository": {
     "url": "https://github.com/pipeworx-io/mcp-edgar",

package/src/index.ts

@@ -16,6 +16,124 @@ interface McpToolExport {
   provider?: string;
 }
 
+// Reusable entity-resolution helpers for MCP packs. SELF-CONTAINED — no internal
+// imports — so publish-pack.sh can inline it into standalone pack builds the same
+// way it inlines the McpToolExport type.
+//
+// Recurring failure mode across financial packs: callers pass a company NAME
+// ("Apple", "apple inc") where a ticker / CIK / provider symbol is expected, and
+// the pack 404s or throws "not found". `rankMatches` is a generic name-ranker any
+// pack can run over its OWN list (US tickers, B3 tickers, drug names, airports…);
+// `resolveSecEntity` wraps it around the SEC company_tickers.json universe, shared
+// by the packs that key on CIK (edgar, sec).
+
+type MatchKind = 'exact' | 'prefix' | 'word' | 'substring';
+
+interface RankedMatch<T> {
+  item: T;
+  kind: MatchKind;
+  score: number;
+}
+
+const normalize = (s: string): string =>
+  s.toUpperCase().replace(/[.,]/g, '').replace(/\s+/g, ' ').trim();
+
+/**
+ * Rank `items` by how well their name matches `query`:
+ * exact (4) > prefix (3) > whole-word (2) > substring (1). Ties break by shortest
+ * name — the primary entity (e.g. "Apple Inc." over "Apple Hospitality REIT").
+ * Returns only items that match at all, best first. Pure (no I/O).
+ */
+function rankMatches<T>(
+  query: string,
+  items: T[],
+  getName: (item: T) => string,
+): RankedMatch<T>[] {
+  const q = normalize(query);
+  if (!q) return [];
+  const scored: { item: T; kind: MatchKind; score: number; len: number }[] = [];
+  for (const item of items) {
+    const name = getName(item);
+    const n = normalize(name);
+    let kind: MatchKind | null = null;
+    let score = 0;
+    if (n === q) { kind = 'exact'; score = 4; }
+    else if (n.startsWith(q)) { kind = 'prefix'; score = 3; }
+    else if (n.includes(` ${q} `) || n.endsWith(` ${q}`)) { kind = 'word'; score = 2; }
+    else if (n.includes(q)) { kind = 'substring'; score = 1; }
+    if (kind) scored.push({ item, kind, score, len: name.length });
+  }
+  scored.sort((a, b) => b.score - a.score || a.len - b.len);
+  return scored.map(({ item, kind, score }) => ({ item, kind, score }));
+}
+
+interface SecTickerRow { cik_str: number; ticker: string; title: string }
+
+interface SecEntity {
+  ticker: string;
+  cik: string;
+  cik_padded: string;
+  company_name: string;
+  matched_by: 'ticker' | 'company_name';
+  alternatives?: { ticker: string; company_name: string; cik: string }[];
+}
+
+const SEC_TICKERS_URL = 'https://www.sec.gov/files/company_tickers.json';
+
+/**
+ * Resolve a ticker OR company name to its SEC identity (CIK + canonical name).
+ * Exact ticker first (the common, unambiguous case), then fuzzy company-name
+ * fallback so "Apple" / "APPLE" → AAPL's CIK. Throws if nothing matches.
+ *
+ * `headers` lets callers pass their pack's SEC User-Agent — www.sec.gov requires
+ * a UA. `fetchImpl` defaults to global fetch (override in tests).
+ */
+async function resolveSecEntity(
+  query: string,
+  opts: { fetchImpl?: typeof fetch; headers?: Record<string, string> } = {},
+): Promise<SecEntity> {
+  if (typeof query !== 'string' || !query.trim()) {
+    throw new Error('Required argument is missing or empty. Pass a ticker like "AAPL" or a company name like "Apple".');
+  }
+  const doFetch = opts.fetchImpl ?? fetch;
+  const res = await doFetch(SEC_TICKERS_URL, { headers: opts.headers });
+  if (!res.ok) throw new Error(`SEC ticker lookup error: ${res.status}`);
+  const data = (await res.json()) as Record<string, SecTickerRow>;
+  const rows = Object.values(data);
+
+  // 1) Exact ticker match — the common, unambiguous case.
+  const q = query.toUpperCase().trim();
+  for (const r of rows) {
+    if (r.ticker === q) return toEntity(r, 'ticker');
+  }
+
+  // 2) Company-name fallback.
+  const ranked = rankMatches(query, rows, (r) => r.title);
+  if (ranked.length) {
+    const best = toEntity(ranked[0].item, 'company_name');
+    const alts = ranked.slice(1, 4).map((m) => ({
+      ticker: m.item.ticker,
+      company_name: m.item.title,
+      cik: String(m.item.cik_str),
+    }));
+    if (alts.length) best.alternatives = alts;
+    return best;
+  }
+
+  throw new Error(`No SEC company matches "${query}". Pass a ticker like "AAPL" or a company name like "Apple Inc.".`);
+}
+
+function toEntity(r: SecTickerRow, matched_by: 'ticker' | 'company_name'): SecEntity {
+  return {
+    ticker: r.ticker,
+    cik: String(r.cik_str),
+    cik_padded: String(r.cik_str).padStart(10, '0'),
+    company_name: r.title,
+    matched_by,
+  };
+}
+
+
 /**
  * EDGAR MCP — SEC EDGAR public APIs (free, no auth)
  *
@@ -25,6 +143,7 @@ interface McpToolExport {
  * - edgar_company_facts: get structured XBRL financial data for a company
  * - edgar_company_concept: get a specific financial metric over time
  * - edgar_ticker_to_cik: look up CIK from ticker symbol
+ * - edgar_filing_documents: list the documents inside one filing by accession number
  *
  * Note: SEC requires a descriptive User-Agent header per their guidelines.
  */
@@ -86,7 +205,7 @@ const tools: McpToolExport['tools'] = [
       properties: {
         cik: {
           type: 'string',
-          description: 'Company CIK number (e.g., "320193" for Apple). Use edgar_ticker_to_cik to look up if needed.',
+          description: 'Ticker ("NVDA") or CIK number ("320193"). Tickers are auto-resolved to CIKs internally.',
         },
       },
       required: ['cik'],
@@ -164,18 +283,66 @@ const tools: McpToolExport['tools'] = [
   {
     name: 'edgar_ticker_to_cik',
     description:
-      'Resolve a US stock ticker (e.g. "TSLA") to the SEC\'s 10-digit CIK identifier — required by every other SEC tool. Call THIS FIRST when you have a ticker and need to use edgar_company_concept, edgar_company_filings, edgar_company_facts, sec_8k_recent, or any other SEC-keyed tool. Returns {cik, cik_padded, company_name}. Cheap, no rate limit concerns. Most other tools also accept tickers directly and call this internally — only use it explicitly when you want the CIK as data.',
+      'Resolve a US stock ticker (e.g. "TSLA") OR a company name (e.g. "Tesla", "Apple Inc") to the SEC\'s 10-digit CIK identifier — required by every other SEC tool. Call THIS FIRST when you have a ticker/name and need to use edgar_company_concept, edgar_company_filings, edgar_company_facts, sec_8k_recent, or any other SEC-keyed tool. Returns {cik, cik_padded, company_name, ticker, matched_by}; when matched by name it also returns `alternatives` for disambiguation. Cheap, no rate limit concerns. Most other tools also accept tickers/names directly and call this internally — only use it explicitly when you want the CIK as data.',
     inputSchema: {
       type: 'object' as const,
       properties: {
         ticker: {
           type: 'string',
-          description: 'Stock ticker symbol (e.g., "AAPL", "MSFT", "TSLA")',
+          description: 'Stock ticker symbol (e.g., "AAPL", "MSFT", "TSLA") or company name (e.g., "Apple", "Microsoft")',
         },
       },
       required: ['ticker'],
     },
   },
+  {
+    name: 'edgar_xbrl_frames',
+    description:
+      'Compare ONE financial metric across ALL public companies for a single period (SEC XBRL "frames"). PREFER OVER WEB SEARCH for "which companies had the most revenue/net income/assets in <year>", "rank companies by <metric>", cross-company financial comparison. concept is a US-GAAP tag (e.g. "Revenues", "NetIncomeLoss", "Assets", "ResearchAndDevelopmentExpense", "CashAndCashEquivalentsAtCarryingValue"). period is a calendar frame: "CY2023" (annual), "CY2023Q1" (quarter), or "CY2023Q1I" (instant/balance-sheet, period-end). Returns companies + values, sorted descending by default. Differs from edgar_company_concept (one company over time) — this is one period across every filer.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        concept: { type: 'string', description: 'US-GAAP (or dei) tag, e.g. "Revenues", "NetIncomeLoss", "Assets", "ResearchAndDevelopmentExpense".' },
+        period: { type: 'string', description: 'Calendar frame: "CY2023" (annual duration), "CY2023Q1" (quarterly duration), or "CY2023Q1I" (instant, balance-sheet items at period end).' },
+        unit: { type: 'string', description: 'Unit of measure (default "USD"). Use "shares" for share counts, "USD-per-shares" for per-share.' },
+        taxonomy: { type: 'string', description: 'Taxonomy: "us-gaap" (default) or "dei".' },
+        sort: { type: 'string', description: '"desc" (default, largest first) or "asc".', enum: ['desc', 'asc'] },
+        limit: { type: 'number', description: 'Max companies to return (1-200, default 25).' },
+      },
+      required: ['concept', 'period'],
+    },
+  },
+  {
+    name: 'edgar_filing_documents',
+    description:
+      'AUTHORITATIVE list of the SEC filing documents inside ONE specific filing, by accession number. Retrieve a filing / its contents / attachments: pass the accession (e.g. "0000320193-25-000079", with or without dashes) plus the filer\'s ticker ("AAPL") or CIK ("320193"). Returns every document in the filing folder — the primary document (10-K / 10-Q / 8-K body), all exhibits, and XBRL files — each with name, type, size, and a direct https URL, plus the filing\'s form type, filing date, and human -index.html page. Set include_primary_text:true to also pull the primary document\'s text (HTML stripped to plaintext, ~40k chars). Use to list a 10-K / 10-Q / 8-K\'s exhibits, retrieve filing contents/attachments, or fetch the text of a filing. You can pass an exact accession, OR just a ticker + form_type to auto-resolve the latest matching filing (no accession lookup needed). Examples: edgar_filing_documents({ticker: "NVDA", form_type: "10-K"}) for the documents in NVIDIA\'s latest annual report; edgar_filing_documents({accession: "0000320193-25-000079", ticker: "AAPL", include_primary_text: true}) for a specific filing\'s text.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        accession: {
+          type: 'string',
+          description: 'Optional SEC accession number of a specific filing, with or without dashes (e.g. "0000320193-25-000079"). Omit it to auto-resolve the latest filing — pass form_type instead.',
+        },
+        ticker: {
+          type: 'string',
+          description: 'The filer\'s ticker (e.g. "AAPL", "NVDA") or company name. Provide this OR cik. Tickers are auto-resolved to CIKs.',
+        },
+        cik: {
+          type: 'string',
+          description: 'The filer\'s CIK number (e.g. "320193"). Provide this OR ticker.',
+        },
+        form_type: {
+          type: 'string',
+          description: 'When accession is omitted, the form type of the latest filing to fetch, e.g. "10-K", "10-Q", "8-K", "DEF 14A". Omit both accession and form_type to get the single most recent filing of any type.',
+        },
+        include_primary_text: {
+          type: 'boolean',
+          description: 'When true, also fetch the primary document and return its text (HTML stripped to plaintext, truncated to ~40,000 chars). Default false.',
+        },
+      },
+      required: [],
+    },
+  },
 ];
 
 // ── Helpers ─────────────────────────────────────────────────────────
@@ -251,31 +418,11 @@ async function searchFilings(
   };
 }
 
+// Resolves a ticker OR company name ("AAPL", "Apple", "apple inc") to its SEC
+// identity. Delegates to the shared resolver so the ticker/name-resolution logic
+// stays consistent across every SEC-keyed pack (edgar, sec).
 async function tickerToCik(ticker: string) {
-  if (typeof ticker !== 'string' || !ticker.trim()) {
-    throw new Error('Required argument "ticker" is missing or empty. Pass a ticker symbol like "AAPL" or "MSFT".');
-  }
-  const res = await fetch('https://www.sec.gov/files/company_tickers.json', { headers: SEC_HEADERS });
-  if (!res.ok) throw new Error(`SEC ticker lookup error: ${res.status}`);
-
-  const data = (await res.json()) as Record<
-    string,
-    { cik_str: number; ticker: string; title: string }
-  >;
-
-  const upperTicker = ticker.toUpperCase().trim();
-  for (const entry of Object.values(data)) {
-    if (entry.ticker === upperTicker) {
-      return {
-        ticker: entry.ticker,
-        cik: String(entry.cik_str),
-        cik_padded: String(entry.cik_str).padStart(10, '0'),
-        company_name: entry.title,
-      };
-    }
-  }
-
-  throw new Error(`Ticker "${ticker}" not found in SEC company tickers`);
+  return resolveSecEntity(ticker, { headers: SEC_HEADERS });
 }
 
 async function resolveCik(tickerOrCik: string): Promise<string> {
@@ -356,7 +503,171 @@ async function companyFilings(tickerOrCik: string, formType?: string, limit?: nu
   };
 }
 
-async function companyFacts(cik: string) {
+// ── Filing documents (list docs inside one filing by accession) ─────
+
+// Normalize an accession number (dashed or undashed) to both forms.
+// SEC accessions are 18 digits shaped 10-2-6 (e.g. 0000320193-25-000079).
+function normalizeAccession(raw: string): { dashed: string; nodash: string } | null {
+  const digits = String(raw ?? '').replace(/\D/g, '');
+  if (digits.length !== 18) return null;
+  const dashed = `${digits.slice(0, 10)}-${digits.slice(10, 12)}-${digits.slice(12)}`;
+  return { dashed, nodash: digits };
+}
+
+// Strip an HTML document to readable plaintext. Workers have no DOMParser;
+// drop script/style blocks, remove tags, decode entities, collapse whitespace.
+function htmlToText(html: string): string {
+  return (decodeEntities(
+    html
+      .replace(/<(script|style)[\s\S]*?<\/\1>/gi, ' ')
+      .replace(/<[^>]+>/g, ' '),
+  ) ?? '')
+    .replace(/[ \t\f\v]+/g, ' ')
+    .replace(/\s*\n\s*/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+async function filingDocuments(
+  accession: string | undefined,
+  tickerOrCik: string,
+  includePrimaryText?: boolean,
+  wantFormTypeArg?: string,
+) {
+  if (typeof tickerOrCik !== 'string' || !tickerOrCik.trim()) {
+    throw new Error(
+      'A ticker or CIK is required. Pass ticker ("AAPL") or cik ("320193"), plus either an accession or a form_type (e.g. edgar_filing_documents({ticker: "NVDA", form_type: "10-K"}) for the latest 10-K).',
+    );
+  }
+  const cik = await resolveCik(tickerOrCik);
+  // Accession is optional: when omitted, resolve the latest filing matching
+  // form_type (or the single most recent filing of any type) so one-shot
+  // questions like "documents in NVIDIA's latest 10-K" work without the caller
+  // first having to look up an accession number.
+  let acc = accession ? normalizeAccession(accession) : null;
+  if (accession && !acc) {
+    throw new Error(
+      `Invalid accession "${accession}". A SEC accession number is 18 digits shaped 10-2-6 (e.g. "0000320193-25-000079", with or without dashes). Get accession numbers from edgar_company_filings, or omit accession and pass form_type to auto-resolve the latest.`,
+    );
+  }
+  if (!acc) {
+    const wantForm = wantFormTypeArg?.trim().toUpperCase();
+    const subRes = await fetch(`${DATA_BASE}/submissions/CIK${padCik(cik)}.json`, { headers: SEC_HEADERS });
+    if (!subRes.ok) throw new Error(`SEC submissions lookup failed (HTTP ${subRes.status}) resolving the latest filing for ${tickerOrCik}.`);
+    const sub = (await subRes.json()) as { filings?: { recent?: { accessionNumber?: string[]; form?: string[] } } };
+    const r = sub.filings?.recent;
+    const forms = r?.form ?? [];
+    const accs = r?.accessionNumber ?? [];
+    const idx = wantForm ? forms.findIndex((f) => f.toUpperCase() === wantForm) : 0;
+    if (idx < 0 || !accs[idx]) {
+      throw new Error(
+        `No ${wantForm ?? 'recent'} filing found for ${tickerOrCik} in the recent index. Use edgar_company_filings({ticker:"${tickerOrCik}"${wantForm ? `, form_type:"${wantForm}"` : ''}}) to list available filings, then pass an accession.`,
+      );
+    }
+    acc = normalizeAccession(accs[idx]);
+    if (!acc) throw new Error('Failed to resolve a valid accession from the submissions index.');
+  }
+  const cikNoZeros = String(Number(cik.replace(/\D/g, ''))); // archive path uses CIK with no leading zeros
+  const paddedCik = padCik(cik);
+
+  // Match the accession in the filer's submissions to enrich with form/date/primaryDoc.
+  let company: string | null = null;
+  let formType: string | null = null;
+  let filingDate: string | null = null;
+  let primaryDocument: string | null = null;
+  let primaryDocDescription: string | null = null;
+  try {
+    const subRes = await fetch(`${DATA_BASE}/submissions/CIK${paddedCik}.json`, { headers: SEC_HEADERS });
+    if (subRes.ok) {
+      const sub = (await subRes.json()) as {
+        name?: string;
+        filings?: {
+          recent?: {
+            accessionNumber?: string[];
+            form?: string[];
+            filingDate?: string[];
+            primaryDocument?: string[];
+            primaryDocDescription?: string[];
+          };
+        };
+      };
+      company = sub.name ?? null;
+      const r = sub.filings?.recent;
+      if (r?.accessionNumber) {
+        const i = r.accessionNumber.indexOf(acc.dashed);
+        if (i >= 0) {
+          formType = r.form?.[i] ?? null;
+          filingDate = r.filingDate?.[i] ?? null;
+          primaryDocument = r.primaryDocument?.[i] ?? null;
+          primaryDocDescription = r.primaryDocDescription?.[i] ?? null;
+        }
+      }
+    }
+  } catch {
+    // Metadata enrichment is best-effort; the document directory below is the core payload.
+  }
+
+  const folder = `https://www.sec.gov/Archives/edgar/data/${cikNoZeros}/${acc.nodash}`;
+  const idxRes = await fetch(`${folder}/index.json`, { headers: SEC_HEADERS });
+  if (idxRes.status === 404) {
+    throw new Error(
+      `No filing found for accession ${acc.dashed} — that accession number does not exist in SEC EDGAR (double-check the digits; it may belong to a different filer). Use edgar_company_filings({ticker_or_cik: "${tickerOrCik}"}) to list this company's real accession numbers.`,
+    );
+  }
+  if (!idxRes.ok) throw new Error(`SEC EDGAR filing index error: ${idxRes.status}`);
+  const idx = (await idxRes.json()) as {
+    directory?: { item?: { name: string; type?: string; size?: string | number; 'last-modified'?: string }[] };
+  };
+
+  const items = idx.directory?.item ?? [];
+  const documents = items.map((it) => ({
+    name: it.name,
+    type: it.type ?? null,
+    ...(it.name === primaryDocument && primaryDocDescription ? { description: primaryDocDescription } : {}),
+    size: it.size !== undefined && it.size !== '' ? Number(it.size) : null,
+    last_modified: it['last-modified'] ?? null,
+    url: `${folder}/${it.name}`,
+  }));
+
+  const result: Record<string, unknown> = {
+    accession: acc.dashed,
+    cik: cikNoZeros,
+    company,
+    form_type: formType,
+    filing_date: filingDate,
+    primary_document: primaryDocument,
+    filing_url: `${folder}/${acc.dashed}-index.html`,
+    documents,
+  };
+
+  if (includePrimaryText && primaryDocument) {
+    try {
+      const docUrl = `${folder}/${primaryDocument}`;
+      const docRes = await fetch(docUrl, { headers: { 'User-Agent': SEC_HEADERS['User-Agent'] } });
+      if (docRes.ok) {
+        const body = await docRes.text();
+        const isHtml = /\.x?html?$/i.test(primaryDocument) || /^\s*</.test(body);
+        const text = isHtml ? htmlToText(body) : body;
+        result.primary_text = text.length > 40000 ? text.slice(0, 40000) + '\n…[truncated]' : text;
+      } else {
+        result.primary_text = null;
+        result.primary_text_error = `fetch ${docRes.status}`;
+      }
+    } catch (e) {
+      result.primary_text = null;
+      result.primary_text_error = String(e);
+    }
+  }
+
+  return result;
+}
+
+async function companyFacts(cikOrTicker: string) {
+  // Was the only EDGAR tool that skipped resolveCik() — it called padCik()
+  // directly, so a ticker ("NVDA") got its letters stripped -> "0000000000" ->
+  // 404, and a missing arg crashed on .replace of undefined. Route through
+  // resolveCik like every sibling: validates the arg and resolves tickers.
+  const cik = await resolveCik(cikOrTicker);
   const paddedCik = padCik(cik);
   const res = await fetch(`${DATA_BASE}/api/xbrl/companyfacts/CIK${paddedCik}.json`, {
     headers: SEC_HEADERS,
@@ -465,6 +776,22 @@ const CONCEPT_CANDIDATES: Record<string, string[]> = {
     'CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents',
   ],
   longtermdebt: ['LongTermDebt', 'LongTermDebtNoncurrent'],
+  // Common concepts an LLM asks for that were MISSING → 404 (net income was
+  // covered but these weren't). Keys are bare-alphanumeric (the lookup strips
+  // spaces/punctuation), so "total assets"/"earnings per share" etc. all match.
+  assets: ['Assets'],
+  totalassets: ['Assets'],
+  liabilities: ['Liabilities'],
+  totalliabilities: ['Liabilities'],
+  stockholdersequity: ['StockholdersEquity', 'StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest'],
+  equity: ['StockholdersEquity', 'StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest'],
+  eps: ['EarningsPerShareDiluted', 'EarningsPerShareBasic'],
+  earningspershare: ['EarningsPerShareDiluted', 'EarningsPerShareBasic'],
+  earningspersharediluted: ['EarningsPerShareDiluted', 'EarningsPerShareBasic'],
+  earningspersharebasic: ['EarningsPerShareBasic', 'EarningsPerShareDiluted'],
+  grossprofit: ['GrossProfit'],
+  operatingincome: ['OperatingIncomeLoss'],
+  operatingincomeloss: ['OperatingIncomeLoss'],
   // ── XBRL-name fallbacks (drove 80-of-84 EDGAR errors in 48h analytics) ──
   longtermdebtnoncurrent: ['LongTermDebtNoncurrent', 'LongTermDebt'],
   salesrevenuenet: ['SalesRevenueNet', 'Revenues', 'RevenueFromContractWithCustomerExcludingAssessedTax'],
@@ -493,6 +820,31 @@ const CONCEPT_CANDIDATES: Record<string, string[]> = {
   ],
 };
 
+// Annual-report forms. 10-K/10-K/A = domestic; 20-F/40-F (+ amendments) =
+// foreign private issuers (IFRS filers). The concept reader filtered to 10-K
+// only, which silently dropped every foreign filer's data even when the tag
+// existed → 404s / empty results.
+const ANNUAL_FORMS = new Set(['10-K', '10-K/A', '20-F', '20-F/A', '40-F', '40-F/A']);
+
+// ifrs-full taxonomy fallback for foreign private issuers (they report under
+// ifrs-full, not us-gaap). Keyed by the same normalized metric name; tried only
+// when the us-gaap candidates all miss, so domestic lookups pay no extra call.
+const IFRS_FALLBACK: Record<string, string[]> = {
+  revenue: ['Revenue', 'RevenueFromContractsWithCustomers'],
+  revenues: ['Revenue', 'RevenueFromContractsWithCustomers'],
+  revenuefromcontractwithcustomerexcludingassessedtax: ['Revenue', 'RevenueFromContractsWithCustomers'],
+  salesrevenuenet: ['Revenue', 'RevenueFromContractsWithCustomers'],
+  netincome: ['ProfitLoss', 'ProfitLossAttributableToOwnersOfParent'],
+  netincomeloss: ['ProfitLoss', 'ProfitLossAttributableToOwnersOfParent'],
+  profitloss: ['ProfitLoss', 'ProfitLossAttributableToOwnersOfParent'],
+  cash: ['CashAndCashEquivalents'],
+  cashandcashequivalentsatcarryingvalue: ['CashAndCashEquivalents'],
+  assets: ['Assets'],
+  liabilities: ['Liabilities'],
+  stockholdersequity: ['Equity', 'EquityAttributableToOwnersOfParent'],
+  equity: ['Equity', 'EquityAttributableToOwnersOfParent'],
+};
+
 async function companyConcept(cikOrTicker: string, concept: string) {
   // Auto-resolve ticker → CIK so callers can pass "AAPL" not "320193".
   // Production analytics: 11% errors on edgar largely from LLMs passing
@@ -500,7 +852,11 @@ async function companyConcept(cikOrTicker: string, concept: string) {
   const cik = await resolveCik(cikOrTicker);
   const paddedCik = padCik(cik);
 
-  const candidates = CONCEPT_CANDIDATES[concept.trim().toLowerCase()] ?? [concept];
+  // Normalize the lookup key to bare alphanumerics so natural-language input
+  // ("net income", "Long-Term Debt", "earnings per share") matches the no-space
+  // map keys — the #1 edgar_company_concept error was "net income" (with a space)
+  // missing the `netincome` key → 404.
+  const candidates = CONCEPT_CANDIDATES[concept.trim().toLowerCase().replace(/[^a-z0-9]/g, '')] ?? [concept];
 
   type ConceptDoc = {
     cik: number;
@@ -523,25 +879,68 @@ async function companyConcept(cikOrTicker: string, concept: string) {
   // $26.9B/FY2022 figure; freshest-data-wins returns the correct $215.9B.
   let lastStatus = 0;
   const found: { doc: ConceptDoc; latestEnd: string }[] = [];
-  for (const candidate of candidates) {
-    const r = await fetch(
-      `${DATA_BASE}/api/xbrl/companyconcept/CIK${paddedCik}/us-gaap/${encodeURIComponent(candidate)}.json`,
-      { headers: SEC_HEADERS },
-    );
-    if (!r.ok) { lastStatus = r.status; continue; }
-    const doc = (await r.json()) as ConceptDoc;
-    let latestEnd = '';
-    for (const values of Object.values(doc.units)) {
-      for (const e of values) {
-        if (e.form !== '10-K' && e.form !== '10-K/A') continue;
-        if ((e.end ?? '') > latestEnd) latestEnd = e.end ?? '';
+  const tryNamespace = async (ns: string, tags: string[]) => {
+    for (const candidate of tags) {
+      const r = await fetch(
+        `${DATA_BASE}/api/xbrl/companyconcept/CIK${paddedCik}/${ns}/${encodeURIComponent(candidate)}.json`,
+        { headers: SEC_HEADERS },
+      );
+      if (!r.ok) { lastStatus = r.status; continue; }
+      const doc = (await r.json()) as ConceptDoc;
+      let latestEnd = '';
+      for (const values of Object.values(doc.units)) {
+        for (const e of values) {
+          if (!ANNUAL_FORMS.has(e.form)) continue;
+          if ((e.end ?? '') > latestEnd) latestEnd = e.end ?? '';
+        }
       }
+      found.push({ doc, latestEnd });
+    }
+  };
+  await tryNamespace('us-gaap', candidates);
+  // Only try the ifrs-full taxonomy when us-gaap returned nothing — foreign
+  // private issuers file under ifrs-full (form 20-F/40-F). Domestic (us-gaap)
+  // lookups short-circuit here and pay no extra request.
+  if (found.length === 0) {
+    const ifrs = IFRS_FALLBACK[concept.trim().toLowerCase().replace(/[^a-z0-9]/g, '')] ?? [];
+    if (ifrs.length) await tryNamespace('ifrs-full', ifrs);
+  }
+  // Fallback: the filer tags this metric under a name not in our candidate list
+  // (very common for debt / lease / segment concepts — e.g. Ford dropped
+  // LongTermDebtNoncurrent, many filers use LongTermDebtAndCapitalLease...). Pull
+  // the full facts once and find the freshest us-gaap tag whose NAME matches the
+  // concept keywords, preferring balance-sheet stock tags over cash-flow tags.
+  if (found.length === 0) {
+    const norm = (s: string) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+    const tokens = candidates.map(norm).filter((t) => t.length >= 3);
+    const factsRes = await fetch(`${DATA_BASE}/api/xbrl/companyfacts/CIK${paddedCik}.json`, { headers: SEC_HEADERS });
+    if (factsRes.ok && tokens.length) {
+      const facts = (await factsRes.json()) as { entityName?: string; facts?: { 'us-gaap'?: Record<string, { label?: string; description?: string; units: Record<string, ConceptDoc['units'][string]> }> } };
+      const gaap = facts.facts?.['us-gaap'] ?? {};
+      const FLOW = /^(ProceedsFrom|RepaymentsOf|PaymentsOf|IncreaseDecrease|AmortizationOf|Gain|Loss)/;
+      const matches: { isFlow: boolean; latestEnd: string; doc: ConceptDoc }[] = [];
+      for (const [tag, entry] of Object.entries(gaap)) {
+        if (!tokens.some((t) => norm(tag).includes(t))) continue;
+        let latestEnd = '';
+        for (const values of Object.values(entry.units)) {
+          for (const e of values) {
+            if (e.form !== '10-K' && e.form !== '10-K/A') continue;
+            if ((e.end ?? '') > latestEnd) latestEnd = e.end ?? '';
+          }
+        }
+        matches.push({
+          isFlow: FLOW.test(tag),
+          latestEnd,
+          doc: { cik: Number(cik), entityName: facts.entityName ?? '', tag, taxonomy: 'us-gaap', label: entry.label ?? tag, description: entry.description ?? '', units: entry.units },
+        });
+      }
+      matches.sort((a, b) => Number(a.isFlow) - Number(b.isFlow) || (b.latestEnd ?? '').localeCompare(a.latestEnd ?? ''));
+      if (matches.length) found.push({ doc: matches[0].doc, latestEnd: matches[0].latestEnd });
     }
-    found.push({ doc, latestEnd });
   }
   if (found.length === 0) {
     throw new Error(
-      `SEC EDGAR company concept error: ${lastStatus} — none of the candidate concepts ${JSON.stringify(candidates)} exist for CIK ${paddedCik}. Use edgar_company_facts({cik: "${cikOrTicker}"}) to see every concept this filer reports.`,
+      `SEC EDGAR company concept error: ${lastStatus} — none of the candidate concepts ${JSON.stringify(candidates)} exist for CIK ${paddedCik}, and no us-gaap tag matched. Use edgar_company_facts({cik: "${cikOrTicker}"}) to see every concept this filer reports.`,
     );
   }
   found.sort((a, b) => (b.latestEnd ?? '').localeCompare(a.latestEnd ?? ''));
@@ -564,7 +963,7 @@ async function companyConcept(cikOrTicker: string, concept: string) {
   const dedup = new Map<string, { entry: Raw; unit: string }>();
   for (const [unit, values] of Object.entries(data.units)) {
     for (const e of values) {
-      if (e.form !== '10-K' && e.form !== '10-K/A') continue;
+      if (!ANNUAL_FORMS.has(e.form)) continue; // 10-K (+/A) domestic, 20-F/40-F (+/A) foreign
       const key = `${unit}|${e.fy ?? ''}|${e.fp ?? 'FY'}|${e.end ?? ''}`;
       const prior = dedup.get(key);
       if (!prior || (e.filed ?? '') > (prior.entry.filed ?? '')) {
@@ -980,12 +1379,69 @@ async function callTool(name: string, args: Record<string, unknown>): Promise<un
     case 'edgar_fund_holdings':
       return fundHoldings(args.ticker as string, args.limit as number | undefined);
     case 'edgar_company_concept':
-      return companyConcept(args.cik as string, args.concept as string);
+      // Accept `ticker_or_cik` too: the schema/handler use `cik` (which takes a
+      // ticker or CIK) but the sibling tools use `ticker_or_cik` and the error
+      // message names it — agents naturally pass it and were rejected.
+      return companyConcept((args.cik ?? args.ticker_or_cik) as string, args.concept as string);
+    case 'edgar_filing_documents':
+      return filingDocuments(
+        args.accession as string | undefined,
+        (args.cik ?? args.ticker ?? args.ticker_or_cik) as string,
+        args.include_primary_text as boolean | undefined,
+        args.form_type as string | undefined,
+      );
     case 'edgar_ticker_to_cik':
       return tickerToCik(args.ticker as string);
+    case 'edgar_xbrl_frames':
+      return xbrlFrames(args);
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
 }
 
+interface FrameDatum { cik?: number; entityName?: string; val?: number; start?: string; end?: string; fy?: number; fp?: string; form?: string }
+
+async function xbrlFrames(args: Record<string, unknown>) {
+  const concept = String(args.concept ?? '').trim().replace(/[^A-Za-z0-9]/g, '');
+  if (!concept) throw new Error('Required argument "concept" is missing (a US-GAAP tag, e.g. "Revenues", "NetIncomeLoss", "Assets").');
+  const period = String(args.period ?? '').trim().toUpperCase().replace(/[^A-Z0-9]/g, '');
+  if (!/^CY\d{4}(Q[1-4]I?)?$/.test(period)) {
+    throw new Error('Required argument "period" must be a calendar frame: "CY2023" (annual), "CY2023Q1" (quarter), or "CY2023Q1I" (instant). Got: ' + (args.period ?? ''));
+  }
+  const taxonomy = String(args.taxonomy ?? 'us-gaap').trim().toLowerCase() === 'dei' ? 'dei' : 'us-gaap';
+  const unit = String(args.unit ?? 'USD').trim() || 'USD';
+  const sortDesc = String(args.sort ?? 'desc').toLowerCase() !== 'asc';
+  const limit = Math.min(200, Math.max(1, Number(args.limit) || 25));
+
+  const url = `${DATA_BASE}/api/xbrl/frames/${taxonomy}/${encodeURIComponent(concept)}/${encodeURIComponent(unit)}/${period}.json`;
+  const res = await fetch(url, { headers: SEC_HEADERS });
+  if (res.status === 404) {
+    return { error: 'not_found', concept, period, unit, taxonomy, message: `No SEC frame for ${taxonomy}/${concept}/${unit}/${period}. Check the tag spelling/casing, unit (USD vs shares), and period type (add "I" for balance-sheet/instant items like Assets).` };
+  }
+  if (!res.ok) throw new Error(`SEC frames error: ${res.status}`);
+  const data = (await res.json()) as { taxonomy?: string; tag?: string; uom?: string; label?: string; description?: string; data?: FrameDatum[] };
+  const rows = (data.data ?? []).slice().sort((a, b) => sortDesc ? (b.val ?? 0) - (a.val ?? 0) : (a.val ?? 0) - (b.val ?? 0));
+
+  return {
+    concept,
+    period,
+    unit,
+    taxonomy,
+    label: data.label ?? null,
+    companies_reporting: rows.length,
+    returned: Math.min(rows.length, limit),
+    sort: sortDesc ? 'desc' : 'asc',
+    source: 'SEC EDGAR XBRL frames (data.sec.gov)',
+    note: 'Values are AS-FILED in each company\'s XBRL submission for this calendar frame. Extreme outliers are often filer reporting errors (wrong units/scale) — cross-check surprising top values with edgar_company_concept before treating a ranking as authoritative.',
+    companies: rows.slice(0, limit).map((r) => ({
+      cik: r.cik ?? null,
+      entity: r.entityName ?? null,
+      value: r.val ?? null,
+      period_start: r.start ?? null,
+      period_end: r.end ?? null,
+      form: r.form ?? null,
+    })),
+  };
+}
+
 export default { tools, callTool, meter: { credits: 10 } } satisfies McpToolExport;