@etsquare/mcp-server-sec 0.2.0 → 0.2.1

package/dist/etsquare-client.d.ts

@@ -2,7 +2,7 @@
  * ETSquare SEC Intelligence API client.
  * Wraps /api/v1/* endpoints with X-API-Key authentication.
  */
-import type { SearchInput, LookupCompanyInput, ExecuteMetricsInput, DiscoverMetricsInput } from './types.js';
+import type { SearchInput, LookupCompanyInput, ExecuteMetricsInput, DiscoverMetricsInput, GetChunkInput, GetChunkContextInput } from './types.js';
 export interface ETSquareClientOptions {
     baseUrl: string;
     apiKey: string;
@@ -17,4 +17,6 @@ export declare class ETSquareClient {
     lookupCompany(input: LookupCompanyInput): Promise<Record<string, unknown>>;
     executeMetrics(input: ExecuteMetricsInput): Promise<Record<string, unknown>>;
     discoverMetrics(input: DiscoverMetricsInput): Promise<Record<string, unknown>>;
+    getChunk(input: GetChunkInput): Promise<Record<string, unknown>>;
+    getChunkContext(input: GetChunkContextInput): Promise<Record<string, unknown>>;
 }

package/dist/etsquare-client.js

@@ -7,6 +7,7 @@ export class ETSquareClient {
         return {
             'Content-Type': 'application/json',
             'X-API-Key': this.apiKey,
+            'X-Entry-Point': 'mcp',
         };
     }
     async handleResponse(res) {
@@ -90,4 +91,24 @@ export class ETSquareClient {
         });
         return this.handleResponse(res);
     }
+    async getChunk(input) {
+        const params = new URLSearchParams({ execution_id: input.execution_id });
+        const res = await fetch(`${this.baseUrl}/api/v1/chunk/${input.chunk_id}?${params}`, {
+            headers: this.headers,
+        });
+        return this.handleResponse(res);
+    }
+    async getChunkContext(input) {
+        const params = new URLSearchParams();
+        if (input.neighbor_span !== undefined)
+            params.set('neighbor_span', String(input.neighbor_span));
+        if (input.window !== undefined)
+            params.set('window', String(input.window));
+        const query = params.toString();
+        const suffix = query ? `?${query}` : '';
+        const res = await fetch(`${this.baseUrl}/api/v1/chunks/${input.chunk_id}/context${suffix}`, {
+            headers: this.headers,
+        });
+        return this.handleResponse(res);
+    }
 }

package/dist/index.js

@@ -41,7 +41,7 @@ function guardrailViolationResponse() {
     };
 }
 // Environment configuration
-const baseUrl = process.env.ETSQUARE_BASE_URL || 'https://www.etsquare.ai';
+const baseUrl = process.env.ETSQUARE_BASE_URL || 'https://sec-intelligence-api-4mk2on5fga-uc.a.run.app';
 const apiKey = process.env.ETSQUARE_API_KEY;
 const DEBUG = process.env.DEBUG === 'true';
 function log(level, message, data) {
@@ -62,7 +62,7 @@ log('info', `ETSquare MCP Server starting with backend: ${baseUrl}`);
 // Initialize MCP Server
 const server = new McpServer({
     name: 'etsquare-mcp-sec',
-    version: '0.2.0',
+    version: '0.2.1',
 });
 // Tool 1: Company Lookup
 server.registerTool('etsquare_lookup_company', {
@@ -110,14 +110,14 @@ server.registerTool('etsquare_lookup_company', {
 // Tool 2: SEC Filing Search
 server.registerTool('etsquare_search', {
     title: 'Search SEC Filings',
-    description: 'Search 1.2M+ SEC filing sections (10-K, 10-Q, 8-K) with hybrid retrieval. ' +
+    description: 'Search 3.4M+ 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' +
         '- scope_lock: COMPANY (specific tickers) | INDUSTRY (SIC sector) | MACRO (cross-market)\n\n' +
         'For structured financial data (revenue, margins, ratios), use etsquare_discover_metrics + etsquare_execute_metrics instead.\n\n' +
         'Use tickers to scope to specific companies (resolve names first with etsquare_lookup_company). ' +
-        'Results include verbatim filing text, similarity scores, and SEC source URLs.',
+        'Results include filing text plus safe citation metadata such as chunk_id, accession number, and SEC URL for follow-up retrieval.',
     inputSchema: {
         query: z.string().min(3).describe('What to search for in SEC filings (e.g., "customer concentration risk", "Show NVDA revenue trend")'),
         mode_lock: z.enum(['NARRATIVE', 'HYBRID']).describe('NARRATIVE for text search, HYBRID for text + any available metrics'),
@@ -147,6 +147,12 @@ server.registerTool('etsquare_search', {
             ? result.xbrl_metrics
             : [];
         const resultCount = searchResults.length;
+        const executionId = typeof result.execution_id === 'string'
+            ? result.execution_id
+            : null;
+        const researchRunId = typeof result.research_run_id === 'string'
+            ? result.research_run_id
+            : null;
         if (resultCount === 0 && xbrlMetrics.length === 0) {
             let text = `No results found for: "${input.query}"`;
             text += '\nTry broadening your query or removing filters.';
@@ -167,6 +173,16 @@ server.registerTool('etsquare_search', {
                 if (r.fiscal_year && r.fiscal_period) {
                     lines[1] += ` | ${r.fiscal_period} FY${r.fiscal_year}`;
                 }
+                const metaParts = [];
+                if (r.chunk_id)
+                    metaParts.push(`Chunk ID: ${r.chunk_id}`);
+                if (r.accession_number)
+                    metaParts.push(`Accession: ${r.accession_number}`);
+                if (r.chunk_text_truncated)
+                    metaParts.push('Truncated: yes');
+                if (metaParts.length > 0) {
+                    lines.push(`    ${metaParts.join(' | ')}`);
+                }
                 if (r.chunk_text) {
                     const snippet = r.chunk_text.substring(0, 600);
                     lines.push(`    ${snippet}${r.chunk_text.length > 600 ? '...' : ''}`);
@@ -178,7 +194,13 @@ server.registerTool('etsquare_search', {
                 return lines.join('\n');
             })
                 .join('\n\n');
-            sections.push(`SEC Filing Citations (${resultCount}):\n\n${formatted}`);
+            const headerParts = [`SEC Filing Citations (${resultCount}):`];
+            if (executionId)
+                headerParts.push(`Execution ID: ${executionId}`);
+            if (researchRunId)
+                headerParts.push(`Research Run ID: ${researchRunId}`);
+            const header = headerParts.join('\n');
+            sections.push(`${header}\n\n${formatted}`);
         }
         // Format XBRL metrics if present (handles both wide-format and long-format rows)
         if (xbrlMetrics.length > 0) {
@@ -283,10 +305,13 @@ server.registerTool('etsquare_discover_metrics', {
     title: 'Discover Financial Metrics Templates',
     description: 'Find available XBRL metrics templates by business question. ' +
         'Returns template IDs and metadata — use the template_id with etsquare_execute_metrics.\n\n' +
+        'Use this only for structured metrics such as revenue, gross margin, operating margin, EPS, debt, liquidity, or cash flow.\n\n' +
+        'Do not use this for narrative KPI questions like same-store sales, comparable sales, traffic, guest count, average check, or AUV. ' +
+        'For those, use etsquare_search in NARRATIVE mode instead.\n\n' +
         'Example: "revenue trend by quarter" → returns matching templates with their required bind_params.\n\n' +
         'Workflow: discover_metrics → pick template_id → execute_metrics with bind_params.',
     inputSchema: {
-        question: z.string().min(3).describe('Business question (e.g., "revenue trend by quarter", "profit margins comparison")'),
+        question: z.string().min(3).describe('Structured metrics question (e.g., "revenue trend by quarter", "gross margin trend", "EPS trend")'),
         scenario: z.enum(['snapshot', 'trends', 'peer_benchmark']).optional().describe('Filter by scenario type'),
         metric_family: z.string().optional().describe('Filter by metric family: REVENUE, EARNINGS, PROFITABILITY_MARGIN, LEVERAGE_DEBT, FREE_CASH_FLOW, LIQUIDITY'),
         max_results: z.number().min(1).max(10).default(5).optional().describe('Max templates to return'),
@@ -300,11 +325,27 @@ server.registerTool('etsquare_discover_metrics', {
         const templates = Array.isArray(result.templates)
             ? result.templates
             : [];
+        const guidance = result.guidance && typeof result.guidance === 'object'
+            ? result.guidance
+            : null;
         if (templates.length === 0) {
+            let text = `No structured metrics templates found for: "${input.question}"`;
+            if (guidance?.message) {
+                text += `\n${guidance.message}`;
+            }
+            if (guidance?.suggested_tool === 'etsquare_search') {
+                text += '\nRecommended next step: use etsquare_search with NARRATIVE mode.';
+            }
+            const examples = Array.isArray(guidance?.valid_metrics_examples)
+                ? guidance.valid_metrics_examples
+                : [];
+            if (examples.length > 0) {
+                text += `\nValid metrics examples: ${examples.join('; ')}`;
+            }
             return {
                 content: [{
                         type: 'text',
-                        text: `No metrics templates found for: "${input.question}"\nTry a different question or remove filters.`,
+                        text,
                     }],
             };
         }
@@ -354,6 +395,102 @@ server.registerTool('etsquare_discover_metrics', {
         };
     }
 });
+// Tool 5: Expand a single chunk to full text
+server.registerTool('etsquare_get_chunk', {
+    title: 'Get Full Chunk Text',
+    description: 'Fetch the full text for a specific search result chunk. ' +
+        'Use this when etsquare_search returns a truncated snippet and you need the complete chunk text. ' +
+        'Requires both chunk_id and execution_id from a prior search result.',
+    inputSchema: {
+        chunk_id: z.string().length(32).describe('Chunk ID from etsquare_search output'),
+        execution_id: z.string().min(32).describe('Execution ID from the etsquare_search response header'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        log('debug', 'Fetching full chunk text', { chunk_id: input.chunk_id });
+        const result = await client.getChunk(input);
+        const chunkText = typeof result.chunk_text === 'string'
+            ? result.chunk_text
+            : '';
+        const chunkLength = result.chunk_text_length;
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Chunk ${input.chunk_id}${typeof chunkLength === 'number' ? ` (${chunkLength} chars)` : ''}:\n\n${chunkText}`,
+                }],
+        };
+    }
+    catch (error) {
+        log('error', 'Chunk fetch failed', { error: error instanceof Error ? error.message : error });
+        return {
+            content: [{ type: 'text', text: `Chunk fetch failed: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// Tool 6: Expand chunk with surrounding context
+server.registerTool('etsquare_get_chunk_context', {
+    title: 'Get Chunk Context',
+    description: 'Fetch the highlighted chunk plus surrounding context from the same filing section. ' +
+        'Use this when you need the paragraphs immediately before and after a search hit.',
+    inputSchema: {
+        chunk_id: z.string().length(32).describe('Chunk ID from etsquare_search output'),
+        neighbor_span: z.number().min(0).max(5).default(1).optional().describe('How many adjacent chunks to include before and after'),
+        window: z.number().min(200).max(4000).default(900).optional().describe('Approximate character budget for surrounding context'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        log('debug', 'Fetching chunk context', { chunk_id: input.chunk_id });
+        const result = await client.getChunkContext(input);
+        const filing = result.filing || {};
+        const context = result.context || {};
+        const navigation = result.navigation || {};
+        const lines = [
+            `Chunk ID: ${result.chunk_id || input.chunk_id}`,
+        ];
+        if (result.sec_url)
+            lines.push(`SEC URL: ${result.sec_url}`);
+        if (filing.ticker || filing.company) {
+            lines.push(`Filing: ${filing.ticker || 'N/A'} - ${filing.company || 'Unknown'} (${filing.form_type || filing.doc_subtype || 'N/A'})`);
+        }
+        if (filing.item_code || filing.accession_number) {
+            lines.push(`Section: ${filing.item_code || 'N/A'}${filing.accession_number ? ` | Accession: ${filing.accession_number}` : ''}`);
+        }
+        if (typeof navigation.chunk_position === 'number' || typeof navigation.total_chunks_in_item === 'number') {
+            lines.push(`Position: ${navigation.chunk_position ?? 'N/A'} of ${navigation.total_chunks_in_item ?? 'N/A'}`);
+        }
+        lines.push('');
+        if (context.before) {
+            lines.push('Before:');
+            lines.push(String(context.before));
+            lines.push('');
+        }
+        lines.push('Highlight:');
+        lines.push(String(context.highlight || ''));
+        if (context.after) {
+            lines.push('');
+            lines.push('After:');
+            lines.push(String(context.after));
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: lines.join('\n'),
+                }],
+        };
+    }
+    catch (error) {
+        log('error', 'Chunk context fetch failed', { error: error instanceof Error ? error.message : error });
+        return {
+            content: [{ type: 'text', text: `Chunk context fetch failed: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
 // Start server
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/types.d.ts

@@ -63,7 +63,32 @@ export declare const discoverMetricsSchema: z.ZodObject<{
     metric_family?: string | undefined;
     max_results?: number | undefined;
 }>;
+export declare const getChunkSchema: z.ZodObject<{
+    chunk_id: z.ZodString;
+    execution_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    chunk_id: string;
+    execution_id: string;
+}, {
+    chunk_id: string;
+    execution_id: string;
+}>;
+export declare const getChunkContextSchema: z.ZodObject<{
+    chunk_id: z.ZodString;
+    neighbor_span: z.ZodOptional<z.ZodNumber>;
+    window: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    chunk_id: string;
+    neighbor_span?: number | undefined;
+    window?: number | undefined;
+}, {
+    chunk_id: string;
+    neighbor_span?: number | undefined;
+    window?: number | undefined;
+}>;
 export type SearchInput = z.infer<typeof searchSchema>;
 export type LookupCompanyInput = z.infer<typeof lookupCompanySchema>;
 export type ExecuteMetricsInput = z.infer<typeof executeMetricsSchema>;
 export type DiscoverMetricsInput = z.infer<typeof discoverMetricsSchema>;
+export type GetChunkInput = z.infer<typeof getChunkSchema>;
+export type GetChunkContextInput = z.infer<typeof getChunkContextSchema>;

package/dist/types.js

@@ -23,3 +23,12 @@ export const discoverMetricsSchema = z.object({
     metric_family: z.string().optional(),
     max_results: z.number().min(1).max(10).optional(),
 });
+export const getChunkSchema = z.object({
+    chunk_id: z.string().length(32, 'chunk_id must be a 32-character hex string'),
+    execution_id: z.string().min(32, 'execution_id is required'),
+});
+export const getChunkContextSchema = z.object({
+    chunk_id: z.string().length(32, 'chunk_id must be a 32-character hex string'),
+    neighbor_span: z.number().min(0).max(5).optional(),
+    window: z.number().min(200).max(4000).optional(),
+});

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@etsquare/mcp-server-sec",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
-  "description": "MCP server for Claude Desktop: search 1.2M+ SEC filing sections with hybrid retrieval, XBRL templates, and company lookup.",
+  "description": "MCP server for Claude Desktop: search 3.4M+ SEC filing sections with hybrid retrieval, XBRL templates, and company lookup.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {