@cyanheads/secedgar-mcp-server 0.4.4 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1>@cyanheads/secedgar-mcp-server</h1>
   <p><b>Query SEC EDGAR filings, XBRL financials, and company data through MCP. STDIO & Streamable HTTP.</b>
-  <div>6 Tools • 2 Resources • 1 Prompt</div>
+  <div>8 Tools (+1 opt-in) • 2 Resources • 1 Prompt</div>
   </p>
 </div>
 
@@ -23,7 +23,7 @@
 
 ## Tools
 
-Six tools for querying SEC EDGAR data:
+Six tools for querying SEC EDGAR data, plus three for SQL analytics over the DuckDB-backed canvas dataframes those tools materialize:
 
 | Tool | Description |
 |:---|:---|
@@ -31,8 +31,11 @@ Six tools for querying SEC EDGAR data:
 | `secedgar_search_filings` | Full-text search across all EDGAR filing documents since 1993 |
 | `secedgar_get_filing` | Fetch a specific filing's metadata and document content |
 | `secedgar_get_financials` | Get historical XBRL financial data for a company |
-| `secedgar_compare_metric` | Compare a financial metric across all reporting companies |
+| `secedgar_fetch_frames` | Fetch SEC XBRL frames for one concept × one period across all reporting companies |
 | `secedgar_search_concepts` | Discover supported XBRL concept names or reverse-lookup a raw tag |
+| `secedgar_dataframe_describe` | List canvas dataframes with provenance, TTL, and schema |
+| `secedgar_dataframe_query` | Run a single-statement SELECT across dataframes |
+| `secedgar_dataframe_drop` | Drop a canvas dataframe by name. Opt-in via `EDGAR_DATAFRAME_DROP_ENABLED=true` — off by default since TTL already handles cleanup |
 
 ### `secedgar_company_search`
 
@@ -52,6 +55,7 @@ Full-text search across all EDGAR filing documents since 1993.
 - Entity targeting within query string (`cik:320193` or `ticker:AAPL`)
 - Date range filtering, form type filtering, pagination up to 10,000 results
 - Returns form distribution for narrowing follow-up searches
+- When post-filter hits exceed the inline limit, the already-fetched EFTS window (entity-filtered when `ticker:`/`cik:` is used) is materialized as a `df_<id>` dataframe — query it with `secedgar_dataframe_query`
 
 ---
 
@@ -78,14 +82,14 @@ Get historical XBRL financial data for a company with friendly concept name reso
 
 ---
 
-### `secedgar_compare_metric`
+### `secedgar_fetch_frames`
 
-Compare a financial metric across all reporting companies for a specific period.
+Fetch SEC XBRL frames for one concept × one period across all reporting companies.
 
 - Same friendly concept names as `secedgar_get_financials`
 - Supports annual (`CY2023`), quarterly (`CY2024Q2`), and instant (`CY2023Q4I`) periods
-- Sorted ranking with configurable limit and direction
-- Enriches results with ticker symbols where available
+- Inline response returns the top N ranked companies (sort + limit), with ticker enrichment
+- The full frames response (all reporters, typically 2k–10k rows) is materialized as a `df_<id>` dataframe — query it with `secedgar_dataframe_query`
 
 ---
 
@@ -96,7 +100,17 @@ Discover supported XBRL concept names before querying financials or cross-compan
 - Search by friendly name, label, or raw XBRL tag
 - Filter by statement group (`income_statement`, `balance_sheet`, `cash_flow`, `per_share`, `entity_info`) or taxonomy
 - Reverse-lookup raw tags like `NetIncomeLoss` to the supported friendly names
-- Returns the same catalog used by `secedgar_get_financials`, `secedgar_compare_metric`, and `secedgar://concepts`
+- Returns the same catalog used by `secedgar_get_financials`, `secedgar_fetch_frames`, and `secedgar://concepts`
+
+---
+
+### `secedgar_dataframe_describe` / `secedgar_dataframe_query` / `secedgar_dataframe_drop`
+
+In-conversation SQL analytics over the dataframes that `secedgar_fetch_frames`, `secedgar_search_filings`, and `secedgar_get_financials` materialize on a shared DuckDB-backed canvas. Each data-returning call adds a `dataset` field with a `df_XXXXX_XXXXX` handle; pass that handle to `secedgar_dataframe_query` for joins, aggregates, window functions, percentiles — standard DuckDB SQL.
+
+- **Read-only by default.** Writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected by the framework SQL gate. System catalogs (`information_schema`, `pg_catalog`, `sqlite_master`, `duckdb_*`) are denied at the bridge layer so callers can't enumerate dataframes they don't already hold a handle for. `secedgar_dataframe_drop` is the only destructive tool and is opt-in (`EDGAR_DATAFRAME_DROP_ENABLED=true`); TTL handles cleanup otherwise.
+- **Per-table TTL.** Each dataframe ages on its own clock (default 24h, override with `EDGAR_DATASET_TTL_SECONDS`). The canvas itself uses the framework's sliding TTL.
+- **`register_as` chaining.** `secedgar_dataframe_query` can persist its result as a new dataframe (`df_XXXXX_XXXXX`) with a fresh TTL — pipe analyses without re-running the source query.
 
 ## Resources
 
@@ -129,6 +143,7 @@ SEC EDGAR–specific:
 - Friendly XBRL concept name mapping with historical tag change handling
 - Searchable concept catalog with statement-group metadata and reverse XBRL tag lookup
 - HTML-to-text conversion for filing documents via `html-to-text`
+- In-conversation SQL analytics: `secedgar_fetch_frames`, `secedgar_search_filings`, and `secedgar_get_financials` materialize their full upstream response as a DuckDB-backed canvas dataframe queryable via `secedgar_dataframe_query`
 - No API keys required — SEC EDGAR is a free, public API
 
 ## Getting started
@@ -232,6 +247,9 @@ All configuration is validated at startup via Zod schemas in `src/config/server-
 | `EDGAR_USER_AGENT` | **Required.** User-Agent header for SEC compliance. Format: `"AppName contact@email.com"`. SEC blocks IPs without a valid User-Agent. | — |
 | `EDGAR_RATE_LIMIT_RPS` | Max requests/second to SEC APIs. Do not exceed 10. | `10` |
 | `EDGAR_TICKER_CACHE_TTL` | Seconds to cache the company tickers lookup file. | `3600` |
+| `EDGAR_DATASET_TTL_SECONDS` | Per-table TTL for canvas-registered dataframes. Sliding window touched on every dataframe op. | `86400` |
+| `EDGAR_DATAFRAME_DROP_ENABLED` | Set to `true` to expose `secedgar_dataframe_drop` — the only destructive tool on this server. Off by default; TTL handles cleanup. | `false` |
+| `CANVAS_PROVIDER_TYPE` | Canvas engine. Defaults to `duckdb`; set to `none` to disable the canvas (e.g. when running on Cloudflare Workers, where DuckDB has no V8-isolate build). | `duckdb` |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |
 | `MCP_HTTP_PORT` | HTTP server port | `3010` |
 | `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |
@@ -266,10 +284,11 @@ docker run -e EDGAR_USER_AGENT="MyApp my@email.com" -p 3010:3010 secedgar-mcp-se
 
 | Directory | Purpose |
 |:---|:---|
-| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). Six SEC EDGAR tools. |
+| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). Six SEC EDGAR tools plus three `dataframe_*` tools for SQL analytics. |
 | `src/mcp-server/resources/definitions/` | Resource definitions. XBRL concepts and filing types. |
 | `src/mcp-server/prompts/definitions/` | Prompt definitions. Company analysis prompt. |
 | `src/services/edgar/` | SEC EDGAR API client, XBRL concept mapping, HTML-to-text conversion. |
+| `src/services/canvas-bridge/` | Adapter over the framework `DataCanvas`: `df_<id>` minting, all-nullable schema derivation, per-table TTL bookkeeping, bridge-layer system-catalog SQL deny. |
 | `src/config/` | Server-specific environment variable parsing and validation with Zod. |
 | `tests/` | Unit and integration tests, mirroring the `src/` structure. |
 

package/dist/config/server-config.d.ts

@@ -7,6 +7,8 @@ declare const ServerConfigSchema: z.ZodObject<{
     userAgent: z.ZodString;
     rateLimitRps: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     tickerCacheTtl: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    datasetTtlSeconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    dataframeDropEnabled: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean, string | undefined>>;
 }, z.core.$strip>;
 export type ServerConfig = z.infer<typeof ServerConfigSchema>;
 export declare function getServerConfig(): ServerConfig;

package/dist/config/server-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,QAAA,MAAM,kBAAkB;;;;iBAiBtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAO9C"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,QAAA,MAAM,kBAAkB;;;;;;iBAgCtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAS9C"}

package/dist/config/server-config.js

@@ -20,6 +20,17 @@ const ServerConfigSchema = z.object({
         .min(60)
         .default(3600)
         .describe('Seconds to cache company_tickers.json'),
+    datasetTtlSeconds: z.coerce
+        .number()
+        .int()
+        .min(60)
+        .default(86400)
+        .describe('Per-table TTL for canvas-registered dataframes, in seconds. Bridge-side bookkeeping in ctx.state (backstop for cyanheads/mcp-ts-core#140 until the framework exposes RegisterTableOptions.ttlMs).'),
+    dataframeDropEnabled: z
+        .string()
+        .optional()
+        .transform((v) => v === 'true' || v === '1')
+        .describe('Set to "true" to expose secedgar_dataframe_drop. Off by default — the canvas already drops tables on the per-table TTL, and a write surface against the shared canvas is the only destructive tool on this server.'),
 });
 let _config;
 export function getServerConfig() {
@@ -27,6 +38,8 @@ export function getServerConfig() {
         userAgent: process.env.EDGAR_USER_AGENT,
         rateLimitRps: process.env.EDGAR_RATE_LIMIT_RPS,
         tickerCacheTtl: process.env.EDGAR_TICKER_CACHE_TTL,
+        datasetTtlSeconds: process.env.EDGAR_DATASET_TTL_SECONDS,
+        dataframeDropEnabled: process.env.EDGAR_DATAFRAME_DROP_ENABLED,
     });
     return _config;
 }

package/dist/config/server-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,CAAC,2EAA2E,CAAC;IACxF,YAAY,EAAE,CAAC,CAAC,MAAM;SACnB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,iCAAiC,CAAC;IAC9C,cAAc,EAAE,CAAC,CAAC,MAAM;SACrB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,uCAAuC,CAAC;CACrD,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,kBAAkB,CAAC,KAAK,CAAC;QACnC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;QACvC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;QAC9C,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB;KACnD,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,CAAC,2EAA2E,CAAC;IACxF,YAAY,EAAE,CAAC,CAAC,MAAM;SACnB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,iCAAiC,CAAC;IAC9C,cAAc,EAAE,CAAC,CAAC,MAAM;SACrB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,uCAAuC,CAAC;IACpD,iBAAiB,EAAE,CAAC,CAAC,MAAM;SACxB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,mMAAmM,CACpM;IACH,oBAAoB,EAAE,CAAC;SACpB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG,CAAC;SAC3C,QAAQ,CACP,oNAAoN,CACrN;CACJ,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,kBAAkB,CAAC,KAAK,CAAC;QACnC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;QACvC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB;QAC9C,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB;QAClD,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,yBAAyB;QACxD,oBAAoB,EAAE,OAAO,CAAC,GAAG,CAAC,4BAA4B;KAC/D,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.js

@@ -4,29 +4,48 @@
  * @module index
  */
 import { createApp } from '@cyanheads/mcp-ts-core';
+import { getServerConfig } from './config/server-config.js';
 import { companyAnalysisPrompt } from './mcp-server/prompts/definitions/company-analysis.prompt.js';
 import { conceptsResource } from './mcp-server/resources/definitions/concepts.resource.js';
 import { filingTypesResource } from './mcp-server/resources/definitions/filing-types.resource.js';
 import { companySearchTool } from './mcp-server/tools/definitions/company-search.tool.js';
-import { compareMetricTool } from './mcp-server/tools/definitions/compare-metric.tool.js';
+import { dataframeDescribeTool } from './mcp-server/tools/definitions/dataframe-describe.tool.js';
+import { dataframeDropTool } from './mcp-server/tools/definitions/dataframe-drop.tool.js';
+import { dataframeQueryTool } from './mcp-server/tools/definitions/dataframe-query.tool.js';
+import { fetchFramesTool } from './mcp-server/tools/definitions/fetch-frames.tool.js';
 import { getFilingTool } from './mcp-server/tools/definitions/get-filing.tool.js';
 import { getFinancialsTool } from './mcp-server/tools/definitions/get-financials.tool.js';
 import { searchConceptsTool } from './mcp-server/tools/definitions/search-concepts.tool.js';
 import { searchFilingsTool } from './mcp-server/tools/definitions/search-filings.tool.js';
+import { initCanvasBridge } from './services/canvas-bridge/canvas-bridge.js';
 import { initEdgarApiService } from './services/edgar/edgar-api-service.js';
+// DuckDB is the only canvas engine we support and ships as a direct dep, so
+// enable the canvas by default. Set CANVAS_PROVIDER_TYPE=none explicitly to
+// turn it off (e.g. on Cloudflare Workers, where DuckDB has no V8-isolate
+// build and the framework would fail to construct a canvas anyway).
+process.env.CANVAS_PROVIDER_TYPE ??= 'duckdb';
+// secedgar_dataframe_drop is the only destructive tool on this server and is
+// off by default — TTL handles cleanup. Set EDGAR_DATAFRAME_DROP_ENABLED=true
+// to expose it.
+const dropEnabled = getServerConfig().dataframeDropEnabled;
 await createApp({
     tools: [
         companySearchTool,
         searchFilingsTool,
         getFilingTool,
         getFinancialsTool,
-        compareMetricTool,
+        fetchFramesTool,
         searchConceptsTool,
+        dataframeDescribeTool,
+        dataframeQueryTool,
+        ...(dropEnabled ? [dataframeDropTool] : []),
     ],
     resources: [conceptsResource, filingTypesResource],
     prompts: [companyAnalysisPrompt],
-    setup() {
+    instructions: 'Use the secedgar_* tools to query SEC EDGAR — US public-company filings since 1993 plus historical XBRL financials. Resolve companies with secedgar_company_search (accepts ticker, name, or CIK), fetch document text with secedgar_get_filing by accession number, and run full-text search across all filings with secedgar_search_filings (supports boolean operators and inline ticker:AAPL / cik:320193 targeting). For financials, secedgar_get_financials and secedgar_fetch_frames accept friendly names like "revenue" or "eps_diluted" (discover them with secedgar_search_concepts) or raw XBRL tags. Data-returning tools also materialize their full upstream response as a df_<id> handle for downstream SQL via secedgar_dataframe_query — list dataframes with secedgar_dataframe_describe.',
+    setup(core) {
         initEdgarApiService();
+        initCanvasBridge(core.canvas);
     },
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,6DAA6D,CAAC;AACpG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yDAAyD,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,mDAAmD,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAE5E,MAAM,SAAS,CAAC;IACd,KAAK,EAAE;QACL,iBAAiB;QACjB,iBAAiB;QACjB,aAAa;QACb,iBAAiB;QACjB,iBAAiB;QACjB,kBAAkB;KACnB;IACD,SAAS,EAAE,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;IAClD,OAAO,EAAE,CAAC,qBAAqB,CAAC;IAChC,KAAK;QACH,mBAAmB,EAAE,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,6DAA6D,CAAC;AACpG,OAAO,EAAE,gBAAgB,EAAE,MAAM,yDAAyD,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,6DAA6D,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,qBAAqB,EAAE,MAAM,2DAA2D,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,MAAM,qDAAqD,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,mDAAmD,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAC7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAE5E,4EAA4E;AAC5E,4EAA4E;AAC5E,0EAA0E;AAC1E,oEAAoE;AACpE,OAAO,CAAC,GAAG,CAAC,oBAAoB,KAAK,QAAQ,CAAC;AAE9C,6EAA6E;AAC7E,8EAA8E;AAC9E,gBAAgB;AAChB,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC,oBAAoB,CAAC;AAE3D,MAAM,SAAS,CAAC;IACd,KAAK,EAAE;QACL,iBAAiB;QACjB,iBAAiB;QACjB,aAAa;QACb,iBAAiB;QACjB,eAAe;QACf,kBAAkB;QAClB,qBAAqB;QACrB,kBAAkB;QAClB,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C;IACD,SAAS,EAAE,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;IAClD,OAAO,EAAE,CAAC,qBAAqB,CAAC;IAChC,YAAY,EACV,8wBAA8wB;IAChxB,KAAK,CAAC,IAAI;QACR,mBAAmB,EAAE,CAAC;QACtB,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview List the dataframes materialized by SEC EDGAR data-returning
+ * tools, with provenance, TTL, and column schema. Reads from the canvas
+ * bridge (which lazy-sweeps expired tables before responding).
+ * @module mcp-server/tools/definitions/dataframe-describe
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const dataframeDescribeTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    dataframes: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        source_tool: z.ZodString;
+        query_params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        created_at: z.ZodString;
+        expires_at: z.ZodString;
+        row_count: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        max_rows: z.ZodOptional<z.ZodNumber>;
+        column_schema: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            nullable: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "canvas_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The DataCanvas service is not configured for this deployment";
+    readonly recovery: "Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.";
+}]>;
+//# sourceMappingURL=dataframe-describe.tool.d.ts.map

package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataframe-describe.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/dataframe-describe.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;GAmHhC,CAAC"}

package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview List the dataframes materialized by SEC EDGAR data-returning
+ * tools, with provenance, TTL, and column schema. Reads from the canvas
+ * bridge (which lazy-sweeps expired tables before responding).
+ * @module mcp-server/tools/definitions/dataframe-describe
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getCanvasBridge } from '../../../services/canvas-bridge/canvas-bridge.js';
+export const dataframeDescribeTool = tool('secedgar_dataframe_describe', {
+    description: 'List dataframes (df_XXXXX_XXXXX) materialized by secedgar_fetch_frames, secedgar_search_filings, and secedgar_get_financials. Each entry surfaces source tool, query parameters, creation/expiry timestamps, row count, column schema, and whether the dataframe is truncated relative to the upstream source.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    errors: [
+        {
+            reason: 'canvas_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'The DataCanvas service is not configured for this deployment',
+            recovery: 'Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.',
+        },
+    ],
+    input: z.object({
+        name: z
+            .string()
+            .optional()
+            .describe('Optional table name (df_XXXXX_XXXXX) to describe a single dataframe. Omit to list all dataframes.'),
+    }),
+    output: z.object({
+        dataframes: z
+            .array(z
+            .object({
+            name: z.string().describe('Canvas table name (df_XXXXX_XXXXX).'),
+            source_tool: z.string().describe('Tool that produced this dataframe.'),
+            query_params: z
+                .record(z.string(), z.unknown())
+                .describe('Input parameters the source tool was called with.'),
+            created_at: z.string().describe('ISO 8601 creation timestamp.'),
+            expires_at: z
+                .string()
+                .describe('ISO 8601 expiry timestamp. Sliding TTL touched on every dataframe op.'),
+            row_count: z.number().describe('Rows materialized in the dataframe.'),
+            truncated: z
+                .boolean()
+                .describe('True when the upstream source had more rows than were materialized.'),
+            max_rows: z
+                .number()
+                .optional()
+                .describe('Materialization cap that produced `truncated`, when applicable.'),
+            column_schema: z
+                .array(z
+                .object({
+                name: z.string().describe('Column name.'),
+                type: z.string().describe('Canvas column type (VARCHAR, BIGINT, DOUBLE, ...).'),
+                nullable: z.boolean().describe('Whether the column permits NULL.'),
+            })
+                .describe('One column declaration in the dataframe schema.'))
+                .describe('Resolved column schema (all SEC dataframe columns are nullable).'),
+        })
+            .describe('Provenance and schema for one dataframe.'))
+            .describe('Active dataframes for this tenant, newest first. Empty when none are registered.'),
+    }),
+    async handler(input, ctx) {
+        const bridge = getCanvasBridge();
+        if (!bridge) {
+            throw ctx.fail('canvas_unavailable', 'DataCanvas is not configured on this server.', {
+                ...ctx.recoveryFor('canvas_unavailable'),
+            });
+        }
+        const entries = await bridge.describe(ctx, input.name);
+        return {
+            dataframes: entries.map((meta) => ({
+                name: meta.tableName,
+                source_tool: meta.sourceTool,
+                query_params: meta.queryParams,
+                created_at: meta.createdAt,
+                expires_at: meta.expiresAt,
+                row_count: meta.rowCount,
+                truncated: meta.truncated,
+                max_rows: meta.maxRows,
+                column_schema: meta.columnSchema.map((c) => ({
+                    name: c.name,
+                    type: c.type,
+                    nullable: c.nullable ?? true,
+                })),
+            })),
+        };
+    },
+    format: (result) => {
+        if (result.dataframes.length === 0) {
+            return [{ type: 'text', text: 'No active dataframes.' }];
+        }
+        const lines = [`**${result.dataframes.length} active dataframe(s):**\n`];
+        for (const df of result.dataframes) {
+            const truncated = df.truncated
+                ? ` (truncated${df.max_rows ? ` at ${df.max_rows}` : ''})`
+                : '';
+            lines.push(`### ${df.name}`);
+            lines.push(`- Source: ${df.source_tool}`);
+            lines.push(`- Rows: ${df.row_count}${truncated}`);
+            lines.push(`- Created: ${df.created_at} — Expires: ${df.expires_at}`);
+            const params = Object.entries(df.query_params)
+                .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+                .join(', ');
+            if (params)
+                lines.push(`- Params: ${params}`);
+            const cols = df.column_schema
+                .map((c) => `${c.name}:${c.type} (nullable=${c.nullable})`)
+                .join(', ');
+            lines.push(`- Columns: ${cols}`);
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n').trimEnd() }];
+    },
+});
+//# sourceMappingURL=dataframe-describe.tool.js.map

package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataframe-describe.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/dataframe-describe.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/dataframe-drop.tool.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Drop a canvas dataframe by name. Idempotent — removes the
+ * canvas table and the bridge-side provenance entry; returns whether anything
+ * was found and removed.
+ * @module mcp-server/tools/definitions/dataframe-drop
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const dataframeDropTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    name: z.ZodString;
+    dropped: z.ZodBoolean;
+}, z.core.$strip>, readonly [{
+    readonly reason: "canvas_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The DataCanvas service is not configured for this deployment";
+    readonly recovery: "Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.";
+}]>;
+//# sourceMappingURL=dataframe-drop.tool.d.ts.map

package/dist/mcp-server/tools/definitions/dataframe-drop.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataframe-drop.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/dataframe-drop.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,iBAAiB;;;;;;;;;;GA2C5B,CAAC"}

package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Drop a canvas dataframe by name. Idempotent — removes the
+ * canvas table and the bridge-side provenance entry; returns whether anything
+ * was found and removed.
+ * @module mcp-server/tools/definitions/dataframe-drop
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getCanvasBridge } from '../../../services/canvas-bridge/canvas-bridge.js';
+export const dataframeDropTool = tool('secedgar_dataframe_drop', {
+    description: 'Drop a canvas dataframe by name. Idempotent — returns dropped=false when nothing matched. Use to free canvas resources ahead of the per-table TTL when an analysis is complete.',
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false },
+    errors: [
+        {
+            reason: 'canvas_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'The DataCanvas service is not configured for this deployment',
+            recovery: 'Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.',
+        },
+    ],
+    input: z.object({
+        name: z.string().min(1).describe('Canvas table name (df_XXXXX_XXXXX) to drop.'),
+    }),
+    output: z.object({
+        name: z.string().describe('Name that was requested for drop.'),
+        dropped: z
+            .boolean()
+            .describe('True when the dataframe existed and was removed; false when nothing matched.'),
+    }),
+    async handler(input, ctx) {
+        const bridge = getCanvasBridge();
+        if (!bridge) {
+            throw ctx.fail('canvas_unavailable', 'DataCanvas is not configured on this server.', {
+                ...ctx.recoveryFor('canvas_unavailable'),
+            });
+        }
+        const dropped = await bridge.drop(ctx, input.name);
+        ctx.log.info('Dataframe drop requested', { name: input.name, dropped });
+        return { name: input.name, dropped };
+    },
+    format: (result) => [
+        {
+            type: 'text',
+            text: result.dropped ? `Dropped ${result.name}.` : `${result.name} not found.`,
+        },
+    ],
+});
+//# sourceMappingURL=dataframe-drop.tool.js.map

package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataframe-drop.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/dataframe-drop.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAE5E,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,yBAAyB,EAAE;IAC/D,WAAW,EACT,iLAAiL;IACnL,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAEhF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,oBAAoB;YAC5B,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,8DAA8D;YACpE,QAAQ,EAAE,iFAAiF;SAC5F;KACF;IAED,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,6CAA6C,CAAC;KAChF,CAAC;IAEF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;QAC9D,OAAO,EAAE,CAAC;aACP,OAAO,EAAE;aACT,QAAQ,CAAC,8EAA8E,CAAC;KAC5F,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,GAAG,CAAC,IAAI,CAAC,oBAAoB,EAAE,8CAA8C,EAAE;gBACnF,GAAG,GAAG,CAAC,WAAW,CAAC,oBAAoB,CAAC;aACzC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACnD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACxE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC;QAClB;YACE,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,aAAa;SAC/E;KACF;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Run a single-statement SELECT against the canvas dataframes
+ * registered by SEC EDGAR data-returning tools. Layered SQL gate: framework
+ * (single-statement → SELECT only → plan-walk allowlist + denied table
+ * functions) plus a bridge-layer deny on DuckDB system catalogs
+ * (information_schema, pg_catalog, sqlite_master, duckdb_*) so callers cannot
+ * enumerate every df_<id> on the shared canvas.
+ * @module mcp-server/tools/definitions/dataframe-query
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const dataframeQueryTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    sql: z.ZodString;
+    register_as: z.ZodOptional<z.ZodString>;
+    preview: z.ZodOptional<z.ZodNumber>;
+    row_limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    columns: z.ZodArray<z.ZodString>;
+    row_count: z.ZodNumber;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    registered_as: z.ZodOptional<z.ZodString>;
+    expires_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "canvas_unavailable";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "The DataCanvas service is not configured for this deployment";
+    readonly recovery: "Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.";
+}]>;
+//# sourceMappingURL=dataframe-query.tool.d.ts.map

package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataframe-query.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/dataframe-query.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;GAiI7B,CAAC"}

package/dist/mcp-server/tools/definitions/dataframe-query.tool.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Run a single-statement SELECT against the canvas dataframes
+ * registered by SEC EDGAR data-returning tools. Layered SQL gate: framework
+ * (single-statement → SELECT only → plan-walk allowlist + denied table
+ * functions) plus a bridge-layer deny on DuckDB system catalogs
+ * (information_schema, pg_catalog, sqlite_master, duckdb_*) so callers cannot
+ * enumerate every df_<id> on the shared canvas.
+ * @module mcp-server/tools/definitions/dataframe-query
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getCanvasBridge } from '../../../services/canvas-bridge/canvas-bridge.js';
+export const dataframeQueryTool = tool('secedgar_dataframe_query', {
+    description: 'Run a single-statement SELECT against the canvas dataframes registered by secedgar_fetch_frames, secedgar_search_filings, and secedgar_get_financials. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied at the bridge layer — list dataframes via secedgar_dataframe_describe. Optional register_as chains the result as a new dataframe with a fresh TTL.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    errors: [
+        {
+            reason: 'canvas_unavailable',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'The DataCanvas service is not configured for this deployment',
+            recovery: 'Set CANVAS_PROVIDER_TYPE=duckdb in the server environment to enable dataframes.',
+        },
+    ],
+    input: z.object({
+        sql: z
+            .string()
+            .min(1)
+            .describe('Single-statement SELECT against df_<id> tables on the shared canvas. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the names returned in fetch/search responses or listed by secedgar_dataframe_describe. BIGINT columns (e.g., XBRL `value`, COUNT/SUM results) serialize as JSON strings to preserve precision past 2^53 — CAST(col AS DOUBLE) in projections for inline arithmetic.'),
+        register_as: z
+            .string()
+            .optional()
+            .describe('When set, persist the result as a new dataframe under this name (must match df_XXXXX_XXXXX shape, or pass a fresh df_<id> generated by the agent). Fresh TTL window — not inherited from the parents in the SELECT. Use to chain analyses without re-running the source SQL.'),
+        preview: z
+            .number()
+            .int()
+            .min(0)
+            .max(10000)
+            .optional()
+            .describe('Rows to include in the immediate response. Defaults to the row limit. Set lower (e.g., 50) when chaining via register_as and only a sample is needed inline.'),
+        row_limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(10000)
+            .default(1000)
+            .describe('Hard cap on rows materialized in the response. Default 1000, max 10000. The full result lives on-canvas under register_as when provided — do not raise this to keep large results.'),
+    }),
+    output: z.object({
+        columns: z.array(z.string()).describe('Column names in projection order.'),
+        row_count: z
+            .number()
+            .describe('Total rows the query produced (may exceed `rows.length` when capped).'),
+        rows: z
+            .array(z.record(z.string(), z.unknown()))
+            .describe('Materialized rows, bounded by `preview` / `row_limit`.'),
+        registered_as: z
+            .string()
+            .optional()
+            .describe('Set when `register_as` was supplied and the new dataframe was materialized.'),
+        expires_at: z
+            .string()
+            .optional()
+            .describe('ISO 8601 expiry timestamp for the newly registered dataframe, when applicable.'),
+    }),
+    async handler(input, ctx) {
+        const bridge = getCanvasBridge();
+        if (!bridge) {
+            throw ctx.fail('canvas_unavailable', 'DataCanvas is not configured on this server.', {
+                ...ctx.recoveryFor('canvas_unavailable'),
+            });
+        }
+        const { result, meta } = await bridge.query(ctx, input.sql, {
+            ...(input.register_as !== undefined && { registerAs: input.register_as }),
+            ...(input.preview !== undefined && { preview: input.preview }),
+            rowLimit: input.row_limit,
+            sourceTool: 'secedgar_dataframe_query',
+            queryParams: { sql: input.sql },
+        });
+        ctx.log.info('Dataframe query executed', {
+            rowCount: result.rowCount,
+            returned: result.rows.length,
+            registeredAs: meta?.tableName,
+        });
+        return {
+            columns: result.columns,
+            row_count: result.rowCount,
+            rows: result.rows,
+            registered_as: meta?.tableName,
+            expires_at: meta?.expiresAt,
+        };
+    },
+    format: (result) => {
+        const lines = [];
+        if (result.registered_as) {
+            lines.push(`Registered as ${result.registered_as} (expires ${result.expires_at ?? 'unknown'}).`);
+        }
+        const cappedNote = result.row_count > result.rows.length
+            ? ` (showing ${result.rows.length} of ${result.row_count})`
+            : '';
+        lines.push(`**${result.row_count} rows**${cappedNote}\n`);
+        if (result.rows.length === 0) {
+            lines.push('_No rows._');
+            return [{ type: 'text', text: lines.join('\n') }];
+        }
+        const header = `| ${result.columns.join(' | ')} |`;
+        const sep = `| ${result.columns.map(() => '---').join(' | ')} |`;
+        lines.push(header, sep);
+        for (const row of result.rows) {
+            const cells = result.columns.map((c) => {
+                const v = row[c];
+                if (v === null || v === undefined)
+                    return '';
+                if (typeof v === 'string')
+                    return v.replace(/\|/g, '\\|');
+                if (typeof v === 'object')
+                    return JSON.stringify(v).replace(/\|/g, '\\|');
+                return String(v);
+            });
+            lines.push(`| ${cells.join(' | ')} |`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=dataframe-query.tool.js.map

package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataframe-query.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/dataframe-query.tool.ts"],"names":[],"mappings":"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"}