@etsquare/mcp-server-sec 0.5.2 → 0.6.2

package/dist/etsquare-client.d.ts

@@ -53,6 +53,14 @@ 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[];
@@ -96,6 +104,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>>;
+    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>>;

package/dist/etsquare-client.js

@@ -158,6 +158,24 @@ 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,

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,16 @@ function buildMarkdownTable(colNames, rows, maxRows = 20) {
 // ─── MCP Server ─────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'etsquare-mcp-sec',
-    version: '0.3.0',
+    version: '0.6.0',
+});
+const CITATION_POLICY = 'Citation policy (required): When `cite: true` appears in the response, you MUST include ' +
+    'the sec_url for every filing referenced in the answer. Cite each URL inline with its claim.';
+const baseRegisterTool = server.registerTool.bind(server);
+server.registerTool = ((name, config, handler) => {
+    const description = typeof config?.description === 'string' && config.description.trim().length > 0
+        ? `${config.description}\n\n${CITATION_POLICY}`
+        : CITATION_POLICY;
+    return baseRegisterTool(name, { ...config, description }, handler);
 });
 // ─── Tool 1: Company Lookup ─────────────────────────────────────────────────
 server.registerTool('etsquare_lookup_company', {
@@ -406,7 +415,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' +
@@ -496,6 +505,7 @@ server.registerTool('etsquare_search', {
                 ? buildColumnMeta(result.xbrl_output_schema?.columns || [], xbrlMetrics)
                 : null;
             const structured = {
+                cite: true,
                 search_context: buildSearchContext(result, input.query),
                 results: searchResults
                     .slice(0, input.top_k || 5)
@@ -678,6 +688,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 +769,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 +863,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 +959,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 +986,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.*`;
@@ -1001,6 +1056,7 @@ server.registerTool('etsquare_kpi_extractions', {
                 content: [{
                         type: 'text',
                         text: JSON.stringify({
+                            cite: true,
                             count,
                             filters,
                             extractions,
@@ -1055,6 +1111,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`;
             }
@@ -1196,12 +1255,13 @@ server.registerTool('etsquare_query_kpis', {
             return {
                 content: [{
                         type: 'text',
-                        text: JSON.stringify({ count, data }, null, 2),
+                        text: JSON.stringify({ cite: true, count, data }, null, 2),
                     }],
             };
         }
-        // Build markdown table
-        const columns = Object.keys(data[0]);
+        // 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';
@@ -1219,6 +1279,18 @@ server.registerTool('etsquare_query_kpis', {
         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) {
@@ -1231,7 +1303,7 @@ server.registerTool('etsquare_query_kpis', {
             }
         }
         // 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.*';
+        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) {
@@ -1341,6 +1413,7 @@ server.registerTool('etsquare_execute_metrics', {
             const autoHint = deriveMetricsVizHint(rows, { columns: columnMeta });
             const colNames = columnMeta.map((c) => c.name);
             const structured = {
+                cite: true,
                 template_id: input.template_id,
                 columns: columnMeta,
                 rows,
@@ -1353,18 +1426,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}`,
                 }],
         };
     }
@@ -1513,10 +1603,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}`,
                 }],
         };
     }
@@ -1735,7 +1829,7 @@ server.registerTool('etsquare_weekly_brief', {
         // ── Structured response path ──
         if (input.response_format === 'structured') {
             log('info', `Weekly brief returned: ${(brief.notable || []).length} notable, ${(brief.edge_signals || []).length} edge signals`);
-            return { content: [{ type: 'text', text: JSON.stringify(output, null, 2) }] };
+            return { content: [{ type: 'text', text: JSON.stringify({ cite: true, ...output }, null, 2) }] };
         }
         // ── Text response path ──
         const lines = [];
@@ -1782,7 +1876,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.2",
+  "version": "0.6.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",