@pipeworx/mcp-edgar 0.3.14 → 0.3.16

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 1878+ 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 1881+ 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
 
@@ -111,7 +111,7 @@ directly, instead of just this one's:
 }
 ```
 
-Both URLs reach the same gateway and the same 1878+ data sources. The
+Both URLs reach the same gateway and the same 1881+ 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.14",
+  "version": "0.3.16",
   "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-22732e078cc175e931b642bd5804d7ba1b2610fd58415c9f8811ec32ff5939f5",
-    "sourceCommit": "29fb434ca65fe0f61191f19c3502f583f5fb99d7"
+    "sourceHash": "v1-7833dc290ad97eca84fde46549d82a1502b8e5f9f99ce63b465d3fe526f25542",
+    "sourceCommit": "24e32b525f9c0b2fd7d94b519b08abb108cc11cd"
   }
 }

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

package/src/index.ts

@@ -1065,25 +1065,64 @@ function rankMatches<T>(
   query: string,
   items: T[],
   getName: (item: T) => string,
+  getAliases?: (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);
+    // `getAliases` (optional, fleet #3607) are OTHER spellings of the same name,
+    // each scored on its own; the best-scoring spelling wins. Additive on
+    // purpose: the raw name is always tried, so a query that already matched
+    // keeps matching exactly as before, and an alias can only ADD a match.
     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; }
+    for (const spelling of [name, ...(getAliases?.(item) ?? [])]) {
+      const n = normalize(spelling);
+      let k: MatchKind | null = null;
+      let sc = 0;
+      if (n === q) { k = 'exact'; sc = 4; }
+      else if (n.startsWith(`${q} `)) { k = 'prefix'; sc = 3; }
+      else if (n.includes(` ${q} `) || n.endsWith(` ${q}`)) { k = 'word'; sc = 2; }
+      else if (n.includes(q)) { k = 'substring'; sc = 1; }
+      if (k && sc > score) { kind = k; score = sc; }
+    }
     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 }));
 }
 
+/**
+ * The trailing designators EDGAR appends to a registrant name that are NOT part
+ * of the company's name: state or country of incorporation ("/DE/", "/MD",
+ * "/CAN/", "/Cayman"), "/NEW", and the ADR marker. Matched case-insensitively
+ * against the WHOLE segment after the last slash, so a name with a slash INSIDE
+ * it ("CULLEN/FROST BANKERS", "M/I HOMES", "Quad/Graphics", "DATA I/O CORP",
+ * "GENMAB A/S") is never cut. A genuine legal form that happens to look like a
+ * 2-letter designator ("Anheuser-Busch InBev SA/NV") gains an extra alias
+ * ("...SA"); the raw title is always tried too, so that costs nothing. Measured
+ * against SEC's company_tickers.json 2026-10-26: 951 of 10,429 titles carry a
+ * slash; the trailing segments are ADR (545), CAN, state codes, NEW, CAYMAN,
+ * DEL(AWARE), CANADA, JAPAN, or empty ("TOYOTA MOTOR CORP/").
+ */
+const EDGAR_TRAILING_DESIGNATOR =
+  /\s*\/\s*(?:[A-Za-z]{2}|ADR|CAN|NEW|CAYMAN|DEL|DELAWARE|CANADA|JAPAN|UK)?\s*\/?\s*$/i;
+
+/**
+ * Other spellings of an EDGAR registrant title that name the same company:
+ * the title with its jurisdiction/ADR designator removed ("TOYOTA MOTOR CORP/"
+ * -> "TOYOTA MOTOR CORP"). Empty when there is nothing to remove. Used as
+ * `rankMatches`'s aliases, never as a replacement for the title (fleet #3607).
+ * Deliberately NOT a change to `normalize`: that is shared by every pack that
+ * ranks its own list, and "/" is not a registrant-name artefact in those.
+ */
+function edgarNameAliases(title: string): string[] {
+  const stripped = title.replace(EDGAR_TRAILING_DESIGNATOR, '').trim();
+  return stripped && stripped !== title.trim() && /\S/.test(stripped) ? [stripped] : [];
+}
+
 interface SecTickerRow$shared { cik_str: number; ticker: string; title: string }
 
 interface SecEntity {
@@ -1100,6 +1139,13 @@ interface SecEntity {
    * `matched_by: 'company_name'` alone cannot (fleet #3100).
    */
   matched_kind?: MatchKind;
+  /**
+   * Other companies whose names also matched — distinct companies, deduped
+   * by CIK, excluding this issuer's own share classes (never the winner's
+   * own ticker/CIK under a different symbol). Consumers read this to tell a
+   * genuinely CONTESTED name match from a clean one. See
+   * `distinctCompanyAlternatives` below for how it's built (fleet #3621).
+   */
   alternatives?: { ticker: string; company_name: string; cik: string; kind: MatchKind }[];
 }
 
@@ -1133,16 +1179,11 @@ async function resolveSecEntity(
   }
 
   // 2) Company-name fallback.
-  const ranked = rankMatches(query, rows, (r) => r.title);
+  const ranked = rankMatches(query, rows, (r) => r.title, (r) => edgarNameAliases(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,
-    }));
+    const alts = distinctCompanyAlternatives(ranked);
     if (alts.length) best.alternatives = alts;
     return best;
   }
@@ -1150,6 +1191,33 @@ async function resolveSecEntity(
   throw new Error(`No SEC company matches "${query}". Pass a US-listed ticker ("AAPL") or the exact listed-company name ("Apple Inc."). If this is a clinical-trial sponsor, an operating subsidiary (e.g. "Merck Sharp & Dohme" → Merck & Co), or a foreign/private entity, call sponsor_to_filer({sponsor}) instead — it resolves subsidiaries to the listed parent and honestly reports when no US-listed filer exists.`);
 }
 
+/** `alternatives` lists at most this many OTHER companies; company-spine.test.ts pins it to the real function. */
+const ALTERNATIVES_CAP = 3;
+
+/**
+ * The runners-up for a name match, as DISTINCT COMPANIES (fleet #3621).
+ *
+ * company_tickers.json lists one row per ticker, so an issuer with preferred
+ * shares appears several times under one CIK (Ford: F, F-PB, F-PC, F-PD; AT&T:
+ * T, TBB, T-PA, T-PC). Slicing the ranked rows left those rows to fill every
+ * alternatives slot, hiding any real rival ranked behind them, and made a company
+ * its own "alternative". So: drop every row that is the winner's own CIK, keep
+ * only the best-ranked row of each other CIK, THEN cap. The winner's other
+ * tickers are not lost information: they are the same company, and `ticker` /
+ * `cik` already identify it. `ranked` is already best-first, so first-seen wins.
+ */
+function distinctCompanyAlternatives(ranked: RankedMatch<SecTickerRow$shared>[]): NonNullable<SecEntity['alternatives']> {
+  const seen = new Set<number>([ranked[0].item.cik_str]);
+  const out: NonNullable<SecEntity['alternatives']> = [];
+  for (const m of ranked.slice(1)) {
+    if (seen.has(m.item.cik_str)) continue;
+    seen.add(m.item.cik_str);
+    out.push({ ticker: m.item.ticker, company_name: m.item.title, cik: String(m.item.cik_str), kind: m.kind });
+    if (out.length >= ALTERNATIVES_CAP) break;
+  }
+  return out;
+}
+
 function toEntity(r: SecTickerRow$shared, matched_by: 'ticker' | 'company_name'): SecEntity {
   return {
     ticker: r.ticker,
@@ -1797,7 +1865,7 @@ const tools: McpToolExport['tools'] = [
   {
     name: 'edgar_ticker_to_cik',
     description:
-      '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. The response carries a `next` hint: the usual NEXT step after resolving is edgar_company_snapshot({ticker_or_cik}), which returns the recent filings list AND the headline XBRL financials in one call — do not chain edgar_company_filings then edgar_company_concept by hand to get that.',
+      '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` — up to 3 OTHER companies whose names also matched, one per distinct CIK, with the winner\'s OWN share classes/tickers excluded (never listed as its own alternative). Use `alternatives` to tell a genuinely CONTESTED name match (a real rival company also matched) from a clean one (nothing else did). 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. The response carries a `next` hint: the usual NEXT step after resolving is edgar_company_snapshot({ticker_or_cik}), which returns the recent filings list AND the headline XBRL financials in one call — do not chain edgar_company_filings then edgar_company_concept by hand to get that.',
     summary: 'The SEC CIK number for a stock ticker or company name, from EDGAR\'s company list.',
     inputSchema: {
       type: 'object' as const,

package/src/server.ts

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