@pipeworx/mcp-edgar 0.3.5 → 0.3.7

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 1683+ live data sources.
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1684+ live data sources.
 
 ## 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 1683+ data sources. The
+Both URLs reach the same gateway and the same 1684+ 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.5",
+  "version": "0.3.7",
   "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-8ebd704e53458e829aea1033aa14ef78911a50cd60211956318c1574f8b1eb4c",
-    "sourceCommit": "1064560fd9dcd0d6fc2606298c2ba244b3a1fbeb"
+    "sourceHash": "v1-32b9918a5b5098bb4af39453590b40c58883a8cca190d5ec3630203cf8236594",
+    "sourceCommit": "7ab72cdcaf29d0be5874bd2191074e69f97c9b0b"
   }
 }

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

package/src/index.ts

@@ -1586,7 +1586,7 @@ const tools: McpToolExport['tools'] = [
   {
     name: 'edgar_filing_text',
     description:
-      'AUTHORITATIVE full text of a SEC filing\'s primary document (10-K / 10-Q / 8-K body), HTML stripped to clean plaintext — the source for disclosures that live in prose, not XBRL: going-concern language, ATM / at-the-market equity facilities, committed-equity share caps, public-float figures, subsequent events, the liquidity footnote, and MD&A KPIs XBRL never tags (test volume, units shipped, subscriber counts, same-store sales). Pass an accession (from edgar_search_filings / edgar_company_filings) plus the filer\'s ticker or CIK; OR omit accession and pass ticker + form_type to auto-resolve the latest matching filing. **For a specific fact inside a long filing, pass `search`** (a word or exact phrase, e.g. "tests processed" or "processed approximately") instead of paging blind — it scans the WHOLE document (before any offset/max_chars windowing) and returns every matching passage with surrounding context and its own `offset` in the document, so a KPI ~100k characters in is found in one call instead of paging through `max_chars` windows by hand. A zero-match `search` is a real answer (the filing does not use that exact wording) — retry with a shorter or different phrase rather than assuming the tool failed. Optionally set `section` to return just one part (going_concern | liquidity | capital_resources | subsequent_events); `search` runs within that slice when both are given. Large docs (a 10-Q is ~100k+ chars of text) are PAGED, not spilled, when `search` is not used: the result caps at `max_chars` (default 50000) from `offset`, and returns `truncated` + `next_offset` — pass next_offset back as `offset` to read the next window. An especially large filing (e.g. an S-1 with heavy inline-XBRL tagging can exceed 10MB of raw HTML) is also capped on the READ side — the response sets `raw_truncated:true` when only the first portion of the document was read at all, which bounds how far `offset` can page (and how far `search` can scan) and can make a late section or search term come back not-found even though it exists further in. Use for "does $TICKER disclose substantial doubt / going concern", "what ATM facility does $TICKER have", "read the liquidity section of the latest 10-Q", "how many tests did $TICKER process this quarter". For the list of documents/exhibits in a filing use edgar_filing_documents; for structured financial numbers use edgar_company_concept.',
+      'AUTHORITATIVE full text of a SEC filing\'s primary document (10-K / 10-Q / 8-K body), HTML stripped to clean plaintext — the source for disclosures that live in prose, not XBRL: going-concern language, ATM / at-the-market equity facilities, committed-equity share caps, public-float figures, subsequent events, the liquidity footnote, and MD&A KPIs XBRL never tags (test volume, units shipped, subscriber counts, same-store sales). Pass an accession (from edgar_search_filings / edgar_company_filings) plus the filer\'s ticker or CIK; OR omit accession and pass ticker + form_type to auto-resolve the latest matching filing. **For a specific fact inside a long filing, pass `search`** (a word or exact phrase, e.g. "tests processed" or "processed approximately") instead of paging blind — it scans the WHOLE document (before any offset/max_chars windowing) and returns every matching passage with surrounding context and its own `offset` in the document, so a KPI ~100k characters in is found in one call instead of paging through `max_chars` windows by hand. A zero-match `search` is a real answer (the filing does not use that exact wording) — retry with a shorter or different phrase rather than assuming the tool failed. **For a question asking two facts from the same filing** ("revenue and test volume in the latest 10-Q"), pass `search` as `|`-separated phrases (e.g. "revenue|tests processed") to get both in this one call under `searches[]` — and when a phrase names a financial total (revenue, net income, EPS, ...), the matching XBRL figure for this exact accession comes back under `xbrl` even if that total never appears as an absolute number in the prose (common: filings often state only the growth delta/percentage in text). Optionally set `section` to return just one part (going_concern | liquidity | capital_resources | subsequent_events); `search` runs within that slice when both are given. Large docs (a 10-Q is ~100k+ chars of text) are PAGED, not spilled, when `search` is not used: the result caps at `max_chars` (default 50000) from `offset`, and returns `truncated` + `next_offset` — pass next_offset back as `offset` to read the next window. An especially large filing (e.g. an S-1 with heavy inline-XBRL tagging can exceed 10MB of raw HTML) is also capped on the READ side — the response sets `raw_truncated:true` when only the first portion of the document was read at all, which bounds how far `offset` can page (and how far `search` can scan) and can make a late section or search term come back not-found even though it exists further in. Use for "does $TICKER disclose substantial doubt / going concern", "what ATM facility does $TICKER have", "read the liquidity section of the latest 10-Q", "how many tests did $TICKER process this quarter". For the list of documents/exhibits in a filing use edgar_filing_documents; for structured financial numbers use edgar_company_concept.',
     summary: 'The full text of an SEC filing\'s main document, HTML stripped to clean plaintext.',
     inputSchema: {
       type: 'object' as const,
@@ -1622,7 +1622,7 @@ const tools: McpToolExport['tools'] = [
         },
         search: {
           type: 'string',
-          description: 'Find a specific fact instead of paging blind. This is a SUBSTRING match, not a relevance search — pass the exact 2-4 word phrase most likely to appear VERBATIM in the prose ("tests processed", "processed approximately", "going concern"), never a compound of every concept in the question. A phrase that ANDs several unrelated question-words together ("oncology Signatera revenue test volume") returns ZERO matches even in the CORRECT filing, because the filing\'s own sentence never contains all of those words together — verified live 2026-09-25 (fleet #2450) on a real Natera 10-Q that DOES report the exact number asked for: "Signatera revenue" and the 4-word compound above both found nothing, while the filing\'s own wording ("processed approximately", "tests processed") is what actually appears. When unsure of the filing\'s exact phrasing, prefer the SHORTEST distinctive 2-3 word fragment of the metric name itself (a unit, a verb+noun like "processed approximately") over restating the question. Case-insensitive substring match over the WHOLE document text (or the whole `section` slice, if both are given), run BEFORE max_chars/offset windowing. Returns every matching passage (surrounding context + its own offset in the document) instead of the normal paged `text` — use the returned offsets with a follow-up call (no `search`, `offset` set to one of them) if you need more surrounding text than the passage gives. Zero matches means try again with a SHORTER, more literal phrase before concluding the filing does not disclose it — this is a real answer about wording, not a tool failure. Accepted aliases: `contains`, `find`, `phrase`.',
+          description: 'Find a specific fact instead of paging blind. Pass a short 2-4 word phrase likely to appear VERBATIM in the prose ("processed approximately", "tests processed", "going concern") rather than restating the question. Case-insensitive substring match over the WHOLE document text (or the whole `section` slice), run BEFORE max_chars/offset windowing; returns matching passages (context + their own offset) instead of the paged `text`, ranking passages with a nearby figure first. If a multi-word phrase has no verbatim match, it falls back to the phrase\'s individual words and returns the passages holding the most of them (search.match_mode "words") — read those passages for the fact rather than treating them as confirmed. Use a returned offset with a follow-up call (no `search`) to read more surrounding text. **For TWO OR MORE facts from this same filing in one call, separate phrases with `|`** (e.g. "Signatera revenue|tests processed") — each is searched independently and reported under `searches[]`, keyed by `phrase`, instead of the singular `search`. This is the way to answer a compound question ("what was revenue AND test volume in the latest 10-Q") without a second call. Note: a phrase naming a financial TOTAL (revenue, net income, EPS, assets, cash, gross/operating profit, long-term debt, stockholders equity, shares outstanding) often has NO verbatim match at all, because filers frequently state only the growth delta/percentage in prose and report the actual total exclusively in XBRL — when a phrase names one of these, the response also attaches that concept\'s value for THIS SAME accession under `xbrl` (sourced like edgar_company_concept, not text-matched), so you don\'t need a separate edgar_company_concept call just to get the number the text search alone would report as a false "not found". Accepted aliases: `contains`, `find`, `phrase`.',
         },
         contains: {
           type: 'string',
@@ -2609,6 +2609,74 @@ function findPassages(
   return { total: offsets.length, distinct_locations: groups.length, passages };
 }
 
+// fleet #2450: the router answers in ONE tool call, so "retry with a shorter
+// phrase" (the old zero-match note) never happens inside ask_pipeworx. Measured
+// live 2026-09-26: 5 of 5 routed calls for the Natera "revenue and test volume
+// in its most recent 10-K or 10-Q" question reached the RIGHT filing and passed
+// a compound phrase ("Signatera revenue", "oncology Signatera revenue test
+// volume") that matches nothing verbatim — while the word "Signatera" alone
+// lands on the "processed approximately 2,056,800 tests" sentence. A description
+// telling the router to pass shorter phrases did not change what it passed.
+// So when the exact phrase misses, fall back to the phrase's WORDS: anchor on
+// the rarer words, rank each window by how many distinct query words it holds
+// (then by a nearby figure), and say plainly that this is a word-level match.
+const WORD_FALLBACK_STOP = new Set([
+  'the', 'and', 'for', 'its', 'our', 'their', 'with', 'from', 'that', 'this', 'what', 'which',
+  'most', 'recent', 'latest', 'report', 'reported', 'reports', 'filing', 'total', 'any', 'all',
+]);
+const WORD_FALLBACK_ANCHOR_MAX = 60;
+
+export function findWordPassages(
+  text: string,
+  phrase: string,
+  contextChars = SEARCH_CONTEXT_CHARS,
+  maxPassages = SEARCH_MAX_PASSAGES,
+): { words: Array<{ word: string; occurrences: number }>; distinct_locations: number; passages: Array<{ offset: number; text: string; words_matched: string[] }> } | null {
+  const words = [...new Set(phrase.toLowerCase().split(/[^a-z0-9&-]+/).filter((w) => w.length >= 3 && !WORD_FALLBACK_STOP.has(w)))];
+  if (words.length < 2) return null;
+  const hay = text.toLowerCase();
+  const occ = new Map<string, number[]>();
+  for (const w of words) {
+    const offs: number[] = [];
+    let from = 0;
+    for (;;) {
+      const i = hay.indexOf(w, from);
+      if (i === -1) break;
+      offs.push(i);
+      from = i + w.length;
+    }
+    occ.set(w, offs);
+  }
+  const present = words.filter((w) => (occ.get(w) ?? []).length > 0);
+  if (present.length === 0) return null;
+  // Anchor on every word rare enough to be distinctive; if every word is
+  // common, anchor on the rarest one only (bounded work on a 200k-char doc).
+  const byRarity = [...present].sort((a, b) => occ.get(a)!.length - occ.get(b)!.length);
+  const anchors = byRarity.filter((w) => occ.get(w)!.length <= WORD_FALLBACK_ANCHOR_MAX);
+  const anchorWords = anchors.length ? anchors : [byRarity[0]];
+  const anchorOffs = [...new Set(anchorWords.flatMap((w) => occ.get(w)!))].sort((a, b) => a - b);
+
+  const groups: Array<{ first: number; last: number }> = [];
+  for (const idx of anchorOffs) {
+    const g = groups[groups.length - 1];
+    if (g && idx - g.last <= contextChars * 2) g.last = idx;
+    else groups.push({ first: idx, last: idx });
+  }
+  const scored = groups.map((g) => {
+    const start = Math.max(0, g.first - contextChars);
+    const end = Math.min(text.length, g.last + contextChars);
+    const win = hay.slice(start, end);
+    const matched = present.filter((w) => win.includes(w));
+    return { start, end, matched, hasNumber: NEARBY_NUMBER_RE.test(text.slice(start, end)) ? 1 : 0 };
+  });
+  scored.sort((a, b) => (b.matched.length - a.matched.length) || (b.hasNumber - a.hasNumber));
+  return {
+    words: words.map((w) => ({ word: w, occurrences: (occ.get(w) ?? []).length })),
+    distinct_locations: groups.length,
+    passages: scored.slice(0, maxPassages).map((s) => ({ offset: s.start, text: text.slice(s.start, s.end), words_matched: s.matched })),
+  };
+}
+
 // Fetch ONE filing's primary-document text, HTML-stripped, paged. Splitting this
 // out (rather than piggybacking edgar_filing_documents' include_primary_text,
 // which caps at 40k and can't page) lets the register pull deep disclosures —
@@ -2709,9 +2777,61 @@ async function filingText(
   // the whole (possibly section-sliced) document and returns matching
   // passages with their own offsets, rather than one page of raw text the
   // caller has to eyeball for the fact they wanted (fleet #2446).
-  const search = (searchTerm ?? '').trim();
-  if (search) {
-    const { total: totalMatches, distinct_locations: distinctLocations, passages } = findPassages(fullText, search);
+  //
+  // fleet #2450: a question can ask for TWO facts from the SAME filing
+  // ("revenue AND test volume") and ask_pipeworx's router picks ONE tool call
+  // for a single-entity question — so a single `search` phrase per call meant
+  // the second fact was structurally unreachable. `search` now accepts
+  // multiple phrases separated by `|` (same convention as `form_type`'s
+  // "10-K|10-Q" set) and reports each phrase's passages independently under
+  // `searches`, keyed by `phrase`. A single phrase (no `|`) keeps the original
+  // singular `search` shape unchanged.
+  const searchPhrases = [...new Set(
+    (searchTerm ?? '').split('|').map((p) => p.trim()).filter(Boolean),
+  )].slice(0, 5);
+  if (searchPhrases.length > 0) {
+    const buildOne = async (term: string) => {
+      const { total: totalMatches, distinct_locations: distinctLocations, passages } = findPassages(fullText, term);
+      const wordHit = totalMatches === 0 ? findWordPassages(fullText, term) : null;
+      // A phrase naming a financial concept (revenue, net income, EPS, ...)
+      // is frequently XBRL-only — never printed as an absolute figure in the
+      // prose at all (verified live: Natera's 10-Q states revenue only as a
+      // dollar/percent DELTA, never the total) — so attach the filer's own
+      // XBRL fact for THIS accession when the phrase names one, regardless of
+      // whether the text search above found anything.
+      const financialConcept = detectFinancialConcept(term);
+      const xbrl = financialConcept
+        ? await financialFactForFiling(tickerOrCik, financialConcept, formType, filingDate)
+        : null;
+      const base = wordHit
+        ? {
+          term,
+          match_mode: 'words' as const,
+          exact_matches: 0,
+          words: wordHit.words,
+          distinct_locations: wordHit.distinct_locations,
+          returned: wordHit.passages.length,
+          truncated: wordHit.distinct_locations > wordHit.passages.length,
+          passages: wordHit.passages,
+          note: `The exact phrase "${term}" does not appear in this document, so these are passages holding its individual WORDS, ranked by how many of them each passage contains (then by a nearby figure). Read each passage for the fact asked — a word-level match is a lead, not a confirmation. Each offset can be passed as \`offset\` (without \`search\`) to read more surrounding text.`,
+        }
+        : {
+          term,
+          match_mode: 'exact' as const,
+          total_matches: totalMatches,
+          distinct_locations: distinctLocations,
+          returned: passages.length,
+          truncated: distinctLocations > passages.length,
+          passages,
+          note: totalMatches === 0
+            ? 'No case-insensitive match for this wording (nor, for a multi-word phrase, for any of its individual words) in the document (or section, if one was given). That is a real answer, not a failure — retry with different wording or drop `section` to search the whole document.'
+            : `Passages carrying a nearby number (a likely KPI figure) are ranked first; the rest keep document order. Each passage's offset is a position in the document text — pass it as \`offset\` (without \`search\`) to read more surrounding text via the normal paged text field.`,
+        };
+      return xbrl ? { ...base, xbrl } : base;
+    };
+
+    const results = await Promise.all(searchPhrases.map(buildOne));
+
     return {
       accession: acc.dashed,
       cik: cikNoZeros,
@@ -2723,17 +2843,12 @@ async function filingText(
       section: sectionApplied,
       ...(sectionFound !== null ? { section_found: sectionFound } : {}),
       total_chars: fullText.length,
-      search: {
-        term: search,
-        total_matches: totalMatches,
-        distinct_locations: distinctLocations,
-        returned: passages.length,
-        truncated: distinctLocations > passages.length,
-        passages,
-        note: totalMatches === 0
-          ? 'No case-insensitive match for this exact wording in the document (or section, if one was given). That is a real answer, not a failure — retry with a shorter phrase or drop `section` to search the whole document.'
-          : `Passages carrying a nearby number (a likely KPI figure) are ranked first; the rest keep document order. Each passage's offset is a position in the document text — pass it as \`offset\` (without \`search\`) to read more surrounding text via the normal paged text field.`,
-      },
+      ...(searchPhrases.length === 1
+        ? { search: results[0] }
+        : {
+            searches: searchPhrases.map((phrase, i) => ({ phrase, ...results[i] })),
+            searches_note: 'Multiple `|`-separated phrases were requested — each is searched independently against the SAME document/section and reported under its own entry, keyed by `phrase`. Read each entry for its own fact rather than assuming they describe the same period (e.g. a quarterly revenue total and a six-month cumulative KPI can both be real and still not comparable).',
+          }),
       ...(rawTruncated
         ? {
             raw_truncated: true,
@@ -3488,6 +3603,80 @@ async function companyConcept(
   };
 }
 
+// fleet #2450: a ClearGene-style question ("Signatera revenue AND test volume
+// from Natera's latest 10-Q") never got both facts, because a financial TOTAL
+// like revenue is frequently XBRL-only and never printed as an absolute
+// dollar figure anywhere in the filing's prose — verified live 2026-09-29:
+// Natera's Q2 2026 10-Q text discusses revenue only as percentage/dollar
+// DELTAS ("increased by $206.2 million, or 37.7%"), never the $752.75M total
+// itself, so no `search` phrasing, exact or word-fallback, can ever surface
+// it from the text. edgar_filing_text's `search` now recognizes when a
+// requested phrase NAMES a financial concept this filer tags in XBRL (the
+// same friendly-name table edgar_company_concept resolves) and attaches that
+// concept's value for THIS SAME accession/period alongside the text
+// passages — one tool call gets the KPI from prose and the total from XBRL.
+// Matching is by N-GRAM of the phrase's tokens (not a raw substring) so a
+// short ambiguous key ("cash", "eps") only fires on a real standalone token,
+// not embedded inside an unrelated word.
+function detectFinancialConcept(phrase: string): string | null {
+  const tokens = phrase.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  for (let n = Math.min(3, tokens.length); n >= 1; n--) {
+    for (let i = 0; i + n <= tokens.length; i++) {
+      const gram = tokens.slice(i, i + n).join('');
+      if (CONCEPT_CANDIDATES[gram]) return gram;
+    }
+  }
+  return null;
+}
+
+// Best-effort: find the XBRL fact for `friendlyConcept` that belongs to the
+// EXACT filing edgar_filing_text is already reading (same form + same filed
+// date), not just "the latest" — a different period would silently pair the
+// wrong quarter's total with this filing's prose. Never throws: an XBRL miss
+// (concept not reported, SEC rate-limited, etc.) just means no `xbrl`
+// companion is attached, and the text passages above stand on their own.
+async function financialFactForFiling(
+  tickerOrCik: string,
+  friendlyConcept: string,
+  wantForm: string | null,
+  wantFiled: string | null,
+): Promise<Record<string, unknown> | null> {
+  if (!wantForm || !wantFiled) return null;
+  try {
+    const cc = (await companyConcept(tickerOrCik, friendlyConcept)) as {
+      concept?: string;
+      label?: string;
+      requested_concept?: string;
+      concept_substituted?: boolean;
+      reported?: boolean;
+      values?: Array<{
+        form: string; filed: string; value: number; unit: string;
+        fiscal_year?: number; fiscal_period?: string;
+        period_start?: string; period_end?: string; derived?: boolean;
+      }>;
+    };
+    if (!cc || cc.reported === false || !Array.isArray(cc.values)) return null;
+    const exact = cc.values.find((v) => v.form === wantForm && v.filed === wantFiled && !v.derived);
+    if (!exact) return null;
+    return {
+      concept: cc.concept ?? friendlyConcept,
+      label: cc.label ?? null,
+      value: exact.value,
+      unit: exact.unit,
+      fiscal_year: exact.fiscal_year ?? null,
+      fiscal_period: exact.fiscal_period ?? null,
+      period_start: exact.period_start ?? null,
+      period_end: exact.period_end ?? null,
+      form: exact.form,
+      filed: exact.filed,
+      source: 'edgar_company_concept (XBRL) — same accession, not extracted from the prose above',
+      note: 'Many financial totals are reported ONLY in XBRL and never appear as an absolute dollar figure in the filing text (the prose typically states growth deltas/percentages instead) — this value is the filer\'s own XBRL fact for this exact filing, not a text match.',
+    };
+  } catch {
+    return null;
+  }
+}
+
 // ── Insider transactions (Form 3/4/5) ───────────────────────────────
 
 // SEC Form 4 transaction codes (Table I / II). Open-market buys (P) and

package/src/server.ts

@@ -9,7 +9,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import pack from './index.js';
 
 const server = new Server(
-  { name: '@pipeworx/mcp-edgar', version: '0.3.5' },
+  { name: '@pipeworx/mcp-edgar', version: '0.3.7' },
   { capabilities: { tools: {} } },
 );