@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 워크플로 템플릿 — 순수 사용자 메시지 생성기, 부작용 없음.

멀티에이전트 워크플로

서버에는 두 개의 상태 저장 계층과 두 개의 범위 지정 축이 있습니다:

하나의 (테넌트, 세션) 내에서 데이터프레임은 자체 정리 공유 노트북 역할을 합니다. 동일한 MCP 세션의 병렬 에이전트 간에 df_<uuid> 이름을 전달하고, 다단계 워크플로 전반에 걸쳐 유지하며, 어느 위치에서든 쿼리/프로젝션/집계/조인할 수 있습니다. 이름으로 주소를 지정하고, 시간 제한이 있으며, 해당 세션으로 범위가 한정됩니다.

기본(격리) 형태. MCP_AUTH_MODE=none + HTTP stateful(기본값)에서 각 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로 쿼리합니다(SQL 페이징 via LIMIT/OFFSET, 프로젝션, 집계). 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 블록으로 인라인 가져오며, imageURL 폴백과 함께 /images/{id}/imagecontent를 우선합니다.

• 자유 텍스트 변수 순위 지정 — OntologyResolver는 쿼리(PUI / 이름 / 동의어 / 형질 클래스)에 대해 변수에 점수를 매겨 /ontologies 없이도 find_variables text:"..."가 순위가 매겨진 후보를 반환합니다.

• 하나의 스키마에 담긴 인증 변형 — 태그된 유니온은 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)로 모든 행을 구체화하지 않고 요약하세요.

데이터프레임 이름은 기본적으로 세션 범위의 기능 토큰입니다. 동일한 MCP 세션의 다른 에이전트(또는 동일 워크플로의 다운스트림 단계)에 tableName을 전달하면 업스트림에서 다시 가져오지 않고 이름으로 동일한 워크스페이스를 쿼리합니다. 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

환경 변수는 필요하지 않습니다. 내장된 6개 별칭(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을 참조하세요.

별칭별 자격 증명

brapi_connect는 에이전트가 이를 생략할 때 환경 변수에서 baseUrl과 auth를 확인합니다 — 자격 증명은 LLM 컨텍스트에 절대 들어가지 않습니다. 네 가지 우선순위 계층:

1. 명시적 에이전트 입력 — 항상 우선합니다.

2. 별칭별 환경 변수 — BRAPI_<ALIAS>_* (대문자, 하이픈 → 밑줄: my-server → BRAPI_MY_SERVER_*).

3. 내장 알려진 서버 레지스트리 — 내장 별칭 참조.

4. 기본 환경 변수 — BRAPI_DEFAULT_*, 별칭이 default와 다를 때만. 내장 URL 위에 계층화되지 않음 — 기본값은 기본 서버에 속합니다.

각 별칭은 하나의 자격 증명 패밀리를 가집니다 — 인증 모드는 어떤 필드가 설정되었는지에서 파생됩니다:

하나의 alias 안에서 계열을 혼용하면 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도, 비밀 정보도 없습니다.

기본 제공 alias

서버는 선별된 공개 BrAPI v2 엔드포인트 레지스트리를 기본 제공합니다. 각 엔드포인트는 별도 설정 없이 바로 동작하며, orientation envelope은 Creative Commons Attribution 하에 attribution 블록에 라이선스, 인용 정보, 홈페이지를 표시합니다.

BRAPI_<ALIAS>_BASE_URL을 설정하면 스테이징 미러나 포크를 가리키도록 변경할 수 있습니다(환경 변수가 기본 제공 URL보다 우선하며, alias의 하이픈은 환경 변수에서 밑줄이 되므로 t3-wheat → BRAPI_T3_WHEAT_BASE_URL). BRAPI_<ALIAS>_USERNAME 등을 설정하면 기본 제공 URL 위에 자격 증명을 추가할 수 있습니다. 각 Breedbase 인스턴스는 고유한 사용자 테이블을 가지므로 쓰기 액세스에는 각 업스트림에 별도로 등록해야 합니다. BRAPI_BUILTIN_ALIASES_DISABLED=bti-cassava,t3-wheat를 사용하면 특정 항목을 제거할 수 있습니다.

인용: 기본 제공 6개 엔드포인트 모두 Morales et al. 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는 세 가지 형태로 실행됩니다. 신뢰 도메인에 맞는 형태를 선택하세요. 차별점은 연결 상태(등록된 alias, 캐시된 업스트림 토큰)와 dataframe을 무엇으로 격리하느냐입니다. 즉, 격리하지 않음, MCP 세션, 또는 인증 테넌트입니다.

형태 선택 가이드:

• SSO가 없는 다중 사용자 공개/기관 HTTP. 세션별 기본값을 사용하세요. 모든 연구자가 tenantId='default'로 해석되더라도 각 연구자의 상태 저장 HTTP 세션은 격리됩니다.

• 기관 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_*)를 거부합니다. dataframe 이름이 곧 capability 토큰이며, 소유가 이를 증명합니다.

개발

전체 아키텍처 규칙은 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 참조.