@etsquare/mcp-server-sec 0.2.1 → 0.5.0

package/dist/etsquare-client.d.ts

@@ -2,7 +2,64 @@
  * ETSquare SEC Intelligence API client.
  * Wraps /api/v1/* endpoints with X-API-Key authentication.
  */
-import type { SearchInput, LookupCompanyInput, ExecuteMetricsInput, DiscoverMetricsInput, GetChunkInput, GetChunkContextInput } 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[];
+}
+/** Stored KPI extractions request. */
+interface KpiExtractionsApiInput {
+    ticker?: string;
+    sector?: string;
+    sic_code?: string;
+    fiscal_year?: number;
+    limit?: number;
+}
+/** 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,10 +70,18 @@ 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>>;
+    getKpiExtractions(input: KpiExtractionsApiInput): 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

@@ -29,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,
@@ -42,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 = {
@@ -67,12 +78,81 @@ 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),
+        });
+    }
+    async getKpiExtractions(input) {
+        const body = {
+            limit: input.limit || 50,
+        };
+        if (input.ticker)
+            body.ticker = input.ticker;
+        if (input.sector)
+            body.sector = input.sector;
+        if (input.sic_code)
+            body.sic_code = input.sic_code;
+        if (input.fiscal_year !== undefined)
+            body.fiscal_year = input.fiscal_year;
+        return this.request('/api/v1/kpis', {
             method: 'POST',
             headers: this.headers,
             body: JSON.stringify(body),
         });
-        return this.handleResponse(res);
     }
     async discoverMetrics(input) {
         const body = {
@@ -84,19 +164,17 @@ 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 });
-        const res = await fetch(`${this.baseUrl}/api/v1/chunk/${input.chunk_id}?${params}`, {
+        return this.request(`/api/v1/chunk/${input.chunk_id}?${params}`, {
             headers: this.headers,
         });
-        return this.handleResponse(res);
     }
     async getChunkContext(input) {
         const params = new URLSearchParams();
@@ -106,9 +184,13 @@ export class ETSquareClient {
             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}`, {
+        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,
         });
-        return this.handleResponse(res);
     }
 }