@pipeworx/mcp-edgar 0.3.9 → 0.3.11

package/README.md

@@ -2,7 +2,7 @@
 
 The Securities and Exchange Commission's filings database. Every public company in the US files here, every filing is timestamped and immutable, and every disclosure (revenue, debt, risk factors, executive compensation, M&A activity, insider trading) is structured for machine retrieval. Free and authoritative.
 
-Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1784+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1819+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.
 
 ## Why this matters for AI agents
 
@@ -106,7 +106,7 @@ directly, instead of just this one's:
 }
 ```
 
-Both URLs reach the same gateway and the same 1784+ data sources. The
+Both URLs reach the same gateway and the same 1819+ data sources. The
 only difference is which pack's tools are listed **directly**; `ask_pipeworx`
 reaches all of them from either one.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipeworx/mcp-edgar",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "EDGAR MCP — SEC EDGAR public APIs (free, no auth)",
   "type": "module",
   "main": "src/index.ts",
@@ -26,7 +26,7 @@
     "@cloudflare/workers-types": "^4.20260405.1"
   },
   "pipeworx": {
-    "sourceHash": "v1-d35d4a284237ace3314859c5df49ad1b77a0a9e2e7696d3f0b601f112b20e42a",
-    "sourceCommit": "3723e46c6d115bd4a1fd2175e6bf758555e7cb50"
+    "sourceHash": "v1-7ce3b2ab39a6713c682f44a33fe013a7e07b55298b5e01883e16f33b0d1ab1d4",
+    "sourceCommit": "a03f96ed672b8c149593c64ecbf30280cabf084c"
   }
 }

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.9",
+  "version": "0.3.11",
   "websiteUrl": "https://pipeworx.io/packs/edgar",
   "repository": {
     "url": "https://github.com/pipeworx-io/mcp-edgar",

package/src/index.ts

@@ -699,6 +699,16 @@ const normalize = (s: string): string =>
  * 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).
+ *
+ * `prefix` requires a WORD BOUNDARY (`n.startsWith(q + ' ')`), not a bare
+ * `startsWith`. A bare `startsWith` let "ZOOM" claim "ZOOMCAR HOLDINGS INC" at
+ * the SAME tier as "Apple" claiming "APPLE INC." — "Zoomcar" is a different
+ * word that happens to begin with the same letters, not the brand name plus a
+ * corporate-form suffix. That conflation is what sent resolve_entity("Zoom")
+ * to Zoomcar and resolve_entity("Audi") to AudioEye Inc (fleet #2776's
+ * mis-resolution fixture) — both now correctly fall through to the weaker
+ * `substring` tier instead of tying with a genuine word-boundary prefix hit
+ * like "Palantir" -> "Palantir Technologies Inc." (fleet #3100).
  */
 function rankMatches<T>(
   query: string,
@@ -714,7 +724,7 @@ function rankMatches<T>(
     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.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 });
@@ -731,7 +741,15 @@ interface SecEntity {
   cik_padded: string;
   company_name: string;
   matched_by: 'ticker' | 'company_name';
-  alternatives?: { ticker: string; company_name: string; cik: string }[];
+  /**
+   * The `rankMatches` kind that won, when `matched_by` is `'company_name'`
+   * (a ticker hit has no kind — it did not go through ranking at all). Lets a
+   * caller tell a word-boundary PREFIX hit ("Palantir" -> "Palantir
+   * Technologies Inc.") from a weaker `word`/`substring` guess, which
+   * `matched_by: 'company_name'` alone cannot (fleet #3100).
+   */
+  matched_kind?: MatchKind;
+  alternatives?: { ticker: string; company_name: string; cik: string; kind: MatchKind }[];
 }
 
 const SEC_TICKERS_URL = 'https://www.sec.gov/files/company_tickers.json';
@@ -767,10 +785,12 @@ async function resolveSecEntity(
   const ranked = rankMatches(query, rows, (r) => r.title);
   if (ranked.length) {
     const best = toEntity(ranked[0].item, 'company_name');
+    best.matched_kind = ranked[0].kind;
     const alts = ranked.slice(1, 4).map((m) => ({
       ticker: m.item.ticker,
       company_name: m.item.title,
       cik: String(m.item.cik_str),
+      kind: m.kind,
     }));
     if (alts.length) best.alternatives = alts;
     return best;
@@ -1238,7 +1258,7 @@ const tools: McpToolExport['tools'] = [
         concept: {
           type: 'string',
           description:
-            'REQUIRED (alias `metric`). Metric name. Common: "Revenue" / "Revenues", "NetIncomeLoss", "Cash", "Assets", "Liabilities", "StockholdersEquity", "EarningsPerShareDiluted", "LongTermDebt".',
+            'REQUIRED (alias `metric`). Metric name. Common: "Revenue" / "Revenues", "NetIncomeLoss", "Cash", "Assets", "Liabilities", "StockholdersEquity", "EarningsPerShareDiluted", "LongTermDebt", "SharesOutstanding" (newest cover-page count, dei), "Capex", "OperatingCashFlow", "ResearchAndDevelopment", "SGA", "CostOfRevenue", "DilutedShares", "PublicFloat". Exact us-gaap or dei tag names also work.',
         },
         period: {
           type: 'string',
@@ -3128,6 +3148,17 @@ async function companyFacts(cikOrTicker: string) {
 // Anything not in the table still falls through to [concept] (the bare
 // literal), so we don't regress for niche concepts not yet observed in
 // failures.
+// Cover-page tags live in the `dei` taxonomy, not us-gaap. Until 2026-10-16
+// every candidate was fetched under /us-gaap/, so the dei tag listed below for
+// "shares outstanding" 404'd on every filer and
+// edgar_company_concept({concept:"EntityCommonStockSharesOutstanding"}) told
+// callers "this filer reports no XBRL tag matching ..." for Tesla, which has 67
+// such facts (latest 3,949,547,394 at 2026-07-16). A report built on that
+// answer took the share count from a stale 10-Q cover instead and was off 5%
+// on every per-share number. Resolve the namespace per TAG, not per lookup.
+const DEI_TAGS = new Set(['EntityCommonStockSharesOutstanding', 'EntityPublicFloat']);
+const namespaceForTag = (defaultNs: string, tag: string): string => (DEI_TAGS.has(tag) ? 'dei' : defaultNs);
+
 const CONCEPT_CANDIDATES: Record<string, string[]> = {
   // ── friendly names ────────────────────────────────────────────────
   revenue: ['RevenueFromContractWithCustomerExcludingAssessedTax', 'Revenues', 'SalesRevenueNet'],
@@ -3145,6 +3176,31 @@ const CONCEPT_CANDIDATES: Record<string, string[]> = {
   sharesoutstanding: ['CommonStockSharesOutstanding', 'EntityCommonStockSharesOutstanding', 'CommonStockSharesIssued'],
   commonsharesoutstanding: ['CommonStockSharesOutstanding', 'EntityCommonStockSharesOutstanding', 'CommonStockSharesIssued'],
   commonstocksharesoutstanding: ['CommonStockSharesOutstanding', 'EntityCommonStockSharesOutstanding'],
+  // The cash-flow and expense lines an equity model needs. Measured 2026-10-16:
+  // a routed "Tesla capex Q2 2026" question reached this tool as
+  // concept:"CapitalExpenditures", which no filer tags, and the answer was
+  // "reports no matching XBRL tag" — a miss on a figure every 10-Q carries as
+  // PaymentsToAcquirePropertyPlantAndEquipment. The report that asked went to a
+  // third-party site for it instead.
+  capex: ['PaymentsToAcquirePropertyPlantAndEquipment', 'PaymentsToAcquireProductiveAssets', 'PaymentsForCapitalImprovements'],
+  capitalexpenditure: ['PaymentsToAcquirePropertyPlantAndEquipment', 'PaymentsToAcquireProductiveAssets', 'PaymentsForCapitalImprovements'],
+  capitalexpenditures: ['PaymentsToAcquirePropertyPlantAndEquipment', 'PaymentsToAcquireProductiveAssets', 'PaymentsForCapitalImprovements'],
+  operatingcashflow: ['NetCashProvidedByUsedInOperatingActivities', 'NetCashProvidedByUsedInOperatingActivitiesContinuingOperations'],
+  cashfromoperations: ['NetCashProvidedByUsedInOperatingActivities', 'NetCashProvidedByUsedInOperatingActivitiesContinuingOperations'],
+  netcashfromoperatingactivities: ['NetCashProvidedByUsedInOperatingActivities', 'NetCashProvidedByUsedInOperatingActivitiesContinuingOperations'],
+  netcashprovidedbyoperatingactivities: ['NetCashProvidedByUsedInOperatingActivities', 'NetCashProvidedByUsedInOperatingActivitiesContinuingOperations'],
+  researchanddevelopment: ['ResearchAndDevelopmentExpense', 'ResearchAndDevelopmentExpenseExcludingAcquiredInProcessCost'],
+  researchanddevelopmentexpense: ['ResearchAndDevelopmentExpense', 'ResearchAndDevelopmentExpenseExcludingAcquiredInProcessCost'],
+  sga: ['SellingGeneralAndAdministrativeExpense'],
+  sellinggeneralandadministrative: ['SellingGeneralAndAdministrativeExpense'],
+  costofrevenue: ['CostOfRevenue', 'CostOfGoodsAndServicesSold', 'CostOfGoodsSold'],
+  costofgoodssold: ['CostOfGoodsAndServicesSold', 'CostOfGoodsSold', 'CostOfRevenue'],
+  cogs: ['CostOfGoodsAndServicesSold', 'CostOfGoodsSold', 'CostOfRevenue'],
+  dilutedshares: ['WeightedAverageNumberOfDilutedSharesOutstanding'],
+  weightedaveragedilutedshares: ['WeightedAverageNumberOfDilutedSharesOutstanding'],
+  basicshares: ['WeightedAverageNumberOfSharesOutstandingBasic'],
+  weightedaveragebasicshares: ['WeightedAverageNumberOfSharesOutstandingBasic'],
+  publicfloat: ['EntityPublicFloat'],
   cash: [
     'CashAndCashEquivalentsAtCarryingValue',
     'Cash',
@@ -3399,7 +3455,7 @@ async function companyConcept(
   const tryNamespace = async (ns: string, tags: string[]) => {
     for (const candidate of tags) {
       const r = await pwFetch(
-        `${DATA_BASE}/api/xbrl/companyconcept/CIK${paddedCik}/${ns}/${encodeURIComponent(candidate)}.json`,
+        `${DATA_BASE}/api/xbrl/companyconcept/CIK${paddedCik}/${namespaceForTag(ns, candidate)}/${encodeURIComponent(candidate)}.json`,
         { headers: SEC_HEADERS },
       );
       if (!r.ok) { lastStatus = r.status; continue; }
@@ -3438,12 +3494,18 @@ async function companyConcept(
     if (!factsRes.ok) {
       lastStatus = factsRes.status;
     } else if (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]> }> } };
+      type FactsNs = Record<string, { label?: string; description?: string; units: Record<string, ConceptDoc['units'][string]> }>;
+      const facts = (await factsRes.json()) as { entityName?: string; facts?: { 'us-gaap'?: FactsNs; dei?: FactsNs } };
       resolvedEntityName = facts.entityName ?? '';
-      const gaap = facts.facts?.['us-gaap'] ?? {};
+      // Scan dei too: cover-page facts (shares outstanding, public float) are
+      // reported there and nowhere in us-gaap for many filers.
+      const scanNamespaces: [string, FactsNs][] = [
+        ['us-gaap', facts.facts?.['us-gaap'] ?? {}],
+        ['dei', facts.facts?.dei ?? {}],
+      ];
       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)) {
+      for (const [scanNs, nsFacts] of scanNamespaces) for (const [tag, entry] of Object.entries(nsFacts)) {
         if (!tokens.some((t) => norm(tag).includes(t))) continue;
         let latestEnd = '';
         for (const [, values] of unitEntries(entry.units)) {
@@ -3455,7 +3517,7 @@ async function companyConcept(
         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 },
+          doc: { cik: Number(cik), entityName: facts.entityName ?? '', tag, taxonomy: scanNs, 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 ?? ''));
@@ -3536,7 +3598,7 @@ async function companyConcept(
       reported: false,
       latest: null,
       values: [],
-      note: `This filer reports no XBRL tag matching "${concept}" under any recognized name — checked us-gaap candidates ${JSON.stringify(candidates)}, IFRS, and a full company-facts name scan. This means EITHER the company genuinely has none (common for e.g. long-term debt at equity-funded filers) OR it reports the item under a tag we didn't match (e.g. convertible/other debt lines). value is null, not zero — call edgar_company_facts({cik:"${cikOrTicker}"}) to see the exact tags this filer uses before treating it as absent.`,
+      note: `This filer reports no XBRL tag matching "${concept}" under any recognized name — checked us-gaap/dei candidates ${JSON.stringify(candidates)}, IFRS, and a full company-facts name scan (us-gaap and dei). This means EITHER the company genuinely has none (common for e.g. long-term debt at equity-funded filers) OR it reports the item under a tag we didn't match (e.g. convertible/other debt lines). value is null, not zero — call edgar_company_facts({cik:"${cikOrTicker}"}) to see the exact tags this filer uses before treating it as absent.`,
     };
   }
   found.sort((a, b) => (b.latestEnd ?? '').localeCompare(a.latestEnd ?? ''));
@@ -3591,6 +3653,17 @@ async function companyConcept(
       value: entry.val,
       form: entry.form, // 10-K / 10-Q / 20-F / 40-F (+ /A amendments)
       filed: entry.filed,
+      // Which filing this exact number came out of (fleet #3178). SEC's
+      // companyconcept payload carries `accn` on every fact and we were
+      // dropping it, so a caller holding a value and a period_end had no way
+      // back to the document without a second edgar_company_filings call and
+      // a date match — and a consumer that FANS OUT over this tool
+      // (entity_profile's fundamentals) could not cite its own figures at all.
+      // Reported rows only: a derived Q4/standalone-quarter row below is
+      // arithmetic over several filings, not a fact any one of them states, so
+      // it carries `accession: undefined` rather than the accession of
+      // whichever leg happened to be the minuend.
+      accession: entry.accn as string | undefined,
       unit,
       derived: false as boolean | undefined,
       note: undefined as string | undefined,
@@ -3640,6 +3713,7 @@ async function companyConcept(
       value: fyRow.value - qSum,
       form: 'derived',
       filed: fyRow.filed,
+      accession: undefined, // arithmetic over FY + Q1-Q3, not a fact one filing states
       unit: fyRow.unit,
       derived: true,
       note: 'Computed as FY minus Q1-Q3 — SEC filers do not report a standalone Q4 fact.',
@@ -3704,6 +3778,7 @@ async function companyConcept(
       value: q2ytd.value - q1.value,
       form: 'derived',
       filed: q2ytd.filed,
+      accession: undefined, // YTD(Q2) minus Q1 — spans two filings
       unit: q2ytd.unit,
       derived: true,
       note: `Computed as the YTD figure filed for Q2 (${q2ytd.value}, covering ${q2ytd.period_start}..${q2ytd.period_end}) minus Q1 (${q1.value}) — this filer reports this concept cumulatively in its 10-Q (a cash-flow-statement concept, typically), not quarter-only.`,
@@ -3723,6 +3798,7 @@ async function companyConcept(
         value: q3ytd.value - q2ytd.value,
         form: 'derived',
         filed: q3ytd.filed,
+        accession: undefined, // YTD(Q3) minus YTD(Q2) — spans two filings
         unit: q3ytd.unit,
         derived: true,
         note: `Computed as the YTD figure filed for Q3 (${q3ytd.value}) minus the YTD figure filed for Q2 (${q2ytd.value}) — this filer reports this concept cumulatively in its 10-Q, not quarter-only.`,
@@ -3823,8 +3899,18 @@ async function companyConcept(
   // neither the caller nor any automatic check can tell it apart". A
   // substituted tag is the same shape, and gets the same treatment.
   const requested = concept.trim();
-  const substituted = requested.length > 0
-    && data.tag.toLowerCase().replace(/[^a-z0-9]/g, '') !== requested.toLowerCase().replace(/[^a-z0-9]/g, '');
+  // A friendly name the tool itself documents ("shares outstanding", "revenue")
+  // resolving to one of ITS OWN listed tags is the advertised behaviour, not a
+  // substitution — the warning below is for the fuzzy name-scan path, where a
+  // narrower tag really can stand in for a broader concept. Until 2026-10-16
+  // "shares outstanding" → CommonStockSharesOutstanding carried the full "NOT
+  // interchangeable" warning on a correct answer.
+  const requestedKey = requested.toLowerCase().replace(/[^a-z0-9]/g, '');
+  const aliasServed = (CONCEPT_CANDIDATES[requestedKey] ?? []).some(
+    (t) => t.toLowerCase() === data.tag.toLowerCase(),
+  );
+  const substituted = requested.length > 0 && !aliasServed
+    && data.tag.toLowerCase().replace(/[^a-z0-9]/g, '') !== requestedKey;
 
   // Coverage-bound disclosure (fleet #693). A returned value can be genuinely
   // CURRENT for this exact XBRL tag while a newer periodic filing exists that

package/src/server.ts

@@ -10,7 +10,7 @@ import pack from './index.js';
 
 
 const server = new Server(
-  { name: '@pipeworx/mcp-edgar', version: '0.3.9' },
+  { name: '@pipeworx/mcp-edgar', version: '0.3.11' },
   { capabilities: { tools: {} } },
 );