@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.
- package/AGENTS.md +18 -15
- package/CLAUDE.md +18 -15
- package/README.md +12 -9
- package/changelog/0.17.x/0.17.1.md +36 -0
- package/dist/config/server-config.js +1 -1
- package/dist/config/server-config.js.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/company-search.tool.js +6 -4
- package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +8 -4
- package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js +169 -39
- package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +4 -4
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +24 -8
- package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +14 -0
- package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/find-holders.tool.js +34 -7
- package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +2 -0
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +146 -77
- package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +4 -4
- package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-filing.tool.js +305 -81
- package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +14 -0
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +8 -0
- package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js +3 -1
- package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
- package/dist/mcp-server/tools/definitions/index.d.ts +453 -423
- package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +33 -0
- package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
- package/dist/mcp-server/tools/definitions/search-filings.tool.js +31 -2
- package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
- package/dist/mcp-server/tools/limit-clamp.d.ts +50 -18
- package/dist/mcp-server/tools/limit-clamp.d.ts.map +1 -1
- package/dist/mcp-server/tools/limit-clamp.js +51 -15
- package/dist/mcp-server/tools/limit-clamp.js.map +1 -1
- package/dist/services/edgar/edgar-api-service.d.ts +75 -11
- package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
- package/dist/services/edgar/edgar-api-service.js +273 -50
- package/dist/services/edgar/edgar-api-service.js.map +1 -1
- package/dist/services/edgar/filing-to-text.d.ts +4 -3
- package/dist/services/edgar/filing-to-text.d.ts.map +1 -1
- package/dist/services/edgar/filing-to-text.js +12 -0
- package/dist/services/edgar/filing-to-text.js.map +1 -1
- package/package.json +4 -4
- package/server.json +3 -3
- 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:
|
|
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: '
|
|
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(
|
|
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).
|
|
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(
|
|
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
|
-
|
|
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,
|
|
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
|
-
|
|
252
|
-
//
|
|
253
|
-
//
|
|
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
|
-
?
|
|
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
|
-
|
|
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
|
-
?
|
|
308
|
-
:
|
|
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,
|
|
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 (!
|
|
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 =
|
|
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:
|
|
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
|
|
827
|
-
|
|
828
|
-
|
|
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
|
-
|
|
832
|
-
|
|
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
|
-
|
|
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
|
|
866
|
-
|
|
867
|
-
|
|
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,
|
|
876
|
-
*
|
|
877
|
-
*
|
|
878
|
-
* wins, and only for the primary: a document the
|
|
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
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
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
|
-
|
|
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
|
|
949
|
-
|
|
950
|
-
|
|
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
|
|
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
|
}
|