@etsquare/mcp-server-sec 0.5.1 → 0.6.1

package/dist/etsquare-client.d.ts

@@ -53,6 +53,31 @@ interface KpiExtractionsApiInput {
     fiscal_year?: number;
     limit?: number;
 }
+/** Company research packet request. */
+interface CompanyResearchApiInput {
+    ticker: string;
+    sections?: Array<'snapshot' | 'financials' | 'earnings' | 'narrative' | 'ownership' | 'kpis'>;
+    detail_level?: 'summary' | 'standard' | 'full';
+    peers?: string[];
+    n_periods?: number;
+}
+/** Server-side KPI query with metric filtering. */
+interface QueryKpisApiInput {
+    select?: string[];
+    filter?: Array<{
+        metric: string;
+        op: string;
+        value: number;
+    }>;
+    sector?: string;
+    tickers?: string[];
+    period?: string;
+    fiscal_year?: number;
+    sort_by?: string;
+    sort_order?: string;
+    limit?: number;
+    action?: string;
+}
 /** Subset of DiscoverMetricsInput that the API v1 backend accepts. */
 interface DiscoverMetricsApiInput {
     question: string;
@@ -79,6 +104,8 @@ export declare class ETSquareClient {
     getInsiderTransactions(input: InsiderTransactionsApiInput): Promise<Record<string, unknown>>;
     getEarningsActuals(input: EarningsActualsApiInput): Promise<Record<string, unknown>>;
     getKpiExtractions(input: KpiExtractionsApiInput): Promise<Record<string, unknown>>;
+    getCompanyResearch(input: CompanyResearchApiInput): Promise<Record<string, unknown>>;
+    queryKpis(input: QueryKpisApiInput): Promise<Record<string, unknown>>;
     discoverMetrics(input: DiscoverMetricsApiInput): Promise<Record<string, unknown>>;
     getChunk(input: GetChunkInput): Promise<Record<string, unknown>>;
     getChunkContext(input: GetChunkContextInput): Promise<Record<string, unknown>>;

package/dist/etsquare-client.js

@@ -158,6 +158,52 @@ export class ETSquareClient {
             body: JSON.stringify(body),
         });
     }
+    async getCompanyResearch(input) {
+        const body = {
+            ticker: input.ticker,
+        };
+        if (input.sections && input.sections.length > 0)
+            body.sections = input.sections;
+        if (input.detail_level)
+            body.detail_level = input.detail_level;
+        if (input.peers && input.peers.length > 0)
+            body.peers = input.peers;
+        if (input.n_periods !== undefined)
+            body.n_periods = input.n_periods;
+        return this.request('/api/v1/company/research', {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+    }
+    async queryKpis(input) {
+        const body = {
+            limit: input.limit || 50,
+        };
+        if (input.select && input.select.length > 0)
+            body.select = input.select;
+        if (input.filter && input.filter.length > 0)
+            body.filter = input.filter;
+        if (input.sector)
+            body.sector = input.sector;
+        if (input.tickers && input.tickers.length > 0)
+            body.tickers = input.tickers;
+        if (input.period)
+            body.period = input.period;
+        if (input.fiscal_year !== undefined)
+            body.fiscal_year = input.fiscal_year;
+        if (input.sort_by)
+            body.sort_by = input.sort_by;
+        if (input.sort_order)
+            body.sort_order = input.sort_order;
+        if (input.action)
+            body.action = input.action;
+        return this.request('/api/v1/kpis/query', {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+    }
     async discoverMetrics(input) {
         const body = {
             question: input.question,

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * @etsquare/mcp-server-sec  v0.3.0
+ * @etsquare/mcp-server-sec  v0.6.0
  * MCP server for SEC Intelligence: search SEC filings,
  * resolve company tickers, execute financial metrics templates,
  * compare companies, and access weekly briefs.
@@ -57,7 +57,7 @@ if (!apiKey) {
     process.exit(1);
 }
 const client = new ETSquareClient({ baseUrl, apiKey });
-log('info', `ETSquare MCP Server v0.3.0 starting with backend: ${baseUrl}`);
+log('info', `ETSquare MCP Server v0.6.0 starting with backend: ${baseUrl}`);
 // ─── Item Code Labels ───────────────────────────────────────────────────────
 const ITEM_CODE_LABELS = {
     // 10-K
@@ -358,7 +358,7 @@ function buildMarkdownTable(colNames, rows, maxRows = 20) {
 // ─── MCP Server ─────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'etsquare-mcp-sec',
-    version: '0.3.0',
+    version: '0.6.0',
 });
 // ─── Tool 1: Company Lookup ─────────────────────────────────────────────────
 server.registerTool('etsquare_lookup_company', {
@@ -406,7 +406,7 @@ server.registerTool('etsquare_lookup_company', {
 // ─── Tool 2: SEC Filing Search ──────────────────────────────────────────────
 server.registerTool('etsquare_search', {
     title: 'Search SEC Filings',
-    description: 'Search 3.4M+ SEC filing sections (10-K, 10-Q, 8-K) with hybrid retrieval. ' +
+    description: 'Search 4.0M+ SEC filing sections (10-K, 10-Q, 8-K) with hybrid retrieval. ' +
         'Returns verbatim filing text with citations — best for qualitative research.\n\n' +
         'Execution contract (required):\n' +
         '- mode_lock: NARRATIVE (recommended) | HYBRID\n' +
@@ -678,6 +678,13 @@ server.registerTool('etsquare_financial_statements', {
                 table += `| **${labelDisplay(dk)}** | ${values.join(' | ')} |\n`;
             }
         }
+        // Filing source URLs per period
+        const periodUrls = periods
+            .filter((p) => p.sec_url)
+            .map((p) => `- FY${p.fiscal_year}${p.fiscal_period !== 'FY' ? ' ' + p.fiscal_period : ''}: ${p.sec_url}`);
+        if (periodUrls.length > 0) {
+            table += `\n**Filing Sources:**\n${periodUrls.join('\n')}\n`;
+        }
         // Provenance note
         const firstPeriod = periods[0];
         const sampleLine = firstPeriod?.lines?.[labels[0]];
@@ -752,14 +759,15 @@ server.registerTool('etsquare_insider_trades', {
         text += `\n\n`;
         // Transaction table — show top 20
         const shown = transactions.slice(0, 20);
-        text += `| Date | Insider | Title | Type | Shares | Price | Value |\n`;
-        text += `|------|---------|-------|------|-------:|------:|------:|\n`;
+        text += `| Date | Insider | Title | Type | Shares | Price | Value | Filing |\n`;
+        text += `|------|---------|-------|------|-------:|------:|------:|:------:|\n`;
         for (const t of shown) {
             const shares = t.shares != null ? t.shares.toLocaleString() : '—';
             const price = t.price_per_share != null ? `$${t.price_per_share.toFixed(2)}` : '—';
             const value = t.total_value != null ? fmtVal(t.total_value) : '—';
             const typeLabel = t.is_derivative ? `${t.transaction_type} *` : t.transaction_type;
-            text += `| ${t.transaction_date} | ${t.owner_name} | ${t.officer_title || '—'} | ${typeLabel} | ${shares} | ${price} | ${value} |\n`;
+            const filing = t.sec_url ? `[SEC](${t.sec_url})` : '—';
+            text += `| ${t.transaction_date} | ${t.owner_name} | ${t.officer_title || '—'} | ${typeLabel} | ${shares} | ${price} | ${value} | ${filing} |\n`;
         }
         if (transactions.length > 20) {
             text += `\n*Showing 20 of ${transactions.length} transactions.*\n`;
@@ -845,6 +853,19 @@ server.registerTool('etsquare_institutional_holdings', {
             if (holders.length > 20) {
                 text += `\n*Showing 20 of ${holders.length} tracked holders.*\n`;
             }
+            // Filing source URLs for this quarter (deduplicated by manager)
+            const seenMgrs = new Set();
+            const quarterLinks = [];
+            for (const h of holders) {
+                const key = h.manager_cik || h.manager_name;
+                if (h.sec_url && key && !seenMgrs.has(key)) {
+                    seenMgrs.add(key);
+                    quarterLinks.push(`- ${h.manager_name || 'Unknown'}: [13F Filing](${h.sec_url})`);
+                }
+            }
+            if (quarterLinks.length > 0) {
+                text += `\n**13F Filing Sources (${q}):**\n${quarterLinks.slice(0, 10).join('\n')}\n`;
+            }
             text += '\n';
         }
         text += `*Source: SEC 13F-HR filings via EDGAR. Tracked managers only — not full institutional ownership.*`;
@@ -928,6 +949,18 @@ server.registerTool('etsquare_earnings_actuals', {
                 const conf = a.confidence != null ? `${(a.confidence * 100).toFixed(0)}%` : '—';
                 text += `| ${a.filing_date || '—'} | ${a.metric_name} | ${val} | ${gaap} | ${fy} | ${fq} | ${conf} |\n`;
             }
+            // Filing source URLs (deduplicated by accession)
+            const seenAccessions = new Set();
+            const filingLinks = [];
+            for (const a of actuals) {
+                if (a.sec_url && a.accession_number && !seenAccessions.has(a.accession_number)) {
+                    seenAccessions.add(a.accession_number);
+                    filingLinks.push(`- ${a.filing_date || '—'}: ${a.sec_url}`);
+                }
+            }
+            if (filingLinks.length > 0) {
+                text += `\n**Filing Sources:**\n${filingLinks.join('\n')}\n`;
+            }
             text += '\n';
         }
         if (guidance.length > 0) {
@@ -943,6 +976,18 @@ server.registerTool('etsquare_earnings_actuals', {
                 const fq = g.fiscal_quarter ?? '—';
                 text += `| ${g.filing_date || '—'} | ${g.metric_name} | ${low} | ${high} | ${mid} | ${gaap} | ${fy} | ${fq} |\n`;
             }
+            // Filing source URLs for guidance (deduplicated)
+            const seenGuidanceAcc = new Set();
+            const guidanceLinks = [];
+            for (const g of guidance) {
+                if (g.sec_url && g.accession_number && !seenGuidanceAcc.has(g.accession_number)) {
+                    seenGuidanceAcc.add(g.accession_number);
+                    guidanceLinks.push(`- ${g.filing_date || '—'}: ${g.sec_url}`);
+                }
+            }
+            if (guidanceLinks.length > 0) {
+                text += `\n**Guidance Filing Sources:**\n${guidanceLinks.join('\n')}\n`;
+            }
             text += '\n';
         }
         text += `*Source: SEC 8-K Item 2.02 press releases — deterministic extraction from issuer filings.*`;
@@ -959,11 +1004,15 @@ server.registerTool('etsquare_earnings_actuals', {
     }
 });
 server.registerTool('etsquare_kpi_extractions', {
-    title: 'Get Sector KPI Extractions',
-    description: 'Query stored KPI extractions from SEC filings for supported sectors such as restaurants, airlines, banks, REITs, pharma, and SaaS.\n\n' +
-        'This returns previously extracted KPI rows with provenance like filing date, fiscal period, and source chunk IDs when available.\n\n' +
-        'Use this for stored non-XBRL operating metrics such as guest traffic, same-store sales, load factor, NIM, deposit trends, or sector-specific KPIs.\n\n' +
-        'Coverage is sector-dependent and may be partial. If coverage is sparse or you need fresh narrative detail, use etsquare_search in NARRATIVE mode.',
+    title: 'Get KPI Extractions (Full Detail + Source Chunk IDs)',
+    description: 'Returns full KPI extraction detail including source_chunk_ids for provenance.\n\n' +
+        'USE THIS TOOL for the provenance chain:\n' +
+        '  1. etsquare_query_kpis -> find interesting metric + extraction_id\n' +
+        '  2. etsquare_kpi_extractions(ticker, sector) -> get source_chunk_ids array\n' +
+        '  3. etsquare_get_chunk(chunk_id) -> read actual filing paragraph\n\n' +
+        'Also use when you need the complete kpi_json payload for deep analysis of a single ticker.\n\n' +
+        'RETURNS: extraction_id, kpi_json (full), source_chunk_ids (array of chunk IDs), notes, extraction_model.\n\n' +
+        'For compact tabular queries across many tickers, prefer etsquare_query_kpis instead.',
     inputSchema: {
         ticker: z.string().min(1).max(10).optional()
             .describe('Single ticker filter (e.g., "TXRH")'),
@@ -1051,6 +1100,9 @@ server.registerTool('etsquare_kpi_extractions', {
                     text += `${entries.join('\n')}\n`;
                 }
             }
+            if (extraction.sec_url) {
+                text += `SEC Filing: ${extraction.sec_url}\n`;
+            }
             if (extraction.notes) {
                 text += `Notes: ${extraction.notes}\n`;
             }
@@ -1072,6 +1124,185 @@ server.registerTool('etsquare_kpi_extractions', {
         };
     }
 });
+server.registerTool('etsquare_query_kpis', {
+    title: 'Query KPI Extractions (Compare, Screen, Catalog)',
+    description: 'Server-side filtered KPI query. Returns compact tabular data with values + YoY changes + summary stats.\n\n' +
+        'WORKFLOW: action="list_metrics" -> discover metrics -> action="query" with select/filter\n\n' +
+        'EXAMPLES:\n' +
+        '  Peer comp:  select="net_interest_margin,cet1_ratio,return_on_tangible_common_equity", sector="banks", period="FY"\n' +
+        '  Screen:     filter="net_interest_margin>3;cet1_ratio>11", sector="banks", period="FY"\n' +
+        '  SaaS:       select="arr,net_dollar_retention,free_cash_flow_margin", sector="saas", sort_by="arr"\n' +
+        '  Catalog:    action="list_metrics", sector="banks"\n' +
+        '  Time series: select="net_interest_margin", tickers="JPM", limit=20\n\n' +
+        'OUTPUT: Each row includes ticker, company_name, extraction_id, metric_value, metric_chg (YoY), metric_unit.\n' +
+        '  Summary stats (min/max/avg/median) per metric included.\n\n' +
+        'PROVENANCE CHAIN: Results include extraction_id. To read source MD&A text:\n' +
+        '  1. etsquare_query_kpis -> get extraction_id\n' +
+        '  2. etsquare_kpi_extractions(ticker) -> get source_chunk_ids\n' +
+        '  3. etsquare_get_chunk(chunk_id) -> read actual filing paragraph\n' +
+        'Use when a number looks surprising or needs management context.',
+    inputSchema: {
+        select: z.string().optional()
+            .describe('Comma-separated metric keys to return (e.g., "net_interest_margin,cet1_ratio,diluted_eps")'),
+        filter: z.string().optional()
+            .describe('Filter conditions as "metric>value" pairs separated by semicolons (e.g., "net_interest_margin>3;cet1_ratio>11")'),
+        sector: z.string().optional()
+            .describe('Sector filter (e.g., "banks", "restaurants", "saas", "airlines")'),
+        tickers: z.string().optional()
+            .describe('Comma-separated tickers (e.g., "JPM,BAC,WFC")'),
+        period: z.string().optional()
+            .describe('Fiscal period: "FY", "Q1", "Q2", "Q3", "Q4"'),
+        fiscal_year: z.number().optional()
+            .describe('Fiscal year filter (e.g., 2025)'),
+        sort_by: z.string().optional()
+            .describe('Metric key to sort by'),
+        sort_order: z.string().optional()
+            .describe('Sort direction: "ASC" or "DESC" (default: DESC)'),
+        limit: z.number().min(1).max(500).default(50)
+            .describe('Maximum rows (default: 50)'),
+        action: z.string().optional()
+            .describe('"query" returns data (default). "list_metrics" returns available metric names for a sector.'),
+        response_format: z.string().optional()
+            .describe('"text" returns a markdown table (default). "structured" returns raw JSON for programmatic use.'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        // Parse string inputs into arrays for the API
+        const apiInput = {
+            limit: input.limit || 50,
+            action: input.action || 'query',
+        };
+        if (input.select) {
+            apiInput.select = input.select.split(',').map((s) => s.trim()).filter(Boolean);
+        }
+        if (input.filter) {
+            // Parse "metric>value;metric2<value2" format
+            const filterParts = input.filter.split(';').map((s) => s.trim()).filter(Boolean);
+            const filters = [];
+            for (const part of filterParts) {
+                const match = part.match(/^([a-z][a-z0-9_]*)\s*(>=|<=|!=|>|<|=)\s*(-?[\d.]+)$/);
+                if (match) {
+                    filters.push({ metric: match[1], op: match[2], value: parseFloat(match[3]) });
+                }
+            }
+            if (filters.length > 0)
+                apiInput.filter = filters;
+        }
+        if (input.tickers) {
+            apiInput.tickers = input.tickers.split(',').map((s) => s.trim().toUpperCase()).filter(Boolean);
+        }
+        if (input.sector)
+            apiInput.sector = input.sector;
+        if (input.period)
+            apiInput.period = input.period;
+        if (input.fiscal_year !== undefined)
+            apiInput.fiscal_year = input.fiscal_year;
+        if (input.sort_by)
+            apiInput.sort_by = input.sort_by;
+        if (input.sort_order)
+            apiInput.sort_order = input.sort_order;
+        const result = await client.queryKpis(apiInput);
+        const data = Array.isArray(result.data)
+            ? result.data
+            : [];
+        const count = typeof result.count === 'number'
+            ? result.count
+            : data.length;
+        // list_metrics action
+        if ((input.action || 'query') === 'list_metrics') {
+            const metrics = result.metrics || [];
+            const otherMetrics = result.other_kpis_metrics || [];
+            let text = `Available KPI metrics`;
+            if (result.sector)
+                text += ` for sector "${result.sector}"`;
+            if (result.ticker)
+                text += ` ticker ${result.ticker}`;
+            text += `:\n\n`;
+            text += `**Top-level metrics (${metrics.length}):**\n`;
+            text += metrics.map(m => `- ${m}`).join('\n');
+            if (otherMetrics.length > 0) {
+                text += `\n\n**other_kpis metrics (${otherMetrics.length}):**\n`;
+                text += otherMetrics.slice(0, 30).map(m => `- ${m}`).join('\n');
+                if (otherMetrics.length > 30)
+                    text += `\n... and ${otherMetrics.length - 30} more`;
+            }
+            return { content: [{ type: 'text', text }] };
+        }
+        // query action
+        if (data.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'No KPI data found for the specified query. Try broader filters or use action="list_metrics" to see available metrics.',
+                    }],
+            };
+        }
+        // Structured format — return raw JSON
+        if ((input.response_format || 'text') === 'structured') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ count, data }, null, 2),
+                    }],
+            };
+        }
+        // Build markdown table — exclude sec_url from columns (too wide for table)
+        const excludeFromTable = new Set(['sec_url']);
+        const columns = Object.keys(data[0]).filter(c => !excludeFromTable.has(c));
+        let text = `Found ${count} results.\n\n`;
+        text += '| ' + columns.join(' | ') + ' |\n';
+        text += '| ' + columns.map(() => '---').join(' | ') + ' |\n';
+        for (const row of data) {
+            const values = columns.map(col => {
+                const v = row[col];
+                if (v === null || v === undefined)
+                    return '—';
+                if (typeof v === 'number')
+                    return Number.isInteger(v) ? String(v) : v.toFixed(2);
+                return String(v);
+            });
+            text += '| ' + values.join(' | ') + ' |\n';
+        }
+        if (count > data.length) {
+            text += `\nShowing ${data.length} of ${count} results.`;
+        }
+        // Filing source URLs (deduplicated by ticker)
+        const seenTickers = new Set();
+        const filingLinks = [];
+        for (const row of data) {
+            if (row.sec_url && row.ticker && !seenTickers.has(row.ticker)) {
+                seenTickers.add(row.ticker);
+                filingLinks.push(`- ${row.ticker}: ${row.sec_url}`);
+            }
+        }
+        if (filingLinks.length > 0) {
+            text += `\n\n**Filing Sources:**\n${filingLinks.join('\n')}`;
+        }
+        // Append summary stats if available
+        const summary = result.summary;
+        if (summary && typeof summary === 'object' && Object.keys(summary).length > 0) {
+            text += '\n\n**Summary Stats:**\n';
+            text += '| Metric | Min | Max | Avg | Median | Count |\n';
+            text += '| --- | --- | --- | --- | --- | --- |\n';
+            for (const [metric, stats] of Object.entries(summary)) {
+                const s = stats;
+                text += `| ${metric} | ${s.min} | ${s.max} | ${s.avg} | ${s.median} | ${s.count} |\n`;
+            }
+        }
+        // Provenance hint
+        text += '\n*Each row includes extraction_id. Filing source URLs are listed above. Use response_format="structured" for per-row sec_url in JSON.*';
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `KPI query failed: ${message}` }],
+            isError: true,
+        };
+    }
+});
 server.registerTool('etsquare_execute_metrics', {
     title: 'Execute Financial Metrics Query',
     description: 'Execute an XBRL metrics template by template_id to get structured financial data ' +
@@ -1183,18 +1414,35 @@ server.registerTool('etsquare_execute_metrics', {
             return { content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }] };
         }
         // ── Text response path (existing behavior) ──
-        const colNames = columns.length > 0
+        const allColNames = columns.length > 0
             ? columns.map((c) => c.name)
             : Object.keys(rows[0] || {});
+        // Exclude sec_url from table columns (too wide for markdown)
+        const colNames = allColNames.filter((c) => c !== 'sec_url');
         const table = buildMarkdownTable(colNames, rows);
         const suffix = truncated || rows.length > 20
             ? `\n\n(Showing ${Math.min(rows.length, 20)} of ${rowCount} rows${truncated ? ', results truncated' : ''})`
             : '';
+        // Filing source URLs (deduplicated)
+        let filingSources = '';
+        const seenUrls = new Set();
+        const urlLinks = [];
+        for (const row of rows) {
+            if (row.sec_url && !seenUrls.has(row.sec_url)) {
+                seenUrls.add(row.sec_url);
+                const label = row.ticker || row.TICKER || '';
+                const year = row.fiscal_year || row.FISCAL_YEAR || row.year || '';
+                urlLinks.push(`- ${label} ${year}: ${row.sec_url}`);
+            }
+        }
+        if (urlLinks.length > 0) {
+            filingSources = `\n\n**Filing Sources:**\n${urlLinks.slice(0, 20).join('\n')}`;
+        }
         log('info', `Metrics query returned ${rowCount} rows`);
         return {
             content: [{
                     type: 'text',
-                    text: `Metrics data (${rowCount} rows):\n\n${table}${suffix}`,
+                    text: `Metrics data (${rowCount} rows):\n\n${table}${suffix}${filingSources}`,
                 }],
         };
     }
@@ -1343,10 +1591,14 @@ server.registerTool('etsquare_get_chunk', {
             ? result.chunk_text
             : '';
         const chunkLength = result.chunk_text_length;
+        const secUrl = result.sec_url;
+        let header = `Chunk ${input.chunk_id}${typeof chunkLength === 'number' ? ` (${chunkLength} chars)` : ''}`;
+        if (secUrl)
+            header += `\nSEC Filing: ${secUrl}`;
         return {
             content: [{
                     type: 'text',
-                    text: `Chunk ${input.chunk_id}${typeof chunkLength === 'number' ? ` (${chunkLength} chars)` : ''}:\n\n${chunkText}`,
+                    text: `${header}\n\n${chunkText}`,
                 }],
         };
     }
@@ -1612,7 +1864,58 @@ server.registerTool('etsquare_weekly_brief', {
         };
     }
 });
+// ─── Tool 9: Company Research ──────────────────────────────────────────────
+server.registerTool('etsquare_company_research', {
+    title: 'Company Research Packet',
+    description: 'Returns a citation-grounded research packet for one company in a single call. ' +
+        'Server-side orchestration assembles financials, earnings, narrative, ownership, and KPIs with SEC provenance.',
+    inputSchema: {
+        ticker: z.string().min(1).max(10)
+            .describe('Company ticker (e.g., "AAPL", "NVDA"). Resolve names first with etsquare_lookup_company.'),
+        sections: z.array(z.enum(['snapshot', 'financials', 'earnings', 'narrative', 'ownership', 'kpis']))
+            .optional()
+            .describe('Sections to include. Returns all if omitted.'),
+        detail_level: z.enum(['summary', 'standard', 'full']).default('standard')
+            .describe('Controls response size: summary (~4K tokens), standard (~8K), full (~15K).'),
+        peers: z.array(z.string().min(1).max(10)).max(3).optional()
+            .describe('Peer tickers for comparison (financial spine + earnings only). Max 3.'),
+        n_periods: z.number().min(1).max(8).default(4)
+            .describe('Financial statement periods (default: 4).'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    const ticker = input.ticker.trim().toUpperCase();
+    try {
+        log('info', `Company research: ${ticker}`, {
+            sections: input.sections,
+            detail_level: input.detail_level,
+            peers: input.peers,
+            n_periods: input.n_periods,
+        });
+        const packet = await client.getCompanyResearch({
+            ticker,
+            sections: input.sections,
+            detail_level: input.detail_level,
+            peers: input.peers?.map((peer) => peer.trim().toUpperCase()),
+            n_periods: input.n_periods,
+        });
+        log('info', `Company research: ${ticker} complete`, {
+            elapsed_ms: packet?.meta?.elapsed_ms,
+            sections_returned: packet?.meta?.sections_returned,
+            sections_failed: packet?.meta?.sections_failed,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(packet, null, 2) }] };
+    }
+    catch (error) {
+        log('error', `Company research failed: ${ticker}`, { error: error instanceof Error ? error.message : error });
+        return {
+            content: [{ type: 'text', text: `Company research failed for ${ticker}: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
 // ─── Start Server ───────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);
-log('info', 'ETSquare MCP Server v0.3.0 ready and listening on stdio (8 tools)');
+log('info', 'ETSquare MCP Server v0.6.0 ready and listening on stdio (15 tools)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etsquare/mcp-server-sec",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "type": "module",
   "description": "MCP server for Claude Desktop: search SEC filing sections, financial statements, insider trades, institutional ownership, earnings actuals, XBRL metrics, and company lookup.",
   "main": "dist/index.js",