@etsquare/mcp-server-sec 0.2.0 → 0.4.0

package/dist/etsquare-client.d.ts

@@ -2,7 +2,56 @@
  * 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 { LookupCompanyInput, GetChunkInput, GetChunkContextInput } from './types.js';
+/** Subset of SearchInput that the API v1 backend accepts (no MCP-layer fields). */
+interface SearchApiInput {
+    query: string;
+    mode_lock: 'NARRATIVE' | 'HYBRID';
+    scope_lock: 'COMPANY' | 'INDUSTRY' | 'MACRO';
+    top_k?: number;
+    tickers?: string[];
+    sic_codes?: string[];
+    sector?: string;
+    doc_types?: string[];
+}
+/** Subset of ExecuteMetricsInput that the API v1 backend accepts. */
+interface ExecuteMetricsApiInput {
+    template_id: string;
+    bind_params?: Record<string, unknown>;
+    row_limit?: number;
+}
+/** Financial statement request. */
+interface FinancialStatementApiInput {
+    ticker: string;
+    statement_type: 'income_statement' | 'balance_sheet' | 'cash_flow';
+    period_mode?: 'latest_annual' | 'latest_quarterly' | 'last_n_annual' | 'last_n_quarterly';
+    n_periods?: number;
+}
+/** Institutional holdings request. */
+interface InstitutionalHoldingsApiInput {
+    ticker: string;
+    quarters?: number;
+}
+/** Insider transactions request. */
+interface InsiderTransactionsApiInput {
+    ticker: string;
+    days_back?: number;
+    transaction_types?: string[];
+    include_derivatives?: boolean;
+}
+/** Earnings actuals & guidance request. */
+interface EarningsActualsApiInput {
+    ticker: string;
+    quarters?: number;
+    metrics?: string[];
+}
+/** Subset of DiscoverMetricsInput that the API v1 backend accepts. */
+interface DiscoverMetricsApiInput {
+    question: string;
+    scenario?: 'snapshot' | 'trends' | 'peer_benchmark';
+    metric_family?: string;
+    max_results?: number;
+}
 export interface ETSquareClientOptions {
     baseUrl: string;
     apiKey: string;
@@ -13,8 +62,17 @@ export declare class ETSquareClient {
     constructor(options: ETSquareClientOptions);
     private get headers();
     private handleResponse;
-    search(input: SearchInput): Promise<Record<string, unknown>>;
+    private request;
+    search(input: SearchApiInput): Promise<Record<string, unknown>>;
     lookupCompany(input: LookupCompanyInput): Promise<Record<string, unknown>>;
-    executeMetrics(input: ExecuteMetricsInput): Promise<Record<string, unknown>>;
-    discoverMetrics(input: DiscoverMetricsInput): Promise<Record<string, unknown>>;
+    executeMetrics(input: ExecuteMetricsApiInput): Promise<Record<string, unknown>>;
+    getFinancialStatement(input: FinancialStatementApiInput): Promise<Record<string, unknown>>;
+    getInstitutionalHoldings(input: InstitutionalHoldingsApiInput): Promise<Record<string, unknown>>;
+    getInsiderTransactions(input: InsiderTransactionsApiInput): Promise<Record<string, unknown>>;
+    getEarningsActuals(input: EarningsActualsApiInput): 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>>;
+    weeklyBrief(): Promise<Record<string, unknown>>;
 }
+export {};

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) {
@@ -28,6 +29,17 @@ export class ETSquareClient {
         }
         return (await res.json());
     }
+    async request(path, init) {
+        const url = `${this.baseUrl}${path}`;
+        try {
+            const res = await fetch(url, init);
+            return this.handleResponse(res);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`ETSquare API fetch failed (${url}): ${message}`);
+        }
+    }
     async search(input) {
         const body = {
             query: input.query,
@@ -41,23 +53,23 @@ export class ETSquareClient {
             body.tickers = input.tickers;
         if (input.sic_codes)
             body.sic_codes = input.sic_codes;
+        if (input.sector)
+            body.sector = input.sector;
         if (input.doc_types)
             body.doc_types = input.doc_types;
-        const res = await fetch(`${this.baseUrl}/api/v1/search`, {
+        return this.request('/api/v1/search', {
             method: 'POST',
             headers: this.headers,
             body: JSON.stringify(body),
         });
-        return this.handleResponse(res);
     }
     async lookupCompany(input) {
         const params = new URLSearchParams({ query: input.query });
         if (input.limit)
             params.set('limit', String(input.limit));
-        const res = await fetch(`${this.baseUrl}/api/v1/companies/lookup?${params}`, {
+        return this.request(`/api/v1/companies/lookup?${params}`, {
             headers: this.headers,
         });
-        return this.handleResponse(res);
     }
     async executeMetrics(input) {
         const body = {
@@ -66,12 +78,63 @@ export class ETSquareClient {
         };
         if (input.row_limit)
             body.row_limit = input.row_limit;
-        const res = await fetch(`${this.baseUrl}/api/v1/metrics/execute`, {
+        return this.request('/api/v1/metrics/execute', {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+    }
+    async getFinancialStatement(input) {
+        const body = {
+            ticker: input.ticker,
+            statement_type: input.statement_type,
+            period_mode: input.period_mode || 'last_n_annual',
+            n_periods: input.n_periods || 5,
+        };
+        return this.request('/api/v1/financials', {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+    }
+    async getInstitutionalHoldings(input) {
+        const body = {
+            ticker: input.ticker,
+            quarters: input.quarters || 2,
+        };
+        return this.request('/api/v1/institutional/holdings', {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+    }
+    async getInsiderTransactions(input) {
+        const body = {
+            ticker: input.ticker,
+            days_back: input.days_back || 90,
+        };
+        if (input.transaction_types)
+            body.transaction_types = input.transaction_types;
+        if (input.include_derivatives !== undefined)
+            body.include_derivatives = input.include_derivatives;
+        return this.request('/api/v1/insider/transactions', {
+            method: 'POST',
+            headers: this.headers,
+            body: JSON.stringify(body),
+        });
+    }
+    async getEarningsActuals(input) {
+        const body = {
+            ticker: input.ticker,
+            quarters: input.quarters || 4,
+        };
+        if (input.metrics)
+            body.metrics = input.metrics;
+        return this.request('/api/v1/earnings/actuals', {
             method: 'POST',
             headers: this.headers,
             body: JSON.stringify(body),
         });
-        return this.handleResponse(res);
     }
     async discoverMetrics(input) {
         const body = {
@@ -83,11 +146,33 @@ export class ETSquareClient {
             body.metric_family = input.metric_family;
         if (input.max_results)
             body.max_results = input.max_results;
-        const res = await fetch(`${this.baseUrl}/api/v1/metrics/discover`, {
+        return this.request('/api/v1/metrics/discover', {
             method: 'POST',
             headers: this.headers,
             body: JSON.stringify(body),
         });
-        return this.handleResponse(res);
+    }
+    async getChunk(input) {
+        const params = new URLSearchParams({ execution_id: input.execution_id });
+        return this.request(`/api/v1/chunk/${input.chunk_id}?${params}`, {
+            headers: this.headers,
+        });
+    }
+    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}` : '';
+        return this.request(`/api/v1/chunks/${input.chunk_id}/context${suffix}`, {
+            headers: this.headers,
+        });
+    }
+    async weeklyBrief() {
+        return this.request('/api/sec-intelligence/weekly-brief', {
+            headers: this.headers,
+        });
     }
 }