@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ワークフローテンプレート — 純粋なユーザーメッセージ生成器であり、副作用はありません。

マルチエージェントワークフロー

サーバーには2つのステートフルなレイヤーと2つのスコープ軸があります。

1つの（テナント、セッション）内では、データフレームは自己クリーニング型の共有ノートブックとして機能します。同じMCPセッション上の並行エージェント間で df_<uuid> 名を渡し、マルチステップのワークフロー全体で永続化し、任意の位置からクエリ/射影/集約/結合を行えます。名前によるアドレス指定、時間制限付き、そのセッションにスコープされます。

デフォルト（分離）の形状。 MCP_AUTH_MODE=none + HTTPステートフル（デフォルト）では、各MCPセッションが独自の接続状態と独自のキャンバスを切り分けます。同じホストに接続した2人の研究者は、互いの brapi_connect エイリアス、交換されたSGN/OAuthトークン、または書き出された df_<uuid> 行を見ることはできません。Stdioは常に1つのセッションとして動作します（シングルプロセス、並行性なし）。

MCPリビジョン2026-07-28のクライアント。 そのリビジョンはすべてのトランスポートでセッションレスです。リクエストは Mcp-Session-Id を運ばないため、ctx.sessionId は未定義になり、それをネゴシエートするクライアントは MCP_SESSION_MODE=stateful であっても共有テナントワークスペースにフォールバックします。セッション分離は2025年世代のクライアントに適用されます。2026年世代のクライアントに厳格な境界が必要なデプロイメントでは、MCP_AUTH_MODE=jwt/oauth でテナントを切り分ける必要があります。

共有ワークスペースの形状。 1つのテナント内でのクロスセッションコラボレーションには BRAPI_SESSION_ISOLATION=false を設定します。これにより、複数のMCPセッションが接続状態と1つのデフォルトキャンバスを共有します。これはpre-0.5.3デプロイメントの動作と同じです。プランニング、分析、レポート作成のエージェントが別々のMCPクライアントとして実行される一方で、共有された上流の資格情報を使って1人の研究者として動作する場合に有用です。

特権データについて。 df_<uuid> 名はキャンバス内のケイパビリティトークンであり、行レベルのアクセス制御ではありません。同じ（テナント、セッション）バケット内でその名前を保持している人は誰でもその行を読むことができます。デフォルトの分離では、そのバケットは1つのMCPセッションです。BRAPI_SESSION_ISOLATION=false では、バケットはテナント全体に広がります（auth=none の場合はすべての呼び出し元、jwt/oauth の場合は1人のユーザーのセッション）。データフレーム名は認証済み共有リンクのように扱ってください。バケット内でのみ渡し、外部には渡さないでください。24時間のTTLが爆発半径を制限し、来歴トレイル（発信元ツール、baseUrl、クエリ）が監査を支援します。二重の安全策として、brapi_dataframe_describe は共有信頼HTTP上で明示的な dataframe 名を要求し（全件列挙は不可）、brapi_dataframe_query はシステムカタログの読み取り（information_schema、pg_catalog、sqlite_master、duckdb_*）を拒否するため、既知の df_<uuid> 名を持たない呼び出し元はどちらの表面からも探索できません。

BrAPI固有の機能

• データフレームのスピルオーバー — find_* ツールはコンテキスト内の行を loadLimit で上限し、より大きなユニオン（最大5万行/50ページ）をDuckDBバックエンドの df_<uuid> キャンバスデータフレームとして具体化します。brapi_dataframe_describe で発見し、brapi_dataframe_query でクエリします（LIMIT/OFFSET によるSQLページング、射影、集約）。SQLゲートで読み取り専用を強制し、デフォルトではセッションスコープです（BRAPI_SESSION_ISOLATION=false ではテナントスコープ）— マルチエージェントワークフロー を参照。

• マルチサーバーセッション — ServerRegistry はエイリアスをライブなBrAPI接続にマッピングします。1つのセッションで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世代しか公開しません）。1,000ノードの安全上限がウォークを制限し、到達すると truncated を設定します。loadLimit より大きいウォークは、ノードセットとエッジセットを2つのJOIN可能なキャンバスデータフレームにスピルし、制限付きのインラインプレビューを返します。

• 画像コンテンツ — brapi_get_image はバイトをMCPの type: image ブロックとしてインラインで取得し、/images/{id}/imagecontent を優先し、imageURL にフォールバックします。

• フリーテキスト変数ランキング — OntologyResolver はクエリ（PUI / 名前 / 同義語 / 形質クラス）に対して変数をスコアリングするため、find_variables text:"..." は /ontologies がなくてもランク付けされた候補を返します。

• 1つのスキーマでの認証バリアント — タグ付きユニオンは 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_dataframe_drop を公開するには、BRAPI_CANVAS_DROP_ENABLED=true を設定します。

はじめに

MCPクライアント設定に追加します。ランナーを1つ選んでください:

{
  "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コンテキストに入ることはありません。優先順位は4層です：

1. 明示的なエージェント入力 — 常に優先されます。

2. エイリアスごとの環境変数 — BRAPI_<ALIAS>_*（大文字に変換、ハイフンはアンダースコアに：my-server → BRAPI_MY_SERVER_*）。

3. 組み込みの既知サーバーレジストリ — 組み込みエイリアス を参照。

4. デフォルト環境変数 — BRAPI_DEFAULT_*。エイリアスが default と異なる場合のみ。組み込みURLの上に重ねられません。デフォルトはデフォルトサーバーに属します。

各エイリアスは 1つ の認証情報ファミリーを持ちます。認証モードはどのフィールドが設定されているかから導出されます：

エイリアス内でファミリーを混在させると 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 ブロックにライセンス、引用、ホームページを表示します。

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 を使用すると、特定のエントリを削除できます。

引用: 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 は 3 つの形態で動作します — 信頼ドメインに合うものを選択してください。違いは、接続状態（登録済みエイリアス、キャッシュされたアップストリームトークン）とデータフレームを何で分離するかです：何もしない、MCP セッション、または認証テナントです。

形態選択ガイド:

• SSO なしのマルチユーザー公開・機関 HTTP。 セッションごとのデフォルトを使用します。各研究者のステートフル 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 アイデンティティバインディングがその上に真のセッションハイジャック保護を提供します。

• 1 人の研究者、並列エージェント。 複数のエージェント（プランナー、アナリスト、レポート作成）が別々の MCP クライアントとして接続するが、1 つのワークスペースを共有する必要がある場合、BRAPI_SESSION_ISOLATION=false を設定し、共有信頼に依存します。これが共有ワークスペース形態です。

• Stdio。 常に 1 セッション。分離は無意味です。このフラグは効果がありません。

• 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 を参照してください。