@etsquare/mcp-server-sec 0.7.0 → 0.7.2

package/dist/etsquare-client.d.ts

@@ -61,6 +61,21 @@ interface CompanyResearchApiInput {
     peers?: string[];
     n_periods?: number;
 }
+/** Ticker cohort resolver request. */
+interface ResolveTickerCohortApiInput {
+    question: string;
+    profile_code?: string;
+    boost_anchor_terms?: string[];
+    boost_topic_terms?: string[];
+    boost_negative_terms?: string[];
+    boost_positive_seeds?: string[];
+    boost_negative_seeds?: string[];
+    output_limit?: number;
+    semantic_mode?: 'auto' | 'off' | 'on';
+    grounding_context?: Record<string, unknown>;
+    ticker_cohort_candidate?: Record<string, unknown>;
+    response_mode?: 'full' | 'compact';
+}
 /** Server-side KPI query with metric filtering. */
 interface QueryKpisApiInput {
     select?: string[];
@@ -105,6 +120,7 @@ export declare class ETSquareClient {
     getEarningsActuals(input: EarningsActualsApiInput): Promise<Record<string, unknown>>;
     getKpiExtractions(input: KpiExtractionsApiInput): Promise<Record<string, unknown>>;
     getCompanyResearch(input: CompanyResearchApiInput): Promise<Record<string, unknown>>;
+    resolveTickerCohort(input: ResolveTickerCohortApiInput): 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

@@ -176,6 +176,37 @@ export class ETSquareClient {
             body: JSON.stringify(body),
         });
     }
+    async resolveTickerCohort(input) {
+        const body = {
+            question: input.question,
+            semantic_mode: input.semantic_mode || 'auto',
+        };
+        if (input.profile_code)
+            body.profile_code = input.profile_code;
+        if (input.boost_anchor_terms && input.boost_anchor_terms.length > 0)
+            body.boost_anchor_terms = input.boost_anchor_terms;
+        if (input.boost_topic_terms && input.boost_topic_terms.length > 0)
+            body.boost_topic_terms = input.boost_topic_terms;
+        if (input.boost_negative_terms && input.boost_negative_terms.length > 0)
+            body.boost_negative_terms = input.boost_negative_terms;
+        if (input.boost_positive_seeds && input.boost_positive_seeds.length > 0)
+            body.boost_positive_seeds = input.boost_positive_seeds;
+        if (input.boost_negative_seeds && input.boost_negative_seeds.length > 0)
+            body.boost_negative_seeds = input.boost_negative_seeds;
+        if (input.output_limit !== undefined)
+            body.output_limit = input.output_limit;
+        if (input.grounding_context)
+            body.grounding_context = input.grounding_context;
+        if (input.ticker_cohort_candidate)
+            body.ticker_cohort_candidate = input.ticker_cohort_candidate;
+        if (input.response_mode)
+            body.response_mode = input.response_mode;
+        return this.request('/api/v1/cohort/resolve', {
+            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.6.0
+ * @etsquare/mcp-server-sec  v0.7.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.6.0 starting with backend: ${baseUrl}`);
+log('info', `ETSquare MCP Server v0.7.0 starting with backend: ${baseUrl}`);
 // ─── Item Code Labels ───────────────────────────────────────────────────────
 const ITEM_CODE_LABELS = {
     // 10-K
@@ -358,7 +358,7 @@ function buildMarkdownTable(colNames, rows, maxRows = 20) {
 // ─── MCP Server ─────────────────────────────────────────────────────────────
 const server = new McpServer({
     name: 'etsquare-mcp-sec',
-    version: '0.6.0',
+    version: '0.7.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.';
@@ -410,11 +410,82 @@ server.registerTool('etsquare_lookup_company', {
         };
     }
 });
-// ─── Tool 2: SEC Filing Search ──────────────────────────────────────────────
+// ─── Tool 2: Resolve Ticker Cohort ──────────────────────────────────────────
+server.registerTool('etsquare_resolve_ticker_cohort', {
+    title: 'Resolve Ticker Cohort',
+    description: 'Resolve a natural-language question into a ranked ticker cohort using corpus-grounded terms. ' +
+        'Use this before precision search for INDUSTRY/MACRO workflows, then pass selected tickers to etsquare_search with scope_lock=COMPANY.',
+    inputSchema: {
+        question: z.string().min(3).max(500)
+            .describe('Natural-language cohort question (e.g., "public SaaS companies discussing AI pricing power").'),
+        profile_code: z.string().min(2).max(80).optional()
+            .describe('Optional curated profile code override.'),
+        boost_anchor_terms: z.array(z.string()).max(5).optional()
+            .describe('WHO anchor terms (industry/exposure/entity class).'),
+        boost_topic_terms: z.array(z.string()).max(5).optional()
+            .describe('WHAT topic terms (KPI/theme/impact).'),
+        boost_negative_terms: z.array(z.string()).max(5).optional()
+            .describe('Negative terms to suppress confusable cohorts.'),
+        boost_positive_seeds: z.array(z.string().min(1).max(10)).max(5).optional()
+            .describe('Manual positive seed tickers (MCP/manual only).'),
+        boost_negative_seeds: z.array(z.string().min(1).max(10)).max(5).optional()
+            .describe('Manual negative seed tickers (MCP/manual only).'),
+        output_limit: z.number().int().min(1).max(50).optional()
+            .describe('Output ticker count override.'),
+        semantic_mode: z.enum(['auto', 'off', 'on']).default('auto')
+            .describe('Semantic embedding mode for resolver matching.'),
+        response_mode: z.enum(['full', 'compact']).default('full')
+            .describe('Response verbosity. Use "compact" for a consumer-focused payload and "full" for trace-rich output.'),
+        grounding_context: z.record(z.unknown()).optional()
+            .describe('Optional pre-computed grounding context from upstream workflow.'),
+        ticker_cohort_candidate: z.record(z.unknown()).optional()
+            .describe('Workflow candidate payload translated into resolver fields before resolution.'),
+    },
+}, async (input) => {
+    if (containsGuardrailBypass(input))
+        return guardrailViolationResponse();
+    try {
+        log('debug', 'Resolving ticker cohort', {
+            question: input.question,
+            profile_code: input.profile_code,
+            output_limit: input.output_limit,
+            semantic_mode: input.semantic_mode,
+        });
+        const result = await client.resolveTickerCohort({
+            question: input.question,
+            profile_code: input.profile_code,
+            boost_anchor_terms: input.boost_anchor_terms,
+            boost_topic_terms: input.boost_topic_terms,
+            boost_negative_terms: input.boost_negative_terms,
+            boost_positive_seeds: input.boost_positive_seeds?.map((t) => t.trim().toUpperCase()),
+            boost_negative_seeds: input.boost_negative_seeds?.map((t) => t.trim().toUpperCase()),
+            output_limit: input.output_limit,
+            semantic_mode: input.semantic_mode,
+            response_mode: input.response_mode,
+            grounding_context: input.grounding_context,
+            ticker_cohort_candidate: input.ticker_cohort_candidate,
+        });
+        log('info', 'Ticker cohort resolved', {
+            cohort_code: result?.cohort_code,
+            profile_match_mode: result?.profile_match_mode,
+            ticker_count: Array.isArray(result?.tickers) ? result.tickers.length : 0,
+        });
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (error) {
+        log('error', 'Ticker cohort resolve failed', { error: error instanceof Error ? error.message : error });
+        return {
+            content: [{ type: 'text', text: `Ticker cohort resolution failed: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// ─── Tool 3: SEC Filing Search ──────────────────────────────────────────────
 server.registerTool('etsquare_search', {
     title: 'Search SEC Filings',
     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' +
+        'Predict literal filing text: draft queries using exact MD&A and Risk Factors disclosure phraseology ("revenue attributable to," "material adverse effect on," "growth driven by adoption of"), never casual topic labels or conceptual summaries.\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")'),
@@ -1865,4 +1936,4 @@ server.registerTool('etsquare_company_research', {
 // ─── Start Server ───────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);
-log('info', 'ETSquare MCP Server v0.6.0 ready and listening on stdio (15 tools)');
+log('info', 'ETSquare MCP Server v0.7.0 ready and listening on stdio (16 tools)');

package/package.json

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