@cyanheads/brapi-mcp-server 0.4.9 → 0.4.10

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** brapi-mcp-server
-**Version:** 0.4.9
+**Version:** 0.4.10
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/brapi-mcp-server</h1>
   <p><b>BrAPI v2.1 MCP server — studies, germplasm, observations, genotypes, images, and pedigrees across Breedbase, T3, Sweetpotatobase, and any BrAPI-compliant server.</b>
-  <div>19 Tools • 6 Resources • 2 Prompts</div>
+  <div>22 Tools • 6 Resources • 2 Prompts</div>
   </p>
 </div>
 
 <div align="center">
 
-[![npm](https://img.shields.io/npm/v/@cyanheads/brapi-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/brapi-mcp-server) [![Version](https://img.shields.io/badge/Version-0.4.9-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
+[![npm](https://img.shields.io/npm/v/@cyanheads/brapi-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/brapi-mcp-server) [![Version](https://img.shields.io/badge/Version-0.4.10-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.29.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/)
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.3-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.11-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Status](https://img.shields.io/badge/Status-Beta-yellow.svg?style=flat-square)](./CHANGELOG.md)
 
@@ -17,7 +17,7 @@
 
 ## Tools
 
-Nineteen tools grouped by shape — connection tools bootstrap a session, `find_*` tools return a summarized page plus distributions and spill overflow rows into the DatasetStore, `get_*` tools fetch a single record with companion counts, plus pedigree walking, dataset lifecycle, an additive write surface for observations, and raw passthrough escape hatches.
+Twenty-two tools grouped by shape — connection tools bootstrap a session, `find_*` tools return a summarized page plus distributions and spill overflow rows into the DatasetStore, `get_*` tools fetch a single record with companion counts, plus pedigree walking, dataset lifecycle, an opt-in SQL/analytical workspace over spilled rows, an additive write surface for observations, and raw passthrough escape hatches.
 
 ### Orient
 
@@ -42,7 +42,7 @@ Nineteen tools grouped by shape — connection tools bootstrap a session, `find_
 | `brapi_get_image` | Fetch image bytes for up to 5 imageDbIds inline as `type: image` content blocks. Prefers `/images/{id}/imagecontent`, falls back to `imageURL`. |
 | `brapi_find_locations` | Find research stations / field sites by country / type / abbreviation, with optional client-side bounding-box filter. |
 | `brapi_find_variants` | Find variant records by variant set, reference, or genomic region (1-based inclusive / exclusive). |
-| `brapi_find_genotype_calls` | Pull genotype calls across a germplasm × variant set via async-search polling. Default 100k cap (hard cap 500k); rows beyond `loadLimit` spill to DatasetStore. |
+| `brapi_find_genotype_calls` | Pull genotype calls across a germplasm × variant set via async-search polling. Upstream pull bounded by deployment policy (`BRAPI_GENOTYPE_CALLS_MAX_PULL`, default 100k, max 500k); rows beyond `loadLimit` spill to DatasetStore. |
 
 ### Orchestrate
 
@@ -50,6 +50,14 @@ Nineteen tools grouped by shape — connection tools bootstrap a session, `find_
 |:----------|:------------|
 | `brapi_manage_dataset` | Lifecycle for `find_*` spillover datasets — list, summary, load (paged rows with column projection), delete. |
 
+### Analyze
+
+| Tool Name | Description |
+|:----------|:------------|
+| `brapi_dataframe_query` | Run SELECT SQL across in-memory dataframes (DuckDB-backed). Spilled `find_*` datasets auto-register as `ds_<datasetId>` dataframes. Use `registerAs` to chain. Read-only — multi-statement, non-SELECT, file-reads, and exports are rejected. **Opt-in via `CANVAS_PROVIDER_TYPE=duckdb` + `BRAPI_CANVAS_ENABLED=true`** — omitted from `tools/list` otherwise. |
+| `brapi_dataframe_describe` | List dataframes with column schema, row counts, and originating-dataset provenance for `ds_*` entries. |
+| `brapi_dataframe_drop` | Drop a dataframe by name. Idempotent — `dropped: false` for unknown names. Underlying DatasetStore dataset is unaffected. |
+
 ### Write
 
 | Tool Name | Description |
@@ -212,8 +220,8 @@ Find variant records by variant set, reference sequence, or genomic region.
 Pull genotype calls for a germplasm × variant set. Handles BrAPI's async-search pattern (`POST /search/calls` → `GET /search/calls/{id}`) transparently.
 
 - Requires at least one filter (`variantSetDbId`, `germplasmDbIds`, `callSetDbIds`, `variantDbIds`) — unfiltered pulls are rejected
-- Default cap of 100,000 calls per call (hard cap 500,000); `truncated: true` flags when the cap was hit
-- Rows beyond `loadLimit` (default 200) spill to `DatasetStore` for export via `brapi_manage_dataset`
+- Upstream pull bounded by deployment policy (`BRAPI_GENOTYPE_CALLS_MAX_PULL`, default 100,000, hard ceiling 500,000) — protects upstream from unbounded sequential paginated GETs. `truncated: true` flags when the cap was hit; agents narrow the filters and re-pull, or query the spilled dataframe
+- Rows beyond `loadLimit` (default 200) spill to `DatasetStore` for paged follow-up via `brapi_manage_dataset`, or SQL-queryable access via `brapi_dataframe_query`
 - Echoes server-reported genotype-encoding (`expandHomozygotes`, `unknownString`, `sepPhased`, `sepUnphased`) so the agent can interpret the values
 
 ---
@@ -230,6 +238,40 @@ Consolidated lifecycle tool for datasets produced by `find_*` spillovers.
 
 ---
 
+### `brapi_dataframe_query`
+
+Run SQL across in-memory dataframes — a SQL/analytical workspace backed by the framework's DuckDB-powered DataCanvas. Spilled `find_*` datasets auto-register as `ds_<datasetId>` dataframes; describe them via `brapi_dataframe_describe` before composing a query.
+
+> **Off by default.** Both gates must be on: `CANVAS_PROVIDER_TYPE=duckdb` (framework-side) and `BRAPI_CANVAS_ENABLED=true` (server-side, default true). Requires the optional `@duckdb/node-api` peer dep. Not available on Cloudflare Workers — DuckDB has no V8-isolate build.
+
+- Read-only enforcement via the framework's three-layer SQL gate (single statement → SELECT only → plan-walk allowlist), plus a server-side deny-list for `read_json*` / `read_parquet*` / `iceberg_scan` / `delta_scan` that bypass the canvas
+- `registerAs` materializes the result as a new dataframe — full result lives in the workspace, response carries a bounded `preview` slice plus the full `rowCount`
+- `BRAPI_CANVAS_MAX_ROWS` (default 10,000) caps response materialization; raising `rowLimit` past this is silently capped — use `registerAs` instead
+- `BRAPI_CANVAS_QUERY_TIMEOUT_MS` (default 30,000) wraps the query in a wall-clock cap on top of `ctx.signal`
+- Per-tenant default workspace cached in `ctx.state` — agents never see the underlying canvasId
+- SQL-gate rejections translate to a typed `sql_rejected` reason, preserving the granular gate code on `data.gateReason`
+
+---
+
+### `brapi_dataframe_describe`
+
+List the dataframes available in the current workspace (or describe one by name) with column schema, row counts, and originating-dataset provenance.
+
+- `ds_*`-prefixed dataframes carry full provenance: originating tool (`source`), `baseUrl`, original `query`, `createdAt`, `expiresAt`
+- User-derived dataframes (created via `brapi_dataframe_query({ registerAs })`) show structural info only
+- Pass `tableName` to scope to one entry; omit to list all
+
+---
+
+### `brapi_dataframe_drop`
+
+Release a dataframe by name. Idempotent — returns `dropped: false` rather than failing when the name is unknown.
+
+- Drops the dataframe and its provenance metadata; the underlying DatasetStore dataset is untouched
+- Use `brapi_manage_dataset mode=delete` to drop both the dataset and its dataframe in one call
+
+---
+
 ### `brapi_raw_get`
 
 Last-resort passthrough to any BrAPI `GET /{path}` the curated tools don't cover (e.g. `/samples`, `/methods`, `/scales`, `/crosses`). Returns the raw upstream envelope plus pagination metadata.
@@ -313,6 +355,7 @@ BrAPI-specific:
 - **Tolerant capability discovery** — if `/serverinfo` is unavailable or sparse, discovery falls back to `/calls` and returns a partial orientation envelope with explicit notes
 - **Find-route planning** — curated `find_*` tools prefer GET list endpoints, then fall back to POST `/search/{noun}` when only search is advertised
 - **Dataset spillover** — `find_*` tools cap in-context rows at `loadLimit` and transparently persist larger unions (up to 50k rows / 50 pages) as handles in `DatasetStore`; `brapi_manage_dataset` pages / projects / deletes them
+- **Dataframes (Tier 3, opt-in)** — spilled `find_*` rows auto-register as DuckDB-backed dataframes named `ds_<datasetId>`; agents run SELECT SQL across them via `brapi_dataframe_query`, with read-only enforcement and a per-tenant workspace. Gated by `CANVAS_PROVIDER_TYPE=duckdb` + `BRAPI_CANVAS_ENABLED=true`; requires the optional `@duckdb/node-api` peer dep. Not available on Cloudflare Workers.
 - **Async-search transparency** — `brapi_find_genotype_calls` and `brapi_raw_search` handle the `POST /search/{noun}` → `GET /search/{noun}/{id}` 202-retry pattern without the agent needing to know
 - **Pedigree DAG walks** — `brapi_walk_pedigree` BFS-traverses ancestry or descendancy with cycle detection, depth limits, and traversal stats — BrAPI only exposes one generation per call
 - **Image content** — `brapi_get_image` fetches image bytes inline as MCP `type: image` blocks, preferring `/images/{id}/imagecontent` and falling back to the metadata `imageURL` field
@@ -394,6 +437,7 @@ No environment variables are required for the public BrAPI test server — agent
 
 - [Bun v1.3.11](https://bun.sh/) or higher (or Node.js v22+).
 - A BrAPI v2 endpoint to point at — the public [test server](https://test-server.brapi.org/brapi/v2) works out of the box; production servers typically need credentials.
+- *(Optional)* [`@duckdb/node-api`](https://www.npmjs.com/package/@duckdb/node-api) — required only to enable the dataframe surface (`CANVAS_PROVIDER_TYPE=duckdb`). Listed as an optional peer dep so the bare install stays light. Linux/macOS/Windows × x64 plus Linux/macOS arm64 supported (Windows arm64 is unsupported by DuckDB upstream). Not available on Cloudflare Workers.
 
 ### Installation
 
@@ -449,6 +493,11 @@ Every variable is optional — agents can configure connections entirely at runt
 | `BRAPI_REFERENCE_CACHE_TTL_SECONDS` | TTL for reference-data cache entries (programs, trials, locations, crops). | `3600` |
 | `BRAPI_ALLOW_PRIVATE_IPS` | Allow connecting to RFC 1918 / loopback targets. Dev-only. | `false` |
 | `BRAPI_ENABLE_WRITES` | Opt-in flag for the write surface (`brapi_submit_observations`). Off by default — the tool is omitted from `tools/list` unless the operator opts in for this deployment. | `false` |
+| `BRAPI_GENOTYPE_CALLS_MAX_PULL` | Hard ceiling on rows pulled from the upstream BrAPI server in a single `brapi_find_genotype_calls` invocation. Bounds total page count per query — protects upstream from unbounded pagination loops. Maximum 500,000. | `100000` |
+| `CANVAS_PROVIDER_TYPE` | Framework-side switch for the `DataCanvas` primitive. Set to `duckdb` to enable the dataframe surface. Fails closed on Cloudflare Workers. | `none` |
+| `BRAPI_CANVAS_ENABLED` | Server-side gate for `brapi_dataframe_*` tools. Effective only when `CANVAS_PROVIDER_TYPE=duckdb`. | `true` |
+| `BRAPI_CANVAS_MAX_ROWS` | Hard cap on rows materialized into a `brapi_dataframe_query` response. Use `registerAs` to keep larger result sets in the workspace. | `10000` |
+| `BRAPI_CANVAS_QUERY_TIMEOUT_MS` | Per-query wall-clock timeout for `brapi_dataframe_query`. | `30000` |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
 | `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
 | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
@@ -558,15 +607,16 @@ In HTTP + `none`, every client shares one bucket: connection aliases registered
 
 | Directory | Purpose |
 |:----------|:--------|
-| `src/index.ts` | `createApp()` entry point — registers 19 tools, 6 resources, 2 prompts, and inits the seven services. |
+| `src/index.ts` | `createApp()` entry point — registers 22 tools, 6 resources, 2 prompts, and inits the eight services. |
 | `src/config` | Server-specific environment variable parsing with Zod. |
 | `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) and shared helpers (`orientation-envelope`, `find-helpers`, `connect-auth-schema`, `raw-routing-hints`). |
 | `src/mcp-server/resources` | Resource definitions (`*.resource.ts`) — URI-addressable mirrors of curated tool data. |
 | `src/mcp-server/prompts` | Prompt definitions (`*.prompt.ts`) — multi-step BrAPI workflow templates. |
 | `src/services/brapi-client` | HTTP client with retry, concurrency capping, async-search polling, private-IP guard, and binary fetch. |
 | `src/services/brapi-filters` | Static BrAPI v2.1 filter catalog. |
+| `src/services/canvas-bridge` | Bridge over the framework's `DataCanvas` primitive — per-tenant default-workspace resolution, dataframe naming, provenance tracking. |
 | `src/services/capability-registry` | Per-connection capability profile cache. |
-| `src/services/dataset-store` | Tenant-scoped dataset handles for spilled `find_*` results. |
+| `src/services/dataset-store` | Tenant-scoped dataset handles for spilled `find_*` results. Auto-registers rows as dataframes when the canvas-bridge is enabled. |
 | `src/services/ontology-resolver` | Free-text → ontology-candidate matcher powering `brapi_find_variables` ranking. |
 | `src/services/reference-data-cache` | Cache for programs, trials, locations, crops. |
 | `src/services/server-registry` | Alias → live BrAPI connection map with auth resolution. |

package/changelog/0.4.x/0.4.10.md

@@ -0,0 +1,30 @@
+---
+summary: "Dataframe surface (Tier 3, opt-in) — spilled find_* rows auto-register as DuckDB-backed dataframes; agents run SELECT SQL across them via brapi_dataframe_query/describe/drop. Genotype-call cap promoted to operator policy."
+breaking: false
+---
+
+# 0.4.10 — 2026-05-03
+
+A SQL/analytical workspace lands on top of the existing dataset surface. When `find_*` tools spill to `DatasetStore`, the rows now also auto-register as `ds_<datasetId>` dataframes on the framework's DuckDB-backed `DataCanvas` — agents query them with SELECT SQL via `brapi_dataframe_query`, describe schemas via `brapi_dataframe_describe`, and drop them via `brapi_dataframe_drop`. The whole surface is Tier 3: optional peer dep `@duckdb/node-api`, gated behind `CANVAS_PROVIDER_TYPE=duckdb` and `BRAPI_CANVAS_ENABLED=true`. Bare installs and Cloudflare Workers are unaffected. Separately, `brapi_find_genotype_calls` retires its per-call `maxCalls` input in favor of a deployment-side `BRAPI_GENOTYPE_CALLS_MAX_PULL` operator policy.
+
+## Added
+
+- **`brapi_dataframe_query`** — run SELECT SQL across in-memory dataframes. Read-only enforcement uses the framework's three-layer SQL gate (single statement → SELECT only → plan-walk allowlist) plus a server-side deny-list for `read_json*` / `read_parquet*` / `iceberg_scan` / `delta_scan` table functions that bypass the canvas. `registerAs` materializes the result as a new dataframe; the response carries a bounded `preview` slice plus the full `rowCount`. Per-tenant default workspace cached in `ctx.state` — agents never see the underlying canvasId. Typed `sql_rejected` reason preserves the granular gate code on `data.gateReason`.
+- **`brapi_dataframe_describe`** — list dataframes (or one by name) with column schema, row count, and originating-dataset provenance for `ds_*` entries (source tool, baseUrl, original query, createdAt, expiresAt). User-derived dataframes from `registerAs` show structural info only.
+- **`brapi_dataframe_drop`** — release a dataframe by name. Idempotent — `dropped: false` rather than failing for unknown names. The underlying `DatasetStore` dataset is untouched; `brapi_manage_dataset mode=delete` drops both.
+- **`CanvasBridge` service** (`src/services/canvas-bridge/`) — owns the three concerns the framework leaves to the consumer: per-tenant default canvas resolution (cached in `ctx.state`, refreshed on stale-id `NotFound`), SQL-safe table naming for UUID-shaped dataset IDs (`ds_<datasetId_with_underscores>`), and originating-dataset provenance tracking. `isEnabled()` is the single gate every dataframe tool checks. `composeSignal()` wraps `ctx.signal` with a wall-clock cap using the manual-AbortController pattern (avoids `AbortSignal.timeout()` realm-mismatch issues in Bun stdio).
+- **`DatasetStore` ↔ canvas integration** — `create()` auto-registers spilled rows on the canvas when the bridge is enabled; the resulting dataframe name surfaces on `DatasetMetadata.dataframe`. `delete()` mirrors the drop. Both directions are best-effort — failure logs a warning but never breaks the dataset op. Dataset handles, `brapi_manage_dataset` summary/list output, and `find_*` formatters all surface `dataframe: <name>` when present so agents can pivot directly into SQL.
+- **5 new env vars**:
+  - `BRAPI_GENOTYPE_CALLS_MAX_PULL` (default 100,000, max 500,000) — operator policy ceiling on rows pulled in a single `brapi_find_genotype_calls` invocation.
+  - `CANVAS_PROVIDER_TYPE` (framework, default `none`) — set to `duckdb` to enable the canvas service. Fails closed on Cloudflare Workers.
+  - `BRAPI_CANVAS_ENABLED` (server, default `true`) — server-side gate for the `brapi_dataframe_*` surface. Effective only when the framework canvas is active.
+  - `BRAPI_CANVAS_MAX_ROWS` (default 10,000) — hard cap on rows materialized into a `brapi_dataframe_query` response. Larger result sets must use `registerAs`.
+  - `BRAPI_CANVAS_QUERY_TIMEOUT_MS` (default 30,000) — per-query wall-clock timeout layered on top of `ctx.signal`.
+- **Optional peer dependency `@duckdb/node-api ^1.5.0`** — listed under `peerDependenciesMeta.optional: true` so bare installs stay light. Linux/macOS/Windows × x64 plus Linux/macOS arm64 supported (Windows arm64 unsupported by DuckDB upstream).
+- **`api-canvas` and `code-simplifier` skills** synced from the framework upgrade. `api-config`, `api-workers`, `add-tool`, `design-mcp-server`, `security-pass`, and the `report-issue-*` pair gained canvas-aware sections.
+
+## Changed
+
+- **`brapi_find_genotype_calls` cap is deployment-side now** — the per-call `maxCalls` input is removed (Zod silently strips it; no wire break for callers still passing it). The cap reads from `BRAPI_GENOTYPE_CALLS_MAX_PULL` instead, so the upstream-protection budget is set by the operator, not the agent. Truncation warning, output `truncated` doc, and the `raw_search` routing nudge updated to point at the new env var. Recovery hint when truncated: narrow the filters and re-pull, or query the spilled dataframe.
+- **Framework bump** — `@cyanheads/mcp-ts-core` `^0.8.8` → `^0.8.10`. Picks up the `DataCanvas` primitive, `core.canvas` wiring on `CoreServices`, and the canvas-related env-var schemas.
+- **`src/index.ts`** registers the dataframe tools conditionally on `serverConfig.canvasEnabled`, mirroring the existing `enableWrites` gate. Tools are omitted from `tools/list` when the gate is off so agents don't see capabilities they can't use.

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

@@ -35,6 +35,13 @@ declare const ServerConfigSchema: z.ZodObject<{
         true: "true";
         false: "false";
     }>>, z.ZodTransform<boolean, "true" | "false">>;
+    genotypeCallsMaxPull: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    canvasEnabled: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "true" | "false">>;
+    canvasMaxRows: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    canvasQueryTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, 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;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyGtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAwB9C;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAG3C,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwItB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CA4B9C;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/config/server-config.js

@@ -107,6 +107,30 @@ const ServerConfigSchema = z.object({
         .default('false')
         .transform((v) => v === 'true')
         .describe('Opt-in flag for the write surface (`brapi_submit_observations`). Off by default — the tool is omitted from `tools/list` unless the operator opts in for this deployment.'),
+    genotypeCallsMaxPull: z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(500_000)
+        .default(100_000)
+        .describe('Hard ceiling on rows pulled from the upstream BrAPI server in a single brapi_find_genotype_calls invocation. Bounds total page count per query — protects the upstream from unbounded pagination loops. Default 100,000 (≈10 pages at the standard pageSize=10,000); maximum 500,000 (≈50 pages, matching the per-query budget of other find_* tools).'),
+    canvasEnabled: z
+        .enum(['true', 'false'])
+        .default('true')
+        .transform((v) => v === 'true')
+        .describe('Gate the brapi_dataframe_* tool surface. Effective only when the framework canvas service is also configured (CANVAS_PROVIDER_TYPE=duckdb). Default true — set false to keep the dependency installed but the tools hidden.'),
+    canvasMaxRows: z.coerce
+        .number()
+        .int()
+        .positive()
+        .default(10_000)
+        .describe('Hard upper bound on rows materialized into a brapi_dataframe_query response. Larger result sets must use registerAs to keep the full set in the workspace.'),
+    canvasQueryTimeoutMs: z.coerce
+        .number()
+        .int()
+        .positive()
+        .default(30_000)
+        .describe('Per-query wall-clock timeout for brapi_dataframe_query.'),
 });
 let _config;
 export function getServerConfig() {
@@ -131,6 +155,10 @@ export function getServerConfig() {
         searchPollIntervalMs: 'BRAPI_SEARCH_POLL_INTERVAL_MS',
         allowPrivateIps: 'BRAPI_ALLOW_PRIVATE_IPS',
         enableWrites: 'BRAPI_ENABLE_WRITES',
+        genotypeCallsMaxPull: 'BRAPI_GENOTYPE_CALLS_MAX_PULL',
+        canvasEnabled: 'BRAPI_CANVAS_ENABLED',
+        canvasMaxRows: 'BRAPI_CANVAS_MAX_ROWS',
+        canvasQueryTimeoutMs: 'BRAPI_CANVAS_QUERY_TIMEOUT_MS',
     });
     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":"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"}
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -10,6 +10,7 @@ import { createApp } from '@cyanheads/mcp-ts-core';
 import { getServerConfig } from './config/server-config.js';
 import { initBrapiClient } from './services/brapi-client/index.js';
 import { initBrapiDialectRegistry } from './services/brapi-dialect/index.js';
+import { initCanvasBridge } from './services/canvas-bridge/index.js';
 import { initCapabilityRegistry } from './services/capability-registry/index.js';
 import { initDatasetStore } from './services/dataset-store/index.js';
 import { initOntologyResolver } from './services/ontology-resolver/index.js';
@@ -23,11 +24,17 @@ import { brapiFiltersResource } from './mcp-server/resources/definitions/brapi-f
 import { brapiGermplasmResource } from './mcp-server/resources/definitions/brapi-germplasm.resource.js';
 import { brapiServerInfoResource } from './mcp-server/resources/definitions/brapi-server-info.resource.js';
 import { brapiStudyResource } from './mcp-server/resources/definitions/brapi-study.resource.js';
-import { readOnlyToolDefinitions, writeToolDefinitions, } from './mcp-server/tools/definitions/index.js';
+import { dataframeToolDefinitions, readOnlyToolDefinitions, writeToolDefinitions, } from './mcp-server/tools/definitions/index.js';
 const serverConfig = getServerConfig();
-const tools = serverConfig.enableWrites
-    ? [...readOnlyToolDefinitions, ...writeToolDefinitions]
-    : readOnlyToolDefinitions;
+const tools = [
+    ...readOnlyToolDefinitions,
+    // Dataframe surface gated by BRAPI_CANVAS_ENABLED. The framework canvas
+    // itself is gated by CANVAS_PROVIDER_TYPE — when that's not `duckdb`, the
+    // bridge returns `isEnabled() === false` and the tools fail with a typed
+    // `dataframe_disabled` error directing the operator to set both env vars.
+    ...(serverConfig.canvasEnabled ? dataframeToolDefinitions : []),
+    ...(serverConfig.enableWrites ? writeToolDefinitions : []),
+];
 await createApp({
     tools,
     resources: [
@@ -39,12 +46,13 @@ await createApp({
         brapiFiltersResource,
     ],
     prompts: [brapiEdaStudy, brapiMetaAnalysis],
-    setup() {
+    setup(core) {
+        const canvasBridge = initCanvasBridge(core.canvas, serverConfig);
         initBrapiClient(serverConfig);
         initCapabilityRegistry(serverConfig);
         initBrapiDialectRegistry();
         initReferenceDataCache(serverConfig);
-        initDatasetStore(serverConfig);
+        initDatasetStore(serverConfig, canvasBridge);
         initServerRegistry(serverConfig);
         initOntologyResolver();
     },

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,4DAA4D,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,gEAAgE,CAAC;AACnG,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAChG,OAAO,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACpG,OAAO,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACpG,OAAO,EAAE,sBAAsB,EAAE,MAAM,gEAAgE,CAAC;AACxG,OAAO,EAAE,uBAAuB,EAAE,MAAM,kEAAkE,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAChG,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,yCAAyC,CAAC;AAEjD,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;AAEvC,MAAM,KAAK,GAAG,YAAY,CAAC,YAAY;IACrC,CAAC,CAAC,CAAC,GAAG,uBAAuB,EAAE,GAAG,oBAAoB,CAAC;IACvD,CAAC,CAAC,uBAAuB,CAAC;AAE5B,MAAM,SAAS,CAAC;IACd,KAAK;IACL,SAAS,EAAE;QACT,uBAAuB;QACvB,kBAAkB;QAClB,kBAAkB;QAClB,sBAAsB;QACtB,oBAAoB;QACpB,oBAAoB;KACrB;IACD,OAAO,EAAE,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC3C,KAAK;QACH,eAAe,CAAC,YAAY,CAAC,CAAC;QAC9B,sBAAsB,CAAC,YAAY,CAAC,CAAC;QACrC,wBAAwB,EAAE,CAAC;QAC3B,sBAAsB,CAAC,YAAY,CAAC,CAAC;QACrC,gBAAgB,CAAC,YAAY,CAAC,CAAC;QAC/B,kBAAkB,CAAC,YAAY,CAAC,CAAC;QACjC,oBAAoB,EAAE,CAAC;IACzB,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qCAAqC,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,4DAA4D,CAAC;AAC3F,OAAO,EAAE,iBAAiB,EAAE,MAAM,gEAAgE,CAAC;AACnG,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAChG,OAAO,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACpG,OAAO,EAAE,oBAAoB,EAAE,MAAM,8DAA8D,CAAC;AACpG,OAAO,EAAE,sBAAsB,EAAE,MAAM,gEAAgE,CAAC;AACxG,OAAO,EAAE,uBAAuB,EAAE,MAAM,kEAAkE,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAAE,MAAM,4DAA4D,CAAC;AAChG,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,yCAAyC,CAAC;AAEjD,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;AAEvC,MAAM,KAAK,GAAG;IACZ,GAAG,uBAAuB;IAC1B,wEAAwE;IACxE,0EAA0E;IAC1E,yEAAyE;IACzE,0EAA0E;IAC1E,GAAG,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/D,GAAG,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;CAC3D,CAAC;AAEF,MAAM,SAAS,CAAC;IACd,KAAK;IACL,SAAS,EAAE;QACT,uBAAuB;QACvB,kBAAkB;QAClB,kBAAkB;QAClB,sBAAsB;QACtB,oBAAoB;QACpB,oBAAoB;KACrB;IACD,OAAO,EAAE,CAAC,aAAa,EAAE,iBAAiB,CAAC;IAC3C,KAAK,CAAC,IAAI;QACR,MAAM,YAAY,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACjE,eAAe,CAAC,YAAY,CAAC,CAAC;QAC9B,sBAAsB,CAAC,YAAY,CAAC,CAAC;QACrC,wBAAwB,EAAE,CAAC;QAC3B,sBAAsB,CAAC,YAAY,CAAC,CAAC;QACrC,gBAAgB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAC7C,kBAAkB,CAAC,YAAY,CAAC,CAAC;QACjC,oBAAoB,EAAE,CAAC;IACzB,CAAC;CACF,CAAC,CAAC"}

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

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview `brapi_dataframe_describe` — list dataframes (or describe one)
+ * with column schema, row count, and originating-dataset provenance.
+ * Auto-registered dataset dataframes (`ds_<datasetId>`) carry full source
+ * metadata (originating tool, baseUrl, query, expiry); user-derived dataframes
+ * created via `brapi_dataframe_query({ registerAs })` only show structural info.
+ *
+ * @module mcp-server/tools/definitions/brapi-dataframe-describe.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const brapiDataframeDescribe: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    dataframe: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    tables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        rowCount: z.ZodNumber;
+        columns: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodString;
+            nullable: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+        approxSizeBytes: z.ZodOptional<z.ZodNumber>;
+        provenance: z.ZodOptional<z.ZodObject<{
+            datasetId: z.ZodString;
+            source: z.ZodString;
+            baseUrl: z.ZodString;
+            query: z.ZodUnknown;
+            createdAt: z.ZodString;
+            expiresAt: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "dataframe_disabled";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Dataframe surface is gated off by env (CANVAS_PROVIDER_TYPE != duckdb or BRAPI_CANVAS_ENABLED=false)";
+    readonly recovery: "Set CANVAS_PROVIDER_TYPE=duckdb and BRAPI_CANVAS_ENABLED=true on the deployment, or use brapi_manage_dataset to enumerate datasets directly.";
+}]>;
+//# sourceMappingURL=brapi-dataframe-describe.tool.d.ts.map

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

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

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

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview `brapi_dataframe_describe` — list dataframes (or describe one)
+ * with column schema, row count, and originating-dataset provenance.
+ * Auto-registered dataset dataframes (`ds_<datasetId>`) carry full source
+ * metadata (originating tool, baseUrl, query, expiry); user-derived dataframes
+ * created via `brapi_dataframe_query({ registerAs })` only show structural info.
+ *
+ * @module mcp-server/tools/definitions/brapi-dataframe-describe.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getCanvasBridge } from '../../../services/canvas-bridge/index.js';
+const ColumnSchema = z.object({
+    name: z.string().describe('Column name.'),
+    type: z.string().describe('SQL column type (VARCHAR, INTEGER, DOUBLE, BOOLEAN, etc.).'),
+    nullable: z.boolean().optional().describe('True when NULL values are allowed.'),
+});
+const ProvenanceSchema = z.object({
+    datasetId: z
+        .string()
+        .describe('Originating dataset ID — pass to brapi_manage_dataset to operate on the underlying rows.'),
+    source: z.string().describe('Tool/operation that produced the dataset (e.g. find_observations).'),
+    baseUrl: z.string().describe('BrAPI base URL the dataset was pulled from.'),
+    query: z.unknown().describe('Original filter map / search body.'),
+    createdAt: z.string().describe('ISO 8601 dataset creation time.'),
+    expiresAt: z.string().describe('ISO 8601 expiry — when the dataframe will be evicted.'),
+});
+const DescribedTableSchema = z.object({
+    name: z.string().describe('Dataframe name. Use this in SQL queries.'),
+    rowCount: z.number().int().nonnegative().describe('Rows currently registered.'),
+    columns: z
+        .array(ColumnSchema.describe('Column declaration.'))
+        .describe('Schema in declaration order.'),
+    approxSizeBytes: z.number().int().nonnegative().optional().describe('Approximate size in bytes.'),
+    provenance: ProvenanceSchema.optional().describe('Originating dataset provenance — present only for auto-registered dataframes (`ds_*`).'),
+});
+const OutputSchema = z.object({
+    tables: z
+        .array(DescribedTableSchema.describe('Dataframe description.'))
+        .describe('All described dataframes.'),
+});
+const InputSchema = z.object({
+    dataframe: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('When set, return only the named dataframe. Omit to list all dataframes.'),
+});
+export const brapiDataframeDescribe = tool('brapi_dataframe_describe', {
+    description: 'List dataframes (or describe one) with columns, row counts, and originating-dataset provenance. Use this to discover what dataframes are available before writing a brapi_dataframe_query.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    errors: [
+        {
+            reason: 'dataframe_disabled',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Dataframe surface is gated off by env (CANVAS_PROVIDER_TYPE != duckdb or BRAPI_CANVAS_ENABLED=false)',
+            recovery: 'Set CANVAS_PROVIDER_TYPE=duckdb and BRAPI_CANVAS_ENABLED=true on the deployment, or use brapi_manage_dataset to enumerate datasets directly.',
+        },
+    ],
+    input: InputSchema,
+    output: OutputSchema,
+    async handler(input, ctx) {
+        const bridge = getCanvasBridge();
+        if (!bridge.isEnabled()) {
+            throw ctx.fail('dataframe_disabled', 'brapi_dataframe_describe is unavailable — dataframes are not enabled on this deployment.', { ...ctx.recoveryFor('dataframe_disabled') });
+        }
+        const describeOpts = {};
+        if (input.dataframe !== undefined)
+            describeOpts.tableName = input.dataframe;
+        const tables = await bridge.describe(ctx, describeOpts);
+        return { tables };
+    },
+    format: (result) => [{ type: 'text', text: renderDescribe(result.tables) }],
+});
+function renderDescribe(tables) {
+    const lines = [];
+    lines.push(`# ${tables.length} dataframe(s)`);
+    if (tables.length === 0) {
+        lines.push('');
+        lines.push('_No dataframes. Run a find_* tool that spills to a dataset, or use brapi_dataframe_query with `registerAs` to materialize one._');
+        return lines.join('\n');
+    }
+    for (const table of tables) {
+        lines.push('');
+        lines.push(`## \`${table.name}\``);
+        lines.push(`- rowCount: ${table.rowCount}`);
+        if (table.approxSizeBytes !== undefined) {
+            lines.push(`- approxSizeBytes: ${table.approxSizeBytes}`);
+        }
+        lines.push(`- columns: ${table.columns.length}`);
+        for (const col of table.columns) {
+            const nullable = col.nullable === undefined ? '' : ` (nullable: ${col.nullable})`;
+            lines.push(`  - ${col.name}: ${col.type}${nullable}`);
+        }
+        if (table.provenance) {
+            lines.push('- provenance:');
+            lines.push(`  - datasetId: \`${table.provenance.datasetId}\``);
+            lines.push(`  - source: ${table.provenance.source}`);
+            lines.push(`  - baseUrl: ${table.provenance.baseUrl}`);
+            lines.push(`  - createdAt: ${table.provenance.createdAt}`);
+            lines.push(`  - expiresAt: ${table.provenance.expiresAt}`);
+            lines.push(`  - query: \`${JSON.stringify(table.provenance.query)}\``);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=brapi-dataframe-describe.tool.js.map

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

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

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

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview `brapi_dataframe_drop` — release a single dataframe by name.
+ * Idempotent (returns `dropped: false` for unknown names rather than failing).
+ * Drops the dataframe and any provenance metadata stored alongside it. The
+ * originating dataset is unaffected — use `brapi_manage_dataset mode=delete`
+ * to drop both.
+ *
+ * @module mcp-server/tools/definitions/brapi-dataframe-drop.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const brapiDataframeDrop: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    dataframe: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    dataframe: z.ZodString;
+    dropped: z.ZodBoolean;
+}, z.core.$strip>, readonly [{
+    readonly reason: "dataframe_disabled";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Dataframe surface is gated off by env (CANVAS_PROVIDER_TYPE != duckdb or BRAPI_CANVAS_ENABLED=false)";
+    readonly recovery: "Set CANVAS_PROVIDER_TYPE=duckdb and BRAPI_CANVAS_ENABLED=true on the deployment, or use brapi_manage_dataset for the underlying dataset.";
+}]>;
+//# sourceMappingURL=brapi-dataframe-drop.tool.d.ts.map

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

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

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

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview `brapi_dataframe_drop` — release a single dataframe by name.
+ * Idempotent (returns `dropped: false` for unknown names rather than failing).
+ * Drops the dataframe and any provenance metadata stored alongside it. The
+ * originating dataset is unaffected — use `brapi_manage_dataset mode=delete`
+ * to drop both.
+ *
+ * @module mcp-server/tools/definitions/brapi-dataframe-drop.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getCanvasBridge } from '../../../services/canvas-bridge/index.js';
+const InputSchema = z.object({
+    dataframe: z
+        .string()
+        .min(1)
+        .describe('Dataframe to drop. Use brapi_dataframe_describe to discover names. Returns dropped:false (no error) when the name is unknown.'),
+});
+const OutputSchema = z.object({
+    dataframe: z.string().describe('The dataframe name that was requested for drop.'),
+    dropped: z
+        .boolean()
+        .describe('True when the dataframe existed and was removed; false when it did not exist.'),
+});
+export const brapiDataframeDrop = tool('brapi_dataframe_drop', {
+    description: 'Drop a dataframe by name. Idempotent — returns dropped:false rather than failing when the name is unknown. The underlying dataset is untouched (use brapi_manage_dataset mode=delete to drop both).',
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false },
+    errors: [
+        {
+            reason: 'dataframe_disabled',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Dataframe surface is gated off by env (CANVAS_PROVIDER_TYPE != duckdb or BRAPI_CANVAS_ENABLED=false)',
+            recovery: 'Set CANVAS_PROVIDER_TYPE=duckdb and BRAPI_CANVAS_ENABLED=true on the deployment, or use brapi_manage_dataset for the underlying dataset.',
+        },
+    ],
+    input: InputSchema,
+    output: OutputSchema,
+    async handler(input, ctx) {
+        const bridge = getCanvasBridge();
+        if (!bridge.isEnabled()) {
+            throw ctx.fail('dataframe_disabled', 'brapi_dataframe_drop is unavailable — dataframes are not enabled on this deployment.', { ...ctx.recoveryFor('dataframe_disabled') });
+        }
+        const dropped = await bridge.drop(ctx, input.dataframe);
+        return { dataframe: input.dataframe, dropped };
+    },
+    format: (result) => [
+        {
+            type: 'text',
+            text: result.dropped
+                ? `# Dropped \`${result.dataframe}\`\n- dropped: true`
+                : `# No-op — \`${result.dataframe}\` not found\n- dropped: false`,
+        },
+    ],
+});
+//# sourceMappingURL=brapi-dataframe-drop.tool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brapi-dataframe-drop.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/brapi-dataframe-drop.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;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,mCAAmC,CAAC;AAEpE,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACP,+HAA+H,CAChI;CACJ,CAAC,CAAC;AAEH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IACjF,OAAO,EAAE,CAAC;SACP,OAAO,EAAE;SACT,QAAQ,CAAC,+EAA+E,CAAC;CAC7F,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,sBAAsB,EAAE;IAC7D,WAAW,EACT,qMAAqM;IACvM,WAAW,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE;IAChF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,oBAAoB;YAC5B,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,sGAAsG;YAC5G,QAAQ,EACN,0IAA0I;SAC7I;KACO;IACV,KAAK,EAAE,WAAW;IAClB,MAAM,EAAE,YAAY;IAEpB,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,CAAC;YACxB,MAAM,GAAG,CAAC,IAAI,CACZ,oBAAoB,EACpB,sFAAsF,EACtF,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,oBAAoB,CAAC,EAAE,CAC7C,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;QACxD,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC;IACjD,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC;QAClB;YACE,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,MAAM,CAAC,OAAO;gBAClB,CAAC,CAAC,eAAe,MAAM,CAAC,SAAS,qBAAqB;gBACtD,CAAC,CAAC,eAAe,MAAM,CAAC,SAAS,gCAAgC;SACpE;KACF;CACF,CAAC,CAAC"}