@etsquare/mcp-server-sec 0.4.0 → 0.5.0

package/dist/etsquare-client.d.ts

@@ -45,6 +45,14 @@ interface EarningsActualsApiInput {
     quarters?: number;
     metrics?: string[];
 }
+/** Stored KPI extractions request. */
+interface KpiExtractionsApiInput {
+    ticker?: string;
+    sector?: string;
+    sic_code?: string;
+    fiscal_year?: number;
+    limit?: number;
+}
 /** Subset of DiscoverMetricsInput that the API v1 backend accepts. */
 interface DiscoverMetricsApiInput {
     question: string;
@@ -70,6 +78,7 @@ export declare class ETSquareClient {
     getInstitutionalHoldings(input: InstitutionalHoldingsApiInput): Promise<Record<string, unknown>>;
     getInsiderTransactions(input: InsiderTransactionsApiInput): Promise<Record<string, unknown>>;
     getEarningsActuals(input: EarningsActualsApiInput): Promise<Record<string, unknown>>;
+    getKpiExtractions(input: KpiExtractionsApiInput): 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

@@ -136,6 +136,24 @@ export class ETSquareClient {
             body: JSON.stringify(body),
         });
     }
+    async getKpiExtractions(input) {
+        const body = {
+            limit: input.limit || 50,
+        };
+        if (input.ticker)
+            body.ticker = input.ticker;
+        if (input.sector)
+            body.sector = input.sector;
+        if (input.sic_code)
+            body.sic_code = input.sic_code;
+        if (input.fiscal_year !== undefined)
+            body.fiscal_year = input.fiscal_year;
+        return this.request('/api/v1/kpis', {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+    }
     async discoverMetrics(input) {
         const body = {
             question: input.question,

package/dist/index.js

@@ -152,19 +152,25 @@ function humanizeColumnName(col) {
 // ─── Structured Response Builders ───────────────────────────────────────────
 function buildSearchContext(apiResponse, originalQuery) {
     const results = apiResponse.narrative_results || [];
+    const metricRows = Array.isArray(apiResponse.xbrl_metrics) ? apiResponse.xbrl_metrics : [];
     const ec = apiResponse.execution_contract || {};
+    const narrativeTickers = [...new Set(results.map((r) => r.ticker).filter(Boolean))];
+    const metricTickers = [...new Set(metricRows.map((r) => r.ticker).filter(Boolean))];
+    const resolvedTickers = [...new Set([...narrativeTickers, ...metricTickers])];
     return {
         query_received: originalQuery,
         query_type: apiResponse.query_type || null,
         scope_confidence: apiResponse.scope_confidence || null,
-        tickers_resolved: [...new Set(results.map((r) => r.ticker).filter(Boolean))],
+        tickers_resolved: resolvedTickers,
+        tickers_with_narrative: narrativeTickers,
+        tickers_with_metrics: metricTickers,
         scope_effective: ec.scope_effective || null,
         mode_effective: ec.mode_effective || null,
         mode_source: ec.mode_source || null,
         scope_source: ec.scope_source || null,
         intent_matched: apiResponse.intent_matched || null,
         results_returned: results.length,
-        unique_tickers: new Set(results.map((r) => r.ticker)).size,
+        unique_tickers: resolvedTickers.length,
         unique_forms: [...new Set(results.map((r) => r.form_type).filter(Boolean))],
         template_match: ec.template_match || null,
         relaxations_applied: ec.relaxations_applied || [],
@@ -172,6 +178,38 @@ function buildSearchContext(apiResponse, originalQuery) {
         processing_time_ms: apiResponse.processing_time_ms || null,
     };
 }
+function backfillMissingMetricTickerRows(rows, requestedTickers) {
+    if (!Array.isArray(rows) || rows.length === 0)
+        return rows;
+    const requested = requestedTickers.filter(Boolean);
+    if (requested.length < 2)
+        return rows;
+    const covered = new Set(rows
+        .map((row) => String(row?.ticker || '').trim().toUpperCase())
+        .filter(Boolean));
+    const missing = requested.filter((ticker) => !covered.has(String(ticker).trim().toUpperCase()));
+    if (missing.length === 0)
+        return rows;
+    const rowKeys = [];
+    const seenKeys = new Set();
+    for (const row of rows) {
+        if (!row || typeof row !== 'object')
+            continue;
+        for (const key of Object.keys(row)) {
+            if (key === 'ticker' || seenKeys.has(key))
+                continue;
+            seenKeys.add(key);
+            rowKeys.push(key);
+        }
+    }
+    const placeholders = missing.map((ticker) => {
+        const placeholder = { ticker };
+        for (const key of rowKeys)
+            placeholder[key] = null;
+        return placeholder;
+    });
+    return [...rows, ...placeholders];
+}
 function deriveLayoutHint(apiResponse) {
     const results = apiResponse.narrative_results || [];
     const tickers = new Set(results.map((r) => r.ticker));
@@ -920,6 +958,120 @@ 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.',
+    inputSchema: {
+        ticker: z.string().min(1).max(10).optional()
+            .describe('Single ticker filter (e.g., "TXRH")'),
+        sector: z.string().min(2).max(50).optional()
+            .describe('Sector key such as "restaurants", "airlines", "banks", "reits", "pharma", or "saas"'),
+        sic_code: z.string().length(4).optional()
+            .describe('Optional SIC code filter'),
+        fiscal_year: z.number().min(1990).max(2100).optional()
+            .describe('Optional fiscal year filter'),
+        limit: z.number().min(1).max(500).default(50)
+            .describe('Maximum rows to return (default: 50)'),
+        response_format: z.enum(['text', 'structured']).default('text')
+            .describe('"text" returns a readable summary (default). "structured" returns the raw extraction payload as JSON.'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        const result = await client.getKpiExtractions(input);
+        const extractions = Array.isArray(result.extractions)
+            ? result.extractions
+            : [];
+        const filters = result.filters && typeof result.filters === 'object'
+            ? result.filters
+            : {};
+        const count = typeof result.count === 'number'
+            ? result.count
+            : extractions.length;
+        if (input.response_format === 'structured') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            count,
+                            filters,
+                            extractions,
+                        }, null, 2),
+                    }],
+            };
+        }
+        if (extractions.length === 0) {
+            const filterBits = [
+                input.ticker ? `ticker=${input.ticker.toUpperCase()}` : null,
+                input.sector ? `sector=${input.sector}` : null,
+                input.sic_code ? `sic_code=${input.sic_code}` : null,
+                input.fiscal_year ? `fiscal_year=${input.fiscal_year}` : null,
+            ].filter(Boolean);
+            const suffix = filterBits.length > 0 ? ` for ${filterBits.join(', ')}` : '';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `No stored KPI extractions found${suffix}. Coverage is sector-dependent. For fresh filing detail, use etsquare_search in NARRATIVE mode.`,
+                    }],
+            };
+        }
+        let text = `Found ${count} KPI extraction`;
+        text += count === 1 ? '' : 's';
+        if (Object.keys(filters).length > 0) {
+            const filterText = Object.entries(filters)
+                .map(([key, value]) => `${key}=${value}`)
+                .join(', ');
+            text += ` for ${filterText}`;
+        }
+        text += '.\n\n';
+        for (const extraction of extractions.slice(0, 20)) {
+            const ticker = extraction.ticker || '—';
+            const periodBits = [
+                extraction.form_type || null,
+                extraction.filing_date || null,
+                extraction.fiscal_year != null ? `FY${extraction.fiscal_year}` : null,
+                extraction.fiscal_period || null,
+            ].filter(Boolean);
+            text += `### ${ticker}${extraction.sector ? ` (${extraction.sector})` : ''}\n`;
+            if (periodBits.length > 0) {
+                text += `${periodBits.join(' | ')}\n`;
+            }
+            const kpiJson = extraction.kpi_json && typeof extraction.kpi_json === 'object'
+                ? extraction.kpi_json
+                : null;
+            if (kpiJson) {
+                const entries = Object.entries(kpiJson)
+                    .slice(0, 12)
+                    .map(([key, value]) => `- ${key}: ${typeof value === 'object' ? JSON.stringify(value) : String(value)}`);
+                if (entries.length > 0) {
+                    text += `${entries.join('\n')}\n`;
+                }
+            }
+            if (extraction.notes) {
+                text += `Notes: ${extraction.notes}\n`;
+            }
+            text += '\n';
+        }
+        if (extractions.length > 20) {
+            text += `Showing 20 of ${count} stored KPI extractions.\n\n`;
+        }
+        text += 'Coverage is sector-dependent and derived from stored extractions, not live on-demand parsing.';
+        return {
+            content: [{ type: 'text', text }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        return {
+            content: [{ type: 'text', text: `KPI extraction request 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 ' +
@@ -1307,9 +1459,10 @@ server.registerTool('etsquare_compare', {
         const allResults = Array.isArray(searchResult.narrative_results)
             ? searchResult.narrative_results
             : [];
-        const xbrlMetrics = Array.isArray(searchResult.xbrl_metrics)
+        const rawXbrlMetrics = Array.isArray(searchResult.xbrl_metrics)
             ? searchResult.xbrl_metrics
             : [];
+        const xbrlMetrics = backfillMissingMetricTickerRows(rawXbrlMetrics, input.tickers);
         // Group results by ticker
         const perTicker = {};
         for (const ticker of input.tickers) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@etsquare/mcp-server-sec",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
-  "description": "MCP server for Claude Desktop: search 3.6M+ SEC filing sections, financial statements, insider trades, institutional ownership, earnings actuals, XBRL metrics, and company lookup.",
+  "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",
   "types": "dist/index.d.ts",
   "bin": {