@etsquare/mcp-server-sec 0.5.0 → 0.5.2

package/dist/etsquare-client.d.ts

@@ -53,6 +53,23 @@ interface KpiExtractionsApiInput {
     fiscal_year?: number;
     limit?: 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 +96,7 @@ 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>>;
+    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

@@ -32,7 +32,11 @@ export class ETSquareClient {
     async request(path, init) {
         const url = `${this.baseUrl}${path}`;
         try {
-            const res = await fetch(url, init);
+            const controller = new AbortController();
+            const timeoutMs = parseInt(process.env.ETSQUARE_FETCH_TIMEOUT_MS || '600000', 10);
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            const res = await fetch(url, { ...init, signal: controller.signal });
+            clearTimeout(timer);
             return this.handleResponse(res);
         }
         catch (error) {
@@ -154,6 +158,34 @@ export class ETSquareClient {
             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

@@ -959,11 +959,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")'),
@@ -1072,6 +1076,172 @@ 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
+        const columns = Object.keys(data[0]);
+        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.`;
+        }
+        // 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 for source tracing. Use etsquare_kpi_extractions(ticker) to get source_chunk_ids, then etsquare_get_chunk(chunk_id) to read the filing text.*';
+        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 ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etsquare/mcp-server-sec",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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",