@cyanheads/brapi-mcp-server

工具

25 个工具按形态分组——连接工具用于引导会话，find_* 工具返回汇总页面及分布信息，并将溢出行转存到画布数据帧中，同一会话中的智能体可按 ID 查询或交接这些数据；get_* 工具获取单条记录并附带关联计数；此外还有谱系遍历、基于溢出行的嵌入式 SQL 工作区（由 DuckDB 驱动）、供人工交接的文件导出、面向观测数据的增量写入接口，以及原始透传逃生通道。

定位

检索

分析

写入（选择启用：BRAPI_ENABLE_WRITES=true）

逃生通道

别名发现。 内置及运维配置的别名会在服务器启动时追加到 brapi_connect 的描述中，因此智能体可以在 tools/list 上看到清单。更改环境变量后请重启以刷新。

Related MCP server: Helix MCP Server

资源

为偏好资源的客户端提供的、可通过 URI 寻址的精选工具面镜像。所有资源均使用默认连接——多服务器工作流通过工具路由。

提示词

多步骤 BrAPI 工作流模板——纯用户消息生成器，无副作用。

多智能体工作流

服务器有两个有状态层和两个作用域轴：

在同一个（租户，会话）内，数据帧充当自清理的共享笔记本：将 df_<uuid> 名称在同一 MCP 会话的并行智能体之间传递，在多步骤工作流中持久化，并可从任意位置查询 / 投影 / 聚合 / 连接。按名称寻址、有时间限制、限定于该会话。

默认（隔离）形态。 在 MCP_AUTH_MODE=none + HTTP 有状态（默认）下，每个 MCP 会话都划分出自己的连接状态和自己的画布。连接到同一主机的两位研究者看不到彼此的 brapi_connect 别名、交换的 SGN/OAuth 令牌或溢出的 df_<uuid> 行。Stdio 始终表现为单个会话（单进程，无并发）。

使用 MCP 修订版 2026-07-28 的客户端。 该修订版在所有传输方式上都是无会话的——请求不携带 Mcp-Session-Id——因此 ctx.sessionId 为 undefined，协商该修订版的客户端即使处于 MCP_SESSION_MODE=stateful 下也会回退到共享的租户工作区。会话隔离适用于 2025 时代的客户端；需要为 2026 时代客户端提供硬边界的部署应使用 MCP_AUTH_MODE=jwt/oauth 划分租户。

共享工作区形态。 设置 BRAPI_SESSION_ISOLATION=false 可在单个租户内进行跨会话协作——多个 MCP 会话随后共享连接状态和一个默认画布，就像 0.5.3 之前的部署那样。当规划、分析和撰写智能体作为独立的 MCP 客户端运行、但以同一位研究者的身份使用共享的上游凭据操作时，这很有用。

关于特权数据。 df_<uuid> 名称是画布内的能力令牌——不是行级访问控制。在同一（租户，会话）桶内持有该名称的任何人都能读取其行。在默认隔离下，该桶就是一个 MCP 会话。在 BRAPI_SESSION_ISOLATION=false 下，桶扩大到整个租户（auth=none 下的所有调用者，或 jwt/oauth 下某位用户的所有会话）。请像对待经过身份验证的共享链接一样对待数据帧名称——只在桶内传递，不要外传。24 小时 TTL 限制了爆炸半径；来源追踪（发起工具、baseUrl、查询）支持审计。双保险：brapi_dataframe_describe 在共享信任的 HTTP 上要求显式的 dataframe 名称（不提供列出全部的枚举），brapi_dataframe_query 拒绝系统目录读取（information_schema、pg_catalog、sqlite_master、duckdb_*）——因此没有已知 df_<uuid> 名称的调用者无法通过这两个表面进行探测。

BrAPI 特有功能

• 数据帧溢出——find_* 工具将上下文内行数限制在 loadLimit，并将更大的并集（最多 50k 行 / 50 页）物化为由 DuckDB 支撑的 df_<uuid> 画布数据帧。用 brapi_dataframe_describe 发现，用 brapi_dataframe_query 查询（通过 LIMIT/OFFSET 进行 SQL 分页、投影、聚合）。在 SQL 网关处强制只读；默认按会话限定作用域（在 BRAPI_SESSION_ISOLATION=false 下按租户限定）——参见 多智能体工作流。

• 多服务器会话——ServerRegistry 将别名映射到实时的 BrAPI 连接；一个会话可以并行横跨 Breedbase、T3 和 Sweetpotatobase。

• 内置已知服务器注册表——bti-cassava、bti-sweetpotato、bti-breedbase-demo、t3-wheat、t3-oat、t3-barley 无需环境变量即可开箱即用地解析；定向信封携带 CC-BY 署名。

• 能力感知调用——CapabilityRegistry 按连接缓存 /serverinfo，并保护每个工具调用免受不支持端点的影响。当 /serverinfo 信息稀疏时回退到 /calls。

• 方言适配——spec / brapi-test / breedbase / cassavabase / bms 方言将 v2.1 复数过滤器键转换为每个服务器家族所认可的单数形式，丢弃已知有问题的过滤器，规范化稀疏形状编码，并在 GET 会静默降级多值过滤器时升级为 POST /search/{noun}。从 /serverinfo（server-name / organization-name）检测；通过 BRAPI_<ALIAS>_DIALECT 按别名固定。已验证与推断的映射计数会显示在定向信封上，让智能体一眼看到置信度下限。

• 需要 DuckDB——@duckdb/node-api 是常规依赖；当框架画布不可用时启动即失败关闭。在 Cloudflare Workers 上不受支持（该运行时没有原生二进制）。

• 异步搜索透明化——brapi_find_genotype_calls 和 brapi_raw_search 自动处理 POST /search/{noun} → GET /search/{noun}/{id} 的 202 重试模式。

• 系谱 DAG 遍历——brapi_walk_pedigree 使用 BFS 遍历祖先 / 后代，并带有循环检测（BrAPI 每次调用只暴露一代）；1,000 个节点的安全上限约束遍历，达到上限时设置 truncated。大于 loadLimit 的遍历会将其节点集和边集溢出到两个可 JOIN 的画布数据帧，并返回有界的内联预览。

• 图像内容——brapi_get_image 将字节以内联方式获取为 MCP type: image 块，优先使用 /images/{id}/imagecontent，并以 imageURL 作为回退。

• 自由文本变量排序——OntologyResolver 根据查询（PUI / 名称 / 同义词 / 性状类别）对变量打分，因此即使没有 /ontologies，find_variables text:"..." 也会返回排序后的候选。

• 单一 schema 中的认证变体——标签联合覆盖 none / bearer / api_key / sgn（会话令牌交换）/ oauth2（客户端凭据）。

• 类型化错误契约——每个声明的失败模式都带有稳定的 data.reason、HTTP 风格的 code 和 recovery.hint，以便客户端进行确定性路由。

基于 @cyanheads/mcp-ts-core 构建——声明式定义、统一错误处理、可插拔认证（none / jwt / oauth）、可替换存储、带可选 OTel 的结构化日志、STDIO + Streamable HTTP 传输。

使用数据帧

当 find_* 工具的上游总数超过 loadLimit 时，完整并集会物化为画布数据帧，响应会携带内联的 dataframe 句柄（{ tableName, rowCount, columns, createdAt, expiresAt, … }）。上游列名中不是 SQL 安全标识符的名称——如 end 之类的保留字、数字开头的 ID——会为数据帧进行净化，句柄上的 columnLegend 会将每个重命名的列映射回其原始键。SQL 是分页惯用法——使用 LIMIT/OFFSET 翻页，使用投影（SELECT col1, col2）裁剪列，使用聚合（COUNT、GROUP BY、AVG）进行汇总，而无需物化每一行。

数据帧名称默认是会话作用域的能力令牌——将 tableName 传递给同一 MCP 会话上的任何其他智能体（或同一工作流中的下游步骤），它们就能按名称查询同一工作区，而无需重新从上游拉取。brapi_dataframe_* 工具提供 SQL 操作等功能。跨会话 / 跨租户规则参见 多智能体工作流。

1. brapi_find_observations { studies: ["s-422"] }
   → first-page rows inline + dataframe.tableName = "df_<uuid>" (when totalCount > loadLimit)
2. brapi_dataframe_describe { dataframe: "df_<uuid>" }
   → schema + provenance (originating tool, baseUrl, query, expiry)
3. brapi_dataframe_query { sql: "SELECT germplasmName, value FROM df_<uuid> WHERE observationVariableDbId = 'V1' LIMIT 100" }
   → typed columns + bounded rows
4. brapi_dataframe_query { sql: "SELECT COUNT(*) AS n, AVG(CAST(value AS DOUBLE)) AS mean FROM df_<uuid> WHERE observationVariableDbId = 'V1'" }
   → aggregate without round-tripping all rows

数据帧通过 TTL 自动过期（BRAPI_DATASET_TTL_SECONDS，默认 24 小时）。设置 BRAPI_CANVAS_DROP_ENABLED=true 可暴露 brapi_dataframe_drop 以进行显式清理。

快速开始

添加到你的 MCP 客户端配置——选择一个运行器：

{
  "mcpServers": {
    "brapi-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/brapi-mcp-server@latest"],
      "env": { "MCP_TRANSPORT_TYPE": "stdio", "MCP_LOG_LEVEL": "info" }
    }
  }
}

将 command/args 替换为 npx -y @cyanheads/brapi-mcp-server@latest（无需 Bun）或 docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/brapi-mcp-server:latest。

对于 Streamable HTTP：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

无需任何环境变量——六个内置别名（bti-cassava、bti-sweetpotato、bti-breedbase-demo、t3-wheat、t3-oat、t3-barley）开箱即用地解析，智能体还可以在运行时通过 brapi_connect 连接到任何其他 BrAPI v2 URL。对于需要凭据的服务器，优先使用环境变量而非智能体输入，这样密码 / 令牌 / API 密钥就不会进入 LLM 上下文——参见 按别名凭据。

先决条件： Bun v1.3.11+ 或 Node.js v24+。@duckdb/node-api 是必需依赖——支持 Linux/macOS/Windows × x64 以及 Linux/macOS arm64（不支持 Windows arm64；不支持 Cloudflare Workers）。

配置

每个变量都是可选的。

每个别名的覆盖项遵循 BRAPI_<ALIAS>_* 模式 — 有关每个覆盖项及内联注释，请参阅 .env.example。

每个别名的凭据

当代理省略 baseUrl 和 auth 时，brapi_connect 会从环境变量中解析它们 — 凭据永远不会进入 LLM 上下文。有四层优先级：

1. 显式代理输入 — 始终优先。

2. 每个别名的环境变量 — BRAPI_<ALIAS>_*（大写，连字符 → 下划线：my-server → BRAPI_MY_SERVER_*）。

3. 内置已知服务器注册表 — 请参阅 内置别名。

4. 默认环境变量 — BRAPI_DEFAULT_*，仅当别名与 default 不同时。不会叠加在内置 URL 之上 — 默认值属于默认服务器。

在同一别名中混用不同认证族会抛出 ValidationError。

# .env — attach write credentials to the built-in 'bti-cassava' alias
BRAPI_BTI_CASSAVA_USERNAME=alice
BRAPI_BTI_CASSAVA_PASSWORD=...
# (BASE_URL omitted — built-in registry covers it)

# Static API key as alias 'prod'
BRAPI_PROD_BASE_URL=https://my-brapi.example.com/brapi/v2
BRAPI_PROD_API_KEY=...
BRAPI_PROD_API_KEY_HEADER=X-API-Key

然后智能体调用 brapi_connect({ alias: 'bti-cassava' }) —— 提示词中没有 baseUrl、没有 auth、没有密钥。

内置别名

服务器自带一份精选的公共 BrAPI v2 端点注册表。每个端点开箱即用；定向信封会在其 attribution 块中，以 Creative Commons Attribution 协议呈现许可证、引用信息和主页。

设置 BRAPI_<ALIAS>_BASE_URL 可将其重新指向暂存镜像或复刻（环境变量优先于内置 URL —— 别名中的连字符在环境变量中会变成下划线，因此 t3-wheat → BRAPI_T3_WHEAT_BASE_URL）。设置 BRAPI_<ALIAS>_USERNAME 等变量可在内置 URL 之上附加凭据 —— 每个 Breedbase 实例都有自己的用户表，因此写访问需要在每个上游分别注册。使用 BRAPI_BUILTIN_ALIASES_DISABLED=bti-cassava,t3-wheat 可移除特定条目。

引用： 全部六个内置别名均引用 Morales 等人 2022 年的论文 "Breedbase: a digital ecosystem for modern plant breeding." G3 12(7): jkac078. doi:10.1093/g3journal/jkac078。

运行服务器

# Hot-reload dev (Bun runs TS directly)
bun --watch src/index.ts

# Production
bun run rebuild
bun run start            # transport via MCP_TRANSPORT_TYPE (stdio default)
bun run start:stdio      # or pin explicitly
bun run start:http

# Checks
bun run devcheck         # lint + format + typecheck + security + changelog sync
bun run test             # Vitest
bun run lint:mcp         # validate MCP definitions

Docker

docker build -t brapi-mcp-server .
docker run --rm -p 3010:3010 brapi-mcp-server

默认采用 HTTP 传输、有状态会话模式（启用 mcp-session-id 生命周期 —— 这是 BRAPI_SESSION_ISOLATION=true 的前提；劫持防护还需在其上叠加 MCP_AUTH_MODE=jwt|oauth），日志写入 /var/log/brapi-mcp-server。OTel 对等依赖默认安装 —— 传入 --build-arg OTEL_ENABLED=false 可将其省略。

部署形态

brapi-mcp-server 以三种形态运行 —— 选择与你的信任域相匹配的一种。其区别在于由什么来隔离连接状态（已注册的别名、缓存的上游令牌）和数据帧：无隔离、MCP 会话，或认证租户。

形态选择指南：

• 多用户公共/机构 HTTP，无 SSO。 使用按会话的默认形态。每位研究者的有状态 HTTP 会话都被隔离，即使他们都解析到 tenantId='default'。

• 带机构 SSO 的多用户。 MCP_AUTH_MODE=jwt（HS256，MCP_AUTH_SECRET_KEY）或 oauth（JWKS，OAUTH_ISSUER_URL + OAUTH_AUDIENCE）。每个用户的 tid 声明划分一个租户 —— 即外层作用域。BRAPI_SESSION_ISOLATION=true（默认）随后在运行并行会话的用户的各租户内部进一步划分子作用域，而 JWT/OAuth 身份绑定在此基础上提供真正的会话劫持防护。

• 一位研究人员，并行智能体。 如果多个智能体（规划、分析、撰写）作为独立的 MCP 客户端连接，但应共享同一个工作区，请设置 BRAPI_SESSION_ISOLATION=false 并依赖共享信任。这就是共享工作区形态。

• Stdio。 始终只有一个会话；隔离无从谈起。该标志不起作用。

• 使用 MCP 修订版 2026-07-28 的客户端。 按协议无会话，因此无论 BRAPI_SESSION_ISOLATION 如何设置，它们都会落入共享租户工作区。只有按用户凭据形态能对它们进行隔离。

共享信任下的双保险。 即使设置了 BRAPI_SESSION_ISOLATION=false，brapi_dataframe_describe 在 HTTP 上也要求显式提供 dataframe 名称（不支持列出全部的枚举），并且 brapi_dataframe_query 拒绝读取系统目录（information_schema、pg_catalog、sqlite_master、duckdb_*）。数据帧名称就是能力令牌；拥有它即证明具备该能力。

开发

完整的架构规则见 CLAUDE.md。简版如下：

• 处理器抛出异常，框架负责捕获 —— 工具逻辑中不使用 try/catch

• 使用 ctx.log 记录日志，使用 ctx.state 存储 —— 不使用 console，不直接持久化

• 在 src/index.ts 的 createApp() 的 tools 数组中注册新工具

• 包装上游调用：校验原始数据 → 规范化 → 返回输出模式；绝不捏造缺失字段

git clone https://github.com/cyanheads/brapi-mcp-server.git
cd brapi-mcp-server
bun install
cp .env.example .env       # edit if you need credentials
bun run devcheck && bun run test

欢迎提交 PR。

许可证

Apache-2.0 —— 见 LICENSE。