@cyanheads/secedgar-mcp-server 0.17.0 → 0.17.1

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 (59) hide show
  1. package/AGENTS.md +18 -15
  2. package/CLAUDE.md +18 -15
  3. package/README.md +12 -9
  4. package/changelog/0.17.x/0.17.1.md +36 -0
  5. package/dist/config/server-config.js +1 -1
  6. package/dist/config/server-config.js.map +1 -1
  7. package/dist/index.js +2 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
  10. package/dist/mcp-server/tools/definitions/company-search.tool.js +6 -4
  11. package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
  12. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +8 -4
  13. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
  14. package/dist/mcp-server/tools/definitions/compare-companies.tool.js +169 -39
  15. package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
  16. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +4 -4
  17. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
  18. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +24 -8
  19. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
  20. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +14 -0
  21. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
  22. package/dist/mcp-server/tools/definitions/find-holders.tool.js +34 -7
  23. package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
  24. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +2 -0
  25. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
  26. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +146 -77
  27. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
  28. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +4 -4
  29. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
  30. package/dist/mcp-server/tools/definitions/get-filing.tool.js +305 -81
  31. package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
  32. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +14 -0
  33. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
  34. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +8 -0
  35. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
  36. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
  37. package/dist/mcp-server/tools/definitions/get-material-events.tool.js +3 -1
  38. package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
  39. package/dist/mcp-server/tools/definitions/index.d.ts +453 -423
  40. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  41. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +33 -0
  42. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
  43. package/dist/mcp-server/tools/definitions/search-filings.tool.js +31 -2
  44. package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
  45. package/dist/mcp-server/tools/limit-clamp.d.ts +50 -18
  46. package/dist/mcp-server/tools/limit-clamp.d.ts.map +1 -1
  47. package/dist/mcp-server/tools/limit-clamp.js +51 -15
  48. package/dist/mcp-server/tools/limit-clamp.js.map +1 -1
  49. package/dist/services/edgar/edgar-api-service.d.ts +75 -11
  50. package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
  51. package/dist/services/edgar/edgar-api-service.js +273 -50
  52. package/dist/services/edgar/edgar-api-service.js.map +1 -1
  53. package/dist/services/edgar/filing-to-text.d.ts +4 -3
  54. package/dist/services/edgar/filing-to-text.d.ts.map +1 -1
  55. package/dist/services/edgar/filing-to-text.js +12 -0
  56. package/dist/services/edgar/filing-to-text.js.map +1 -1
  57. package/package.json +4 -4
  58. package/server.json +3 -3
  59. package/skills/secedgar-guide/SKILL.md +1 -0
@@ -3,7 +3,7 @@
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';
6
+ import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
7
7
  import { escapeMarkdownInline } from '@cyanheads/mcp-ts-core/utils';
8
8
  import { limitClamp, withLimitClamps, } from '../limit-clamp.js';
9
9
  import { CallScope } from '../../../services/edgar/call-scope.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;
@@ -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,
@@ -809,6 +840,10 @@ function renderDocumentCatalog(documents) {
809
840
  return '';
810
841
  return `\n\nAvailable documents (up to ${MAX_DOCUMENTS_IN_ERROR} shown per category):\n${sections.join('\n')}`;
811
842
  }
843
+ /** True when the catalog lists a readable filing document other than `excluded` and SEC's index pages. */
844
+ function listsAnotherReadable(documents, excluded) {
845
+ return [...documents.primary, ...documents.exhibits, ...documents.auxiliary].some((entry) => !entry.binary && isNonIndexFile(entry.name) && !excluded.includes(entry.name));
846
+ }
812
847
  /**
813
848
  * Normalize a schema-validated accession number to dash format (0000320193-23-000106).
814
849
  * Input shape is guaranteed by the input schema regex: dash format or 18-digit no-dash.
@@ -818,26 +853,93 @@ function normalizeAccessionNumber(input) {
818
853
  return input;
819
854
  return `${input.slice(0, 10)}-${input.slice(10, 12)}-${input.slice(12)}`;
820
855
  }
856
+ /**
857
+ * At most this many parties the filing's index page names are tried past the
858
+ * candidate CIKs (#203). A filing lives under every party's directory, so the
859
+ * first untried one almost always serves it; a group filing can name dozens.
860
+ */
861
+ const INDEX_PAGE_PARTY_CAP = 3;
821
862
  /**
822
863
  * Resolve filing archive: fetch index + primary document HTML.
823
864
  * Used on cache misses to get both the document content and index metadata.
865
+ *
866
+ * When no candidate directory serves the filing, the filing's index page names its
867
+ * parties, and up to {@link INDEX_PAGE_PARTY_CAP} of them not yet tried are
868
+ * searched the same way (#203). A pre-2001 accession filed through an agent needs
869
+ * it: full-text search has no record before 2001, and the agent's directory, the
870
+ * only other candidate, holds no copy the archive serves. The page costs one
871
+ * request, sent only after every candidate failed, and only when a directory's
872
+ * listing named the target but the archive did not serve it, or no directory
873
+ * answered at all — a document no listing names is missing from every party's
874
+ * directory alike.
824
875
  */
825
876
  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;
877
+ const candidates = await resolveCandidateCiks(api, scope, accessionNumber, providedCik);
878
+ let filerLookupFailed = candidates.filerLookupFailed;
879
+ const search = {
880
+ tried: new Set(),
881
+ requestedNotServed: false,
882
+ primaryNotServed: false,
883
+ };
884
+ const found = await searchArchive(api, scope, accessionNumber, candidates.ciks, requestedDocument, search);
885
+ if (found)
886
+ return found;
887
+ if (!search.lastIndexed?.items.length || search.requestedNotServed || search.primaryNotServed) {
888
+ const parties = await readFilingParties(api, scope, accessionNumber);
889
+ filerLookupFailed ||= parties === undefined;
890
+ const untried = (parties ?? [])
891
+ .filter((cik) => !search.tried.has(cik))
892
+ .slice(0, INDEX_PAGE_PARTY_CAP);
893
+ if (untried.length > 0) {
894
+ const refound = await searchArchive(api, scope, accessionNumber, untried, requestedDocument, search);
895
+ if (refound)
896
+ return refound;
897
+ }
898
+ }
899
+ const { lastIndexed } = search;
900
+ if (!lastIndexed?.items.length) {
901
+ return { ok: false, kind: 'filing_not_found', providedCik, filerLookupFailed };
902
+ }
903
+ // Categorize as the success path does: the same primary, the header page's types.
904
+ const errorPrimaryName = findPrimaryDocument(lastIndexed.items, accessionNumber, lastIndexed.records) ?? '';
905
+ const documents = categorizeDocuments(lastIndexed.items, errorPrimaryName, lastIndexed.records.headers?.documents ?? null, false);
906
+ if (requestedDocument) {
907
+ return {
908
+ ok: false,
909
+ kind: 'document_not_found',
910
+ requestedDocument,
911
+ notServed: search.requestedNotServed,
912
+ documents,
913
+ filerLookupFailed,
914
+ };
915
+ }
916
+ return { ok: false, kind: 'no_documents', documents, filerLookupFailed };
917
+ }
918
+ /**
919
+ * Search the archive directories of `ciks` in order for the filing, recording what
920
+ * each taught in `search`: the filing's outcome once a directory serves its target
921
+ * or holds it as a binary entry, else `undefined`. Each directory reads the target
922
+ * under every name SEC may serve it by before the next is tried: a sequence-numbered
923
+ * name, then its accession-prefixed spelling (#213); for an XML form's primary, SEC's
924
+ * rendering, then the raw file (#216). A primary none of these directories serves is
925
+ * then read from the full submission (#158).
926
+ */
927
+ async function searchArchive(api, scope, accessionNumber, ciks, requestedDocument, search) {
829
928
  /** First archive path whose index named a primary the archive answered 404 for. */
830
929
  let unserved;
831
- let requestedNotServed = false;
832
- for (const cik of candidateCiks) {
930
+ for (const cik of ciks) {
931
+ search.tried.add(cik);
833
932
  const index = await api.tryGetFilingIndex(cik, accessionNumber, scope);
834
933
  if (!index)
835
934
  continue;
836
935
  // Records name the primary every outcome below reports, error catalogs included.
837
936
  const items = index.directory.item;
838
937
  const records = await readFilingRecords(api, scope, cik, accessionNumber);
839
- lastIndexed = { items, records };
840
- if (requestedDocument && !items.some((item) => item.name === requestedDocument))
938
+ search.lastIndexed = { items, records };
939
+ const requestedNames = requestedDocument
940
+ ? requestedReadNames(requestedDocument, accessionNumber, items, records)
941
+ : undefined;
942
+ if (requestedDocument && !requestedNames)
841
943
  continue;
842
944
  const filingPrimaryName = findPrimaryDocument(items, accessionNumber, records);
843
945
  if (!filingPrimaryName)
@@ -862,54 +964,60 @@ async function resolveFilingArchive(api, scope, accessionNumber, providedCik, re
862
964
  documents,
863
965
  };
864
966
  }
865
- const html = await api.tryGetFilingDocument(cik, accessionNumber, targetName, scope);
866
- if (html)
867
- return { ok: true, cik, html, index, targetName, filingPrimaryName, records };
967
+ const rendering = requestedDocument
968
+ ? undefined
969
+ : renderingToRead(filingPrimaryName, accessionNumber, items, records);
970
+ const names = requestedNames ??
971
+ (rendering
972
+ ? [rendering, filingPrimaryName]
973
+ : archiveSpellings(filingPrimaryName, accessionNumber));
974
+ for (const name of names) {
975
+ const read = () => api.tryGetFilingDocument(cik, accessionNumber, name, scope);
976
+ /**
977
+ * A primary read under a name the index does not list — SEC's rendering, or
978
+ * the accession-prefixed spelling — gives way, when SEC cannot serve it, to
979
+ * the raw file or the full submission (#158), the way an unavailable index
980
+ * page leaves the outcome the candidates reached (#203). A document the
981
+ * caller named is never optional.
982
+ */
983
+ const optional = !requestedDocument && name !== filingPrimaryName;
984
+ const html = optional ? await unlessSecUnavailable(scope, read) : await read();
985
+ if (html) {
986
+ return { ok: true, cik, html, index, targetName: name, filingPrimaryName, records };
987
+ }
988
+ }
868
989
  if (requestedDocument)
869
- requestedNotServed = true;
990
+ search.requestedNotServed = true;
870
991
  else
871
992
  unserved ??= { cik, index, primary: targetName, records };
872
993
  }
873
994
  /**
874
995
  * 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.
996
+ * `0001.txt`) the archive answers 404 for, and serves under their
997
+ * accession-prefixed spelling (#213); for a filing that serves neither, the full
998
+ * submission `<accession>.txt` is read instead (#158) — after the loop, so a CIK
999
+ * that serves the primary still wins, and only for the primary: a document the
1000
+ * caller named fails with a hint pointing at the submission.
880
1001
  */
1002
+ if (!unserved)
1003
+ return;
1004
+ search.primaryNotServed = true;
881
1005
  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 };
1006
+ if (unserved.primary === submission)
1007
+ return;
1008
+ const html = await api.tryGetFilingDocument(unserved.cik, accessionNumber, submission, scope);
1009
+ if (!html)
1010
+ return;
1011
+ return {
1012
+ ok: true,
1013
+ cik: unserved.cik,
1014
+ html,
1015
+ index: unserved.index,
1016
+ targetName: submission,
1017
+ filingPrimaryName: submission,
1018
+ unservedPrimary: unserved.primary,
1019
+ records: unserved.records,
1020
+ };
913
1021
  }
914
1022
  /**
915
1023
  * Resolve filing index and document names under one CIK WITHOUT fetching the
@@ -921,10 +1029,11 @@ async function resolveFilingMeta(api, scope, accessionNumber, cik, requestedDocu
921
1029
  if (!index)
922
1030
  return { ok: false };
923
1031
  const items = index.directory.item;
924
- if (requestedDocument && !items.some((item) => item.name === requestedDocument)) {
1032
+ const records = await readFilingRecords(api, scope, cik, accessionNumber);
1033
+ if (requestedDocument &&
1034
+ !requestedReadNames(requestedDocument, accessionNumber, items, records)) {
925
1035
  return { ok: false };
926
1036
  }
927
- const records = await readFilingRecords(api, scope, cik, accessionNumber);
928
1037
  const filingPrimaryName = findPrimaryDocument(items, accessionNumber, records);
929
1038
  if (!filingPrimaryName)
930
1039
  return { ok: false };
@@ -942,12 +1051,57 @@ async function readFilingRecords(api, scope, cik, accessionNumber) {
942
1051
  ]);
943
1052
  return { headers, submissions };
944
1053
  }
1054
+ /**
1055
+ * The CIKs whose archive directories are searched first, in order: the caller's
1056
+ * `cik` alone, or the filers EDGAR full-text search records for the accession, then
1057
+ * the CIK the accession number opens with — the filer's own, or a filing agent's.
1058
+ * When SEC cannot answer the search (#215), the prefix alone is searched and
1059
+ * `filerLookupFailed` says so; the caller's cancellation and a rate-limit refusal
1060
+ * still end the call.
1061
+ */
945
1062
  async function resolveCandidateCiks(api, scope, accessionNumber, providedCik) {
946
1063
  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])];
1064
+ return { ciks: [providedCik.padStart(10, '0')], filerLookupFailed: false };
1065
+ const searched = await unlessSecUnavailable(scope, () => api.findFilingCiks(accessionNumber, scope));
1066
+ return {
1067
+ ciks: [...new Set([...(searched ?? []), accessionPrefixCik(accessionNumber)])],
1068
+ filerLookupFailed: searched === undefined,
1069
+ };
1070
+ }
1071
+ /**
1072
+ * The parties the filing's index page names, read under the accession number's
1073
+ * own prefix CIK: SEC serves the page there for any filing that exists, a filing
1074
+ * agent's prefix included, even when that directory holds no `index.json` (#203).
1075
+ * `null` when the page is missing; `undefined` when SEC could not serve it.
1076
+ */
1077
+ function readFilingParties(api, scope, accessionNumber) {
1078
+ return unlessSecUnavailable(scope, () => api.tryGetFilingPartyCiks(accessionPrefixCik(accessionNumber), accessionNumber, scope));
1079
+ }
1080
+ /** The CIK an accession number opens with, padded to 10 digits: the submitter's, filer or agent. */
1081
+ function accessionPrefixCik(accessionNumber) {
1082
+ return accessionNumber.slice(0, 10);
1083
+ }
1084
+ /**
1085
+ * Run an optional SEC lookup, answering `undefined` when SEC is unavailable for it:
1086
+ * no response or an unreadable body (`sec_unreachable`), a 5xx, or a full-text
1087
+ * search backend failure or refusal (`efts_degraded_response`), all
1088
+ * `ServiceUnavailable`, or a 504, which maps to `Timeout`. Everything else is
1089
+ * rethrown untouched — the caller's cancellation, a rate-limit refusal (SEC's block
1090
+ * covers every request the call would send next), and any other failure that says
1091
+ * the request itself is wrong.
1092
+ */
1093
+ async function unlessSecUnavailable(scope, lookup) {
1094
+ try {
1095
+ return await lookup();
1096
+ }
1097
+ catch (error) {
1098
+ const unavailable = error instanceof McpError &&
1099
+ (error.code === JsonRpcErrorCode.ServiceUnavailable ||
1100
+ error.code === JsonRpcErrorCode.Timeout);
1101
+ if (!unavailable || scope.signal.aborted)
1102
+ throw error;
1103
+ return;
1104
+ }
951
1105
  }
952
1106
  /** SEC's XBRL viewer pages (`R1.htm`, `R2.htm`, …), which can outweigh a filing's own documents. */
953
1107
  const RENDERER_PAGE = /^R\d+\.html?$/;
@@ -983,13 +1137,83 @@ function findPrimaryDocument(items, accessionNumber, records) {
983
1137
  * (`xslF345X06/form4.xml`), so only the last segment names the archive file.
984
1138
  */
985
1139
  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;
1140
+ const fromFeed = feedPrimaryDocument(accessionNumber, submissions)?.split('/').pop();
989
1141
  const form = headers?.submission.form;
990
1142
  const typed = headers && form ? [...headers.documents].find(([, doc]) => doc.type === form)?.[0] : undefined;
991
1143
  return [fromFeed, typed];
992
1144
  }
1145
+ /** The `primaryDocument` the submissions feed records for the accession, when it sits in the recent window. */
1146
+ function feedPrimaryDocument(accessionNumber, submissions) {
1147
+ const recent = submissions.filings.recent;
1148
+ const row = recent.accessionNumber.indexOf(accessionNumber);
1149
+ return row >= 0 ? recent.primaryDocument[row] : undefined;
1150
+ }
1151
+ /**
1152
+ * A 2000–2001 sequence-numbered document name (`0001.htm`, `0002.txt`). Anchored,
1153
+ * one quantified class after a fixed prefix: linear in a caller-named document.
1154
+ */
1155
+ const SEQUENCE_NUMBERED_NAME = /^\d{4}\.\w+$/;
1156
+ /** A stylesheet path the submissions feed records an XML form through (`xslF345X06/form4.xml`). */
1157
+ const RENDERING_PATH = /^xsl[^/]+\/[^/]+$/;
1158
+ /**
1159
+ * The largest raw XML file whose SEC rendering is read in its place (#216). A
1160
+ * holdings report's rendering runs to about 20 times its raw file — an NPORT-P
1161
+ * listing 505 positions is 500,525 bytes raw and 9,777,862 rendered — and the
1162
+ * HTML converter silently cuts input past 16,777,216 characters, 28 times this
1163
+ * bound, so a raw file past it is read as filed. A 13D or Form 4 is far below it.
1164
+ */
1165
+ const MAX_RENDERED_RAW_BYTES = 600_000;
1166
+ /**
1167
+ * `name`, then — for a 2000–2001 sequence-numbered name the archive may not serve
1168
+ * as listed — its accession-prefixed spelling (`<accession>-0001.htm`), under
1169
+ * which SEC serves the same document (#213).
1170
+ */
1171
+ function archiveSpellings(name, accessionNumber) {
1172
+ return SEQUENCE_NUMBERED_NAME.test(name) ? [name, `${accessionNumber}-${name}`] : [name];
1173
+ }
1174
+ /**
1175
+ * The stylesheet path the submissions feed records the filing's primary through
1176
+ * when `file` is that primary (`xslSCHEDULE_13D_X02/primary_doc.xml` for
1177
+ * `primary_doc.xml`): SEC serves its rendering of the form there (#216).
1178
+ */
1179
+ function renderingOf(file, accessionNumber, { submissions }) {
1180
+ const recorded = feedPrimaryDocument(accessionNumber, submissions);
1181
+ return recorded !== undefined && RENDERING_PATH.test(recorded) && recorded.endsWith(`/${file}`)
1182
+ ? recorded
1183
+ : undefined;
1184
+ }
1185
+ /**
1186
+ * The rendering read in place of the primary `file` when no document is named
1187
+ * (#216): the one {@link renderingOf} finds, while the index lists the raw file at
1188
+ * most {@link MAX_RENDERED_RAW_BYTES}. A raw file listed with no size reads as filed.
1189
+ */
1190
+ function renderingToRead(file, accessionNumber, items, records) {
1191
+ const rendering = renderingOf(file, accessionNumber, records);
1192
+ const size = Number.parseInt(items.find((item) => item.name === file)?.size ?? '', 10);
1193
+ return rendering !== undefined && size <= MAX_RENDERED_RAW_BYTES ? rendering : undefined;
1194
+ }
1195
+ /**
1196
+ * The names a caller-named document is read under, in order, or `undefined` when
1197
+ * the filing holds no such document: a listed name, then its accession-prefixed
1198
+ * spelling (see {@link archiveSpellings}); the prefixed spelling of a listed
1199
+ * sequence-numbered name, then that name (#213); or the stylesheet path the
1200
+ * submissions feed records for a listed file, read as SEC renders it (#216).
1201
+ */
1202
+ function requestedReadNames(requested, accessionNumber, items, records) {
1203
+ const listed = (name) => items.some((item) => item.name === name);
1204
+ if (listed(requested))
1205
+ return archiveSpellings(requested, accessionNumber);
1206
+ const prefix = `${accessionNumber}-`;
1207
+ if (requested.startsWith(prefix)) {
1208
+ const name = requested.slice(prefix.length);
1209
+ if (SEQUENCE_NUMBERED_NAME.test(name) && listed(name))
1210
+ return [requested, name];
1211
+ }
1212
+ const file = requested.slice(requested.lastIndexOf('/') + 1);
1213
+ return listed(file) && renderingOf(file, accessionNumber, records) === requested
1214
+ ? [requested]
1215
+ : undefined;
1216
+ }
993
1217
  function getLargestDocument(items) {
994
1218
  return [...items].sort((a, b) => (Number.parseInt(b.size, 10) || 0) - (Number.parseInt(a.size, 10) || 0))[0];
995
1219
  }