@cyanheads/brapi-mcp-server 0.6.4 → 0.7.1

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Agent Protocol
 
 **Server:** brapi-mcp-server
-**Version:** 0.6.4
+**Version:** 0.7.1
 **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.
@@ -168,7 +168,7 @@ Handlers receive a unified `ctx` object. Currently used surface:
 | `ctx.requestId` | Unique request ID — auto-attached to every `ctx.log` entry. |
 | `ctx.tenantId` | Tenant ID from JWT or `'default'` for stdio / HTTP+`auth=none` — outer scope on all `ctx.state` reads/writes. |
 
-`ctx.elicit` is used by `brapi_submit_observations` to gate apply-mode writes behind user confirmation (with explicit `force: true` as the bypass). `ctx.sample` and `ctx.progress` are not used yet — they'll show up when long-running workflows (pedigree traversal, genotype-call pulls) need progress reporting or LLM sampling. `ctx.fail(reason, …)` is the typed thrower keyed off declared `errors[]` contracts — used by 8 tools and 3 resources today. `ctx.recoveryFor(reason)` resolves the matching contract entry's recovery hint into `data.recovery.hint` so it surfaces on the wire.
+`ctx.elicit` is used by `brapi_submit_observations` to gate apply-mode writes behind user confirmation (with explicit `force: true` as the bypass). `ctx.sample` and `ctx.progress` are not used yet — they'll show up when long-running workflows (pedigree traversal, genotype-call pulls) need progress reporting or LLM sampling. `ctx.fail(reason, …)` is the typed thrower keyed off declared `errors[]` contracts — used by 14 tools and 1 resource today. `ctx.recoveryFor(reason)` resolves the matching contract entry's recovery hint into `data.recovery.hint` so it surfaces on the wire.
 
 ---
 
@@ -176,7 +176,7 @@ Handlers receive a unified `ctx` object. Currently used surface:
 
 Handlers throw — the framework catches, classifies, and formats.
 
-**Default for new tools: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required descriptive metadata (≥ 5 words, lint-validated); to surface it on the wire, spread `...ctx.recoveryFor('reason')` into `data` or pass an explicit `{ recovery: { hint: '...' } }` when runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring. Live across the BrAPI surface today: `brapi_connect`, `brapi_dataframe_query`, `brapi_describe_filters`, `brapi_find_genotype_calls`, `brapi_get_germplasm`, `brapi_get_image`, `brapi_get_study`, `brapi_raw_get`, `brapi_raw_search`, `brapi_submit_observations`, plus the `brapi://study/{studyDbId}`, `brapi://germplasm/{germplasmDbId}`, and `brapi://filters/{endpoint}` resources.
+**Default for new tools: typed error contract.** Declare `errors: [{ reason, code, when, recovery, retryable? }]` on `tool()` to receive a typed `ctx.fail(reason, …)` keyed by the declared reason union. TypeScript catches `ctx.fail('typo')` at compile time, `data.reason` is auto-populated for observability, and the linter enforces conformance against the handler body. The `recovery` field is required descriptive metadata (≥ 5 words, lint-validated); to surface it on the wire, spread `...ctx.recoveryFor('reason')` into `data` or pass an explicit `{ recovery: { hint: '...' } }` when runtime context matters. Baseline codes (`InternalError`, `ServiceUnavailable`, `Timeout`, `ValidationError`, `SerializationError`) bubble freely and don't need declaring. Live across the BrAPI surface today: `brapi_build_phenotype_matrix`, `brapi_dataframe_describe`, `brapi_dataframe_export`, `brapi_dataframe_query`, `brapi_describe_filters`, `brapi_export_genotype_matrix`, `brapi_find_genotype_calls`, `brapi_germplasm_performance`, `brapi_get_germplasm`, `brapi_get_image`, `brapi_get_study`, `brapi_raw_get`, `brapi_raw_search`, `brapi_submit_observations`, plus the `brapi://variable/{observationVariableDbId}` resource.
 
 ```ts
 errors: [
@@ -219,7 +219,7 @@ Available factories include `notFound`, `validationError`, `forbidden`, `unautho
 
 ```text
 src/
-  index.ts                                # createApp() entry point — registers 21 tools, 5 resources, 2 prompts; inits 7 services
+  index.ts                                # createApp() entry point — registers 25 tools, 6 resources, 2 prompts; inits 7 services
   config/
     server-config.ts                      # BRAPI_* env vars (Zod schema, lazy-parsed)
     alias-credentials.ts                  # Per-alias env-var resolution (BRAPI_<ALIAS>_*) for brapi_connect
@@ -254,6 +254,9 @@ src/
         brapi-dataframe-query.tool.ts     # Run SQL across canvas dataframes (SELECT only); typed columns response
         brapi-dataframe-drop.tool.ts      # Drop a dataframe by name (opt-in via BRAPI_CANVAS_DROP_ENABLED)
         brapi-dataframe-export.tool.ts    # Write CSV/Parquet/JSON to BRAPI_EXPORT_DIR (opt-in, stdio-only)
+        brapi-build-phenotype-matrix.tool.ts  # Germplasm × trait matrix from studies; materialized as canvas dataframe
+        brapi-germplasm-performance.tool.ts   # Per-variable aggregates (n, mean, median, sd) for a single germplasm
+        brapi-export-genotype-matrix.tool.ts  # Genotype calls → germplasm × variant dataframe + VCF-lite / PLINK serialization
         brapi-submit-observations.tool.ts # Two-phase observation write — preview / apply (POST + PUT) with elicit gate
         brapi-raw-get.tool.ts             # Last-resort GET passthrough with routing nudge
         brapi-raw-search.tool.ts          # Last-resort POST /search passthrough with async polling
@@ -262,6 +265,9 @@ src/
         orientation-envelope.ts           # Shared envelope builder + formatter
         find-helpers.ts                   # Alias / loadLimit / extraFilters fragments, mergeFilters, maybeSpill, DataframeHandleSchema
         raw-routing-hints.ts              # Routing nudges emitted by raw_get / raw_search when a curated tool exists
+        canvas-columns.ts                 # SQL-safe column-name sanitizer + variableLegend builder (shared by matrix tools)
+        observations.ts                   # Study-anchored observation pull shared by phenotype-matrix and germplasm-performance
+        genotype-calls.ts                 # Async genotype-call collector shared by find-genotype-calls and export-genotype-matrix
     resources/
       definitions/
         brapi-server-info.resource.ts     # brapi://server/info — orientation envelope (default connection)
@@ -269,6 +275,7 @@ src/
         brapi-study.resource.ts           # brapi://study/{studyDbId} — single study with FKs
         brapi-germplasm.resource.ts       # brapi://germplasm/{germplasmDbId} — single germplasm with attributes + parents
         brapi-filters.resource.ts         # brapi://filters/{endpoint} — filter catalog
+        brapi-variable.resource.ts        # brapi://variable/{observationVariableDbId} — observation variable (trait, scale, method)
     prompts/
       definitions/
         brapi-eda-study.prompt.ts         # EDA playbook for one study (orient → variables → coverage → outliers → report)

package/README.md

@@ -1,13 +1,13 @@
 <div align="center">
   <h1>@cyanheads/brapi-mcp-server</h1>
   <p><b>A collaborative BrAPI v2.1 workspace for multi-agent research via MCP. Search studies, germplasm, genotypes, & more - across Breedbase, T3, Sweetpotatobase, & any BrAPI v2-compliant server.</b>
-  <div>22 Tools • 5 Resources • 2 Prompts • Multi-agent collaboration</div>
+  <div>25 Tools • 6 Resources • 2 Prompts • Multi-agent collaboration</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.6.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![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)
+[![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.7.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![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)
 
 </div>
 
@@ -23,7 +23,7 @@
 
 ## Tools
 
-22 tools grouped by shape — connection tools bootstrap a session, `find_*` tools return a summarized page plus distributions and spill overflow rows into a canvas dataframe that agents on the same session can query or hand off by ID, `get_*` tools fetch a single record with companion counts, plus pedigree walking, an embedded SQL workspace over spilled rows (DuckDB-backed), file export for human handoff, an additive write surface for observations, and raw passthrough escape hatches.
+25 tools grouped by shape — connection tools bootstrap a session, `find_*` tools return a summarized page plus distributions and spill overflow rows into a canvas dataframe that agents on the same session can query or hand off by ID, `get_*` tools fetch a single record with companion counts, plus pedigree walking, an embedded SQL workspace over spilled rows (DuckDB-backed), file export for human handoff, an additive write surface for observations, and raw passthrough escape hatches.
 
 ### Orient
 
@@ -58,6 +58,9 @@
 | `brapi_dataframe_query` | SELECT SQL across in-memory dataframes (DuckDB-backed). Spilled `find_*` rows auto-register as `df_<uuid>`. Read-only — multi-statement, non-SELECT, file-reads, and exports rejected. Returns typed columns (`{ name, type }[]`). |
 | `brapi_dataframe_drop` | _Opt-in via `BRAPI_CANVAS_DROP_ENABLED=true`._ Drop a dataframe by name. Idempotent. Dataframes also expire via TTL when left unmanaged. |
 | `brapi_dataframe_export` | _Opt-in via `BRAPI_EXPORT_DIR=<path>`, stdio-only._ Export a dataframe to disk (CSV / Parquet / JSON) under the configured directory and return the absolute path for the human to open. Optional `columns` projection or `sql` filter materializes a derived table for the export, dropped after. |
+| `brapi_build_phenotype_matrix` | Build a germplasm × trait matrix from one or more studies and materialize it as a canvas dataframe. Supports wide (pivot) or long shape with configurable per-cell aggregation. |
+| `brapi_germplasm_performance` | Per-variable performance aggregates (n, mean, median, sd, min, max, studyCount) for a single germplasm across all studies where it has observations. |
+| `brapi_export_genotype_matrix` | Export genotype calls for a variant set as a germplasm × variant canvas dataframe; also serializes to VCF-lite or PLINK `.ped`/`.map` text. |
 
 ### Write (opt-in: `BRAPI_ENABLE_WRITES=true`)
 
@@ -87,6 +90,7 @@ URI-addressable mirrors of the curated tool surface for clients that prefer reso
 | `brapi://study/{studyDbId}` | `brapi_get_study` |
 | `brapi://germplasm/{germplasmDbId}` | `brapi_get_germplasm` |
 | `brapi://filters/{endpoint}` | `brapi_describe_filters` |
+| `brapi://variable/{observationVariableDbId}` | Observation variable record (trait, scale, method, ontology) |
 
 ---
 
@@ -129,7 +133,7 @@ Within one (tenant, session), dataframes act as a self-cleaning shared notebook:
 - **Dialect adaptation** — `spec` / `brapi-test` / `breedbase` / `cassavabase` / `bms` dialects translate v2.1 plural filter keys to the singular form each server family honors, drop filters known to be broken, normalize sparse-shape encodings, and escalate to POST `/search/{noun}` when GET would silently downcast multi-value filters. Detected from `/serverinfo` (server-name / organization-name); pin per-alias via `BRAPI_<ALIAS>_DIALECT`. Verified-vs-inferred mapping counts surface on the orientation envelope so agents see the confidence floor at a glance.
 - **DuckDB required** — `@duckdb/node-api` is a regular dependency; startup fails closed when the framework canvas is unavailable. Not supported on Cloudflare Workers (no native binary in that runtime).
 - **Async-search transparency** — `brapi_find_genotype_calls` and `brapi_raw_search` handle the `POST /search/{noun}` → `GET /search/{noun}/{id}` 202-retry pattern automatically.
-- **Pedigree DAG walks** — `brapi_walk_pedigree` BFS-traverses ancestry / descendancy with cycle detection (BrAPI only exposes one generation per call).
+- **Pedigree DAG walks** — `brapi_walk_pedigree` BFS-traverses ancestry / descendancy with cycle detection (BrAPI only exposes one generation per call); a 1,000-node safety cap bounds the walk and sets `truncated` when reached.
 - **Image content** — `brapi_get_image` fetches bytes inline as MCP `type: image` blocks, preferring `/images/{id}/imagecontent` with `imageURL` fallback.
 - **Free-text variable ranking** — `OntologyResolver` scores variables against a query (PUI / name / synonym / trait-class) so `find_variables text:"..."` returns ranked candidates even without `/ontologies`.
 - **Auth variants in one schema** — tagged-union covers `none` / `bearer` / `api_key` / `sgn` (session-token exchange) / `oauth2` (client-credentials).
@@ -141,7 +145,7 @@ Built on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp
 
 ## Working with dataframes
 
-When a `find_*` tool's upstream total exceeds `loadLimit`, the full union materializes as a canvas dataframe and the response carries an inline `dataframe` handle (`{ tableName, rowCount, columns, createdAt, expiresAt, … }`). SQL is the paging idiom — use `LIMIT/OFFSET` to walk pages, projection (`SELECT col1, col2`) to trim columns, and aggregation (`COUNT`, `GROUP BY`, `AVG`) to summarize without materializing every row.
+When a `find_*` tool's upstream total exceeds `loadLimit`, the full union materializes as a canvas dataframe and the response carries an inline `dataframe` handle (`{ tableName, rowCount, columns, createdAt, expiresAt, … }`). Upstream column names that aren't SQL-safe identifiers — reserved words like `end`, digit-leading IDs — are sanitized for the dataframe, and a `columnLegend` on the handle maps each renamed column back to its original key. SQL is the paging idiom — use `LIMIT/OFFSET` to walk pages, projection (`SELECT col1, col2`) to trim columns, and aggregation (`COUNT`, `GROUP BY`, `AVG`) to summarize without materializing every row.
 
 Dataframe names are session-scoped capability tokens by default — pass `tableName` to any other agent on the same MCP session (or a downstream step in the same workflow) and they query the same workspace by name without re-pulling from the upstream. The `brapi_dataframe_*` tools offer SQL manipulation and more. See [Multi-agent workflows](#multi-agent-workflows) for cross-session / cross-tenant rules.
 
@@ -167,7 +171,7 @@ Add to your MCP client config — pick one runner:
 ```json
 {
   "mcpServers": {
-    "brapi": {
+    "brapi-mcp-server": {
       "type": "stdio",
       "command": "bunx",
       "args": ["@cyanheads/brapi-mcp-server@latest"],

package/changelog/0.7.x/0.7.0.md

@@ -0,0 +1,23 @@
+---
+summary: "phenotype matrix, germplasm performance, genotype export, observation variable resource"
+breaking: false
+security: false
+---
+
+# 0.7.0 — 2026-06-01
+
+## Added
+
+- **`brapi_build_phenotype_matrix`** — builds a germplasm × trait observation matrix from one or more studies and materializes it as a canvas dataframe. Supports wide (pivot) and long shape with configurable per-cell aggregation; wide-column names are SQL-safe identifiers with a `variableLegend` map back to display names. Study-anchored pull prefers `GET /observations?studyDbId`, falls back to observation-unit embedded observations then germplasm-anchored observations for servers where the `studyDbId` filter is unsupported. Shared observation-pull machinery with `brapi_germplasm_performance`. ([#8](https://github.com/cyanheads/brapi-mcp-server/issues/8))
+- **`brapi_germplasm_performance`** — per-variable performance aggregates (n, mean, median, sample sd, min, max, studyCount, studyDbIds, seasons) for a single germplasm across all studies where it has observations. Discovers candidate studies via `GET /studies?germplasmDbIds` with a dialect-honor cross-check that warns when a server silently ignores the filter. ([#9](https://github.com/cyanheads/brapi-mcp-server/issues/9))
+- **`brapi_export_genotype_matrix`** — exports genotype calls for a variant set as a germplasm × variant canvas dataframe (SQL-safe column names, `variantColumnLegend` map); also serializes to VCF-lite (`#CHROM POS ID REF ALT` + per-sample genotype columns) and PLINK (`.ped` + `.map`). Reuses `tools/shared/genotype-calls.ts` extracted from `brapi_find_genotype_calls`. ([#12](https://github.com/cyanheads/brapi-mcp-server/issues/12))
+- **`brapi://variable/{observationVariableDbId}`** resource — single observation-variable record (trait, scale, method, ontology) on the default connection via `GET /variables/{id}`. ([#14](https://github.com/cyanheads/brapi-mcp-server/issues/14))
+- **`tools/shared/canvas-columns.ts`** — SQL-safe column-name sanitizer and `variableLegend` / `variantColumnLegend` builder, shared by `brapi_build_phenotype_matrix` and `brapi_export_genotype_matrix`.
+- **`tools/shared/observations.ts`** — study-anchored observation pull shared by `brapi_build_phenotype_matrix` and `brapi_germplasm_performance`.
+- **`tools/shared/genotype-calls.ts`** — async genotype-call collector extracted from `brapi_find_genotype_calls`, shared by `brapi_export_genotype_matrix`.
+
+## Changed
+
+- **`brapi_find_genotype_calls`** refactored to consume `tools/shared/genotype-calls.ts`; behavior unchanged.
+- **`@duckdb/node-api`** `^1.5.3-r.2` → `^1.5.3-r.3`
+- **`vitest`** `^4.1.7` → `^4.1.8` (dev)

package/changelog/0.7.x/0.7.1.md

@@ -0,0 +1,17 @@
+---
+summary: "fix: find_* dataframe spillover survives reserved-word columns (end, order, etc.) via centralized sanitization; brapi_walk_pedigree now enforces its 1,000-node cap mid-traversal as a hard ceiling"
+breaking: false
+security: false
+---
+
+# 0.7.1 — 2026-06-01
+
+## Added
+
+- **`DataframeHandleSchema.columnLegend`** — optional `Record<string, string>` mapping each sanitized SQL column name back to its original upstream key (e.g. `end_` → `end`). Present only when one or more columns were renamed; absent otherwise. Surfaces in `brapi_dataframe_query`/`brapi_dataframe_describe` consumers so agents know which columns to reference in SQL. ([#37](https://github.com/cyanheads/brapi-mcp-server/issues/37))
+- **`brapi_walk_pedigree` truncation warning** — emits a warning when the 1,000-node cap cuts a walk short; `truncated: true` propagates to the result. ([#17](https://github.com/cyanheads/brapi-mcp-server/issues/17))
+
+## Fixed
+
+- **`find_*` dataframe spillover** no longer throws `Canvas column name "end" is a reserved SQL keyword` when an upstream row carries a reserved word or invalid identifier shape. Sanitization is centralized in `CanvasBridge.registerDataframe` via `sanitizeRowColumns`, covering germplasm, studies, observations, locations, images, variables, variants, and any future `find_*` tool automatically. ([#37](https://github.com/cyanheads/brapi-mcp-server/issues/37))
+- **`brapi_walk_pedigree` node cap** was enforced only at the start of each depth iteration; a single high-fan-out expansion could overshoot to ~4× the limit before the next check. The cap is now a hard per-registration ceiling enforced inside the expansion loop. ([#17](https://github.com/cyanheads/brapi-mcp-server/issues/17))

package/dist/index.js

@@ -46,6 +46,7 @@ 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 { brapiVariableResource } from './mcp-server/resources/definitions/brapi-variable.resource.js';
 import { dropToolDefinitions, exportToolDefinitions, readOnlyToolDefinitions, writeToolDefinitions, } from './mcp-server/tools/definitions/index.js';
 const serverConfig = getServerConfig();
 /**
@@ -100,6 +101,7 @@ await createApp({
         brapiCallsResource,
         brapiStudyResource,
         brapiGermplasmResource,
+        brapiVariableResource,
         brapiFiltersResource,
     ],
     prompts: [brapiEdaStudy, brapiMetaAnalysis],

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/resources/definitions/brapi-variable.resource.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview `brapi://variable/{observationVariableDbId}` — single
+ * observation-variable record on the default connection. The single-record,
+ * URI-addressable counterpart to `brapi_find_variables` (which returns a list
+ * envelope). Fills the resource gap alongside `brapi://study/{id}` and
+ * `brapi://germplasm/{id}`.
+ *
+ * Fetches the canonical `/variables/{observationVariableDbId}` payload directly
+ * (trait, scale, method, ontology) and returns it verbatim — mirroring how
+ * `brapi_get_germplasm` reads `/germplasm/{id}`. A 404 (or an empty record)
+ * surfaces as the typed `variable_not_found` error.
+ *
+ * @module mcp-server/resources/definitions/brapi-variable.resource
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const brapiVariableResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<z.ZodObject<{
+    observationVariableDbId: z.ZodString;
+}, z.core.$strip>, undefined, readonly [{
+    readonly reason: "unknown_alias";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No default BrAPI connection has been registered";
+    readonly recovery: "Call brapi_connect (without an alias, or with alias `default`) before reading this resource.";
+}, {
+    readonly reason: "variable_not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Upstream returned no observation variable record for the requested DbId";
+    readonly recovery: "Verify the observationVariableDbId on the target server, or run brapi_find_variables to discover valid IDs.";
+}]>;
+//# sourceMappingURL=brapi-variable.resource.d.ts.map

package/dist/mcp-server/resources/definitions/brapi-variable.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brapi-variable.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/brapi-variable.resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAQjE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;GA8EhC,CAAC"}

package/dist/mcp-server/resources/definitions/brapi-variable.resource.js

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview `brapi://variable/{observationVariableDbId}` — single
+ * observation-variable record on the default connection. The single-record,
+ * URI-addressable counterpart to `brapi_find_variables` (which returns a list
+ * envelope). Fills the resource gap alongside `brapi://study/{id}` and
+ * `brapi://germplasm/{id}`.
+ *
+ * Fetches the canonical `/variables/{observationVariableDbId}` payload directly
+ * (trait, scale, method, ontology) and returns it verbatim — mirroring how
+ * `brapi_get_germplasm` reads `/germplasm/{id}`. A 404 (or an empty record)
+ * surfaces as the typed `variable_not_found` error.
+ *
+ * @module mcp-server/resources/definitions/brapi-variable.resource
+ */
+import { resource, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { buildRequestOptions, isUpstreamNotFound, requireRegisteredConnection, } from '../../../mcp-server/tools/shared/find-helpers.js';
+import { getBrapiClient } from '../../../services/brapi-client/index.js';
+export const brapiVariableResource = resource('brapi://variable/{observationVariableDbId}', {
+    name: 'brapi-variable',
+    title: 'BrAPI observation variable record',
+    description: 'Single observation-variable resource on the default BrAPI connection — the canonical /variables/{id} record (trait, scale, method, ontology), addressable by URI. The single-record equivalent of brapi_find_variables.',
+    mimeType: 'application/json',
+    errors: [
+        {
+            reason: 'unknown_alias',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No default BrAPI connection has been registered',
+            recovery: 'Call brapi_connect (without an alias, or with alias `default`) before reading this resource.',
+        },
+        {
+            reason: 'variable_not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Upstream returned no observation variable record for the requested DbId',
+            recovery: 'Verify the observationVariableDbId on the target server, or run brapi_find_variables to discover valid IDs.',
+        },
+    ],
+    params: z.object({
+        observationVariableDbId: z
+            .string()
+            .min(1)
+            .describe('Observation variable identifier on the default connection.'),
+    }),
+    async handler(params, ctx) {
+        const client = getBrapiClient();
+        const connection = await requireRegisteredConnection(ctx, undefined);
+        const id = encodeURIComponent(params.observationVariableDbId);
+        let env;
+        try {
+            env = await client.get(connection.baseUrl, `/variables/${id}`, ctx, buildRequestOptions(connection, undefined, { singleton: true }));
+        }
+        catch (err) {
+            if (isUpstreamNotFound(err)) {
+                throw ctx.fail('variable_not_found', `Observation variable '${params.observationVariableDbId}' not found on ${connection.baseUrl}.`, {
+                    observationVariableDbId: params.observationVariableDbId,
+                    baseUrl: connection.baseUrl,
+                    ...ctx.recoveryFor('variable_not_found'),
+                }, { cause: err });
+            }
+            throw err;
+        }
+        const variable = env.result;
+        if (!variable ||
+            typeof variable !== 'object' ||
+            !variable.observationVariableDbId) {
+            throw ctx.fail('variable_not_found', `Observation variable '${params.observationVariableDbId}' not found on ${connection.baseUrl}.`, {
+                observationVariableDbId: params.observationVariableDbId,
+                baseUrl: connection.baseUrl,
+                ...ctx.recoveryFor('variable_not_found'),
+            });
+        }
+        return variable;
+    },
+    list: async () => ({
+        resources: [],
+    }),
+});
+//# sourceMappingURL=brapi-variable.resource.js.map

package/dist/mcp-server/resources/definitions/brapi-variable.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brapi-variable.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/brapi-variable.resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,GAC5B,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAElE,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAQ,CAAC,4CAA4C,EAAE;IAC1F,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,mCAAmC;IAC1C,WAAW,EACT,yNAAyN;IAC3N,QAAQ,EAAE,kBAAkB;IAC5B,MAAM,EAAE;QACN;YACE,MAAM,EAAE,eAAe;YACvB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,iDAAiD;YACvD,QAAQ,EACN,8FAA8F;SACjG;QACD;YACE,MAAM,EAAE,oBAAoB;YAC5B,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,yEAAyE;YAC/E,QAAQ,EACN,6GAA6G;SAChH;KACO;IACV,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,uBAAuB,EAAE,CAAC;aACvB,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,4DAA4D,CAAC;KAC1E,CAAC;IACF,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG;QACvB,MAAM,MAAM,GAAG,cAAc,EAAE,CAAC;QAChC,MAAM,UAAU,GAAG,MAAM,2BAA2B,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QACrE,MAAM,EAAE,GAAG,kBAAkB,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC;QAE9D,IAAI,GAAoE,CAAC;QACzE,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,MAAM,CAAC,GAAG,CACpB,UAAU,CAAC,OAAO,EAClB,cAAc,EAAE,EAAE,EAClB,GAAG,EACH,mBAAmB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAChE,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5B,MAAM,GAAG,CAAC,IAAI,CACZ,oBAAoB,EACpB,yBAAyB,MAAM,CAAC,uBAAuB,kBAAkB,UAAU,CAAC,OAAO,GAAG,EAC9F;oBACE,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;oBACvD,OAAO,EAAE,UAAU,CAAC,OAAO;oBAC3B,GAAG,GAAG,CAAC,WAAW,CAAC,oBAAoB,CAAC;iBACzC,EACD,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC;QAC5B,IACE,CAAC,QAAQ;YACT,OAAO,QAAQ,KAAK,QAAQ;YAC5B,CAAE,QAAoC,CAAC,uBAAuB,EAC9D,CAAC;YACD,MAAM,GAAG,CAAC,IAAI,CACZ,oBAAoB,EACpB,yBAAyB,MAAM,CAAC,uBAAuB,kBAAkB,UAAU,CAAC,OAAO,GAAG,EAC9F;gBACE,uBAAuB,EAAE,MAAM,CAAC,uBAAuB;gBACvD,OAAO,EAAE,UAAU,CAAC,OAAO;gBAC3B,GAAG,GAAG,CAAC,WAAW,CAAC,oBAAoB,CAAC;aACzC,CACF,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjB,SAAS,EAAE,EAAE;KACd,CAAC;CACH,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/brapi-build-phenotype-matrix.tool.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview `brapi_build_phenotype_matrix` — pull observations across one or
+ * more studies and pivot them into a germplasm × trait matrix materialized as a
+ * canvas dataframe. Returns a dataframe handle plus a summary of dimensions,
+ * aggregate method, and any warnings encountered during the pull.
+ *
+ * The per-study observation pull (with its `/observations` → `/observationunits`
+ * fallback chain) lives in `../shared/observations.ts`, shared with
+ * `brapi_germplasm_performance`.
+ *
+ * Column safety: wide-matrix column names are SQL-safe identifiers derived from
+ * `observationVariableDbId` via `../shared/canvas-columns.ts` — BrAPI DbIds are
+ * routinely numeric (Breedbase) or collide with reserved SQL words, both of
+ * which the canvas identifier gate rejects. A `variableLegend` mapping safe
+ * column → display name is returned so callers can resolve columns back.
+ *
+ * @module mcp-server/tools/definitions/brapi-build-phenotype-matrix.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const brapiBuildPhenotypeMatrix: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    alias: z.ZodOptional<z.ZodString>;
+    studies: z.ZodArray<z.ZodString>;
+    variables: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    germplasm: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    shape: z.ZodDefault<z.ZodEnum<{
+        wide: "wide";
+        long: "long";
+    }>>;
+    aggregate: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        mean: "mean";
+        median: "median";
+        first: "first";
+    }>>;
+    loadLimit: z.ZodOptional<z.ZodNumber>;
+    extraFilters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    alias: z.ZodString;
+    studies: z.ZodArray<z.ZodString>;
+    shape: z.ZodEnum<{
+        wide: "wide";
+        long: "long";
+    }>;
+    aggregate: z.ZodEnum<{
+        all: "all";
+        mean: "mean";
+        median: "median";
+        first: "first";
+    }>;
+    observationCount: z.ZodNumber;
+    germplasmCount: z.ZodNumber;
+    variableCount: z.ZodNumber;
+    variableLegend: z.ZodRecord<z.ZodString, z.ZodString>;
+    dataframe: z.ZodOptional<z.ZodObject<{
+        tableName: z.ZodString;
+        rowCount: z.ZodNumber;
+        columns: z.ZodArray<z.ZodString>;
+        columnLegend: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        createdAt: z.ZodString;
+        expiresAt: z.ZodString;
+        truncated: z.ZodOptional<z.ZodBoolean>;
+        maxRows: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    warnings: z.ZodArray<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "unknown_alias";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No connection has been registered under the requested alias";
+    readonly recovery: "Run brapi_connect with this alias (or omit `alias` to use the default connection) before calling brapi_build_phenotype_matrix.";
+}, {
+    readonly reason: "all_filters_dropped";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "The active dialect dropped every filter supplied — the call would silently widen to the unfiltered baseline";
+    readonly recovery: "Drop unsupported filters or use studies / germplasm / variables to scope the query to supported filter paths on the active dialect.";
+}, {
+    readonly reason: "no_observation_path";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Neither /observations nor /observationunits returned data for any requested study after probing both paths";
+    readonly recovery: "Verify the studyDbIds exist and the BrAPI server exposes /observations or /observationunits. Use brapi_server_info to inspect the capability list.";
+}], undefined>;
+//# sourceMappingURL=brapi-build-phenotype-matrix.tool.d.ts.map

package/dist/mcp-server/tools/definitions/brapi-build-phenotype-matrix.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brapi-build-phenotype-matrix.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/brapi-build-phenotype-matrix.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAoEjE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAgPpC,CAAC"}