@cyanheads/secedgar-mcp-server 0.13.0 → 0.14.0

package/dist/mcp-server/tools/definitions/find-holders.tool.js

@@ -0,0 +1,396 @@
+/**
+ * @fileoverview Reverse 13F lookup — which institutions reported holding an issuer.
+ * Searches the EDGAR full-text index scoped to 13F-HR within one quarter's filing
+ * window and returns the filer list, each row chaining into
+ * secedgar_get_institutional_holdings for the actual position.
+ * @module mcp-server/tools/definitions/find-holders
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getCanvasBridge, toDatasetField } from '../../../services/canvas-bridge/canvas-bridge.js';
+import { cleanDisplayName, getEdgarApiService } from '../../../services/edgar/edgar-api-service.js';
+/**
+ * Hits returned by one EFTS request. The endpoint ignores the `size` parameter
+ * and always answers with a full page, so paging is done with `from` alone.
+ */
+const EFTS_PAGE_SIZE = 100;
+/**
+ * Pages fetched in one call — 500 filer rows. Measured against the Q1 2026
+ * filing window (2026-04-01 → 2026-06-30): Apple (CUSIP 037833100) draws 6,652
+ * 13F-HR filings, so the budget returns a 500-row sample with the exact total
+ * still reported and `dataset.truncated` set; Liberty Live Holdings (530909100)
+ * draws 246 and Louisiana-Pacific (546347105) 451, both complete. Five requests
+ * at ~0.4s each keeps a call around two seconds and well inside SEC's 10 req/s
+ * limit, and the list is unranked either way — a deeper sample buys no ordering
+ * the caller can use.
+ */
+const FETCH_PAGE_BUDGET = 5;
+/** Days after a quarter end by which a 13F-HR is due. */
+const FILING_DEADLINE_DAYS = 45;
+const QUARTER_END_SUFFIX = ['03-31', '06-30', '09-30', '12-31'];
+/** Shift a YYYY-MM-DD date by whole days, staying in UTC. */
+function addDays(date, days) {
+    const d = new Date(`${date}T00:00:00Z`);
+    d.setUTCDate(d.getUTCDate() + days);
+    return d.toISOString().slice(0, 10);
+}
+/** Calendar quarter-end date (YYYY-MM-DD) for a `YYYY-QN` string. */
+function quarterEndDate(quarter) {
+    const [year, q] = quarter.split('-Q');
+    return `${year}-${QUARTER_END_SUFFIX[Number(q) - 1]}`;
+}
+/** End date of the quarter after `quarter` — the close of its filing window. */
+function nextQuarterEndDate(quarter) {
+    const [year, q] = quarter.split('-Q');
+    const n = Number(q);
+    return n === 4 ? `${Number(year) + 1}-03-31` : `${year}-${QUARTER_END_SUFFIX[n]}`;
+}
+/**
+ * Newest reporting quarter whose 13F-HR deadline has already passed as of
+ * `today` — the default target, so an unqualified call returns a quarter that
+ * institutions have actually filed for rather than an empty in-flight one.
+ */
+function latestClosedQuarter(today) {
+    const cutoff = addDays(today, -FILING_DEADLINE_DAYS);
+    const year = Number(cutoff.slice(0, 4));
+    // Suffixes ascend, so the last one at or before the cutoff is the newest closed quarter.
+    const quarter = QUARTER_END_SUFFIX.findLastIndex((suffix) => `${year}-${suffix}` <= cutoff) + 1;
+    return quarter > 0 ? `${year}-Q${quarter}` : `${year - 1}-Q4`;
+}
+function hitToHolder(hit) {
+    const displayName = hit._source.display_names?.[0] ?? '';
+    return {
+        accession_number: hit._source.adsh || hit._id.split(':')[0] || hit._id,
+        filer_cik: hit._source.ciks?.[0] ?? '',
+        filer_name: cleanDisplayName(displayName),
+        filing_date: hit._source.file_date,
+        form: hit._source.form ?? undefined,
+        period_ending: hit._source.period_ending ?? undefined,
+    };
+}
+export const findHoldersTool = tool('secedgar_find_holders', {
+    title: 'Find Holders',
+    description: 'Find which institutional managers reported holding an issuer, by searching 13F-HR information tables for one reporting quarter. This is the reverse direction of secedgar_get_institutional_holdings: that tool takes a manager and returns its portfolio, this one takes an issuer and returns its managers — pass a returned filer_cik plus the same quarter to read the actual position. Searching by cusip is the precise path, matching the identifier the information table itself carries; without it the issuer name is matched as a phrase against the filing text, which both over-matches (unrelated issuers sharing a word) and under-matches (managers writing the name differently), so prefer cusip whenever one is known. A CUSIP cannot be derived from a ticker here — read one off any 13F information table returned by secedgar_get_institutional_holdings. The returned list is unranked: the search index scores by text relevance, which carries no signal about position size, and no ordering by shares or market value is available without opening each filing. Managers holding under $100M in 13(f) securities are exempt from filing at all.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    errors: [
+        {
+            reason: 'issuer_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No cusip was given and the issuer does not resolve to a known EDGAR company',
+            recovery: 'Confirm the issuer with secedgar_company_search, or pass the cusip parameter to search the information tables directly.',
+        },
+        {
+            reason: 'ambiguous_issuer',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'The issuer name matches several EDGAR companies and no cusip was given',
+            recovery: 'Retry with the ticker or the 10-digit CIK of the intended issuer from the matches list.',
+        },
+    ],
+    input: z.object({
+        issuer: z
+            .string()
+            .trim()
+            .min(1, 'Issuer cannot be blank')
+            .describe('The portfolio company whose holders you want — a ticker ("AAPL"), a 10-digit CIK ("0000320193"), or a company name. Without cusip, this resolves to the company\'s EDGAR-conformed name and that name is phrase-matched against 13F information tables, so it must identify one company. With cusip supplied, it is used only to label the result.'),
+        cusip: z
+            .union([
+            z.literal(''),
+            z
+                .string()
+                .regex(/^[0-9A-Za-z]{9}$/, 'Expected a 9-character CUSIP or CINS identifier')
+                .describe('9-character CUSIP/CINS'),
+        ])
+            .optional()
+            .describe('The issuer\'s 9-character CUSIP (e.g. "037833100" for Apple common stock; foreign issuers use a CINS starting with a letter, e.g. "H1467J104"). The precise match key — information tables identify every position by CUSIP, so this avoids the name-phrase misses. Each share class has its own CUSIP, so a multi-class issuer needs one call per class. Read a CUSIP off the holdings returned by secedgar_get_institutional_holdings.'),
+        quarter: z
+            .union([
+            z.literal(''),
+            z
+                .string()
+                .regex(/^\d{4}-Q[1-4]$/, 'Expected YYYY-QN, e.g. 2026-Q1')
+                .describe('YYYY-QN'),
+        ])
+            .optional()
+            .describe('Reporting quarter to search, "YYYY-QN" (e.g. "2026-Q1"). Omit for the newest quarter whose 45-day filing deadline has passed — the applied quarter and its filing window are echoed in the response. A quarter still inside its deadline returns nothing, because the filings do not exist yet.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(20)
+            .describe('Filer rows returned inline. The full fetched set (up to 500 rows) is materialized as a dataframe when a canvas is available. Default 20.'),
+    }),
+    output: z.object({
+        issuer: z.string().describe('The issuer input, echoed.'),
+        resolved_issuer_name: z
+            .string()
+            .optional()
+            .describe('EDGAR-conformed company name the issuer resolved to, and the phrase that was searched. Absent when cusip was supplied (no company lookup runs).'),
+        resolved_issuer_cik: z
+            .string()
+            .optional()
+            .describe('CIK of the resolved issuer, zero-padded to 10 digits. Absent when cusip was supplied.'),
+        search_mode: z
+            .enum(['cusip', 'name'])
+            .describe('Which key matched the information tables. "cusip" matches the identifier the table itself carries; "name" phrase-matches the filing text and is looser in both directions.'),
+        search_key: z.string().describe('The exact term searched — the CUSIP, or the quoted phrase.'),
+        quarter: z
+            .string()
+            .describe('Reporting quarter searched, "YYYY-QN" — the requested one, or the applied default.'),
+        filed_from: z.string().describe('Start of the filing window searched (YYYY-MM-DD).'),
+        filed_to: z.string().describe('End of the filing window searched (YYYY-MM-DD).'),
+        total_filings: z
+            .number()
+            .describe("Total 13F-HR filings matching the search key inside the filing window, as reported by the index. A slight over-count of this quarter's holders on two counts, both of which the returned rows correct for: a few percent are amendments restating an older quarter, and a few more are managers amending their own report for this quarter, which puts them in the window twice."),
+        total_is_exact: z
+            .boolean()
+            .describe('False when total_filings is a lower bound (the index capped the count).'),
+        fetched: z
+            .number()
+            .describe('Filings retrieved from the index, capped by the fetch budget of 500. Equals total_filings when the whole window fit inside the budget.'),
+        holders_in_quarter: z
+            .number()
+            .describe('Distinct managers among the fetched filings reporting this quarter as their period — the set paged by limit and materialized on the dataframe. Lower than fetched by the filings dropped as amendments restating other quarters, and by managers that amended this quarter (kept once, at their latest filing).'),
+        holders: z
+            .array(z
+            .object({
+            filer_name: z
+                .string()
+                .describe('Institutional manager that filed, with ticker/CIK parentheticals stripped.'),
+            filer_cik: z
+                .string()
+                .describe("Filer CIK, zero-padded to 10 digits. Pass as ticker_or_cik to secedgar_get_institutional_holdings for this manager's positions."),
+            accession_number: z
+                .string()
+                .describe('Accession number of the 13F-HR — pass to secedgar_get_filing.'),
+            filing_date: z.string().describe('Date the 13F-HR was submitted (YYYY-MM-DD).'),
+            form: z
+                .string()
+                .optional()
+                .describe('Form type, "13F-HR" or "13F-HR/A" for an amendment. Absent when the index carries no form tag.'),
+        })
+            .describe('One institutional manager reporting a position in this issuer.'))
+            .describe('One page of filers, capped at limit. Order carries no position-size meaning — see the ordering note.'),
+        dataset: z
+            .object({
+            name: z
+                .string()
+                .describe('Dataframe handle (df_XXXXX_XXXXX) — pass to secedgar_dataframe_query.'),
+            row_count: z.number().describe('Rows materialized in the dataframe.'),
+            expires_at: z.string().describe('ISO 8601 expiry timestamp.'),
+            truncated: z
+                .boolean()
+                .describe('True when more filers exist beyond the fetch budget — total_filings exceeds fetched.'),
+        })
+            .optional()
+            .describe('Canvas dataframe holding every fetched filer row, each carrying the issuer key and quarter so it joins across issuers and quarters. Absent when the result fits inline, canvas is unavailable, or materialization failed. Query with secedgar_dataframe_query.'),
+    }),
+    enrichment: {
+        ordering: z
+            .string()
+            .describe('How the holder list is ordered, and what that ordering does not mean.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Guidance when the search returned no filers — names the likely cause.'),
+        truncated: z.boolean().optional().describe('True when the inline holders list was capped.'),
+        shown: z.number().optional().describe('Number of filers shown inline.'),
+        cap: z.number().optional().describe('The limit cap applied.'),
+    },
+    async handler(input, ctx) {
+        const api = getEdgarApiService();
+        const cusip = input.cusip?.toUpperCase() || undefined;
+        // With a CUSIP in hand the information tables are matched directly, so no
+        // company lookup runs and the issuer input is carried through as a label.
+        let resolvedName;
+        let resolvedCik;
+        if (!cusip) {
+            const resolved = await api.resolveCik(input.issuer);
+            const candidates = Array.isArray(resolved) ? resolved : [resolved];
+            if (candidates.length > 1) {
+                const shown = candidates.slice(0, 10);
+                const list = shown.map((c) => `${c.ticker ?? c.cik} (${c.name ?? 'Unknown'})`).join(', ');
+                throw ctx.fail('ambiguous_issuer', `'${input.issuer}' matches multiple EDGAR companies: ${list}.`, {
+                    ...ctx.recoveryFor('ambiguous_issuer'),
+                    matches: shown.map((c) => ({ cik: c.cik, name: c.name, ticker: c.ticker })),
+                });
+            }
+            const match = candidates[0];
+            // A bare numeric CIK absent from the ticker cache resolves without a name,
+            // leaving nothing to phrase-match — that is a miss, not a silent broadening.
+            if (!match?.name) {
+                throw ctx.fail('issuer_not_found', `No EDGAR company name found for issuer '${input.issuer}', so there is nothing to match against 13F information tables.`, { ...ctx.recoveryFor('issuer_not_found') });
+            }
+            resolvedName = match.name;
+            resolvedCik = match.cik;
+        }
+        const quarter = input.quarter || latestClosedQuarter(new Date().toISOString().slice(0, 10));
+        const quarterEnd = quarterEndDate(quarter);
+        // The window runs from the day after the reporting quarter to the end of the
+        // next one. It covers the 45-day deadline with room for late filers, and stops
+        // before the following quarter's originals start arriving — those report a
+        // different period and would otherwise be counted as this quarter's holders.
+        const filedFrom = addDays(quarterEnd, 1);
+        const filedTo = nextQuarterEndDate(quarter);
+        const searchKey = cusip ?? `"${resolvedName}"`;
+        const searchMode = cusip ? 'cusip' : 'name';
+        // EFTS answers with a full page regardless of the requested size, so the
+        // budget is expressed in pages and `from` walks the window.
+        /**
+         * One row per manager, keyed by filer CIK. A manager that amended its report
+         * for this same quarter files twice inside one window — 7 of Cracker Barrel's
+         * 256 Q1 2026 filings — and listing it twice would inflate a holder count by
+         * a few percent. The later filing wins: the amendment supersedes the original
+         * and its accession is the one worth reading.
+         */
+        const byFiler = new Map();
+        const seen = new Set();
+        let total = 0;
+        let totalIsExact = true;
+        let hitsFetched = 0;
+        for (let page = 0; page < FETCH_PAGE_BUDGET; page++) {
+            const response = await api.searchFilings({
+                query: searchKey,
+                forms: ['13F-HR'],
+                startDate: filedFrom,
+                endDate: filedTo,
+                from: page * EFTS_PAGE_SIZE,
+                size: EFTS_PAGE_SIZE,
+            });
+            if (page === 0) {
+                total = response.hits.total.value;
+                totalIsExact = response.hits.total.relation === 'eq';
+            }
+            const hits = response.hits.hits;
+            hitsFetched += hits.length;
+            for (const hit of hits) {
+                const row = hitToHolder(hit);
+                // One filing can match on several documents; the filer is listed once.
+                if (seen.has(row.accession_number))
+                    continue;
+                seen.add(row.accession_number);
+                // Amendments to older quarters keep arriving inside any filing window —
+                // roughly 6% of the Q1 2026 window — so the reported period is what
+                // decides membership, not the filing date.
+                if (row.period_ending !== quarterEnd)
+                    continue;
+                const existing = byFiler.get(row.filer_cik);
+                if (!existing || row.filing_date > existing.filing_date) {
+                    byFiler.set(row.filer_cik, row);
+                }
+            }
+            if (hits.length < EFTS_PAGE_SIZE || hitsFetched >= total)
+                break;
+        }
+        const rows = [...byFiler.values()];
+        const truncated = hitsFetched < total;
+        let dataset;
+        const bridge = getCanvasBridge();
+        if (bridge && rows.length > input.limit) {
+            const registered = await bridge.registerDataframe(ctx, {
+                rows: rows.map((row) => ({
+                    issuer: input.issuer,
+                    issuer_cusip: cusip ?? null,
+                    issuer_cik: resolvedCik ?? null,
+                    quarter,
+                    reporting_period: quarterEnd,
+                    filer_name: row.filer_name,
+                    filer_cik: row.filer_cik,
+                    accession_number: row.accession_number,
+                    filing_date: row.filing_date,
+                    form: row.form ?? null,
+                })),
+                sourceTool: 'secedgar_find_holders',
+                queryParams: {
+                    issuer: input.issuer,
+                    cusip,
+                    quarter,
+                    filed_from: filedFrom,
+                    filed_to: filedTo,
+                    search_mode: searchMode,
+                },
+                truncated,
+            });
+            if (registered)
+                dataset = { ...toDatasetField(registered), truncated };
+        }
+        /**
+         * The budget slices the window in relevance order, so once it binds the
+         * result is a sample rather than a short list — an aggregate over it is an
+         * aggregate over that sample, which is worth saying before someone counts it.
+         */
+        const sampleNote = truncated
+            ? ` The fetch budget stopped at ${hitsFetched} of ${total} matching filings, and the index served them in that same relevance order, so this is a sample of the holders rather than the first ones by any measure.`
+            : '';
+        ctx.enrich({
+            ordering: `Filers are listed in EDGAR search-relevance order, which reflects text match strength only — it is not a ranking by shares held or market value.${sampleNote} Read a manager's actual position with secedgar_get_institutional_holdings using its filer_cik and quarter "${quarter}".`,
+        });
+        const searchedTerm = searchMode === 'cusip' ? `CUSIP ${searchKey}` : `the phrase ${searchKey}`;
+        if (total === 0) {
+            const deadline = addDays(quarterEnd, FILING_DEADLINE_DAYS);
+            const cause = deadline > new Date().toISOString().slice(0, 10)
+                ? `13F-HR filings for ${quarter} are not due until ${deadline}, so few or none exist yet — search an earlier quarter.`
+                : searchMode === 'cusip'
+                    ? 'Verify the CUSIP identifies a 13(f)-reportable security and covers the intended share class, or drop cusip to phrase-match the issuer name instead.'
+                    : 'The issuer name is phrase-matched against filing text and managers may write it differently — pass cusip for an exact match, read one off any secedgar_get_institutional_holdings result.';
+            ctx.enrich.notice(`No 13F-HR filings matched ${searchedTerm} filed ${filedFrom} to ${filedTo}. ${cause}`);
+        }
+        else if (rows.length === 0) {
+            ctx.enrich.notice(`${total} 13F-HR filings matched ${searchedTerm} in the ${filedFrom} to ${filedTo} window, but none of the ${hitsFetched} fetched report ${quarter} (period ending ${quarterEnd}) — they are amendments restating other quarters. Search the quarter those amendments cover, or a later one.`);
+        }
+        else if (rows.length > input.limit) {
+            ctx.enrich.truncated({
+                shown: input.limit,
+                cap: input.limit,
+                guidance: truncated
+                    ? `${total} filings matched in the window; the fetch budget of ${FETCH_PAGE_BUDGET * EFTS_PAGE_SIZE} retrieved ${hitsFetched}, resolving to ${rows.length} managers reporting ${quarter}. Query that set with secedgar_dataframe_query, or narrow to a single share class with cusip.`
+                    : 'Query the full matched set with secedgar_dataframe_query.',
+            });
+        }
+        ctx.log.info('Holder search completed', {
+            issuer: input.issuer,
+            searchMode,
+            quarter,
+            total,
+            fetched: hitsFetched,
+            inQuarter: rows.length,
+            datasetName: dataset?.name,
+        });
+        return {
+            issuer: input.issuer,
+            resolved_issuer_name: resolvedName,
+            resolved_issuer_cik: resolvedCik,
+            search_mode: searchMode,
+            search_key: searchKey,
+            quarter,
+            filed_from: filedFrom,
+            filed_to: filedTo,
+            total_filings: total,
+            total_is_exact: totalIsExact,
+            fetched: hitsFetched,
+            holders_in_quarter: rows.length,
+            holders: rows.slice(0, input.limit),
+            dataset,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**13F holders of ${result.issuer}** — ${result.quarter}, filed ${result.filed_from} to ${result.filed_to}`,
+        ];
+        if (result.resolved_issuer_name) {
+            lines.push(`Resolved issuer: ${result.resolved_issuer_name} (CIK ${result.resolved_issuer_cik})`);
+        }
+        lines.push(`Matched by ${result.search_mode}: ${result.search_key}`, `${result.total_filings} filings in the window (${result.total_is_exact ? 'exact count' : 'lower bound'}); ${result.fetched} fetched, ${result.holders_in_quarter} managers reporting ${result.quarter}, ${result.holders.length} shown`);
+        for (const h of result.holders) {
+            lines.push(`- ${h.filer_name} (CIK ${h.filer_cik}) — ${h.form ?? '13F-HR'} ${h.filing_date} [${h.accession_number}]`);
+        }
+        if (result.dataset) {
+            const truncatedNote = result.dataset.truncated
+                ? ' (truncated — more filers exist beyond the fetch budget)'
+                : '';
+            lines.push(`\nDataset: ${result.dataset.name} (${result.dataset.row_count} rows, expires ${result.dataset.expires_at})${truncatedNote} — query with secedgar_dataframe_query.`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=find-holders.tool.js.map

package/dist/mcp-server/tools/definitions/find-holders.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-holders.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/find-holders.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts

@@ -27,24 +27,28 @@ export declare const getFilingTool: import("@cyanheads/mcp-ts-core").ToolDefinit
             type: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
             size: z.ZodOptional<z.ZodNumber>;
+            binary: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
         exhibits: z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             type: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
             size: z.ZodOptional<z.ZodNumber>;
+            binary: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
         auxiliary: z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             type: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
             size: z.ZodOptional<z.ZodNumber>;
+            binary: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
         xbrl: z.ZodOptional<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             type: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
             size: z.ZodOptional<z.ZodNumber>;
+            binary: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>;
     }, z.core.$strip>;
     content: z.ZodString;
@@ -66,6 +70,11 @@ export declare const getFilingTool: import("@cyanheads/mcp-ts-core").ToolDefinit
     readonly code: JsonRpcErrorCode.NotFound;
     readonly when: "Filing index lists items but no fetchable primary document was found";
     readonly recovery: "Set document to one of the filenames listed in the error message.";
+}, {
+    readonly reason: "binary_document";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The requested document is a binary entry (scanned image, PDF, archive) with no text to return";
+    readonly recovery: "Pick a text document (.htm, .txt, .xml) from the list in the error message.";
 }, {
     readonly reason: "filing_not_found";
     readonly code: JsonRpcErrorCode.NotFound;

package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-filing.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-filing.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA8FjE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2axB,CAAC"}
+{"version":3,"file":"get-filing.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-filing.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA+GjE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkcxB,CAAC"}

package/dist/mcp-server/tools/definitions/get-filing.tool.js

@@ -30,12 +30,16 @@ const documentEntrySchema = z
     name: z.string().describe('Document filename within the filing archive.'),
     type: z
         .string()
-        .describe('SEC document type from the submission header (e.g., "10-K", "EX-21.1", "GRAPHIC", "XML"). When the submission header is unavailable, falls back to a label inferred from the filename: known XBRL artifacts ("XBRL-LINKBASE", "XBRL-INSTANCE", etc.), "exhibit" for common exhibit filename patterns (ex-21.htm, exhibit21, dex991), and "unknown" for everything else.'),
+        .describe('SEC document type from the submission header (e.g., "10-K", "EX-21.1", "GRAPHIC", "XML"). When the submission header is unavailable, falls back to a label inferred from the filename: known XBRL artifacts ("XBRL-LINKBASE", "XBRL-INSTANCE", etc.), "exhibit" for common exhibit filename patterns (ex-21.htm, exhibit21, dex991), "GRAPHIC"/"PDF"/"BINARY" for known binary file extensions, and "unknown" for everything else.'),
     description: z
         .string()
         .optional()
         .describe('Human-readable description (e.g., "Annual Report", "Subsidiaries of the Registrant"). Absent when SEC published none for this entry.'),
     size: z.number().optional().describe('File size in bytes.'),
+    binary: z
+        .boolean()
+        .optional()
+        .describe('Present and true when the entry holds binary bytes — a scanned page or logo, a PDF exhibit, a packaged archive or spreadsheet. These cannot be converted to text and are rejected by the document input. Absent for readable entries.'),
 })
     .describe('One document entry from the filing.');
 export const getFilingTool = tool('secedgar_get_filing', {
@@ -54,6 +58,12 @@ export const getFilingTool = tool('secedgar_get_filing', {
             when: 'Filing index lists items but no fetchable primary document was found',
             recovery: 'Set document to one of the filenames listed in the error message.',
         },
+        {
+            reason: 'binary_document',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'The requested document is a binary entry (scanned image, PDF, archive) with no text to return',
+            recovery: 'Pick a text document (.htm, .txt, .xml) from the list in the error message.',
+        },
         {
             reason: 'filing_not_found',
             code: JsonRpcErrorCode.NotFound,
@@ -93,7 +103,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
         document: z
             .string()
             .optional()
-            .describe('Specific document filename within the filing (e.g., "ex-21.htm" for subsidiaries list). Default: the primary document. Available documents listed in the response metadata.'),
+            .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.'),
         include_xbrl: z
             .boolean()
             .default(false)
@@ -152,7 +162,7 @@ export const getFilingTool = tool('secedgar_get_filing', {
                 .optional()
                 .describe('XBRL viewer artifacts and machine-readable taxonomy files. Only present when include_xbrl=true.'),
         })
-            .describe('Filing documents grouped by category. Names from any list are valid values for the document input. XBRL viewer artifacts are suppressed by default; setting include_xbrl=true surfaces them under the xbrl bucket.'),
+            .describe('Filing documents grouped by category. Every name is a valid document input EXCEPT entries carrying binary: true — scanned pages, PDFs, packaged archives and spreadsheets, which hold no text and are rejected with a binary_document error. Scans can outnumber readable documents in a filing, so read the flag before picking a name. XBRL viewer artifacts are suppressed by default; setting include_xbrl=true surfaces them under the xbrl bucket.'),
         content: z.string().describe('Document text content for this page window.'),
         content_truncated: z.boolean().describe('True if content was truncated at content_limit.'),
         content_total_length: z.number().describe('Full document length before any truncation.'),
@@ -210,6 +220,19 @@ export const getFilingTool = tool('secedgar_get_filing', {
                         recovery: { hint },
                     });
                 }
+                if (resolved.kind === 'binary_document') {
+                    const catalogBlock = renderDocumentCatalog(resolved.documents);
+                    const primaryName = resolved.documents.primary[0]?.name;
+                    const hint = primaryName
+                        ? `Use document="${primaryName}" (the primary) or another entry not marked binary. Binary entries hold image, PDF, or archive bytes and have no text to return.`
+                        : 'Pick an entry not marked binary from the list above — binary entries hold image, PDF, or archive bytes and have no text to return.';
+                    throw ctx.fail('binary_document', `Document '${resolved.requestedDocument}' is a ${resolved.documentType} entry and holds no readable text.${catalogBlock}`, {
+                        requested_document: resolved.requestedDocument,
+                        document_type: resolved.documentType,
+                        documents: resolved.documents,
+                        recovery: { hint },
+                    });
+                }
                 if (resolved.kind === 'no_documents') {
                     const catalogBlock = renderDocumentCatalog(resolved.documents);
                     throw ctx.fail('no_documents', `No primary document found in filing ${accn}.${catalogBlock}`, {
@@ -388,8 +411,16 @@ function renderDocumentCatalog(documents) {
     const addCategory = (label, entries) => {
         if (entries.length === 0)
             return;
-        const shown = entries.slice(0, MAX_DOCUMENTS_IN_ERROR);
-        const names = shown.map((d) => `${d.name} [${d.type}]`).join(', ');
+        /**
+         * Readable entries first. A sample this small is otherwise consumed by scan
+         * images on filings that carry hundreds of them, leaving the caller with a
+         * recovery list of names it cannot actually pass back. Stable sort, so order
+         * within each half is the filing index's own.
+         */
+        const shown = [...entries]
+            .sort((a, b) => Number(a.binary ?? false) - Number(b.binary ?? false))
+            .slice(0, MAX_DOCUMENTS_IN_ERROR);
+        const names = shown.map((d) => `${d.name} [${d.type}${d.binary ? ', binary' : ''}]`).join(', ');
         const omitted = entries.length - shown.length;
         const tail = omitted > 0 ? ` (+${omitted} more)` : '';
         sections.push(`${label} (${entries.length} total): ${names}${tail}`);
@@ -432,6 +463,26 @@ async function resolveFilingArchive(api, accessionNumber, providedCik, requested
         const targetName = requestedDocument ?? filingPrimaryName;
         if (!items.some((item) => item.name === targetName))
             continue;
+        /**
+         * Reject a binary target BEFORE the body is fetched. `filingToExtract` runs
+         * `html-to-text` over whatever bytes arrive and never inspects a content
+         * type, so a `.jpg` would come back as its own decoded payload with a
+         * plausible length and no error (#96). The check is filename-only — the
+         * canonical GRAPHIC type lives in the submission header, which this path
+         * has not fetched yet, and requiring it here would trade the parallel
+         * header/submissions fetch for a sequential one on every call.
+         */
+        const binaryType = binaryTypeFromName(targetName);
+        if (binaryType) {
+            const documents = categorizeDocuments(items, filingPrimaryName, null, false);
+            return {
+                ok: false,
+                kind: 'binary_document',
+                requestedDocument: targetName,
+                documentType: binaryType,
+                documents,
+            };
+        }
         const html = await api.tryGetFilingDocument(cik, accessionNumber, targetName);
         if (!html)
             continue;
@@ -520,6 +571,7 @@ function categorizeDocuments(items, primaryName, headers, includeXbrl) {
             type,
             description: header?.description,
             size: item.size ? Number.parseInt(item.size, 10) || undefined : undefined,
+            ...(isBinaryDocument(item.name, type) ? { binary: true } : {}),
         };
         if (item.name === primaryName) {
             primary.push(entry);
@@ -565,6 +617,35 @@ function isXbrlArtifact(name, type) {
  * `d123456dex991.htm` / `aapl-20230930xex21d1.htm` (printer "dex"/"xex" + number).
  */
 const EXHIBIT_NAME_PATTERN = /(?:^|[^a-z])ex[-_.]?\d|exhibit[-_.]?\d|\d[dx]ex[-_.]?\d/i;
+/**
+ * Binary file extensions EDGAR filings carry, mapped to the type label reported
+ * for them. Images use SEC's own canonical TYPE (`GRAPHIC`) so header-derived and
+ * inferred types read identically. The set is deliberately extension-driven: it
+ * is the only signal available before the document body is fetched, and it works
+ * for a binary entry in any bucket — a PDF exhibit is typed `EX-99.*` in the
+ * submission header and lands under exhibits, not among the graphics.
+ */
+const BINARY_EXTENSIONS = [
+    [/\.(?:jpe?g|gif|png|bmp|tiff?)$/i, 'GRAPHIC'],
+    [/\.pdf$/i, 'PDF'],
+    [/\.(?:zip|xlsx?)$/i, 'BINARY'],
+];
+/** Type label for a binary filename, or undefined when the name reads as text. */
+function binaryTypeFromName(name) {
+    for (const [pattern, label] of BINARY_EXTENSIONS) {
+        if (pattern.test(name))
+            return label;
+    }
+    return;
+}
+/**
+ * Whether an entry holds bytes rather than text. The filename is authoritative
+ * for the fetch guard; the header type adds the cases a filer named oddly, since
+ * SEC types every scanned page `GRAPHIC` regardless of extension.
+ */
+function isBinaryDocument(name, type) {
+    return binaryTypeFromName(name) !== undefined || type.toUpperCase() === 'GRAPHIC';
+}
 /** Fallback type label when the submission header is unavailable. */
 function inferTypeFromName(name) {
     if (/^R\d+\.htm$/i.test(name))
@@ -587,7 +668,10 @@ function inferTypeFromName(name) {
         return 'FINANCIAL-REPORT';
     if (EXHIBIT_NAME_PATTERN.test(name))
         return 'exhibit';
-    return 'unknown';
+    // Last, so the named XBRL artifacts and exhibit filename patterns above keep
+    // their more specific labels. An entry's `binary` flag is derived separately,
+    // so a PDF exhibit is still marked unreadable while reading as an exhibit.
+    return binaryTypeFromName(name) ?? 'unknown';
 }
 function formatDocumentSection(docs) {
     const sections = [];
@@ -630,6 +714,7 @@ function formatDocList(entries) {
         .map((d) => {
         const tail = [
             d.type,
+            d.binary ? 'binary' : null,
             d.size !== undefined ? `${d.size}B` : null,
             d.description ? `"${d.description}"` : null,
         ]