@pipeworx/mcp-edgar 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipeworx/mcp-edgar",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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-da12d4be03a1cfefdc692b867a5dfa74a7d539061c1d7ff62c65bb2d24944675",
-    "sourceCommit": "4fa4c64448be06f4a2ee4cee19f756f3558a7cad"
+    "sourceHash": "v1-11e345a6ca7725b75cd7b396ad673e52735a250951201acc76dbfd62907be72f",
+    "sourceCommit": "6182c4cfebddb94950e060b5d2fca18f18ad1aca"
   }
 }

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

package/src/index.ts

@@ -1569,7 +1569,7 @@ const tools: McpToolExport['tools'] = [
         },
         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.',
+          description: 'When accession is omitted, the form type of the latest filing to fetch, e.g. "10-K", "10-Q", "8-K", "DEF 14A" — or a `|`-separated SET ("10-K|10-Q") for "the most recent of either, whichever is newer". Omit both accession and form_type to get the single most recent filing of ANY type at all (routine 8-Ks/Form 4s/Form 144s included, not just annual/quarterly reports) — use the `|` set instead when you specifically want the newest 10-K or 10-Q.',
         },
         include_primary_text: {
           type: 'boolean',
@@ -1605,7 +1605,7 @@ const tools: McpToolExport['tools'] = [
         },
         form_type: {
           type: 'string',
-          description: 'When accession is omitted, the form type of the latest filing to fetch — "10-K", "10-Q", "8-K", "DEF 14A", etc. A question asking for the "most recent 10-K OR 10-Q" (or otherwise not committed to one type) should OMIT this field entirely rather than guess "10-K" by habit — omitting form_type (along with accession) returns the single most recent filing of ANY type, and a 10-Q is very often more recent than the last 10-K since it files quarterly while the 10-K only files once a year (verified live 2026-09-25, fleet #2450: NTRA\'s most recent 10-Q was filed 2026-08-07, five months after its 2026-02-27 10-K — passing form_type:"10-K" here silently skips the newer filing and the KPI it asked about).',
+          description: 'When accession is omitted, the form type of the latest filing to fetch — "10-K", "10-Q", "8-K", "DEF 14A", etc. For "the most recent 10-K OR 10-Q" (or any "whichever of these is newer" question), pass a `|`-separated SET, e.g. "10-K|10-Q" — do NOT guess a single type ("10-K" by habit skips a newer 10-Q) and do NOT omit this field to get "any type", since a company files far more 8-Ks/Form 4s/Form 144s between annual or quarterly reports than it files the reports themselves and an empty form_type returns the single most recent filing of ANY kind (verified live 2026-09-25, fleet #2450: NTRA\'s single most recent SEC filing was a Form 144 insider-sale notice, filed weeks after its real 10-Q and completely unrelated to the question asked).',
         },
         section: {
           type: 'string',
@@ -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. Accepted aliases: `contains`, `find`, `phrase`.',
         },
         contains: {
           type: 'string',
@@ -2368,6 +2368,34 @@ function htmlToText(html: string): string {
     .trim();
 }
 
+/**
+ * Index into SEC's own recent-first `forms` array of the latest filing
+ * matching `wantFormTypeArg` — a single form ("10-Q") or a `|`-separated SET
+ * ("10-K|10-Q" for "the most recent annual or quarterly report, whichever is
+ * newer"), same pipe convention this catalog already uses for status fields
+ * (grants-gov's "posted|forecasted"). Omitted/empty returns 0 — the single
+ * most recent filing of ANY type.
+ *
+ * Fleet #2450: a question asking for "the most recent 10-K or 10-Q" cannot
+ * be answered by omitting form_type — that resolves to the single most
+ * recent filing of ANY type, and a company files far more 8-Ks, Form 4s and
+ * Form 144s between annual/quarterly reports than it files the reports
+ * themselves. Verified live: NTRA's single most recent SEC filing on
+ * 2026-09-23 was a Form 144 insider-sale notice, not an annual or quarterly
+ * report at all — form_type left empty silently returns THAT instead of the
+ * 10-Q the question meant. Nor does picking one type and hoping work: a
+ * 10-Q is very often newer than the last 10-K. "10-K|10-Q" is the answer to
+ * "I don't care which, just the newest of these".
+ */
+function findLatestFormIndex(forms: string[], wantFormTypeArg: string | undefined): number {
+  const wanted = (wantFormTypeArg ?? '')
+    .split('|')
+    .map((f) => f.trim().toUpperCase())
+    .filter(Boolean);
+  if (!wanted.length) return 0;
+  return forms.findIndex((f) => wanted.includes(f.toUpperCase()));
+}
+
 async function filingDocuments(
   accession: string | undefined,
   tickerOrCik: string,
@@ -2398,7 +2426,7 @@ async function filingDocuments(
     const r = sub.filings?.recent;
     const forms = r?.form ?? [];
     const accs = r?.accessionNumber ?? [];
-    const idx = wantForm ? forms.findIndex((f) => f.toUpperCase() === wantForm) : 0;
+    const idx = findLatestFormIndex(forms, wantFormTypeArg);
     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.`,
@@ -2581,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 —
@@ -2619,7 +2715,7 @@ async function filingText(
 
   if (!acc) {
     const wantForm = wantFormTypeArg?.trim().toUpperCase();
-    const idx = wantForm ? forms.findIndex((f) => f.toUpperCase() === wantForm) : 0;
+    const idx = findLatestFormIndex(forms, wantFormTypeArg);
     if (idx < 0 || !accs[idx]) {
       throw new Error(`No ${wantForm ?? 'recent'} filing found for ${tickerOrCik}. Use edgar_company_filings({ticker_or_cik:"${tickerOrCik}"${wantForm ? `, form_type:"${wantForm}"` : ''}}) to list filings, then pass an accession.`);
     }
@@ -2684,6 +2780,7 @@ async function filingText(
   const search = (searchTerm ?? '').trim();
   if (search) {
     const { total: totalMatches, distinct_locations: distinctLocations, passages } = findPassages(fullText, search);
+    const wordHit = totalMatches === 0 ? findWordPassages(fullText, search) : null;
     return {
       accession: acc.dashed,
       cik: cikNoZeros,
@@ -2695,17 +2792,30 @@ 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.`,
-      },
+      search: wordHit
+        ? {
+          term: search,
+          match_mode: 'words',
+          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 "${search}" 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: search,
+          match_mode: 'exact',
+          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.`,
+        },
       ...(rawTruncated
         ? {
             raw_truncated: true,

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.4' },
+  { name: '@pipeworx/mcp-edgar', version: '0.3.6' },
   { capabilities: { tools: {} } },
 );