---
summary: "Phase 3 tool surface — 7 read-side BrAPI tools (connect, server_info, describe_filters, find/get studies & germplasm) plus ServerRegistry for session-scoped multi-server workflows and a static BrAPI v2.1 filter catalog."
breaking: false
---

# 0.1.1 — 2026-04-23

Phase 3 of the BrAPI MCP surface lands the first read-side tools end-to-end and the final service needed to run them. Agents can now connect to a BrAPI v2 server, orient against the capability profile, and drive studies / germplasm workflows without hitting `raw_get`.

## Added

- **`ServerRegistry` service** (`src/services/server-registry/`) — session-scoped alias map that resolves connection auth (none / bearer / api_key / sgn-password-exchange) and persists each registration under the tenant's `ctx.state`. OAuth2 is accepted at the schema level but rejected at runtime pending a proper client-credentials flow.
- **BrAPI filter catalog** (`src/services/brapi-filters/`) — static v2.1 filter descriptors for `studies`, `germplasm`, `variables`, `observations`, `images`, `variants`, and `locations`, each paired with a spec-reference URL. Drives dynamic discovery for the `extraFilters` passthrough.
- **Phase 3 tools** — 7 read-side tools registered in `createApp()`:
  - `brapi_connect` — authenticate, register an alias, load the capability profile, and inline the orientation envelope.
  - `brapi_server_info` — on-demand orientation envelope for any registered alias (`forceRefresh` bypasses cache).
  - `brapi_describe_filters` — filter catalog lookup per endpoint with a discovery list of every available endpoint.
  - `brapi_find_studies` / `brapi_find_germplasm` — single-page fetch with distributions, refinement hints, and `DatasetStore` spillover when the upstream total exceeds `loadLimit` (capped at 50k rows / 50 pages per call).
  - `brapi_get_study` — single study with program / trial / location FKs resolved via `ReferenceDataCache` plus `pageSize=0` probes for observation / observation-unit / variable counts.
  - `brapi_get_germplasm` — single germplasm with attributes, direct parents, and companion counts (study count, parent count, direct descendant count).
- **Shared tool helpers** — `connect-auth-schema.ts` (Zod discriminated union mirroring `ConnectAuth`), `orientation-envelope.ts` (the shared envelope builder + markdown formatter for `brapi_connect` and `brapi_server_info`), and `find-helpers.ts` (alias / loadLimit / extraFilters input fragments, `mergeFilters`, `computeDistribution`, `loadInitialPage`, `spillToDataset`).
- **End-to-end tool tests** — `tests/tools/` covers every tool handler against a dependency-injected fetcher, plus a dedicated `ServerRegistry` unit test suite covering alias validation, URL normalization, and SGN token exchange.

## Changed

- **Dependencies** — `@cyanheads/mcp-ts-core` ^0.6.14 → ^0.6.15; `@biomejs/biome` ^2.4.7 → ^2.4.13; `tsx` ^4.19.0 → ^4.21.0; `typescript` ^5.9.3 → ^6.0.3; `vitest` ^4.1.0 → ^4.1.5.
- **`skills/security-pass`** — synced to v1.1 with mcp-ts-core 0.6.15 (expanded to cover resources, prompts, descriptions, sampling / roots / elicit response validation, HTTP deployment surface, constant-time comparisons, and parse size/depth limits).