@cyanheads/secedgar-mcp-server 0.1.9

package/dist/mcp-server/prompts/definitions/company-analysis.prompt.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Prompt template for structured analysis of a public company's SEC filings.
+ * @module mcp-server/prompts/definitions/company-analysis
+ */
+import { prompt, z } from '@cyanheads/mcp-ts-core';
+export const companyAnalysisPrompt = prompt('secedgar_company_analysis', {
+    description: `Guides a structured analysis of a public company's SEC filings: identify recent filings, extract financial trends, surface risk factors, and note material events.`,
+    args: z.object({
+        company: z.string().describe('Company name, ticker symbol, or CIK number to analyze.'),
+        focus_areas: z
+            .string()
+            .optional()
+            .describe('Specific areas to focus on (e.g., "revenue growth, debt levels, insider activity"). If omitted, performs a general analysis.'),
+    }),
+    generate: (args) => [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: [
+                    `Analyze the SEC filings for **${args.company}**${args.focus_areas ? ` with a focus on: ${args.focus_areas}` : ''}.`,
+                    '',
+                    'Follow this structured workflow:',
+                    '',
+                    '1. **Company Identification** — Use `secedgar_company_search` to resolve the company and review recent filings.',
+                    '2. **Financial Trends** — Use `secedgar_get_financials` to pull key metrics (revenue, net_income, eps_diluted, assets, debt, operating_cash_flow) and identify trends over the last 3-5 years.',
+                    '3. **Recent Filings Review** — Use `secedgar_get_filing` to read the most recent 10-K or 10-Q for qualitative insights (risk factors, MD&A, business overview).',
+                    '4. **Material Events** — Search for recent 8-K filings to identify material events (M&A, leadership changes, earnings surprises).',
+                    '5. **Industry Context** — Use `secedgar_compare_metric` to compare key metrics against peers.',
+                    '',
+                    'Present findings as:',
+                    '- **Company Overview** — entity details, industry, fiscal year',
+                    '- **Financial Summary** — key metrics table with trends',
+                    '- **Risk Factors** — material risks from latest filings',
+                    '- **Recent Events** — notable 8-K filings and their significance',
+                    '- **Peer Comparison** — how the company stacks up on key metrics',
+                    '- **Key Takeaways** — 3-5 bullet points summarizing the analysis',
+                ].join('\n'),
+            },
+        },
+    ],
+});
+//# sourceMappingURL=company-analysis.prompt.js.map

package/dist/mcp-server/prompts/definitions/company-analysis.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"company-analysis.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/company-analysis.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,2BAA2B,EAAE;IACvE,WAAW,EAAE,oKAAoK;IAEjL,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;QACtF,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,8HAA8H,CAC/H;KACJ,CAAC;IAEF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB;YACE,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE;oBACJ,iCAAiC,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,qBAAqB,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG;oBACpH,EAAE;oBACF,kCAAkC;oBAClC,EAAE;oBACF,iHAAiH;oBACjH,gMAAgM;oBAChM,iKAAiK;oBACjK,mIAAmI;oBACnI,+FAA+F;oBAC/F,EAAE;oBACF,sBAAsB;oBACtB,gEAAgE;oBAChE,yDAAyD;oBACzD,yDAAyD;oBACzD,kEAAkE;oBAClE,kEAAkE;oBAClE,kEAAkE;iBACnE,CAAC,IAAI,CAAC,IAAI,CAAC;aACb;SACF;KACF;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/concepts.resource.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Reference list of common XBRL financial concepts grouped by financial statement.
+ * The "menu" an agent reads before calling secedgar_get_financials.
+ * @module mcp-server/resources/definitions/concepts
+ */
+export declare const conceptsResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<Readonly<{
+    [k: string]: import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+}>, import("zod/v4/core").$strip>, undefined>;
+//# sourceMappingURL=concepts.resource.d.ts.map

package/dist/mcp-server/resources/definitions/concepts.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concepts.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/concepts.resource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,eAAO,MAAM,gBAAgB;;6CAsF3B,CAAC"}

package/dist/mcp-server/resources/definitions/concepts.resource.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Reference list of common XBRL financial concepts grouped by financial statement.
+ * The "menu" an agent reads before calling secedgar_get_financials.
+ * @module mcp-server/resources/definitions/concepts
+ */
+import { resource } from '@cyanheads/mcp-ts-core';
+import { getAllConcepts } from '../../../services/edgar/concept-map.js';
+export const conceptsResource = resource('secedgar://concepts', {
+    name: 'XBRL Financial Concepts',
+    description: 'Reference list of common XBRL financial concepts grouped by financial statement, ' +
+        'mapping friendly names to XBRL tags. Read this before calling secedgar_get_financials to see available concept names.',
+    mimeType: 'text/markdown',
+    handler(_params, _ctx) {
+        const concepts = getAllConcepts();
+        const groups = {
+            'Income Statement': [],
+            'Balance Sheet': [],
+            'Cash Flow': [],
+            'Per Share': [],
+            'Entity Info': [],
+        };
+        const groupMap = {
+            revenue: 'Income Statement',
+            net_income: 'Income Statement',
+            operating_income: 'Income Statement',
+            gross_profit: 'Income Statement',
+            assets: 'Balance Sheet',
+            liabilities: 'Balance Sheet',
+            equity: 'Balance Sheet',
+            cash: 'Balance Sheet',
+            debt: 'Balance Sheet',
+            eps_basic: 'Per Share',
+            eps_diluted: 'Per Share',
+            operating_cash_flow: 'Cash Flow',
+            capex: 'Cash Flow',
+            shares_outstanding: 'Entity Info',
+        };
+        for (const [name, mapping] of Object.entries(concepts)) {
+            const group = groupMap[name] ?? 'Other';
+            if (!groups[group])
+                groups[group] = [];
+            groups[group].push({
+                name,
+                label: mapping.label,
+                tags: mapping.tags,
+                taxonomy: mapping.taxonomy,
+                unit: mapping.unit,
+            });
+        }
+        const lines = ['# XBRL Financial Concepts', ''];
+        lines.push('Use these friendly names with `secedgar_get_financials` and `secedgar_compare_metric`.', '');
+        lines.push('Raw XBRL tags are also accepted as an escape hatch for concepts not listed here.', '');
+        for (const [group, items] of Object.entries(groups)) {
+            if (items.length === 0)
+                continue;
+            lines.push(`## ${group}`, '');
+            lines.push('| Friendly Name | Label | XBRL Tags | Taxonomy | Unit |');
+            lines.push('|:------|:------|:----------|:---------|:-----|');
+            for (const item of items) {
+                lines.push(`| \`${item.name}\` | ${item.label} | ${item.tags.map((t) => `\`${t}\``).join(', ')} | ${item.taxonomy} | ${item.unit} |`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    },
+    list: async () => ({
+        resources: [
+            {
+                uri: 'secedgar://concepts',
+                name: 'XBRL Financial Concepts',
+                description: 'Common financial concept names and their XBRL tag mappings',
+                mimeType: 'text/markdown',
+            },
+        ],
+    }),
+});
+//# sourceMappingURL=concepts.resource.js.map

package/dist/mcp-server/resources/definitions/concepts.resource.js.map

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

package/dist/mcp-server/resources/definitions/filing-types.resource.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Reference list of common SEC filing types with descriptions and use cases.
+ * @module mcp-server/resources/definitions/filing-types
+ */
+export declare const filingTypesResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<Readonly<{
+    [k: string]: import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+}>, import("zod/v4/core").$strip>, undefined>;
+//# sourceMappingURL=filing-types.resource.d.ts.map

package/dist/mcp-server/resources/definitions/filing-types.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filing-types.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/filing-types.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsEH,eAAO,MAAM,mBAAmB;;6CA+B9B,CAAC"}

package/dist/mcp-server/resources/definitions/filing-types.resource.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Reference list of common SEC filing types with descriptions and use cases.
+ * @module mcp-server/resources/definitions/filing-types
+ */
+import { resource } from '@cyanheads/mcp-ts-core';
+const FILING_TYPES = [
+    {
+        form: '10-K',
+        cadence: 'Annual',
+        description: 'Annual report with audited financials, MD&A, risk factors, and business overview.',
+        use_cases: 'Financial analysis, due diligence, competitive research',
+    },
+    {
+        form: '10-Q',
+        cadence: 'Quarterly (Q1-Q3)',
+        description: 'Quarterly report with unaudited financials, MD&A, and market risks.',
+        use_cases: 'Tracking quarterly performance, identifying trends',
+    },
+    {
+        form: '8-K',
+        cadence: 'Event-driven',
+        description: 'Current report for material events: M&A (1.01), earnings (2.02), exec changes (5.02).',
+        use_cases: 'Breaking news, material events, earnings announcements',
+    },
+    {
+        form: 'DEF 14A',
+        cadence: 'Annual proxy',
+        description: 'Definitive proxy statement with board elections, executive pay, and shareholder votes.',
+        use_cases: 'Executive compensation analysis, governance research',
+    },
+    {
+        form: '13F-HR',
+        cadence: 'Quarterly',
+        description: 'Institutional investment manager holdings ($100M+ AUM).',
+        use_cases: 'Tracking institutional ownership, portfolio analysis',
+    },
+    {
+        form: 'Form 4',
+        cadence: 'Per-transaction',
+        description: 'Insider buy/sell report: date, shares, price, and transaction code.',
+        use_cases: 'Insider trading activity, management confidence signals',
+    },
+    {
+        form: 'SC 13D',
+        cadence: 'Threshold',
+        description: 'Beneficial ownership report for 5%+ activist investors.',
+        use_cases: 'Activist investor tracking, ownership changes',
+    },
+    {
+        form: 'SC 13G',
+        cadence: 'Threshold',
+        description: 'Beneficial ownership report for 5%+ passive investors.',
+        use_cases: 'Passive institutional ownership tracking',
+    },
+    {
+        form: 'S-1',
+        cadence: 'One-time',
+        description: 'IPO registration statement with prospectus, financials, and risk factors.',
+        use_cases: 'IPO research, pre-IPO due diligence',
+    },
+    {
+        form: '20-F',
+        cadence: 'Annual',
+        description: 'Foreign private issuer annual report (equivalent of 10-K).',
+        use_cases: 'International company analysis',
+    },
+];
+export const filingTypesResource = resource('secedgar://filing-types', {
+    name: 'SEC Filing Types',
+    description: 'Reference list of common SEC filing types with descriptions, cadence, and typical use cases. ' +
+        'Helps determine which form_types to filter when searching filings.',
+    mimeType: 'text/markdown',
+    handler(_params, _ctx) {
+        const lines = ['# SEC Filing Types', ''];
+        lines.push('Use these form types with `secedgar_company_search` (form_types filter) and `secedgar_search_filings` (forms filter).', '');
+        lines.push('| Form | Cadence | Description | Use Cases |');
+        lines.push('|:-----|:--------|:------------|:----------|');
+        for (const ft of FILING_TYPES) {
+            lines.push(`| **${ft.form}** | ${ft.cadence} | ${ft.description} | ${ft.use_cases} |`);
+        }
+        return lines.join('\n');
+    },
+    list: async () => ({
+        resources: [
+            {
+                uri: 'secedgar://filing-types',
+                name: 'SEC Filing Types',
+                description: 'Common SEC filing types with descriptions and use cases',
+                mimeType: 'text/markdown',
+            },
+        ],
+    }),
+});
+//# sourceMappingURL=filing-types.resource.js.map

package/dist/mcp-server/resources/definitions/filing-types.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filing-types.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/filing-types.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,MAAM,YAAY,GAAG;IACnB;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,QAAQ;QACjB,WAAW,EACT,mFAAmF;QACrF,SAAS,EAAE,yDAAyD;KACrE;IACD;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,mBAAmB;QAC5B,WAAW,EAAE,qEAAqE;QAClF,SAAS,EAAE,oDAAoD;KAChE;IACD;QACE,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,cAAc;QACvB,WAAW,EACT,uFAAuF;QACzF,SAAS,EAAE,wDAAwD;KACpE;IACD;QACE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,cAAc;QACvB,WAAW,EACT,wFAAwF;QAC1F,SAAS,EAAE,sDAAsD;KAClE;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW;QACpB,WAAW,EAAE,yDAAyD;QACtE,SAAS,EAAE,sDAAsD;KAClE;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,iBAAiB;QAC1B,WAAW,EAAE,qEAAqE;QAClF,SAAS,EAAE,yDAAyD;KACrE;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW;QACpB,WAAW,EAAE,yDAAyD;QACtE,SAAS,EAAE,+CAA+C;KAC3D;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,WAAW;QACpB,WAAW,EAAE,wDAAwD;QACrE,SAAS,EAAE,0CAA0C;KACtD;IACD;QACE,IAAI,EAAE,KAAK;QACX,OAAO,EAAE,UAAU;QACnB,WAAW,EAAE,2EAA2E;QACxF,SAAS,EAAE,qCAAqC;KACjD;IACD;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,QAAQ;QACjB,WAAW,EAAE,4DAA4D;QACzE,SAAS,EAAE,gCAAgC;KAC5C;CACO,CAAC;AAEX,MAAM,CAAC,MAAM,mBAAmB,GAAG,QAAQ,CAAC,yBAAyB,EAAE;IACrE,IAAI,EAAE,kBAAkB;IACxB,WAAW,EACT,+FAA+F;QAC/F,oEAAoE;IACtE,QAAQ,EAAE,eAAe;IAEzB,OAAO,CAAC,OAAO,EAAE,IAAI;QACnB,MAAM,KAAK,GAAa,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;QACnD,KAAK,CAAC,IAAI,CACR,uHAAuH,EACvH,EAAE,CACH,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;QAC3D,KAAK,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;QAC3D,KAAK,MAAM,EAAE,IAAI,YAAY,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,OAAO,MAAM,EAAE,CAAC,WAAW,MAAM,EAAE,CAAC,SAAS,IAAI,CAAC,CAAC;QACzF,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjB,SAAS,EAAE;YACT;gBACE,GAAG,EAAE,yBAAyB;gBAC9B,IAAI,EAAE,kBAAkB;gBACxB,WAAW,EAAE,yDAAyD;gBACtE,QAAQ,EAAE,eAAe;aAC1B;SACF;KACF,CAAC;CACH,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/company-search.tool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Find companies and retrieve entity info with optional recent filings.
+ * Entry point for most SEC EDGAR workflows.
+ * @module mcp-server/tools/definitions/company-search
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const companySearchTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    include_filings: z.ZodDefault<z.ZodBoolean>;
+    form_types: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    filing_limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    cik: z.ZodString;
+    name: z.ZodString;
+    tickers: z.ZodArray<z.ZodString>;
+    exchanges: z.ZodArray<z.ZodString>;
+    sic: z.ZodString;
+    sic_description: z.ZodString;
+    state_of_incorporation: z.ZodOptional<z.ZodString>;
+    fiscal_year_end: z.ZodString;
+    filings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        accession_number: z.ZodString;
+        form: z.ZodString;
+        filing_date: z.ZodString;
+        report_date: z.ZodOptional<z.ZodString>;
+        primary_document: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    total_filings: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;
+//# sourceMappingURL=company-search.tool.d.ts.map

package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"company-search.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/company-search.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAIjD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;kBAiK5B,CAAC"}

package/dist/mcp-server/tools/definitions/company-search.tool.js

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Find companies and retrieve entity info with optional recent filings.
+ * Entry point for most SEC EDGAR workflows.
+ * @module mcp-server/tools/definitions/company-search
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { notFound } from '@cyanheads/mcp-ts-core/errors';
+import { getEdgarApiService } from '../../../services/edgar/edgar-api-service.js';
+export const companySearchTool = tool('secedgar_company_search', {
+    description: 'Find companies and retrieve entity info with optional recent filings. ' +
+        'Entry point for most EDGAR workflows — resolve tickers, names, or CIKs to entity details.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe('Company ticker symbol (e.g., "AAPL"), name (e.g., "Apple"), or CIK number (e.g., "320193"). Ticker is the fastest lookup. Name search does fuzzy matching.'),
+        include_filings: z
+            .boolean()
+            .default(true)
+            .describe('Include recent filings in the response. Set to false for entity-info-only lookups.'),
+        form_types: z
+            .array(z.string())
+            .optional()
+            .describe('Filter filings to specific form types (e.g., ["10-K", "10-Q", "8-K"]). Without this, returns all form types.'),
+        filing_limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .default(10)
+            .describe('Maximum number of filings to return.'),
+    }),
+    output: z.object({
+        cik: z.string().describe('Central Index Key, zero-padded to 10 digits.'),
+        name: z.string().describe('SEC-conformed company name.'),
+        tickers: z.array(z.string()).describe('Associated ticker symbols.'),
+        exchanges: z.array(z.string()).describe('Exchanges where listed.'),
+        sic: z.string().describe('SIC industry code.'),
+        sic_description: z.string().describe('Human-readable SIC description.'),
+        state_of_incorporation: z.string().optional().describe('State of incorporation.'),
+        fiscal_year_end: z.string().describe('Fiscal year end (MMDD format).'),
+        filings: z
+            .array(z.object({
+            accession_number: z.string().describe('Filing accession number.'),
+            form: z.string().describe('Form type (e.g., 10-K).'),
+            filing_date: z.string().describe('Date filed.'),
+            report_date: z.string().optional().describe('Period of report.'),
+            primary_document: z.string().describe('Primary document filename.'),
+            description: z.string().optional().describe('Filing description.'),
+        }))
+            .optional()
+            .describe('Recent filings, filtered by form_types if specified.'),
+        total_filings: z
+            .number()
+            .optional()
+            .describe('Total filings matching the filter (may exceed filing_limit).'),
+    }),
+    async handler(input, ctx) {
+        const api = getEdgarApiService();
+        const resolved = await api.resolveCik(input.query);
+        if (Array.isArray(resolved)) {
+            if (resolved.length === 0) {
+                throw notFound(`No company found for '${input.query}'. Try a ticker symbol (e.g., 'AAPL'), full company name, or 10-digit CIK.`);
+            }
+            if (resolved.length > 1) {
+                const matches = resolved.map((m) => `${m.ticker} (${m.name})`).join(', ');
+                throw notFound(`Multiple matches for '${input.query}': ${matches}. Specify a ticker for an exact match.`);
+            }
+        }
+        const match = Array.isArray(resolved) ? resolved[0] : resolved;
+        if (!match)
+            throw notFound(`No company found for '${input.query}'.`);
+        const submissions = await api.getSubmissions(match.cik);
+        ctx.log.info('Company resolved', {
+            query: input.query,
+            cik: match.cik,
+            name: submissions.name,
+        });
+        let filings;
+        let totalFilings;
+        if (input.include_filings) {
+            const recent = submissions.filings.recent;
+            const count = recent.accessionNumber.length;
+            // Zip parallel arrays into objects
+            const all = [];
+            for (let i = 0; i < count; i++) {
+                all.push({
+                    accession_number: recent.accessionNumber[i] ?? '',
+                    form: recent.form[i] ?? '',
+                    filing_date: recent.filingDate[i] ?? '',
+                    report_date: recent.reportDate[i] || undefined,
+                    primary_document: recent.primaryDocument[i] ?? '',
+                    description: recent.primaryDocDescription[i] || undefined,
+                });
+            }
+            // Filter by form types
+            const filtered = input.form_types
+                ? all.filter((f) => input.form_types?.some((ft) => f.form.toUpperCase() === ft.toUpperCase()))
+                : all;
+            totalFilings = filtered.length;
+            filings = filtered.slice(0, input.filing_limit);
+        }
+        return {
+            cik: match.cik,
+            name: submissions.name,
+            tickers: submissions.tickers,
+            exchanges: submissions.exchanges,
+            sic: submissions.sic,
+            sic_description: submissions.sicDescription,
+            state_of_incorporation: submissions.stateOfIncorporation || undefined,
+            fiscal_year_end: submissions.fiscalYearEnd,
+            filings,
+            total_filings: totalFilings,
+        };
+    },
+    format: (result) => {
+        const lines = [`**${result.name}** (${result.tickers.join(', ') || 'no ticker'})`];
+        lines.push(`CIK: ${result.cik} | SIC: ${result.sic} (${result.sic_description})`);
+        if (result.filings?.length) {
+            lines.push(`\nRecent filings (${result.filings.length} of ${result.total_filings}):`);
+            for (const f of result.filings) {
+                lines.push(`- ${f.form} ${f.filing_date} [${f.accession_number}]`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=company-search.tool.js.map

package/dist/mcp-server/tools/definitions/company-search.tool.js.map

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

package/dist/mcp-server/tools/definitions/compare-metric.tool.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Compare a financial metric across all reporting companies for a specific period.
+ * @module mcp-server/tools/definitions/compare-metric
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const compareMetricTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    concept: z.ZodString;
+    period: z.ZodString;
+    unit: z.ZodDefault<z.ZodEnum<{
+        USD: "USD";
+        shares: "shares";
+        "USD-per-shares": "USD-per-shares";
+        pure: "pure";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    sort: z.ZodDefault<z.ZodEnum<{
+        desc: "desc";
+        asc: "asc";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    concept: z.ZodString;
+    period: z.ZodString;
+    unit: z.ZodString;
+    label: z.ZodString;
+    total_companies: z.ZodNumber;
+    data: z.ZodArray<z.ZodObject<{
+        rank: z.ZodNumber;
+        company_name: z.ZodString;
+        cik: z.ZodString;
+        ticker: z.ZodOptional<z.ZodString>;
+        value: z.ZodNumber;
+        location: z.ZodOptional<z.ZodString>;
+        period_end: z.ZodString;
+        accession_number: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=compare-metric.tool.d.ts.map

package/dist/mcp-server/tools/definitions/compare-metric.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare-metric.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/compare-metric.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAMjD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA8I5B,CAAC"}

package/dist/mcp-server/tools/definitions/compare-metric.tool.js

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Compare a financial metric across all reporting companies for a specific period.
+ * @module mcp-server/tools/definitions/compare-metric
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { notFound } from '@cyanheads/mcp-ts-core/errors';
+import { resolveConcept } from '../../../services/edgar/concept-map.js';
+import { getEdgarApiService } from '../../../services/edgar/edgar-api-service.js';
+export const compareMetricTool = tool('secedgar_compare_metric', {
+    description: 'Compare a financial metric across all reporting companies for a specific period. ' +
+        'Uses the same friendly concept names as secedgar_get_financials (e.g., "revenue", "assets").',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        concept: z
+            .string()
+            .describe('Financial concept — same friendly names as secedgar_get_financials ' +
+            '(e.g., "revenue", "assets", "eps_basic") or raw XBRL tag.'),
+        period: z
+            .string()
+            .describe('Calendar period. Formats:\n' +
+            '  "CY2023" — full year 2023 (duration, for income statement items)\n' +
+            '  "CY2024Q2" — Q2 2024 (duration, for quarterly income items)\n' +
+            '  "CY2023Q4I" — Q4 2023 instant (balance sheet items like assets, cash)\n' +
+            'Use duration periods (no I suffix) for income/cash flow items. ' +
+            'Use instant periods (I suffix) for balance sheet items.'),
+        unit: z
+            .enum(['USD', 'USD-per-shares', 'shares', 'pure'])
+            .default('USD')
+            .describe('Unit of measure. Use "USD-per-shares" for EPS, "shares" for share counts, "pure" for ratios.'),
+        limit: z.number().int().min(1).max(100).default(25).describe('Number of companies to return.'),
+        sort: z
+            .enum(['desc', 'asc'])
+            .default('desc')
+            .describe('Sort direction. "desc" for highest values first (typical for revenue, assets). "asc" for lowest values.'),
+    }),
+    output: z.object({
+        concept: z.string().describe('XBRL tag used.'),
+        period: z.string().describe('Calendar period.'),
+        unit: z.string().describe('Unit of measure.'),
+        label: z.string().describe('Human-readable concept label.'),
+        total_companies: z.number().describe('Total companies reporting this metric for this period.'),
+        data: z
+            .array(z.object({
+            rank: z.number().describe('Rank in sorted order.'),
+            company_name: z.string().describe('Entity name.'),
+            cik: z.string().describe('Company CIK.'),
+            ticker: z.string().optional().describe('Ticker symbol (if available).'),
+            value: z.number().describe('Reported value.'),
+            location: z.string().optional().describe('Business location.'),
+            period_end: z.string().describe('Period end date.'),
+            accession_number: z.string().describe('Source filing for secedgar_get_filing.'),
+        }))
+            .describe('Ranked companies for this metric.'),
+    }),
+    async handler(input, ctx) {
+        const api = getEdgarApiService();
+        // Resolve concept
+        const mapping = resolveConcept(input.concept);
+        const tag = mapping?.tags[0] ?? input.concept;
+        const taxonomy = mapping?.taxonomy ?? 'us-gaap';
+        const label = mapping?.label ?? input.concept;
+        const unit = mapping ? mapping.unit.replace('/', '-per-') : input.unit;
+        // Fetch frames data
+        let framesResponse;
+        try {
+            framesResponse = await api.getFrames(taxonomy, tag, unit, input.period);
+        }
+        catch (err) {
+            const is404 = err instanceof Error && /404|not found/i.test(err.message);
+            if (!is404)
+                throw err;
+            // Distinguish unknown concept (no mapping + 404) from valid concept with no data
+            const hint = !mapping
+                ? `Unknown concept '${input.concept}'. Use a friendly name (e.g., "revenue", "assets") ` +
+                    'or a valid XBRL tag. See secedgar://concepts for available names.'
+                : `No data for ${label}/${unit}/${input.period}. Check: ` +
+                    'duration vs. instant period (add "I" for balance sheet items), ' +
+                    'correct unit (USD-per-shares for EPS), and period exists (data starts ~CY2009).';
+            throw notFound(hint);
+        }
+        // Sort by value
+        const sorted = [...framesResponse.data].sort((a, b) => input.sort === 'desc' ? b.val - a.val : a.val - b.val);
+        // Slice to limit and enrich with tickers
+        const sliced = sorted.slice(0, input.limit);
+        const data = await Promise.all(sliced.map(async (entry, i) => {
+            const cik = String(entry.cik).padStart(10, '0');
+            const ticker = await api.cikToTicker(cik);
+            return {
+                rank: i + 1,
+                company_name: entry.entityName,
+                cik,
+                ticker: ticker || undefined,
+                value: entry.val,
+                location: entry.loc || undefined,
+                period_end: entry.end,
+                accession_number: entry.accn,
+            };
+        }));
+        ctx.log.info('Metric comparison completed', {
+            concept: tag,
+            period: input.period,
+            totalCompanies: framesResponse.pts,
+            returned: data.length,
+        });
+        return {
+            concept: tag,
+            period: input.period,
+            unit,
+            label: framesResponse.label || label,
+            total_companies: framesResponse.pts,
+            data,
+        };
+    },
+    format: (result) => {
+        const lines = [`**${result.label}** — ${result.period} (${result.total_companies} companies)`];
+        for (const d of result.data) {
+            const ticker = d.ticker ? ` (${d.ticker})` : '';
+            const formatted = result.unit === 'USD'
+                ? `$${(d.value / 1_000_000_000).toFixed(2)}B`
+                : result.unit === 'USD-per-shares'
+                    ? `$${d.value.toFixed(2)}`
+                    : d.value.toLocaleString();
+            lines.push(`${d.rank}. ${d.company_name}${ticker}: ${formatted}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=compare-metric.tool.js.map

package/dist/mcp-server/tools/definitions/compare-metric.tool.js.map

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