@cyanheads/brapi-mcp-server

Herramientas

25 herramientas agrupadas por forma — las herramientas de conexión inician una sesión, las herramientas find_* devuelven una página resumida con distribuciones y vuelcan las filas sobrantes en un dataframe de canvas que los agentes de la misma sesión pueden consultar o transferir por ID, las herramientas get_* obtienen un único registro con recuentos asociados, además de recorrido de pedigrí, un espacio de trabajo SQL integrado sobre filas volcadas (respaldado por DuckDB), exportación de archivos para entrega a humanos, una superficie de escritura aditiva para observaciones y vías de escape de paso directo sin procesar.

Orientar

Recuperar

Analizar

Escribir (activación opcional: BRAPI_ENABLE_WRITES=true)

Vías de escape

Descubrimiento de alias. Los alias integrados y los configurados por el operador se añaden a la descripción de brapi_connect al iniciar el servidor, de modo que los agentes ven el inventario en tools/list. Reinicia después de cambiar las variables de entorno para actualizarlo.

Related MCP server: Helix MCP Server

Recursos

Espejos direccionables por URI de la superficie de herramientas seleccionadas para clientes que prefieren recursos. Todos los recursos usan la conexión predeterminada; los flujos de trabajo multiservidor se enrutan a través de las herramientas.

Indicaciones

Multi-step BrAPI workflow templates — pure user-message generators, no side effects.

Flujos de trabajo multiagente

El servidor tiene dos capas con estado y dos ejes de alcance:

Dentro de un mismo (tenant, sesión), los dataframes actúan como un cuaderno compartido que se autolimpia: pasa el nombre df_<uuid> entre agentes paralelos en la misma sesión MCP, consérvalo a lo largo de un flujo de trabajo de varios pasos, y consulta / proyecta / agrega / combina desde cualquier posición. Direccionamiento por nombre, con límite de tiempo y ámbito limitado a esa sesión.

Forma predeterminada (aislada). Con MCP_AUTH_MODE=none + HTTP con estado (el valor predeterminado), cada sesión MCP crea su propio estado de conexión y su propio lienzo. Dos investigadores conectados al mismo host no ven los alias brapi_connect del otro, ni los tokens SGN/OAuth intercambiados, ni las filas df_<uuid> volcadas. Stdio siempre se comporta como una sola sesión (proceso único, sin concurrencia).

Clientes en la revisión MCP 2026-07-28. Esa revisión no tiene sesión en ningún transporte: las solicitudes no llevan Mcp-Session-Id, por lo que ctx.sessionId no está definido y un cliente que la negocia recurre al espacio de trabajo compartido del tenant incluso con MCP_SESSION_MODE=stateful. El aislamiento de sesión se aplica a los clientes de la era 2025; los despliegues que necesiten un límite estricto para clientes de la era 2026 deberían crear tenants con MCP_AUTH_MODE=jwt/oauth.

Forma de espacio de trabajo compartido. Establece BRAPI_SESSION_ISOLATION=false para la colaboración entre sesiones en un mismo tenant: varias sesiones MCP comparten entonces el estado de conexión y un lienzo predeterminado, tal como se comportaban los despliegues anteriores a 0.5.3. Útil cuando los agentes de planificación, análisis y redacción se ejecutan como clientes MCP separados pero operan como un solo investigador con credenciales compartidas de origen.

Sobre datos privilegiados. El nombre df_<uuid> es un token de capacidad dentro de un lienzo, no un control de acceso a nivel de fila. Cualquiera que tenga el nombre dentro del mismo cubo (tenant, sesión) puede leer sus filas. Con el aislamiento predeterminado, ese cubo es una sesión MCP. Con BRAPI_SESSION_ISOLATION=false, el cubo se amplía a todo el tenant (todos los llamadores con auth=none, o las sesiones de un usuario con jwt/oauth). Trata los nombres de dataframe como enlaces de uso compartido autenticados: pásalos dentro del cubo, no externamente. El TTL de 24 h limita el radio de impacto; el rastro de procedencia (herramienta de origen, baseUrl, consulta) respalda la auditoría. Como refuerzo adicional: brapi_dataframe_describe exige un nombre dataframe explícito en HTTP de confianza compartida (sin enumeración de listado completo), y brapi_dataframe_query rechaza lecturas del catálogo del sistema (information_schema, pg_catalog, sqlite_master, duckdb_*), de modo que un llamador sin un nombre df_<uuid> conocido no puede sondear ninguna de las dos superficies.

Funciones específicas de BrAPI

• Desbordamiento de dataframes — las herramientas find_* limitan las filas en contexto a loadLimit y materializan uniones más grandes (hasta 50 000 filas / 50 páginas) como dataframes de lienzo df_<uuid> respaldados por DuckDB. Descúbrelos con brapi_dataframe_describe, consúltalos con brapi_dataframe_query (paginación SQL mediante LIMIT/OFFSET, proyección, agregación). Aplicación de solo lectura en la puerta SQL; ámbito de sesión por defecto (ámbito de tenant con BRAPI_SESSION_ISOLATION=false) — ver Flujos de trabajo multiagente.

• Sesión multiservidor — ServerRegistry asigna alias a conexiones BrAPI activas; una sesión puede abarcar Breedbase, T3 y Sweetpotatobase en paralelo.

• Registro integrado de servidores conocidos — bti-cassava, bti-sweetpotato, bti-breedbase-demo, t3-wheat, t3-oat, t3-barley se resuelven de serie sin variables de entorno; el sobre de orientación incluye la atribución CC-BY.

• Llamadas conscientes de capacidades — CapabilityRegistry almacena en caché /serverinfo por conexión y protege cada llamada de herramienta contra endpoints no admitidos. Recurre a /calls cuando /serverinfo es escaso.

• Adaptación de dialectos — los dialectos spec / brapi-test / breedbase / cassavabase / bms traducen las claves de filtro en plural de v2.1 a la forma singular que cada familia de servidores respeta, eliminan filtros que se sabe que están rotos, normalizan las codificaciones de forma dispersa y escalan a POST /search/{noun} cuando GET degradaría silenciosamente los filtros de valores múltiples. Se detecta desde /serverinfo (server-name / organization-name); se fija por alias mediante BRAPI_<ALIAS>_DIALECT. Los recuentos de mapeo verificado frente a inferido aparecen en el sobre de orientación para que los agentes vean de un vistazo el suelo de confianza.

• DuckDB requerido — @duckdb/node-api es una dependencia normal; el arranque falla de forma segura cuando el lienzo del framework no está disponible. No es compatible con Cloudflare Workers (no hay binario nativo en ese runtime).

• Transparencia de búsqueda asíncrona — brapi_find_genotype_calls y brapi_raw_search manejan automáticamente el patrón de reintento 202 de POST /search/{noun} → GET /search/{noun}/{id}.

• Recorridos DAG de pedigrí — brapi_walk_pedigree recorre en BFS la ascendencia / descendencia con detección de ciclos (BrAPI solo expone una generación por llamada); un límite de seguridad de 1000 nodos acota el recorrido y establece truncated al alcanzarlo. Los recorridos mayores que loadLimit vuelcan sus conjuntos de nodos y aristas a dos dataframes de lienzo combinables con JOIN y devuelven una vista previa en línea acotada.

• Contenido de imagen — brapi_get_image obtiene los bytes en línea como bloques MCP type: image, prefiriendo /images/{id}/imagecontent con respaldo a imageURL.

• Clasificación de variables por texto libre — OntologyResolver puntúa las variables frente a una consulta (PUI / nombre / sinónimo / clase de rasgo) para que find_variables text:"..." devuelva candidatos clasificados incluso sin /ontologies.

• Variantes de autenticación en un solo esquema — la unión etiquetada cubre none / bearer / api_key / sgn (intercambio de token de sesión) / oauth2 (credenciales de cliente).

• Contratos de error tipados — cada modo de fallo declarado lleva un data.reason estable, un code de estilo HTTP y un recovery.hint para que los clientes puedan enrutar de forma determinista.

Construido sobre @cyanheads/mcp-ts-core — definiciones declarativas, manejo de errores unificado, autenticación conectable (none / jwt / oauth), almacenamiento intercambiable, registro estructurado con OTel opcional, transportes STDIO + HTTP Streamable.

Trabajar con dataframes

Cuando el total upstream de una herramienta find_* supera loadLimit, la unión completa se materializa como un dataframe de lienzo y la respuesta incluye un identificador dataframe en línea ({ tableName, rowCount, columns, createdAt, expiresAt, … }). Los nombres de columna upstream que no son identificadores seguros para SQL — palabras reservadas como end, IDs que empiezan por dígitos — se sanean para el dataframe, y un columnLegend en el identificador asigna cada columna renombrada a su clave original. SQL es el idioma de paginación — usa LIMIT/OFFSET para recorrer páginas, proyección (SELECT col1, col2) para recortar columnas y agregación (COUNT, GROUP BY, AVG) para resumir sin materializar cada fila.

Los nombres de dataframe son tokens de capacidad con ámbito de sesión por defecto — pasa tableName a cualquier otro agente en la misma sesión MCP (o a un paso posterior del mismo flujo de trabajo) y consultarán el mismo espacio de trabajo por nombre sin volver a extraer datos del upstream. Las herramientas brapi_dataframe_* ofrecen manipulación SQL y más. Ver Flujos de trabajo multiagente para las reglas entre sesiones / entre tenants.

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

Los dataframes caducan automáticamente mediante TTL (BRAPI_DATASET_TTL_SECONDS, 24 h por defecto). Establece BRAPI_CANVAS_DROP_ENABLED=true para exponer brapi_dataframe_drop y permitir la limpieza explícita.

Primeros pasos

Añádelo a la configuración de tu cliente MCP — elige un ejecutor:

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

Sustituye command/args por npx -y @cyanheads/brapi-mcp-server@latest (sin Bun) o docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/brapi-mcp-server:latest.

Para Streamable HTTP:

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

No se requieren variables de entorno — los seis alias integrados (bti-cassava, bti-sweetpotato, bti-breedbase-demo, t3-wheat, t3-oat, t3-barley) se resuelven de serie, y los agentes pueden conectarse a cualquier otra URL de BrAPI v2 en tiempo de ejecución mediante brapi_connect. Para servidores con credenciales, prefiere las variables de entorno sobre la entrada del agente para que las contraseñas / tokens / claves de API no entren en el contexto del LLM — ver Credenciales por alias.

Requisitos previos: Bun v1.3.11+ o Node.js v24+. @duckdb/node-api es una dependencia obligatoria: compatible con Linux/macOS/Windows × x64, además de Linux/macOS arm64 (no Windows arm64; no Cloudflare Workers).

Configuración

Todas las variables son opcionales.

Las sobrescrituras por alias siguen el patrón BRAPI_<ALIAS>_*; consulte .env.example para ver cada sobrescritura y los comentarios en línea.

Credenciales por alias

brapi_connect resuelve baseUrl y auth a partir de variables de entorno cuando el agente las omite; las credenciales nunca entran en el contexto del LLM. Cuatro capas de precedencia:

1. Entrada explícita del agente — siempre gana.

2. Variables de entorno por alias — BRAPI_<ALIAS>_* (en mayúsculas, guiones → guiones bajos: my-server → BRAPI_MY_SERVER_*).

3. Registro integrado de servidores conocidos — consulte Alias integrados.

4. Variables de entorno predeterminadas — BRAPI_DEFAULT_*, solo cuando el alias difiere de default. No se superponen a una URL integrada — los valores predeterminados pertenecen al servidor predeterminado.

Cada alias lleva una familia de credenciales — el modo de autenticación se deriva de qué campos están establecidos:

Mezclar familias dentro de un alias lanza un 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

Entonces el agente llama a brapi_connect({ alias: 'bti-cassava' }) — sin baseUrl, sin auth, sin secretos en el prompt.

Alias integrados

El servidor incluye un registro curado de endpoints públicos de BrAPI v2. Cada uno se resuelve sin configuración adicional; la envoltura de orientación expone licencia, cita y página de inicio en su bloque attribution bajo Creative Commons Attribution.

Establece BRAPI_<ALIAS>_BASE_URL para reapuntar a un espejo de staging o un fork (la variable de entorno prevalece sobre la URL integrada — los guiones del alias se convierten en guiones bajos en la variable de entorno, así t3-wheat → BRAPI_T3_WHEAT_BASE_URL). Establece BRAPI_<ALIAS>_USERNAME, etc. para adjuntar credenciales sobre la URL integrada — cada instancia de Breedbase tiene su propia tabla de usuarios, por lo que el acceso de escritura requiere un registro separado en cada upstream. Usa BRAPI_BUILTIN_ALIASES_DISABLED=bti-cassava,t3-wheat para eliminar entradas específicas.

Cita: los seis alias integrados hacen referencia a Morales et al. 2022, "Breedbase: a digital ecosystem for modern plant breeding." G3 12(7): jkac078. doi:10.1093/g3journal/jkac078.

Ejecutar el servidor

# 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

Por defecto usa transporte HTTP, modo de sesión con estado (activa el ciclo de vida de mcp-session-id — requisito previo para BRAPI_SESSION_ISOLATION=true; la protección contra el secuestro de sesión requiere añadir MCP_AUTH_MODE=jwt|oauth encima), registra en /var/log/brapi-mcp-server. Las dependencias pares de OTel se instalan por defecto — --build-arg OTEL_ENABLED=false para omitirlas.

Formas de despliegue

brapi-mcp-server se ejecuta en tres formas — elige la que coincida con tu dominio de confianza. El factor diferenciador es lo que aísla el estado de conexión (alias registrados, tokens de upstream en caché) y los dataframes: nada, la sesión MCP o el tenant de autenticación.

Guía de selección de forma:

• HTTP público/institucional multiusuario, sin SSO. Usa el valor predeterminado por sesión. La sesión HTTP con estado de cada investigador está aislada aunque todos resuelvan a tenantId='default'.

• Multiusuario con SSO institucional. MCP_AUTH_MODE=jwt (HS256, MCP_AUTH_SECRET_KEY) u oauth (JWKS, OAUTH_ISSUER_URL + OAUTH_AUDIENCE). El claim tid de cada usuario crea un tenant — el ámbito externo. BRAPI_SESSION_ISOLATION=true (predeterminado) subdivide entonces dentro de cada tenant para usuarios que ejecutan sesiones paralelas, y la vinculación de identidad JWT/OAuth proporciona una protección real contra el secuestro de sesión encima.

• Un investigador, agentes paralelos. Si varios agentes (planificador, analista, redactor) se conectan como clientes MCP separados pero deben compartir un espacio de trabajo, establece BRAPI_SESSION_ISOLATION=false y confía en la confianza compartida. Esta es la forma de espacio de trabajo compartido.

• Stdio. Siempre hay una sesión; el aislamiento es irrelevante. La opción no tiene efecto.

• Clientes en la revisión de MCP 2026-07-28. Sin sesión por protocolo, por lo que aterrizan en el espacio de trabajo del tenant compartido diga lo que diga BRAPI_SESSION_ISOLATION. Solo la forma de credenciales por usuario los aísla.

Doble seguridad bajo confianza compartida. Incluso con BRAPI_SESSION_ISOLATION=false, brapi_dataframe_describe requiere un nombre dataframe explícito en HTTP (sin enumeración de listado completo), y brapi_dataframe_query rechaza lecturas del catálogo del sistema (information_schema, pg_catalog, sqlite_master, duckdb_*). El nombre del dataframe es el token de capacidad; la posesión lo demuestra.

Desarrollo

Consulta CLAUDE.md para conocer las reglas arquitectónicas completas. Versión resumida:

• Los handlers lanzan excepciones, el framework las captura — nada de try/catch en la lógica de las herramientas.

• Usa ctx.log para el registro, ctx.state para el almacenamiento — nada de console, nada de persistencia directa.

• Registra nuevas herramientas en el array tools de createApp() en src/index.ts.

• Envuelve las llamadas upstream: valida el raw → normaliza → devuelve el esquema de salida; nunca inventes campos que falten.

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

Se aceptan PRs.

Licencia

Apache-2.0 — consulta LICENSE.