@cyanheads/secedgar-mcp-server 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/AGENTS.md +22 -16
  2. package/CLAUDE.md +22 -16
  3. package/README.md +14 -10
  4. package/changelog/0.17.x/0.17.1.md +36 -0
  5. package/changelog/0.18.x/0.18.0.md +16 -0
  6. package/dist/config/server-config.js +1 -1
  7. package/dist/config/server-config.js.map +1 -1
  8. package/dist/index.js +2 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/mcp-server/tools/ambiguous-matches.d.ts +20 -0
  11. package/dist/mcp-server/tools/ambiguous-matches.d.ts.map +1 -0
  12. package/dist/mcp-server/tools/ambiguous-matches.js +22 -0
  13. package/dist/mcp-server/tools/ambiguous-matches.js.map +1 -0
  14. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
  15. package/dist/mcp-server/tools/definitions/company-search.tool.js +15 -8
  16. package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
  17. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +8 -4
  18. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
  19. package/dist/mcp-server/tools/definitions/compare-companies.tool.js +182 -45
  20. package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
  21. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map +1 -1
  22. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js +10 -2
  23. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js.map +1 -1
  24. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js +6 -6
  26. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
  28. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +10 -10
  29. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
  30. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +4 -4
  31. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
  32. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +36 -15
  33. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
  34. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +14 -0
  35. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
  36. package/dist/mcp-server/tools/definitions/find-holders.tool.js +80 -16
  37. package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
  38. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +2 -0
  39. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
  40. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +147 -77
  41. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +4 -4
  43. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/get-filing.tool.js +321 -90
  45. package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
  46. package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts.map +1 -1
  47. package/dist/mcp-server/tools/definitions/get-financials.tool.js +19 -21
  48. package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
  49. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
  50. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +11 -19
  51. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
  52. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +10 -0
  53. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
  54. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +23 -9
  55. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
  56. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +14 -0
  57. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
  58. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +16 -14
  59. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
  60. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
  61. package/dist/mcp-server/tools/definitions/get-material-events.tool.js +9 -5
  62. package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
  63. package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts.map +1 -1
  64. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js +11 -8
  65. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js.map +1 -1
  66. package/dist/mcp-server/tools/definitions/index.d.ts +635 -594
  67. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  68. package/dist/mcp-server/tools/definitions/search-concepts.tool.js +2 -2
  69. package/dist/mcp-server/tools/definitions/search-concepts.tool.js.map +1 -1
  70. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +45 -0
  71. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
  72. package/dist/mcp-server/tools/definitions/search-filings.tool.js +64 -12
  73. package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
  74. package/dist/mcp-server/tools/escape-inline.d.ts +35 -0
  75. package/dist/mcp-server/tools/escape-inline.d.ts.map +1 -0
  76. package/dist/mcp-server/tools/escape-inline.js +51 -0
  77. package/dist/mcp-server/tools/escape-inline.js.map +1 -0
  78. package/dist/mcp-server/tools/format-usd.d.ts +22 -0
  79. package/dist/mcp-server/tools/format-usd.d.ts.map +1 -0
  80. package/dist/mcp-server/tools/format-usd.js +53 -0
  81. package/dist/mcp-server/tools/format-usd.js.map +1 -0
  82. package/dist/mcp-server/tools/limit-clamp.d.ts +50 -18
  83. package/dist/mcp-server/tools/limit-clamp.d.ts.map +1 -1
  84. package/dist/mcp-server/tools/limit-clamp.js +51 -15
  85. package/dist/mcp-server/tools/limit-clamp.js.map +1 -1
  86. package/dist/services/edgar/edgar-api-service.d.ts +96 -11
  87. package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
  88. package/dist/services/edgar/edgar-api-service.js +333 -50
  89. package/dist/services/edgar/edgar-api-service.js.map +1 -1
  90. package/dist/services/edgar/filing-to-text.d.ts +4 -3
  91. package/dist/services/edgar/filing-to-text.d.ts.map +1 -1
  92. package/dist/services/edgar/filing-to-text.js +12 -0
  93. package/dist/services/edgar/filing-to-text.js.map +1 -1
  94. package/package.json +4 -4
  95. package/server.json +3 -3
  96. package/skills/secedgar-guide/SKILL.md +1 -0
@@ -3,8 +3,8 @@
3
3
  * @module mcp-server/tools/definitions/get-filing
4
4
  */
5
5
  import { tool, z } from '@cyanheads/mcp-ts-core';
6
- import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
7
- import { escapeMarkdownInline } from '@cyanheads/mcp-ts-core/utils';
6
+ import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
7
+ import { escapeInline } from '../escape-inline.js';
8
8
  import { limitClamp, withLimitClamps, } from '../limit-clamp.js';
9
9
  import { CallScope } from '../../../services/edgar/call-scope.js';
10
10
  import { filingArchiveUrl, getEdgarApiService } from '../../../services/edgar/edgar-api-service.js';
@@ -28,6 +28,10 @@ const FILING_CONTENT_BEGIN = '--- BEGIN SEC FILING CONTENT (upstream document te
28
28
  const FILING_CONTENT_END = '--- END SEC FILING CONTENT ---';
29
29
  /** Sentinel key suffix when no specific document is requested (primary document path). */
30
30
  const PRIMARY_SENTINEL = '\x00primary';
31
+ /** What an archive miss asks the caller to pass, after a verb (#203). */
32
+ const FILER_CIK = "the filer's CIK as cik (resolve it with secedgar_company_search)";
33
+ /** Leads an archive miss's hint when SEC could not answer a lookup of the filing's filers (#215). */
34
+ const FILER_LOOKUP_UNAVAILABLE = 'The filer lookup for this accession number was unavailable, so some directories that may hold the filing were not searched.';
31
35
  const documentEntrySchema = z
32
36
  .object({
33
37
  name: z.string().describe('Document filename within the filing archive.'),
@@ -78,13 +82,13 @@ export const getFilingTool = tool('secedgar_get_filing', {
78
82
  reason: 'document_not_found',
79
83
  code: JsonRpcErrorCode.NotFound,
80
84
  when: 'A specific document was requested but not present in the filing archive',
81
- recovery: 'Pick a filename from the categorized document list in the error message.',
85
+ recovery: "Pick a filename from the categorized document list in the error message; when the archive does not serve the one requested, pass the filer's CIK as cik.",
82
86
  },
83
87
  {
84
88
  reason: 'no_documents',
85
89
  code: JsonRpcErrorCode.NotFound,
86
90
  when: 'Filing index lists items but no fetchable primary document was found',
87
- recovery: 'Set document to one of the filenames listed in the error message.',
91
+ recovery: "Pass the filer's CIK as cik (resolve it with secedgar_company_search), or set document to another filename listed in the error message.",
88
92
  },
89
93
  {
90
94
  reason: 'binary_document',
@@ -136,12 +140,12 @@ export const getFilingTool = tool('secedgar_get_filing', {
136
140
  .string()
137
141
  .regex(/^\d{1,10}$/, 'Expected a CIK of 1-10 digits')
138
142
  .optional()
139
- .describe('Company CIK, digits only (resolve via secedgar_company_search if you have a ticker or name). Optional but recommended — speeds up archive lookup. If omitted, likely filing CIKs are inferred from SEC search metadata and archive paths.'),
143
+ .describe("Filer CIK, digits only (resolve via secedgar_company_search if you have a ticker or name). Optional but recommended — speeds up archive lookup. If omitted, the filer is looked up from the accession number through EDGAR full-text search (2001 onward) and the accession number's own prefix, which for many filings is a filing agent's CIK, and when none of those directories serves the filing, through the filers its index page names."),
140
144
  content_limit: contentLimit.schema(true),
141
145
  document: z
142
146
  .string()
143
147
  .optional()
144
- .describe('Specific document filename within the filing (e.g., "ex-21.htm" for subsidiaries list). Default: the primary document. Available documents are listed in the response metadata under documents; entries marked binary hold no text and are rejected.'),
148
+ .describe('Specific document filename within the filing (e.g., "ex-21.htm" for subsidiaries list). Omitted or blank: the primary document. Available documents are listed in the response metadata under documents, and a primary_document value is accepted too; entries marked binary hold no text and are rejected.'),
145
149
  include_xbrl: z
146
150
  .boolean()
147
151
  .default(false)
@@ -179,7 +183,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
179
183
  .describe('Period of report (YYYY-MM-DD), from the same source as form. Absent for forms without one (S-8, Form 4, proxy statements) or when neither source has it.'),
180
184
  primary_document: z
181
185
  .string()
182
- .describe('Filename of the primary document. When the archive does not serve the one the index names (common in 2000–2001), this is the full submission file <accession>.txt instead; the notice names both.'),
186
+ .describe("Primary document as read: an XML form's SEC rendering (xsl…/form4.xml) up to 600 KB raw; a 2000–2001 name SEC does not serve, as <accession>-<name>, else the full submission <accession>.txt."),
183
187
  requested_document: z
184
188
  .string()
185
189
  .optional()
@@ -226,7 +230,10 @@ export const getFilingTool = tool('secedgar_get_filing', {
226
230
  const scope = new CallScope(ctx.signal);
227
231
  const pageLimit = contentLimit.apply(input.content_limit, ctx);
228
232
  const accn = normalizeAccessionNumber(input.accession_number);
229
- const documentKey = input.document ?? PRIMARY_SENTINEL;
233
+ // A blank `document` reads as omitted (#203): no archive file has a blank name,
234
+ // and requesting one fetches SEC's directory listing page instead.
235
+ const document = input.document?.trim() ? input.document : undefined;
236
+ const documentKey = document ?? PRIMARY_SENTINEL;
230
237
  const cacheKey = `${accn}:${documentKey}`;
231
238
  // If we have a cache hit, skip the document fetch entirely.
232
239
  const cached = getExtractCache(cacheKey);
@@ -239,8 +246,13 @@ export const getFilingTool = tool('secedgar_get_filing', {
239
246
  let records;
240
247
  if (cached === undefined) {
241
248
  // Cache miss — fetch, convert, and cache.
242
- const resolved = await resolveFilingArchive(api, scope, accn, input.cik, input.document);
249
+ const resolved = await resolveFilingArchive(api, scope, accn, input.cik, document);
243
250
  if (!resolved.ok) {
251
+ // Each miss below comes after every directory the filer lookups found was
252
+ // tried, so the filer's own CIK is the way out an archive miss offers (#203).
253
+ const lookupNote = resolved.kind !== 'binary_document' && resolved.filerLookupFailed
254
+ ? `${FILER_LOOKUP_UNAVAILABLE} `
255
+ : '';
244
256
  if (resolved.kind === 'document_not_found') {
245
257
  // Render candidates into the message itself — clients reliably see only
246
258
  // message + recovery hint, not error data (#88), so a content-only client
@@ -248,15 +260,20 @@ export const getFilingTool = tool('secedgar_get_filing', {
248
260
  // section_not_found already uses for its outline, bounded per category.
249
261
  const catalogBlock = renderDocumentCatalog(resolved.documents);
250
262
  const primaryName = resolved.documents.primary[0]?.name;
251
- // A document the index lists but the archive does not serve (the
252
- // sequence-numbered names in many 2000–2001 indexes) is readable only
253
- // through the full submission file (#158).
263
+ const submission = `${accn}.txt`;
264
+ // A document the index lists but the archive serves under neither its
265
+ // name nor, for a 2000–2001 sequence-numbered one, its accession-prefixed
266
+ // spelling (#213) is readable only through the full submission file
267
+ // (#158) — unless that is the document that just failed, when only the
268
+ // filer's CIK is left (#203).
254
269
  // Otherwise: a non-empty primary bucket is exactly the condition under
255
270
  // which the no-document call succeeds — the loop only reaches this
256
271
  // branch past findPrimaryDocument. Without one, that call fails the
257
272
  // same way, so don't advertise a route that dead-ends.
258
273
  const hint = resolved.notServed
259
- ? `Use document="${accn}.txt", the full submission file, which the archive serves for this filing.`
274
+ ? resolved.requestedDocument === submission
275
+ ? `${lookupNote}The SEC archive does not serve the full submission file under the CIKs tried; pass ${FILER_CIK}.`
276
+ : `${lookupNote}Use document="${submission}", the full submission file, which holds every document of this filing, or pass ${FILER_CIK}.`
260
277
  : primaryName
261
278
  ? `Use document="${primaryName}" (the primary), or pick another filename from the list above. Call secedgar_get_filing again with the same accession_number and no document argument for the complete catalog.`
262
279
  : catalogBlock
@@ -286,17 +303,21 @@ export const getFilingTool = tool('secedgar_get_filing', {
286
303
  }
287
304
  if (resolved.kind === 'no_documents') {
288
305
  const catalogBlock = renderDocumentCatalog(resolved.documents);
306
+ // A primary always stands in when the index lists anything, and this
307
+ // branch is reached only with a listing (filing_not_found otherwise).
308
+ const primaryName = resolved.documents.primary[0]?.name ?? '';
309
+ // No `document` was requested here — that is what this branch means — so
310
+ // omitting it is the call that just failed and is not a route out. Neither
311
+ // is the primary that just failed, nor the full submission tried in its
312
+ // place (#158); another listed document may be served.
313
+ const another = listsAnotherReadable(resolved.documents, [primaryName, `${accn}.txt`])
314
+ ? ' Or set document to another filename listed above.'
315
+ : '';
289
316
  throw ctx.fail('no_documents', `No primary document found in filing ${accn}.${catalogBlock}`, {
290
317
  accession_number: accn,
291
318
  documents: resolved.documents,
292
319
  recovery: {
293
- // No `document` was requested here — that is what this branch means —
294
- // so omitting it is the call that just failed and is not a route out.
295
- // Naming a fetchable document is, and a successful response carries
296
- // the complete catalog.
297
- hint: catalogBlock
298
- ? 'Set the document input to one of the filenames listed above; a successful response lists the complete document catalog.'
299
- : 'Specify the document input using a filename from documents.primary in error data.',
320
+ hint: `${lookupNote}Pass ${FILER_CIK}: the SEC archive does not serve the primary document, ${primaryName}, under the CIKs tried.${another}`,
300
321
  },
301
322
  });
302
323
  }
@@ -304,8 +325,10 @@ export const getFilingTool = tool('secedgar_get_filing', {
304
325
  ? ` (CIK ${resolved.providedCik.padStart(10, '0')})`
305
326
  : '';
306
327
  const recoveryHint = resolved.providedCik
307
- ? 'Verify the accession number and CIK are correct.'
308
- : 'Verify the accession number and pass the company CIK explicitly.';
328
+ ? `${lookupNote}Verify the accession number and CIK are correct.`
329
+ : resolved.filerLookupFailed
330
+ ? `${lookupNote}Pass ${FILER_CIK}, or retry in a minute.`
331
+ : 'Verify the accession number and pass the company CIK explicitly.';
309
332
  throw ctx.fail('filing_not_found', `Filing '${accn}' not found${cikSuffix}.`, {
310
333
  accession_number: accn,
311
334
  cik: resolved.providedCik,
@@ -327,7 +350,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
327
350
  // archive served the cached text (no candidate search, no document body fetch).
328
351
  // A resolution failure here is a real failure (EDGAR index unavailable or the
329
352
  // filing gone): fail honestly rather than fabricating placeholder metadata.
330
- const metaResolved = await resolveFilingMeta(api, scope, accn, cached.cik, input.document);
353
+ const metaResolved = await resolveFilingMeta(api, scope, accn, cached.cik, document);
331
354
  if (!metaResolved.ok) {
332
355
  throw ctx.fail('filing_not_found', `Filing '${accn}' could not be resolved.`, {
333
356
  accession_number: accn,
@@ -341,7 +364,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
341
364
  targetName = cached.document;
342
365
  filingPrimaryName = metaResolved.filingPrimaryName;
343
366
  // A primary read cached from the full submission keeps reporting it (#158).
344
- if (!input.document &&
367
+ if (!document &&
345
368
  cached.document === `${accn}.txt` &&
346
369
  cached.document !== metaResolved.filingPrimaryName) {
347
370
  unservedPrimary = metaResolved.filingPrimaryName;
@@ -377,7 +400,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
377
400
  ? undefined
378
401
  : resolveSection(fullText, headings, input.section, PROXY_FORM_RE.test(form ?? ''));
379
402
  // The notices are authored Markdown, so the caller's section text is escaped.
380
- const sectionText = escapeMarkdownInline(input.section);
403
+ const sectionText = escapeInline(input.section);
381
404
  if (landing?.source === 'line') {
382
405
  lineNotice = `No detected heading matches section '${sectionText}', so this page starts at the first document line that does.`;
383
406
  }
@@ -423,7 +446,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
423
446
  // guidance. The outline is emitted only on a truncated page, so the cut
424
447
  // always has guidance to join.
425
448
  const fallbackNotice = unservedPrimary
426
- ? `The filing index names ${escapeMarkdownInline(unservedPrimary)} as the primary document, but the SEC archive does not serve it, so this text is the full submission file ${escapeMarkdownInline(targetName)}.`
449
+ ? `The filing index names ${escapeInline(unservedPrimary)} as the primary document, but the SEC archive does not serve it, so this text is the full submission file ${escapeInline(targetName)}.`
427
450
  : undefined;
428
451
  if (truncated) {
429
452
  // section outranks offset, so a caller who keeps it reads this page again.
@@ -453,7 +476,15 @@ export const getFilingTool = tool('secedgar_get_filing', {
453
476
  headersResolved: headers !== null,
454
477
  unservedPrimary,
455
478
  });
456
- const requestedDocument = input.document && input.document !== filingPrimaryName ? input.document : undefined;
479
+ const requestedDocument = document && document !== filingPrimaryName ? document : undefined;
480
+ // A primary read under a name the index does not list — its accession-prefixed
481
+ // spelling (#213) or SEC's rendering (#216) — is reported by that name, as
482
+ // filing_url is; documents keeps the index's names.
483
+ const primaryDocument = !document &&
484
+ (targetName === renderingOf(filingPrimaryName, accn, records) ||
485
+ archiveSpellings(filingPrimaryName, accn).includes(targetName))
486
+ ? targetName
487
+ : filingPrimaryName;
457
488
  return {
458
489
  accession_number: accn,
459
490
  form: form || undefined,
@@ -461,7 +492,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
461
492
  company_name: submissions.name || undefined,
462
493
  cik: resolvedCik,
463
494
  period_ending: periodEnding || undefined,
464
- primary_document: filingPrimaryName,
495
+ primary_document: primaryDocument,
465
496
  requested_document: requestedDocument,
466
497
  documents,
467
498
  content: text,
@@ -474,7 +505,10 @@ export const getFilingTool = tool('secedgar_get_filing', {
474
505
  },
475
506
  format: (result) => {
476
507
  const formLabel = result.form ?? 'Filing';
477
- const entity = result.company_name ?? 'Unknown entity';
508
+ // SEC's name, the filer's headings, and document descriptions render through
509
+ // escapeInline, so content[] reads back the structuredContent value (#221).
510
+ // The filing body between the sentinels stays verbatim (#69).
511
+ const entity = result.company_name ? escapeInline(result.company_name) : 'Unknown entity';
478
512
  const header = `**${formLabel}** — ${entity} (CIK ${result.cik})`;
479
513
  const filedPart = result.filing_date ? `Filed: ${result.filing_date}` : 'Filed: Unknown';
480
514
  const periodPart = result.period_ending ? ` | Period: ${result.period_ending}` : '';
@@ -487,9 +521,11 @@ export const getFilingTool = tool('secedgar_get_filing', {
487
521
  : '';
488
522
  const meta = `Accession: ${result.accession_number} | ${docLabel} | ${result.content_total_length} chars${truncatedNote}`;
489
523
  const docs = formatDocumentSection(result.documents);
490
- const outlineText = result.outline && result.outline.length > 0
491
- ? `\n\nOutline:\n${renderOutline(result.outline)}`
492
- : '';
524
+ const outline = result.outline?.map((h) => ({
525
+ ...h,
526
+ heading: escapeInline(h.heading),
527
+ }));
528
+ const outlineText = outline?.length ? `\n\nOutline:\n${renderOutline(outline)}` : '';
493
529
  const url = `\nURL: ${result.filing_url}`;
494
530
  return [
495
531
  {
@@ -766,7 +802,9 @@ function outlineCutNote(outline, detected) {
766
802
  * Render outline entries as ` [offset] HEADING` lines. Shared by format()
767
803
  * and the section_not_found error message, so both surfaces read identically.
768
804
  * Both render a {@link selectOutline} cut, which bounds the block at
769
- * {@link OUTLINE_MAX_ENTRIES} entries.
805
+ * {@link OUTLINE_MAX_ENTRIES} entries. Headings go in as given: format() passes
806
+ * them escaped, while the error message takes them raw, since the framework
807
+ * escapes the whole message when it renders it (#221).
770
808
  */
771
809
  function renderOutline(outline) {
772
810
  return outline.map((h) => ` [${h.offset}] ${h.heading}`).join('\n');
@@ -809,6 +847,10 @@ function renderDocumentCatalog(documents) {
809
847
  return '';
810
848
  return `\n\nAvailable documents (up to ${MAX_DOCUMENTS_IN_ERROR} shown per category):\n${sections.join('\n')}`;
811
849
  }
850
+ /** True when the catalog lists a readable filing document other than `excluded` and SEC's index pages. */
851
+ function listsAnotherReadable(documents, excluded) {
852
+ return [...documents.primary, ...documents.exhibits, ...documents.auxiliary].some((entry) => !entry.binary && isNonIndexFile(entry.name) && !excluded.includes(entry.name));
853
+ }
812
854
  /**
813
855
  * Normalize a schema-validated accession number to dash format (0000320193-23-000106).
814
856
  * Input shape is guaranteed by the input schema regex: dash format or 18-digit no-dash.
@@ -818,26 +860,93 @@ function normalizeAccessionNumber(input) {
818
860
  return input;
819
861
  return `${input.slice(0, 10)}-${input.slice(10, 12)}-${input.slice(12)}`;
820
862
  }
863
+ /**
864
+ * At most this many parties the filing's index page names are tried past the
865
+ * candidate CIKs (#203). A filing lives under every party's directory, so the
866
+ * first untried one almost always serves it; a group filing can name dozens.
867
+ */
868
+ const INDEX_PAGE_PARTY_CAP = 3;
821
869
  /**
822
870
  * Resolve filing archive: fetch index + primary document HTML.
823
871
  * Used on cache misses to get both the document content and index metadata.
872
+ *
873
+ * When no candidate directory serves the filing, the filing's index page names its
874
+ * parties, and up to {@link INDEX_PAGE_PARTY_CAP} of them not yet tried are
875
+ * searched the same way (#203). A pre-2001 accession filed through an agent needs
876
+ * it: full-text search has no record before 2001, and the agent's directory, the
877
+ * only other candidate, holds no copy the archive serves. The page costs one
878
+ * request, sent only after every candidate failed, and only when a directory's
879
+ * listing named the target but the archive did not serve it, or no directory
880
+ * answered at all — a document no listing names is missing from every party's
881
+ * directory alike.
824
882
  */
825
883
  async function resolveFilingArchive(api, scope, accessionNumber, providedCik, requestedDocument) {
826
- const candidateCiks = await resolveCandidateCiks(api, scope, accessionNumber, providedCik);
827
- /** The last archive path whose index exists, with its records, for the error catalog. */
828
- let lastIndexed;
884
+ const candidates = await resolveCandidateCiks(api, scope, accessionNumber, providedCik);
885
+ let filerLookupFailed = candidates.filerLookupFailed;
886
+ const search = {
887
+ tried: new Set(),
888
+ requestedNotServed: false,
889
+ primaryNotServed: false,
890
+ };
891
+ const found = await searchArchive(api, scope, accessionNumber, candidates.ciks, requestedDocument, search);
892
+ if (found)
893
+ return found;
894
+ if (!search.lastIndexed?.items.length || search.requestedNotServed || search.primaryNotServed) {
895
+ const parties = await readFilingParties(api, scope, accessionNumber);
896
+ filerLookupFailed ||= parties === undefined;
897
+ const untried = (parties ?? [])
898
+ .filter((cik) => !search.tried.has(cik))
899
+ .slice(0, INDEX_PAGE_PARTY_CAP);
900
+ if (untried.length > 0) {
901
+ const refound = await searchArchive(api, scope, accessionNumber, untried, requestedDocument, search);
902
+ if (refound)
903
+ return refound;
904
+ }
905
+ }
906
+ const { lastIndexed } = search;
907
+ if (!lastIndexed?.items.length) {
908
+ return { ok: false, kind: 'filing_not_found', providedCik, filerLookupFailed };
909
+ }
910
+ // Categorize as the success path does: the same primary, the header page's types.
911
+ const errorPrimaryName = findPrimaryDocument(lastIndexed.items, accessionNumber, lastIndexed.records) ?? '';
912
+ const documents = categorizeDocuments(lastIndexed.items, errorPrimaryName, lastIndexed.records.headers?.documents ?? null, false);
913
+ if (requestedDocument) {
914
+ return {
915
+ ok: false,
916
+ kind: 'document_not_found',
917
+ requestedDocument,
918
+ notServed: search.requestedNotServed,
919
+ documents,
920
+ filerLookupFailed,
921
+ };
922
+ }
923
+ return { ok: false, kind: 'no_documents', documents, filerLookupFailed };
924
+ }
925
+ /**
926
+ * Search the archive directories of `ciks` in order for the filing, recording what
927
+ * each taught in `search`: the filing's outcome once a directory serves its target
928
+ * or holds it as a binary entry, else `undefined`. Each directory reads the target
929
+ * under every name SEC may serve it by before the next is tried: a sequence-numbered
930
+ * name, then its accession-prefixed spelling (#213); for an XML form's primary, SEC's
931
+ * rendering, then the raw file (#216). A primary none of these directories serves is
932
+ * then read from the full submission (#158).
933
+ */
934
+ async function searchArchive(api, scope, accessionNumber, ciks, requestedDocument, search) {
829
935
  /** First archive path whose index named a primary the archive answered 404 for. */
830
936
  let unserved;
831
- let requestedNotServed = false;
832
- for (const cik of candidateCiks) {
937
+ for (const cik of ciks) {
938
+ search.tried.add(cik);
833
939
  const index = await api.tryGetFilingIndex(cik, accessionNumber, scope);
834
940
  if (!index)
835
941
  continue;
836
942
  // Records name the primary every outcome below reports, error catalogs included.
837
943
  const items = index.directory.item;
838
944
  const records = await readFilingRecords(api, scope, cik, accessionNumber);
839
- lastIndexed = { items, records };
840
- if (requestedDocument && !items.some((item) => item.name === requestedDocument))
945
+ search.lastIndexed = { items, records };
946
+ const requestedNames = requestedDocument
947
+ ? requestedReadNames(requestedDocument, accessionNumber, items, records)
948
+ : undefined;
949
+ if (requestedDocument && !requestedNames)
841
950
  continue;
842
951
  const filingPrimaryName = findPrimaryDocument(items, accessionNumber, records);
843
952
  if (!filingPrimaryName)
@@ -862,54 +971,60 @@ async function resolveFilingArchive(api, scope, accessionNumber, providedCik, re
862
971
  documents,
863
972
  };
864
973
  }
865
- const html = await api.tryGetFilingDocument(cik, accessionNumber, targetName, scope);
866
- if (html)
867
- return { ok: true, cik, html, index, targetName, filingPrimaryName, records };
974
+ const rendering = requestedDocument
975
+ ? undefined
976
+ : renderingToRead(filingPrimaryName, accessionNumber, items, records);
977
+ const names = requestedNames ??
978
+ (rendering
979
+ ? [rendering, filingPrimaryName]
980
+ : archiveSpellings(filingPrimaryName, accessionNumber));
981
+ for (const name of names) {
982
+ const read = () => api.tryGetFilingDocument(cik, accessionNumber, name, scope);
983
+ /**
984
+ * A primary read under a name the index does not list — SEC's rendering, or
985
+ * the accession-prefixed spelling — gives way, when SEC cannot serve it, to
986
+ * the raw file or the full submission (#158), the way an unavailable index
987
+ * page leaves the outcome the candidates reached (#203). A document the
988
+ * caller named is never optional.
989
+ */
990
+ const optional = !requestedDocument && name !== filingPrimaryName;
991
+ const html = optional ? await unlessSecUnavailable(scope, read) : await read();
992
+ if (html) {
993
+ return { ok: true, cik, html, index, targetName: name, filingPrimaryName, records };
994
+ }
995
+ }
868
996
  if (requestedDocument)
869
- requestedNotServed = true;
997
+ search.requestedNotServed = true;
870
998
  else
871
999
  unserved ??= { cik, index, primary: targetName, records };
872
1000
  }
873
1001
  /**
874
1002
  * Many 2000–2001 indexes list sequence-numbered documents (`0001.htm`,
875
- * `0001.txt`) the archive answers 404 for, while the full submission
876
- * `<accession>.txt` is served (#158). A primary no candidate CIK serves is read
877
- * from it instead — after the loop, so a CIK that serves the primary still
878
- * wins, and only for the primary: a document the caller named fails with a
879
- * hint pointing at the submission.
1003
+ * `0001.txt`) the archive answers 404 for, and serves under their
1004
+ * accession-prefixed spelling (#213); for a filing that serves neither, the full
1005
+ * submission `<accession>.txt` is read instead (#158) — after the loop, so a CIK
1006
+ * that serves the primary still wins, and only for the primary: a document the
1007
+ * caller named fails with a hint pointing at the submission.
880
1008
  */
1009
+ if (!unserved)
1010
+ return;
1011
+ search.primaryNotServed = true;
881
1012
  const submission = `${accessionNumber}.txt`;
882
- if (unserved && unserved.primary !== submission) {
883
- const html = await api.tryGetFilingDocument(unserved.cik, accessionNumber, submission, scope);
884
- if (html) {
885
- return {
886
- ok: true,
887
- cik: unserved.cik,
888
- html,
889
- index: unserved.index,
890
- targetName: submission,
891
- filingPrimaryName: submission,
892
- unservedPrimary: unserved.primary,
893
- records: unserved.records,
894
- };
895
- }
896
- }
897
- if (!lastIndexed?.items.length) {
898
- return { ok: false, kind: 'filing_not_found', providedCik };
899
- }
900
- // Categorize as the success path does: the same primary, the header page's types.
901
- const errorPrimaryName = findPrimaryDocument(lastIndexed.items, accessionNumber, lastIndexed.records) ?? '';
902
- const documents = categorizeDocuments(lastIndexed.items, errorPrimaryName, lastIndexed.records.headers?.documents ?? null, false);
903
- if (requestedDocument) {
904
- return {
905
- ok: false,
906
- kind: 'document_not_found',
907
- requestedDocument,
908
- notServed: requestedNotServed,
909
- documents,
910
- };
911
- }
912
- return { ok: false, kind: 'no_documents', documents };
1013
+ if (unserved.primary === submission)
1014
+ return;
1015
+ const html = await api.tryGetFilingDocument(unserved.cik, accessionNumber, submission, scope);
1016
+ if (!html)
1017
+ return;
1018
+ return {
1019
+ ok: true,
1020
+ cik: unserved.cik,
1021
+ html,
1022
+ index: unserved.index,
1023
+ targetName: submission,
1024
+ filingPrimaryName: submission,
1025
+ unservedPrimary: unserved.primary,
1026
+ records: unserved.records,
1027
+ };
913
1028
  }
914
1029
  /**
915
1030
  * Resolve filing index and document names under one CIK WITHOUT fetching the
@@ -921,10 +1036,11 @@ async function resolveFilingMeta(api, scope, accessionNumber, cik, requestedDocu
921
1036
  if (!index)
922
1037
  return { ok: false };
923
1038
  const items = index.directory.item;
924
- if (requestedDocument && !items.some((item) => item.name === requestedDocument)) {
1039
+ const records = await readFilingRecords(api, scope, cik, accessionNumber);
1040
+ if (requestedDocument &&
1041
+ !requestedReadNames(requestedDocument, accessionNumber, items, records)) {
925
1042
  return { ok: false };
926
1043
  }
927
- const records = await readFilingRecords(api, scope, cik, accessionNumber);
928
1044
  const filingPrimaryName = findPrimaryDocument(items, accessionNumber, records);
929
1045
  if (!filingPrimaryName)
930
1046
  return { ok: false };
@@ -942,12 +1058,57 @@ async function readFilingRecords(api, scope, cik, accessionNumber) {
942
1058
  ]);
943
1059
  return { headers, submissions };
944
1060
  }
1061
+ /**
1062
+ * The CIKs whose archive directories are searched first, in order: the caller's
1063
+ * `cik` alone, or the filers EDGAR full-text search records for the accession, then
1064
+ * the CIK the accession number opens with — the filer's own, or a filing agent's.
1065
+ * When SEC cannot answer the search (#215), the prefix alone is searched and
1066
+ * `filerLookupFailed` says so; the caller's cancellation and a rate-limit refusal
1067
+ * still end the call.
1068
+ */
945
1069
  async function resolveCandidateCiks(api, scope, accessionNumber, providedCik) {
946
1070
  if (providedCik)
947
- return [providedCik.padStart(10, '0')];
948
- const ciks = await api.findFilingCiks(accessionNumber, scope);
949
- const prefixCik = (accessionNumber.split('-')[0] ?? accessionNumber.slice(0, 10)).padStart(10, '0');
950
- return [...new Set([...ciks, prefixCik])];
1071
+ return { ciks: [providedCik.padStart(10, '0')], filerLookupFailed: false };
1072
+ const searched = await unlessSecUnavailable(scope, () => api.findFilingCiks(accessionNumber, scope));
1073
+ return {
1074
+ ciks: [...new Set([...(searched ?? []), accessionPrefixCik(accessionNumber)])],
1075
+ filerLookupFailed: searched === undefined,
1076
+ };
1077
+ }
1078
+ /**
1079
+ * The parties the filing's index page names, read under the accession number's
1080
+ * own prefix CIK: SEC serves the page there for any filing that exists, a filing
1081
+ * agent's prefix included, even when that directory holds no `index.json` (#203).
1082
+ * `null` when the page is missing; `undefined` when SEC could not serve it.
1083
+ */
1084
+ function readFilingParties(api, scope, accessionNumber) {
1085
+ return unlessSecUnavailable(scope, () => api.tryGetFilingPartyCiks(accessionPrefixCik(accessionNumber), accessionNumber, scope));
1086
+ }
1087
+ /** The CIK an accession number opens with, padded to 10 digits: the submitter's, filer or agent. */
1088
+ function accessionPrefixCik(accessionNumber) {
1089
+ return accessionNumber.slice(0, 10);
1090
+ }
1091
+ /**
1092
+ * Run an optional SEC lookup, answering `undefined` when SEC is unavailable for it:
1093
+ * no response or an unreadable body (`sec_unreachable`), a 5xx, or a full-text
1094
+ * search backend failure or refusal (`efts_degraded_response`), all
1095
+ * `ServiceUnavailable`, or a 504, which maps to `Timeout`. Everything else is
1096
+ * rethrown untouched — the caller's cancellation, a rate-limit refusal (SEC's block
1097
+ * covers every request the call would send next), and any other failure that says
1098
+ * the request itself is wrong.
1099
+ */
1100
+ async function unlessSecUnavailable(scope, lookup) {
1101
+ try {
1102
+ return await lookup();
1103
+ }
1104
+ catch (error) {
1105
+ const unavailable = error instanceof McpError &&
1106
+ (error.code === JsonRpcErrorCode.ServiceUnavailable ||
1107
+ error.code === JsonRpcErrorCode.Timeout);
1108
+ if (!unavailable || scope.signal.aborted)
1109
+ throw error;
1110
+ return;
1111
+ }
951
1112
  }
952
1113
  /** SEC's XBRL viewer pages (`R1.htm`, `R2.htm`, …), which can outweigh a filing's own documents. */
953
1114
  const RENDERER_PAGE = /^R\d+\.html?$/;
@@ -983,13 +1144,83 @@ function findPrimaryDocument(items, accessionNumber, records) {
983
1144
  * (`xslF345X06/form4.xml`), so only the last segment names the archive file.
984
1145
  */
985
1146
  function recordedPrimaryNames(accessionNumber, { headers, submissions }) {
986
- const recent = submissions.filings.recent;
987
- const row = recent.accessionNumber.indexOf(accessionNumber);
988
- const fromFeed = row >= 0 ? recent.primaryDocument[row]?.split('/').pop() : undefined;
1147
+ const fromFeed = feedPrimaryDocument(accessionNumber, submissions)?.split('/').pop();
989
1148
  const form = headers?.submission.form;
990
1149
  const typed = headers && form ? [...headers.documents].find(([, doc]) => doc.type === form)?.[0] : undefined;
991
1150
  return [fromFeed, typed];
992
1151
  }
1152
+ /** The `primaryDocument` the submissions feed records for the accession, when it sits in the recent window. */
1153
+ function feedPrimaryDocument(accessionNumber, submissions) {
1154
+ const recent = submissions.filings.recent;
1155
+ const row = recent.accessionNumber.indexOf(accessionNumber);
1156
+ return row >= 0 ? recent.primaryDocument[row] : undefined;
1157
+ }
1158
+ /**
1159
+ * A 2000–2001 sequence-numbered document name (`0001.htm`, `0002.txt`). Anchored,
1160
+ * one quantified class after a fixed prefix: linear in a caller-named document.
1161
+ */
1162
+ const SEQUENCE_NUMBERED_NAME = /^\d{4}\.\w+$/;
1163
+ /** A stylesheet path the submissions feed records an XML form through (`xslF345X06/form4.xml`). */
1164
+ const RENDERING_PATH = /^xsl[^/]+\/[^/]+$/;
1165
+ /**
1166
+ * The largest raw XML file whose SEC rendering is read in its place (#216). A
1167
+ * holdings report's rendering runs to about 20 times its raw file — an NPORT-P
1168
+ * listing 505 positions is 500,525 bytes raw and 9,777,862 rendered — and the
1169
+ * HTML converter silently cuts input past 16,777,216 characters, 28 times this
1170
+ * bound, so a raw file past it is read as filed. A 13D or Form 4 is far below it.
1171
+ */
1172
+ const MAX_RENDERED_RAW_BYTES = 600_000;
1173
+ /**
1174
+ * `name`, then — for a 2000–2001 sequence-numbered name the archive may not serve
1175
+ * as listed — its accession-prefixed spelling (`<accession>-0001.htm`), under
1176
+ * which SEC serves the same document (#213).
1177
+ */
1178
+ function archiveSpellings(name, accessionNumber) {
1179
+ return SEQUENCE_NUMBERED_NAME.test(name) ? [name, `${accessionNumber}-${name}`] : [name];
1180
+ }
1181
+ /**
1182
+ * The stylesheet path the submissions feed records the filing's primary through
1183
+ * when `file` is that primary (`xslSCHEDULE_13D_X02/primary_doc.xml` for
1184
+ * `primary_doc.xml`): SEC serves its rendering of the form there (#216).
1185
+ */
1186
+ function renderingOf(file, accessionNumber, { submissions }) {
1187
+ const recorded = feedPrimaryDocument(accessionNumber, submissions);
1188
+ return recorded !== undefined && RENDERING_PATH.test(recorded) && recorded.endsWith(`/${file}`)
1189
+ ? recorded
1190
+ : undefined;
1191
+ }
1192
+ /**
1193
+ * The rendering read in place of the primary `file` when no document is named
1194
+ * (#216): the one {@link renderingOf} finds, while the index lists the raw file at
1195
+ * most {@link MAX_RENDERED_RAW_BYTES}. A raw file listed with no size reads as filed.
1196
+ */
1197
+ function renderingToRead(file, accessionNumber, items, records) {
1198
+ const rendering = renderingOf(file, accessionNumber, records);
1199
+ const size = Number.parseInt(items.find((item) => item.name === file)?.size ?? '', 10);
1200
+ return rendering !== undefined && size <= MAX_RENDERED_RAW_BYTES ? rendering : undefined;
1201
+ }
1202
+ /**
1203
+ * The names a caller-named document is read under, in order, or `undefined` when
1204
+ * the filing holds no such document: a listed name, then its accession-prefixed
1205
+ * spelling (see {@link archiveSpellings}); the prefixed spelling of a listed
1206
+ * sequence-numbered name, then that name (#213); or the stylesheet path the
1207
+ * submissions feed records for a listed file, read as SEC renders it (#216).
1208
+ */
1209
+ function requestedReadNames(requested, accessionNumber, items, records) {
1210
+ const listed = (name) => items.some((item) => item.name === name);
1211
+ if (listed(requested))
1212
+ return archiveSpellings(requested, accessionNumber);
1213
+ const prefix = `${accessionNumber}-`;
1214
+ if (requested.startsWith(prefix)) {
1215
+ const name = requested.slice(prefix.length);
1216
+ if (SEQUENCE_NUMBERED_NAME.test(name) && listed(name))
1217
+ return [requested, name];
1218
+ }
1219
+ const file = requested.slice(requested.lastIndexOf('/') + 1);
1220
+ return listed(file) && renderingOf(file, accessionNumber, records) === requested
1221
+ ? [requested]
1222
+ : undefined;
1223
+ }
993
1224
  function getLargestDocument(items) {
994
1225
  return [...items].sort((a, b) => (Number.parseInt(b.size, 10) || 0) - (Number.parseInt(a.size, 10) || 0))[0];
995
1226
  }
@@ -1164,7 +1395,7 @@ function formatDocList(entries) {
1164
1395
  d.type,
1165
1396
  d.binary ? 'binary' : null,
1166
1397
  d.size !== undefined ? `${d.size}B` : null,
1167
- d.description ? `"${d.description}"` : null,
1398
+ d.description ? `"${escapeInline(d.description)}"` : null,
1168
1399
  ]
1169
1400
  .filter(Boolean)
1170
1401
  .join(', ');