@etsquare/mcp-server-sec 0.6.2 → 0.7.0

package/dist/index.js

@@ -372,9 +372,7 @@ server.registerTool = ((name, config, handler) => {
 // ─── Tool 1: Company Lookup ─────────────────────────────────────────────────
 server.registerTool('etsquare_lookup_company', {
     title: 'Look Up Company Ticker',
-    description: 'Resolve a company name or partial ticker to its official SEC ticker symbol and CIK number. ' +
-        'Call this when a user mentions a company by name (e.g., "Apple" -> AAPL, "Texas Roadhouse" -> TXRH). ' +
-        'Returns ticker, company name, CIK, and SIC industry code.',
+    description: 'Resolve company name to ticker/CIK. Call before other tools when user gives a name, not a ticker.',
     inputSchema: {
         query: z.string().min(2).describe('Company name or partial ticker to look up (e.g., "Apple", "Texas Road", "NVDA")'),
         limit: z.number().min(1).max(10).default(5).describe('Max results to return'),
@@ -415,21 +413,13 @@ server.registerTool('etsquare_lookup_company', {
 // ─── Tool 2: SEC Filing Search ──────────────────────────────────────────────
 server.registerTool('etsquare_search', {
     title: 'Search SEC Filings',
-    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' +
-        '- scope_lock: COMPANY (specific tickers) | INDUSTRY (SIC sector) | MACRO (cross-market)\n\n' +
-        'For canonical financial statements (income statement, balance sheet, cash flow), use etsquare_financial_statements.\n' +
-        'For custom financial queries or peer comparisons, use etsquare_discover_metrics + etsquare_execute_metrics.\n\n' +
-        'For INDUSTRY scope, use sector to target a specific industry (e.g., sector="semiconductors"). ' +
-        'Use tickers to scope to specific companies (resolve names first with etsquare_lookup_company). ' +
-        'Results include filing text plus safe citation metadata such as chunk_id, accession number, and SEC URL for follow-up retrieval.\n\n' +
-        'Set response_format="structured" for typed JSON with search_context, layout hints, and chart-ready data.',
+    description: 'Search SEC filing text (10-K, 10-Q, 8-K). Returns verbatim excerpts with SEC URL citations.\n\n' +
+        'COMPANY + tickers = precision. INDUSTRY + sector = breadth. When precision matters, supply tickers.\n\n' +
+        'For financial statements use etsquare_financial_statements. For metrics use etsquare_discover_metrics.',
     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'),
-        scope_lock: z.enum(['COMPANY', 'INDUSTRY', 'MACRO']).describe('COMPANY for specific tickers, INDUSTRY for SIC sector-wide, MACRO for cross-market'),
+        scope_lock: z.enum(['COMPANY', 'INDUSTRY', 'MACRO']).describe('COMPANY = specific tickers (precision). INDUSTRY = sector-wide (breadth). MACRO = cross-market.'),
         top_k: z.number().min(1).max(50).default(5).describe('Number of results to return (default: 5)'),
         tickers: z.array(z.string()).optional().describe('Limit to specific companies by ticker (e.g., ["AAPL", "MSFT"])'),
         doc_types: z.array(z.string()).optional().describe('Limit by SEC form type: "10-k", "10-q", "8-k"'),
@@ -613,12 +603,8 @@ server.registerTool('etsquare_search', {
 // ─── Tool 3: Execute Metrics ────────────────────────────────────────────────
 server.registerTool('etsquare_financial_statements', {
     title: 'Get Financial Statements',
-    description: 'Get canonical income statement, balance sheet, or cash flow statement for a company. ' +
-        'Assembles structured line items from XBRL facts with concept precedence and provenance.\n\n' +
-        'Each line item includes the selected XBRL concept, priority rank, and unit for auditability.\n\n' +
-        'Coverage: ~5,100 tickers for income statement and cash flow. ' +
-        'Balance sheet coverage is limited for some companies pending XBRL pipeline enhancement.\n\n' +
-        'For custom financial queries or peer comparisons, use etsquare_discover_metrics + etsquare_execute_metrics instead.',
+    description: 'Canonical income statement, balance sheet, or cash flow from XBRL. ~5,100 tickers. ' +
+        'For custom queries or peer comparisons, use etsquare_discover_metrics instead.',
     inputSchema: {
         ticker: z.string().min(1).max(10).describe('Company ticker (e.g., "AAPL", "NVDA")'),
         statement_type: z.enum(['income_statement', 'balance_sheet', 'cash_flow'])
@@ -715,11 +701,7 @@ server.registerTool('etsquare_financial_statements', {
 });
 server.registerTool('etsquare_insider_trades', {
     title: 'Insider Trading Activity',
-    description: 'Get insider buying and selling activity for a company from SEC Form 3/4/5 filings. ' +
-        'Shows officer/director stock purchases, sales, option exercises, and tax withholdings.\n\n' +
-        'Data is sourced directly from SEC EDGAR ownership filings, filed within 2 business days of each transaction.\n\n' +
-        'Summary includes open-market buy/sell counts, net shares, and total values. ' +
-        'Derivative transactions (options, RSUs) are separated from open-market trades.',
+    description: 'Insider buy/sell activity from SEC Form 3/4/5. Open-market trades + derivatives (options, RSUs).',
     inputSchema: {
         ticker: z.string().min(1).max(10).describe('Company ticker (e.g., "AAPL", "NVDA")'),
         days_back: z.number().min(1).max(730).default(90)
@@ -797,12 +779,7 @@ server.registerTool('etsquare_insider_trades', {
 });
 server.registerTool('etsquare_institutional_holdings', {
     title: 'Institutional Ownership (13F)',
-    description: 'Get institutional investor holdings for a company from SEC 13F filings. ' +
-        'Shows tracked managers holding the stock, their position sizes, and portfolio concentration.\n\n' +
-        'Data is from tracked institutional managers (top filers by AUM). ' +
-        'Coverage is partial — not all institutional holders are tracked. ' +
-        'Multiple rows per manager may appear due to sub-manager reporting. ' +
-        'Source: SEC EDGAR 13F-HR filings, filed quarterly.',
+    description: 'Institutional holdings from SEC 13F filings. Position sizes, portfolio concentration, quarterly changes.',
     inputSchema: {
         ticker: z.string().min(1).max(10).describe('Company ticker (e.g., "NVDA", "AAPL")'),
         quarters: z.number().min(1).max(8).default(2)
@@ -893,14 +870,8 @@ server.registerTool('etsquare_institutional_holdings', {
 });
 server.registerTool('etsquare_earnings_actuals', {
     title: 'Earnings Actuals & Guidance',
-    description: 'Get issuer-reported earnings actuals and forward guidance for a company from SEC 8-K filings. ' +
-        'Extracts revenue, EPS (basic/diluted), and net income from Item 2.02 press releases.\n\n' +
-        'Values are deterministically extracted from exhibit press releases (EX-99.1) attached to 8-K filings. ' +
-        'Only explicit issuer-reported values are included — no analyst estimates or consensus.\n\n' +
-        'Guidance shows forward-looking ranges (low/high) when the issuer provides them.\n\n' +
-        'Coverage: ~1,900 tickers, most recent 1-2 quarters (Dec 2025 onward). ' +
-        'Historical depth is expanding — some tickers may have fewer quarters than requested.\n\n' +
-        'Source: SEC EDGAR 8-K Item 2.02 filings with attached press releases.',
+    description: 'Issuer-reported earnings actuals + guidance from 8-K press releases. Revenue, EPS, net income. ' +
+        'No analyst estimates — SEC filings only. ~1,900 tickers.',
     inputSchema: {
         ticker: z.string().min(1).max(10).describe('Company ticker (e.g., "AAPL", "NVDA")'),
         quarters: z.number().min(1).max(20).default(4)
@@ -1015,14 +986,8 @@ server.registerTool('etsquare_earnings_actuals', {
 });
 server.registerTool('etsquare_kpi_extractions', {
     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.',
+    description: 'Full KPI extraction with source_chunk_ids for provenance. Use etsquare_get_chunk to read the source filing text. ' +
+        'For tabular queries across many tickers, prefer etsquare_query_kpis.',
     inputSchema: {
         ticker: z.string().min(1).max(10).optional()
             .describe('Single ticker filter (e.g., "TXRH")'),
@@ -1137,20 +1102,9 @@ 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' +
+    description: 'Tabular KPI query with select/filter/sort. Returns values + YoY changes + summary stats.\n\n' +
+        'action="list_metrics" to discover available metrics for a sector, then action="query" with select/filter.\n\n' +
+        'Examples: select="arr,net_dollar_retention", sector="saas" | filter="net_interest_margin>3", sector="banks"\n' +
         'Use when a number looks surprising or needs management context.',
     inputSchema: {
         select: z.string().optional()
@@ -1316,12 +1270,8 @@ server.registerTool('etsquare_query_kpis', {
 });
 server.registerTool('etsquare_execute_metrics', {
     title: 'Execute Financial Metrics Query',
-    description: 'Execute an XBRL metrics template by template_id to get structured financial data ' +
-        '(numbers, ratios, time series). Returns tabular rows with columns like revenue, margins, EPS, etc.\n\n' +
-        'Common bind_params: p_tickers (comma-separated tickers), p_ticker (single ticker), p_sic_code (industry), ' +
-        'p_start_year / p_end_year (time range, e.g., 2023-2025).\n\n' +
-        'Use the tickers array to pass multiple companies — automatically joins as p_tickers comma-separated string.\n\n' +
-        'Set response_format="structured" for typed JSON with column metadata, visualization hints, and summary stats.',
+    description: 'Execute XBRL metrics template by template_id. Returns tabular financial data. ' +
+        'Use tickers array for multi-company. Common params: p_ticker, p_tickers, p_sic_code, p_start_year, p_end_year.',
     inputSchema: {
         template_id: z.string().min(10).describe('Template ID for metrics execution'),
         bind_params: z.record(z.unknown()).optional().describe('Template parameters as key-value pairs'),
@@ -1469,14 +1419,9 @@ server.registerTool('etsquare_execute_metrics', {
 // ─── Tool 4: Discover Metrics Templates ─────────────────────────────────────
 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.\n\n' +
-        'Set response_format="structured" for JSON with similarity scores and visualization hints.',
+    description: 'Find XBRL metrics templates by question. Returns template_id → use with etsquare_execute_metrics.\n\n' +
+        'For XBRL metrics (revenue, margins, EPS, debt, cash flow) only. ' +
+        'For narrative KPIs (comps, traffic, ARR), use etsquare_search or etsquare_query_kpis instead.',
     inputSchema: {
         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'),
@@ -1586,9 +1531,7 @@ server.registerTool('etsquare_discover_metrics', {
 // ─── Tool 5: Get Full Chunk 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.',
+    description: 'Fetch full chunk text when etsquare_search returned a truncated snippet.',
     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'),
@@ -1625,8 +1568,7 @@ server.registerTool('etsquare_get_chunk', {
 // ─── Tool 6: Get Chunk 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.',
+    description: 'Fetch chunk with surrounding paragraphs from the same filing section.',
     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'),
@@ -1686,11 +1628,8 @@ server.registerTool('etsquare_get_chunk_context', {
 // ─── Tool 7: Compare Companies ──────────────────────────────────────────────
 server.registerTool('etsquare_compare', {
     title: 'Compare Companies in SEC Filings',
-    description: 'Compare 2-5 companies across SEC filings in a single call. ' +
-        'Returns per-ticker results grouped for easy side-by-side analysis.\n\n' +
-        'Resolve company names to tickers first with etsquare_lookup_company.\n\n' +
-        'Use mode_lock=HYBRID to include both narrative text and structured metrics.\n\n' +
-        'Always returns structured JSON (comparison results are inherently structured).',
+    description: 'Compare 2-5 companies side-by-side across SEC filings. Returns per-ticker grouped results. ' +
+        'Use HYBRID mode for text + metrics together.',
     inputSchema: {
         tickers: z.array(z.string()).min(2).max(5)
             .describe('Company tickers to compare (2-5). Resolve names first with etsquare_lookup_company.'),
@@ -1790,10 +1729,7 @@ server.registerTool('etsquare_compare', {
 // ─── Tool 8: Weekly Brief ───────────────────────────────────────────────────
 server.registerTool('etsquare_weekly_brief', {
     title: 'Weekly SEC Filing Intelligence Brief',
-    description: 'Get the latest weekly SEC filing intelligence brief. ' +
-        'Returns notable 8-K events, edge signals (unusual filings), and sector heatmap. ' +
-        'Updated weekly. Great for market monitoring and identifying emerging risks.\n\n' +
-        'Default response_format is "structured" (full JSON). Use "text" for readable summary.',
+    description: 'Weekly SEC filing brief: notable 8-K events, edge signals, sector heatmap. Updated weekly.',
     inputSchema: {
         sections: z.array(z.enum(['notable', 'edge_signals', 'heatmap', 'methodology'])).optional()
             .describe('Filter to specific sections. Returns all if omitted.'),
@@ -1879,8 +1815,7 @@ 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.',
+    description: 'Full research packet for one company: financials, earnings, narrative, ownership, KPIs. Single call.',
     inputSchema: {
         ticker: z.string().min(1).max(10)
             .describe('Company ticker (e.g., "AAPL", "NVDA"). Resolve names first with etsquare_lookup_company.'),

package/package.json

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