brapi-mcp-server

---

概要

あらゆる BrAPI（Breeding API）v2 サーバーからの作物育種データに対応します。Cassavabase や Sweetpotatobase のような Breedbase インスタンス、Triticeae Toolbox（T3）などを、一度に複数利用できます。試験、遺伝資源、観察データ、遺伝子型を検索し、系譜をたどり、表現型および遺伝子型の行列を構築できます。また、大規模な結果は SQL でクエリできます。

ツール

ツール	説明
brapi_connect	BrAPI v2 サーバーに認証し、エイリアスを登録して、オリエンテーションエンベロープを返します
brapi_server_info	エイリアスのオリエンテーションエンベロープを返します。必要に応じてケイパビリティを更新します
brapi_describe_filters	エンドポイントで有効なフィルター名を一覧表示します。各検索ツールの extraFilters で使用します
brapi_find_studies	作物、試験タイプ、シーズン、場所、またはプログラムで試験を検索します
brapi_get_study	プログラム、試験、場所を解決し、関連件数も含めて試験を取得します
brapi_find_germplasm	名前、別名、アクセッション、PUI、作物、またはフリーテキストで遺伝資源を検索します
brapi_get_germplasm	属性、直接の親、および関連件数を含めて遺伝資源を取得します
brapi_walk_pedigree	サイクルを検出しながら、重複を排除した DAG として祖先または子孫をたどります
brapi_find_variables	名前、形質クラス、またはオントロジー用語で観測変数を検索し、フリーテキストでランキングします
brapi_find_observations	試験、遺伝資源、変数、シーズン、または単位で観測レコードを取得します
brapi_find_images	単位、観測、試験、オントロジー用語、または MIME タイプで画像メタデータを検索します
brapi_get_image	最大5枚の画像をインラインの画像コンテンツブロックとして取得します
brapi_find_locations	国、タイプ、略称、またはバウンディングボックスで研究ステーションを検索します
brapi_find_variants	バリアントセット、参照配列、またはゲノム領域でバリアントを検索します
brapi_find_genotype_calls	デプロイごとの取得上限内で、非同期検索を通じて遺伝子型コールを取得します
brapi_dataframe_describe	データフレームを一覧表示するか、列、行数、出所を含めて1つのデータフレームを説明します
brapi_dataframe_query	データフレーム全体に対して読み取り専用の SQL を実行します
brapi_dataframe_drop	オプトイン。 名前を指定してデータフレームを削除します
brapi_dataframe_export	オプトイン、stdio 専用。 データフレームを CSV、Parquet、または JSON としてディスクにエクスポートします
brapi_build_phenotype_matrix	1つ以上の試験から遺伝資源 × 形質の行列をデータフレームとして構築します
brapi_germplasm_performance	遺伝資源1つについて、その各試験の変数ごとの集計値（n、平均値、中央値、sd、最小値、最大値）を算出します
brapi_export_genotype_matrix	バリアントセットのコールを遺伝資源 × バリアントの行列にピボットし、VCF-lite または PLINK テキストで出力します
brapi_submit_observations	オプトイン。 2段階の観測書き込みです。preview で検証し、apply で確定して書き込みます
brapi_raw_get	用意されたツールがカバーしていない任意の GET /{path} エンドポイントへのパススルーです
brapi_raw_search	任意の POST /search/{noun} エンドポイントへのパススルーです。非同期ポーリングも処理します

リソース

リソース	説明
brapi://server/info	デフォルト接続のオリエンテーションエンベロープ
brapi://calls	デフォルト接続の生のケイパビリティプロファイル（/serverinfo + /calls）
brapi://study/{studyDbId}	プログラム、試験、場所を解決した1つの試験
brapi://germplasm/{germplasmDbId}	属性と親を含む1つの遺伝資源
brapi://filters/{endpoint}	1つのエンドポイントのフィルターカタログ
brapi://variable/{observationVariableDbId}	1つの観測変数（形質、尺度、方法、オントロジー）

すべてのリソースは default 接続を読み取り、ツールに対応しています。ツール専用のクライアントや複数サーバーを使うワークフローでは、ツールを使用します。

プロンプト

プロンプト	説明
brapi_eda_study	構造化レポートで締めくくる、1つの試験を対象とした探索的データ分析の手順書
brapi_meta_analysis	遺伝資源 × 形質の組み合わせを対象とした、試験横断的なメタ分析の手順書

ケイパビリティのリファレンス

識別子フィルターでは、同等の BrAPI *DbId / *DbIds 表記も使用できます。たとえば、imageDbIds に対する imageDbId、studies に対する studyDbIds、variables に対する observationVariableDbIds です。配列フィルターには、単独の文字列または複数の ID を指定できます。各フィルターには1つの表記のみ指定してください。競合する表記は拒否されます。

brapi_connect _ツール

• baseUrl と auth は省略可能です。省略した値は、環境変数 BRAPI_<ALIAS>_*、組み込みエイリアス、次に BRAPI_DEFAULT_* から取得されます（エイリアスごとの認証情報を参照）。alias（デフォルトは default、パターンは ^[a-zA-Z0-9_-]+$）を使うと、複数のサーバーを同時に登録できます。auth.mode は none、bearer、api_key、sgn（Breedbase の /token とのトークン交換）、または oauth2（クライアントクレデンシャル）です。
• オリエンテーションエンベロープを返します。内容は、server の識別情報、auth の概要、capabilities（supported、notableGaps）、有効な dialect、content の件数、組み込みサーバーの attribution、およびこのサーバーが対応できるエントリーポイント検索ツールを示す nextToolSuggestions です。
• 型付きエラー：auth_session_required、auth_base_url_mismatch、alias_base_url_unset、alias_base_url_invalid、private_address_blocked、auth_token_exchange_failed、auth_no_access_token、upstream_unauthorized、upstream_forbidden、capability_discovery_unavailable（再試行可能）。接続に失敗しても、そのエイリアスに以前登録されていた内容は保持されます。
• サーバーの URL が設定されているエイリアス（BRAPI_DEFAULT_BASE_URL が設定されている場合の default、組み込みエイリアス、または BRAPI_<ALIAS>_BASE_URL が設定されているエイリアス）では省略できます。ほかのツールまたはリソースが初回使用時に接続します。これは baseUrl も auth も指定せずに brapi_connect を呼び出した場合と同じ動作であり、同時に行われた初回呼び出しでは接続が共有されます。独自の URL が設定されていないエイリアスは、BRAPI_DEFAULT_* が設定されていても unknown_alias で失敗するため、入力を誤ったエイリアスがデフォルトサーバーに接続されることはありません。これらのツールとリソースは、発生しうる接続エラー（上記のトークン、ディスカバリー、認証ウォール、alias_base_url_invalid、private_address_blocked の各エラー）と、それぞれの復旧ヒントを宣言します。

---

brapi_server_info _ツール

• alias は省略可能です。forceRefresh（デフォルトは false）を指定すると、キャッシュを読み込まずにケイパビリティプロファイルを再取得します。
• brapi_connect と同じオリエンテーションエンベロープを返します。

---

brapi_describe_filters _ツール

• endpoint は studies、germplasm、observations、variables、images、variants、locations のいずれかです。unknown_endpoint には availableEndpoints が含まれます。
• 各フィルターには name、type、description、example が含まれます。カタログは v2.1 仕様に準拠しており、各サーバーが対応するのはその一部である場合があります。

---

brapi_find_studies _ツール

• フィルター：crop、trialTypes、seasons、locations、programs、trials、studyNames、active。/studies のロケーションフィルターを無視する SGN サーバー（CassavaBase、Breedbase、Sweetpotatobase）では、スキャンした試験に対して locations をクライアント側で適用し、totalCount には一致した件数を返します。
• programName、studyType、seasons、locationName、commonCropName に関する distributions。
• SGN/Breedbase の試験では、不足しているプログラム ID と名前を additionalInfo から補完し、生のメタデータはそのまま保持します。

---

brapi_get_study _ツール

• studyDbId は必須です。program、trial、location をインラインで解決します。上流サーバーに該当する試験がない場合は study_not_found を返します。
• SGN/Breedbase サーバーでは、不足しているプログラムフィールドを additionalInfo から補完します。試験にプログラム ID がない場合、取得した親トライアルの情報をプログラムの解決に使用できます。
• 関連件数として observationCount、observationUnitCount、variableCount を返します。サーバーが試験単位で集計できない件数は警告とともに省略し、サーバー全体の件数として報告することはありません。

brapi_find_germplasm _ツール

• フィルター：names、germplasmDbIds、germplasmPUIs、accessionNumbers、crops、synonyms、collections、genus、species。text は、名前、PUI、アクセッション、表示名、シノニムを対象にクライアント側で部分文字列検索を行い、一致しない行を除外します。最初のリクエストでは、インラインの loadLimit とは別に BRAPI_PAGE_SIZE を使用します。データセット全体が 1 回のデータフレーム走査に収まる場合（デフォルトのページサイズでは 50,000 行）、上流のすべての行を走査します。それを超える場合、最初のページで一致が見つからなければ 1 回のリクエストで停止し、実際に走査した行数を報告します。これはカタログに存在しないことを確認するものではないため、サーバー側フィルターと組み合わせてください。
• commonCropName、genus、species、collection、countryOfOriginCode に対する distributions

---

brapi_get_germplasm _ツール

• germplasmDbId は必須です。attributes と直接の parents を返します。上流に該当する遺伝資源がない場合は germplasm_not_found を返します。
• 付随する件数：studyCount、directParentCount、directDescendantCount

---

brapi_walk_pedigree _ツール

• ルートの germplasmDbIds は 1～20 件です（germplasmDbId も使用できます）。direction は ancestors（デフォルト）、descendants、both のいずれかです。maxDepth は 1～10（デフォルトは 3）です。走査は 1,000 ノードまたは 10,000 エッジで停止し、truncated を設定します。
• both は 2 つの走査の和集合です。祖先は /pedigree のみ、子孫は /progeny のみを通じて展開するため、子孫のもう一方の親は取得されません。
• 親子の組み合わせごとにエッジは 1 つです。cycleCount は isCycle が付いたエッジの数を数えます。これは遺伝資源が自身の祖先となる場合を示し、共通の祖先や兄弟姉妹はサイクルではありません。
• leafCount は深度境界のノードを含む、グラフの終端ノード数です。confirmedLeafCount は、関連する検索が正常に完了し、親族がいないことが確認されたルート以外のノード数です。frontier / frontierCount は、深度制限、安全上の理由によるスキップ、失敗、未対応の方向を区別します。deadEndCount は検索に失敗したノードも数えます。
• nodes と edges は、それぞれ loadLimit および配列の JSON とシリアライズ済みの表示行を合わせた 24,000 バイトの上限に収まります。プレビューを切り詰めても、検出済みのグラフは nodesDataframe と edgesDataframe に保持されます。最初の行が予算を超える場合、インライン行は 0 件になります。プレビューの切り詰めによって走査時の truncated が変わることはありません。
• 安全上の上限に達したグラフテーブルには truncated が設定され、検出済みのノードとエッジのみが含まれます。knownOmittedRelativeCount と omittedRelativesDataframe には、すでに取得済みで省略された親族が germplasmDbId、expansionNodeDbId、side、ordinal とともに保持されます。リクエストされていない方向の件数は不明です。フロンティアが大きい場合は frontierDataframe も作成されます。
• 省略された ID は SELECT germplasmDbId, expansionNodeDbId, side FROM <table> ORDER BY ordinal LIMIT 20 OFFSET 0 で取得し、実際に表示された行数だけオフセットを進めてから、それらの ID を最大 20 件のルートに分けて走査します。0 件しか収まらない場合は、列を絞るか集約してください。これらのテーブルから走査を再開することはできません。
• diagram: "mermaid" | "dot" を指定すると、プレビューを超える行も含む、検出済みのグラフが追加されます。安全上の上限に達した場合は、一部のみを網羅した状態になります。エッジは親 → 子として描画され、ループを閉じるエッジは破線になります。どちらの形式も 50,000 文字を超えると警告とともに省略され、Mermaid は 500 エッジを超えた場合も省略されます。

---

brapi_find_variables _ツール

• フィルター：variables、variableNames、variablePUIs、traitClasses、ontologies、studies、methods、scales、crop。複数の異なる研究は、共通のページ、行数、時間の予算内で、変数 ID ごとに統合されます。出典を示す studyDbIds も付与されます。studyCoverage は、完了、一部完了、失敗、未処理の研究を報告します。ある研究が失敗しても、正常に取得できた研究の結果は利用できます。
• text は取得したすべての行を順位付けし、一致した行を先頭に移動しますが、残りの行も除外しません。ontologyCandidates には順位付けされた一致候補が列挙され、各候補に source（puiMatch、nameMatch、synonymMatch、traitClassMatch）が含まれます。
• ontologyDbId、traitClass、scaleName に対する distributions

---

brapi_find_observations _ツール

• フィルター：studies、germplasm、variables、observationUnits、observations、seasons、programs、trials、observationLevels、timestampFrom / timestampTo
• 試験にスコープされた SGN/Breedbase クエリでは、通知された /observationunits?includeObservations=true を使用し、値が 0 の測定値も保持します。ページングにはユニットの合計数を使用します。子フィールドは継承されたユニットメタデータより優先され、重複する観察 ID は 1 回だけカウントされます。観察レベルのフィルターはフラット化後に確認されます。appliedFilters では、上流へのリクエストとクライアント側の条件が分けて示されます
• studies、trials、observationUnits、observations のいずれも指定しない GET クエリでは、最初に 1 行の件数確認を実行します。確認に失敗するか、一致件数が 5,000 件を超える場合は、一括取得をスキップし、その旨を warnings に記載します
• observationVariableName、studyName、germplasmName、observationLevel、season に関する distributions

---

brapi_find_images _ツール

• フィルター：images、observationUnits、observations、studies、imageFileNames、mimeTypes、descriptiveOntologyTerms。メタデータのみを返し、バイトデータは brapi_get_image で取得します
• mimeType、studyName、observationUnitName、descriptiveOntologyTerms に関する distributions

---

brapi_get_image _ツール

• 1 回の呼び出しにつき imageDbIds は 1～5 件、それぞれ最大 20 MB です。サーバーが /images を通知しない場合は images_unsupported になります
• 各画像の source は imagecontent、またはフォールバックの imageURL です。どちらのソースでも、有効な image/* MIME タイプが必要です（大文字・小文字とパラメーターは正規化されます。バイト応答にタイプがない場合はメタデータが使用されます）。画像以外の応答と取得の失敗は画像ごとの errors[] に記録されます。取得に成功した画像は引き続き返されます
• バイトデータは content[] の画像ブロックとして 1 回だけ表示されます。images[] にはメタデータ、MIME タイプ、バイトサイズ、ソースのみが含まれます。format() は base64 を重複させずにメタデータを表示します

---

brapi_find_locations _ツール

• フィルター：locations、locationNames、countryCodes（アルファベットコードは大文字に変換され、数値の上流コードはそのまま保持されます）、countryNames（英語名を alpha-3 に解決します）、locationTypes、abbreviations。解決できない名前は、有効な国コード制限が残らない場合はエラーになります。省略可能な bbox は取得後に適用されます。空でないボックスには、順序どおりの 4 つの境界値（minLat、maxLat、minLon、maxLon）がすべて必要です。満たさない場合、ロケーションの取得前にエラーになります。空のボックスは省略されます。
• countryCode、locationType に関する distributions。coordinateAxisOrder: "swapped" は、座標を [lat, lon] として保存するサーバーを示します

---

brapi_find_variants _ツール

• フィルター：variantSets、variants、references、および referenceName + start（包含） / end（排他）で指定するゲノム領域。0 ベースです
• variantType、referenceName、variantSetDbId に関する distributions

---

brapi_find_genotype_calls _ツール

• variantSetDbId、variantSetDbIds、germplasmDbIds、callSetDbIds、variantDbIds のうち少なくとも 1 つが必要です（それ以外の場合は no_filters）。省略可能な callFormat（VCF、FLAPJACK、DARTSEQ、JSON）
• バリアントセットは brapi_raw_get({ path: "/variantsets" }) で一覧表示されます。必要に応じて params.studyDbId を指定できます。Breedbase 系のサーバーでは、バリアントセットは遺伝子型解析プロジェクトに属しており、brapi_find_studies には表示されません
• callSetName、variantName、variantSetDbId に関する distributions と、サーバーの callFormatting。有効なダイアレクトで POST /search/calls が無効とされている場合は search_endpoint_disabled になります
• 上流からの取得は BRAPI_GENOTYPE_CALLS_MAX_PULL（デフォルトは 100,000）で停止し、truncated を設定します。呼び出しの 50 秒の上流期限により 1 ページ目の後で取得が停止した場合は、そこまでに収集したコールを保持し、hasMore を設定して、その旨を warnings に記載します。loadLimit と 24,000 バイトのインライン予算はインラインプレビューのみを制限し、その状況を shown / cap で報告します。プレビューが打ち切られた場合、収集したすべてのコールはデータフレームに格納されます

brapi_dataframe_describe _ツール

• dataframe は省略可能です。省略するとすべてのデータフレームを一覧表示し、名前を指定すると列、行数、由来（元のツール、baseUrl、クエリ、有効期限）を表示します。これらの情報を持つのは、自動登録された df_* テーブルのみです
• すべての呼び出し元が default テナントを共有する HTTP デプロイでは、MCP セッション内で BRAPI_SESSION_ISOLATION=true の場合、名前を指定せずに一覧表示するとそのセッションのデータフレームのみが表示されます。セッションのないリクエスト、または分離が無効な場合は、list_all_disabled_on_shared_http エラーになります

---

brapi_dataframe_query _ツール

• sql は単一の SELECT 文です。書き込み、DDL、COPY、PRAGMA、ATTACH、ファイルの読み取り（テーブル名として指定したファイルや URL を含む）、システムカタログの読み取り、DESCRIBE／SUMMARIZE／SHOW は sql_rejected として失敗し、具体的な理由は data.gateReason に示されます（データフレームの列と型を一覧表示するには brapi_dataframe_describe を使用してください）
• データに対するクエリの実行に失敗した場合（変換できないキャストなど）は sql_execution_error、存在しなくなったデータフレーム名は missing_table、すでに使用されている registerAs 名は register_as_clash として失敗します
• rowCount、型付きの columns、先頭の rows を返します。上限は preview、rowLimit、BRAPI_CANVAS_MAX_ROWS によって制限され、それぞれ次の値を上限として適用します。さらに、シリアライズされた各行配列とレンダリングされた行セクション（エスケープ文字とマーカーを含む）のサイズは 24,000 バイトまでです。shown は返された行数で、cap は有効な行数の上限です。最初の行が大きすぎる場合、行は返されません。列を絞るか集計してください
• registerAs（識別子、最大 63 文字）を指定すると、結果全体が新しいデータフレームとして保存され、連鎖して使用できます
• 永続化された結果をページ分割するには、決定的な ORDER BY と LIMIT/OFFSET を指定し、要求した上限ではなく実際に返された行数分だけオフセットを進めてください。registerAs を指定していない場合は、保存した結果をページ分割する前に、registerAs を指定して再実行してください

---

brapi_dataframe_drop _ツール

• dataframe は必須です。不明な名前の場合、エラーではなく dropped: false を返します
• BRAPI_CANVAS_DROP_ENABLED=true の場合のみ登録されます

---

brapi_dataframe_export _ツール

• format は csv、parquet、json のいずれかです。任意の columns または sql（相互に排他的）と filename（パス区切り文字または .. は使用不可。省略するとタイムスタンプ付きのデフォルト値を使用）を指定できます。絶対パスの path、sizeBytes、rowCount を返します
• 型付きエラー：export_dir_unset、dataframe_not_found、invalid_filename、mutually_exclusive_projection
• stdio で BRAPI_EXPORT_DIR が設定されている場合のみ登録されます

---

brapi_build_phenotype_matrix _ツール

• studies は必須（1件以上）です。variables／germplasm のサブセットは任意です。shape は wide（デフォルト）または long、aggregate は mean（デフォルト）、median、first、または all（常にロング形式）です。loadLimit は、スタディごとの一致する観測値の上限を設定します
• 各スタディの観測値を上流の合計件数と照合しながらページ取得します。SGN／Breedbase で通知されている場合は、ゼロ値を保持できるよう、埋め込みの観測単位を優先します。単位の合計は生の単位数を数え、loadLimit は一致する観測値を数えます。その他のサーバーでは /observations とフォールバックのパスを引き続き使用します。スタディ／変数／遺伝資源のサブセットは、返された行に対してチェックします
• extraFilters は転送された後、brapi_find_observations と同様に、マトリックスの構築元となる行に対してチェックされます。warnings には行と矛盾するキーと、どの行からも判断できないキーが示されます
• マトリックスをデータフレームとして返すほか、observationCount、germplasmCount、variableCount、SQL で安全な列名を変数名に対応付ける variableLegend を返します。truncated／cap は、スタディの合計に達する前にスキャンが停止した場合（loadLimit、ページ上限、失敗、空または繰り返しのページ、あるいは呼び出しの期限による）にそのスタディを示し、通知には調査済みの行数も記載されます
• studies には要求された ID が保持されます。coverage.studies では、収集件数とともに、contributed、empty、failed、partial、unprocessed の結果を区別します。coverage.partial と truncated により、両方の出力で失敗または不完全な取得が明示されます。あるスタディの取得に失敗しても、他のスタディのマトリックス構築は妨げられません。呼び出しが失敗するのは、すべてのスタディの取得に失敗した場合のみです。サーバーがどちらの観測ルートも公開していない場合は no_observation_path が返されます

---

brapi_germplasm_performance _ツール

• germplasmDbId は必須です。SGN／Breedbase では、通知されている遺伝資源スコープの埋め込み単位を使用し、スタディ検出の上限を設けずに生の合計件数分を取得します。その他のサーバーでは最大 200 件のスタディを検出します。studyDbIds を明示すると検出をスキップし、それらのスタディのみを収集対象とします。variables のサブセットは任意です。上流に該当する遺伝資源がない場合は germplasm_not_found が返されます
• perVariable の行には n、mean、median、sd（n < 2 または数値以外の場合は省略）、min、max、studyCount、studyDbIds、seasons が含まれます
• studyCount／studyDbIds には、引き続きデータを提供したスタディのみが含まれます。追加の coverage では、contributed、empty、failed、partial、unprocessed のスタディを区別します。スコープ付き単位のスキャンでは、生の単位数、ページ数、判明している場合は合計件数、および完了状況が報告されます。不完全な単位走査では、未確認のスタディ数を確定できません。繰り返しの観測 ID は一度だけ数え、異なる ID の反復値とゼロ値は保持されます。デプロイメントの観測上限は、遺伝資源単位の走査を含め、スタディごとに適用されます。ページ数、観測値、期限の各上限が明示され、期限によってスキップされたスタディには件数に関する警告が 1 件付けられます

---

brapi_export_genotype_matrix _ツール

• variantSetDbId は必須です（それ以外の場合は no_filters。セットの一覧は brapi_raw_get({ path: "/variantsets" }) で取得できます）。germplasmDbIds は任意です。format は matrix-json、vcf-lite（vcf テキストを追加）、または plink（ped／map テキストを追加）で、すべての形式で遺伝資源 × 変異のデータフレームが登録されます
• variantColumnLegend は SQL で安全な列名を変異 ID に対応付けます。使用中の方言で POST /search/calls が無効とされている場合は search_endpoint_disabled が返されます
• VCF の POS と PLINK の塩基対位置は 1 始まりです。有効な 0 始まりの BrAPI start 値 0 と 500 は、それぞれ 1 と 501 としてエクスポートされます。位置がない、または無効な場合は、プレースホルダーとして VCF では .、PLINK では 0 が保持されます。
• maxCalls／maxColumns は BRAPI_GENOTYPE_CALLS_MAX_PULL／BRAPI_GENOTYPE_MATRIX_MAX_COLUMNS の値を引き下げられますが、引き上げることはできません。truncated は、上限に達した場合、または呼び出しの 50 s の上流期限によってコールの取得が早期終了した場合を示します。warnings にはその要因が記載されます

brapi_submit_observations _ツール

• studyDbId と 1～5,000 件の observations を指定します。observationDbId を含む行は PUT で更新し、含まない行は POST で作成します。削除は行われません
• mode: "preview"（デフォルト）では、書き込みを行わずに valid、invalid、routing の件数と perRowWarnings を返します。mode: "apply" では、呼び出し元に確認を求め（force: true で省略可能）、同じ呼び出し元、サーバー、試験、行に対するそのプロンプトのサーバー記録を消費するラウンドでのみ書き込みを行います。事前に指定された回答や再利用された回答の場合は、再度確認を求めます。結果として posted、updated、studyObservationCount を返します。失敗は observations_unsupported、study_not_found、post_unsupported、put_unsupported、user_declined です
• BRAPI_ENABLE_WRITES=true の場合にのみ登録されます。brapi:write:observations スコープが必要です

---

brapi_raw_get _ツール

• /samples のような相対ルートを path に指定します（完全な URL を指定すると cross_origin_path エラーになります）。params と loadLimit は任意です
• エンベロープ（url、metadata、result）と、キュレーション済みツールがそのエンドポイントをカバーしている場合、または一覧に示された ID を受け取る場合の suggestion を返します。リストのプレビュー（result 配列または result.data）は、シリアル化された各行配列とレンダリングされた行セクションについて、マーカーとエスケープを含めて loadLimit 件、かつ 24,000 バイト以内に収まります。リスト以外の結果とエンベロープ内の兄弟要素は保持されます。インライン表示されない取得済みの行はすべてステージングされます。最初の行が大きすぎてインライン表示できず、インライン行が 0 件になる場合も同様です
• params.page / params.pageSize を指定すると、上流の要求したページのみを取得します。切り詰められたページは、追加のページを巡回せずにステージングされます。SQL オフセットでは、ステージングされたテーブルを上流のページネーションとは独立してページ分割します。決定的な ORDER BY を使用し、実際に表示された行数分だけ進め、表示できる行が 0 件の場合は、より狭い列選択を使用してください

---

brapi_raw_search _ツール

• noun（例：observations、calls、germplasm）と、POST /search/{noun} にそのまま送信する body を指定します。非同期検索は完了までポーリングされます
• kind（sync または async）、searchResultsDbId、result、suggestion を返します。プレビューとステージングの動作は brapi_raw_get と同様です。body.page / body.pageSize で上流の要求したページに収集対象を制限できます。有効な方言でそのルートが無効とされている場合は search_endpoint_disabled を返します

---

brapi://server/info _リソース

• default 接続の概要エンベロープを application/json として返します
• 引数なしで brapi_server_info を呼び出した場合と同じペイロードです

---

brapi://calls _リソース

• default 接続の機能プロファイルです。対応サービスとその HTTP メソッドおよびバージョンに加え、作物を示します
• 最後に読み込んだときに /serverinfo + /calls が返した内容を反映します

---

brapi://study/{studyDbId} _リソース

• default 接続での brapi_get_study と同じペイロードです
• 上流に該当する試験がない場合は study_not_found を返します

---

brapi://germplasm/{germplasmDbId} _リソース

• default 接続での brapi_get_germplasm と同じペイロードです
• 上流に該当する生殖質がない場合は germplasm_not_found を返します

---

brapi://filters/{endpoint} _リソース

• brapi_describe_filters と同じペイロードです。カタログにないエンドポイントの場合は unknown_endpoint を返します
• brapi://filters を一覧表示すると、エンドポイントごとに 1 つのリソースが返されます

---

brapi://variable/{observationVariableDbId} _リソース

• default 接続における /variables/{id} のレコード（形質、尺度、手法、オントロジー）です
• 上流に該当する変数がない場合は variable_not_found を返します

---

brapi_eda_study _{プロンプト}

• 引数：studyDbId は必須、alias は任意です
• ユーザーメッセージを 1 件返します。次のステップを推奨する Markdown レポートで締めくくる、6 段階の手順書（概要把握、変数、網羅率、欠損データ、IQR 外れ値、任意の系譜調査）です

---

brapi_meta_analysis _{プロンプト}

• 引数：germplasmDbIds（カンマ区切り）とtraitNameは必須です。aliasは任意で、複数のサーバーを対象に分析する場合はエイリアスごとに1回実行します
• ユーザーメッセージを1つ返します。形質の特定、研究の発見、観測テーブルの作成、尺度の調和、研究ごとおよび研究横断での要約、任意の系譜の追跡という7段階の手順書で、使用したすべてのデータフレームハンドルまたはフィルターマップを引用したレポートで締めくくります

機能

@cyanheads/mcp-ts-core を基盤としており、stdio と Streamable HTTP トランスポート、差し替え可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログを提供します。

BrAPI 固有の機能：

• 共通の検索コントラクト：7 種類のフィルター検索ツール（studies、germplasm、variables、observations、images、locations、variants）は、alias、loadLimit、extraFilters（brapi_describe_filters のキー）を受け取り、results、hasMore、distributions、および任意の dataframe ハンドルを返します。results は、配列の JSON またはシリアライズされたエスケープ済み行テキストのいずれかで、先に上限に達した方に従い、loadLimit または 24,000 バイトで停止します。予算を単独で超える場合でも、最初に一致した行は保持されます。切り詰められた位置は truncated / shown / cap で示します
• Dataframe へのスピルオーバー：results に一致した行の一部しか格納できない場合、検索ツールは一致したデータセットを DuckDB の df_<uuid> テーブルに一時格納します（残りの結果をページングし、最大 50 ページ、50,000 行）。そのハンドルを返します
• 方言アダプター（spec、brapi-test、breedbase、cassavabase、bms）は接続ごとに検出され、v2.1 の複数形フィルターを各サーバーファミリーが受け入れる形式に変換し、無視されるフィルターを除外します。また、複数値フィルターが GET によって絞り込まれる場合は、POST /search/{noun} に切り替えます。BRAPI_<ALIAS>_DIALECT で固定できます
• 名前付きエイリアスを使って複数の接続を同時に利用できます。Breedbase の公開サーバー 3 台が組み込まれており、認証情報はエイリアスごとに環境変数から解決されるため、LLM のコンテキストには含まれません
• 機能認識型の呼び出し：各接続の /serverinfo と /calls のプロファイルをキャッシュし、ツールがエンドポイントを呼び出す前に確認します。接続ごとの同時実行数上限と指数バックオフによる再試行で 429/5xx に対処します

エージェントに適した出力：

• 上流の名前、識別子、補足フィールドはリテラルテキストとして表示されます。構造化された値と生成された系譜図は元の意味を保持します
• 型付きエラー：接続を対象とする各ツールおよびリソースは、登録もサーバー上で設定もされていないエイリアス（設定済みのエイリアスは初回使用時に接続します）に対して unknown_alias で失敗します。また、サーバーから到達できないプライベートまたは予約済みアドレスがベース URL の場合は、何もキャッシュまたは登録せずに private_address_blocked で失敗します。方言によって指定されたフィルターがすべて除外された場合、フィルター検索ツールはフィルターなしの取得に拡大せず、all_filters_dropped で失敗します。また、要求されたすべてのスタディについて方言がスタディフィルターを除外した場合、brapi_build_phenotype_matrix は dialect_all_filters_dropped で失敗します
• 空または空白のみの ID やフィルター値は、上流に送信される前に入力スキーマで失敗します。上流では、空白のフィルターによって取得範囲が広がり、空白の ID によってリクエストパスが不正になるためです。空の text は引き続きテキストフィルターなしを意味します
• すべての検索ツールでクエリーをエコーします：totalCount、returnedCount、appliedFilters を返します。埋め込みの observations 取得では上流へのリクエストとクライアント側の条件を分け、brapi_find_studies ではクライアント側の locations を別に列挙します。スキャンが途中で停止した場合、完全な dataframe を指すか、より絞り込んだフィルターを提案する refinementHint を返します。結果が空の場合は notice を付け、制限事項は warnings で開示します
• 部分的な失敗を適切に処理：brapi_get_image はバッチ全体を失敗させる代わりに、画像ごとの errors[] と warnings[] の行を返します
• 識別子付きの出力：brapi_submit_observations は mode で識別される結果（preview / apply）を返し、brapi_raw_search は kind を報告し、brapi_get_image は画像ごとに source を報告します

データフレームの操作

ファインダーのインライン results に、マッチした行数より少ない行しか含まれない場合（loadLimit または24,000バイトのインライン上限に先に達した場合）、レスポンスには dataframe ハンドルが含まれます。内容は tableName、rowCount、columns、createdAt、expiresAt、およびサーバーが報告する場合は上流の totalCount です。データフレームに上流の合計より少ない行しか含まれない場合は、truncated（行数の上限に達した場合は maxRows も）が含まれ、warnings に走査が停止した理由が示されます。SQL 識別子のチェックを通すために名前が変更された列は、columnLegend で上流のキーに対応付けられます。

データフレームを作成するすべてのレスポンスには、各テーブル名、行数、対象範囲を示し、続いて brapi_dataframe_describe、さらに brapi_dataframe_query を案内する notice が含まれます。これにはファインダー、行数またはバイト数の上限によってリストが切り詰められた場合の brapi_raw_get / brapi_raw_search、brapi_build_phenotype_matrix と brapi_export_genotype_matrix が返すすべての行列、グラフ／フロンティアのプレビューが切り詰められた場合、または取得した近縁個体が省略された場合の brapi_walk_pedigree が含まれます。登録されている場合は、brapi_dataframe_export も案内されます（BRAPI_EXPORT_DIR が設定された stdio）。ファインダーでは、同じ notice に、どの上限によって results が切り詰められたかも示されます。

1. brapi_find_observations { studies: ["s-422"] }
   → leading rows inline + dataframe.tableName = "df_<uuid>" (when results holds fewer rows than matched)
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

データフレーム名は行レベルの ACL ではなく、機能へのアクセストークンです。同じセッションまたはテナントのバケット内で名前を持つ人は誰でも、その行を読み取れます（デプロイ形態を参照）。データの由来情報は BRAPI_DATASET_TTL_SECONDS（既定値は24時間）の間保持されます。明示的なクリーンアップ用に brapi_dataframe_drop を公開するには、BRAPI_CANVAS_DROP_ENABLED=true を設定します。

はじめに

公開ホスト型インスタンス

公開インスタンスは https://brapi.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントから接続してください。

{
  "mcpServers": {
    "brapi-mcp-server": {
      "type": "streamable-http",
      "url": "https://brapi.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

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

または npx を使用します（Bun は不要です）。

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

または Docker を使用します。

{
  "mcpServers": {
    "brapi-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["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）はそのまま接続でき、brapi_connect は実行時にほかの任意の BrAPI v2 URL を受け付けます。ログインが必要なサーバーでは、パスワード、トークン、キーが LLM のコンテキストに含まれないよう、認証情報を環境変数に設定してください（エイリアスごとの認証情報を参照）。

前提条件

• Bun v1.4.0 以上（または Node.js v24+）。
• @duckdb/node-api。通常の依存関係としてインストールし、macOS、Linux（glibc および musl）、Windows の x64 および arm64 向けのビルド済みネイティブバインディングを使用します。Cloudflare Workers はサポートされていません。

インストール

1. リポジトリをクローンします。

git clone https://github.com/cyanheads/brapi-mcp-server.git

2. ディレクトリに移動します。

cd brapi-mcp-server

3. 依存関係をインストールします。

bun install

4. 環境を設定します。

cp .env.example .env
# edit .env if you need credentials or non-default settings

設定

すべての変数は省略可能です。

変数	説明	デフォルト
BRAPI_DEFAULT_BASE_URL	default エイリアスのベース URL（例：https://test-server.brapi.org/brapi/v2）。	—
BRAPI_DEFAULT_* credentials	default エイリアス用の認証情報ファミリーです。エイリアスごとの認証情報を参照してください。	—
BRAPI_DEFAULT_API_KEY_HEADER	default エイリアスの API キーヘッダー、およびヘッダーが指定されていない api_key 認証のフォールバックヘッダーです。	Authorization
BRAPI_BUILTIN_ALIASES_DISABLED	削除する組み込みエイリアスをカンマ区切りで指定します（大文字と小文字は区別されません）。	—
BRAPI_LOAD_LIMIT	ファインダーのインライン行数のデフォルト上限です。24,000 バイトの予算もインライン行数を制限し、いずれかの上限によって行数が制限されると、マッチしたデータセットはデータフレームに格納されます。	1000
BRAPI_PAGE_SIZE	スピルオーバー時のページ取得に使う上流の pageSize です。データフレームの上限は pageSize × 50 で、最大 50,000 行です。	1000
BRAPI_MAX_CONCURRENT_REQUESTS	接続ごとの同時リクエスト上限です。	4
BRAPI_RETRY_MAX_ATTEMPTS / BRAPI_RETRY_BASE_DELAY_MS	429／5xx エラーおよびタイムアウト時の再試行回数と、指数バックオフの基本遅延です。タイムアウトしたリクエストは、呼び出しの上流期限 50 秒以内に次の試行を実行できる場合にのみ再試行されます。	3 / 500
BRAPI_REQUEST_TIMEOUT_MS	リクエストごとの HTTP タイムアウトです。1 回のツール呼び出しで発行されるすべての上流リクエストには、呼び出し開始から 50 秒の共通期限も適用されるため、サーバーが応答しない場合、MCP クライアントのデフォルトのリクエストタイムアウト 60 秒に達する前に、呼び出しは Timeout で失敗します。	30000
BRAPI_COMPANION_TIMEOUT_MS	重要度の低い補助処理（FK 検索、件数の確認）のタイムアウトです。これらの処理では再試行も省略されます。	8000
BRAPI_SEARCH_POLL_TIMEOUT_MS / BRAPI_SEARCH_POLL_INTERVAL_MS	非同期 /search のポーリング予算と間隔です。ポーリングは呼び出しの上流期限 50 秒に達した時点でも停止します。	60000 / 1000
BRAPI_DATASET_TTL_SECONDS	データフレームの出所情報（ハンドルの expiresAt）の有効期間です。	86400
BRAPI_REFERENCE_CACHE_TTL_SECONDS	キャッシュされた機能プロファイルと参照データ（プログラム、試験、場所、作物）の TTL です。	3600
BRAPI_ALLOW_PRIVATE_IPS	RFC 1918／ループバックのターゲットを許可します。開発時のみ使用してください。	false
BRAPI_SESSION_ISOLATION	MCP セッションがある場合、接続とデフォルトのキャンバスをそのセッションにスコープします。false の場合はテナント全体で共有されます。デプロイ形態を参照してください。	true
BRAPI_ENABLE_WRITES	機能フラグ。 brapi_submit_observations を登録します。	false
BRAPI_CANVAS_DROP_ENABLED	機能フラグ。 brapi_dataframe_drop を登録します。	false
BRAPI_EXPORT_DIR	機能フラグ。 brapi_dataframe_export の出力ディレクトリです。設定すると、stdio の場合に限りツールが登録されます。	—
BRAPI_CANVAS_MAX_ROWS / BRAPI_CANVAS_QUERY_TIMEOUT_MS	brapi_dataframe_query の応答行数上限とクエリごとのタイムアウトです。上限はフレームワークの CANVAS_DEFAULT_ROW_LIMIT（デフォルト 10000）を超えることはできません。超えた場合、起動に失敗します。	10000 / 30000
BRAPI_GENOTYPE_CALLS_MAX_PULL	brapi_find_genotype_calls または brapi_export_genotype_matrix の呼び出しごとの上流呼び出し上限です。最大値は 500000 です。	100000
BRAPI_GENOTYPE_MATRIX_MAX_COLUMNS	brapi_export_genotype_matrix のマトリックスごとのバリアント列数の上限です。最大値は 500000 です。	10000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモードです。このサーバーでは stateful が必要です（apply モードの書き込みはセッション経由で確定され、分離にはセッションが使用されます）。stateless と判定された場合、HTTP 起動は失敗します。	auto（stateful と判定）
MCP_AUTH_MODE	認証方式：none、jwt、または oauth。	none
MCP_REQUEST_STATE_KEY	32 バイト以上で、すべてのインスタンスで同一のシークレットです。確認のラウンドトリップで返される requestState を保護します。それ以外の状態は、ハンドラーの実行前に拒否されます。BRAPI_ENABLE_WRITES と併用することを推奨します。	—
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOG_TOOL_FAILURE_PAYLOADS	失敗した各ツール呼び出しの引数と結果をログに記録します（キー名のみを秘匿化します）。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	明示的に有効化する OTLP ログのエクスポート先です。ベースの OTEL_EXPORTER_OTLP_ENDPOINT を設定しても有効にはなりません。	—
省略可能な上書き設定の一覧は、.env.example を参照してください。

エイリアスごとの認証情報

エージェントが値を省略した場合、brapi_connect は次の順序で環境変数から baseUrl と auth を設定します。

1. エージェントの入力。以下のペアリングルールに従います。
2. エイリアスごとの環境変数：BRAPI_<ALIAS>_*。ハイフンはアンダースコアに置き換えて大文字にします（my-server → BRAPI_MY_SERVER_*）。
3. 組み込みエイリアス：組み込みエイリアスを参照してください。
4. BRAPI_DEFAULT_BASE_URL。URLまたは認証情報を持たないエイリアスに適用されます。

環境変数の認証情報は、その設定先のサーバーにのみ送信されます。

• エイリアスの認証情報は、そのエイリアスの BRAPI_<ALIAS>_BASE_URL、または有効になっている組み込み URL と組み合わされます。呼び出し元の baseUrl が別の URL を指している場合は、auth_base_url_mismatch で失敗します。組み込みエイリアスが BRAPI_BUILTIN_ALIASES_DISABLED によって無効化された場合など、独自の URL を持たない認証情報は alias_base_url_unset で失敗し、BRAPI_DEFAULT_BASE_URL に送信されることはありません。
• BRAPI_DEFAULT_* の認証情報は、解決された URL が BRAPI_DEFAULT_BASE_URL の場合にのみ設定されます。それ以外の URL を指定されたエイリアスは、独自の認証情報がない限り、認証なしで接続します。BRAPI_DEFAULT_BASE_URL が設定されていない場合、デフォルトの認証情報は alias_base_url_unset で失敗します。

URL の比較では、ホスト名の大文字・小文字、デフォルトポート、末尾のスラッシュを正規化します。呼び出し元が指定した auth と環境変数の認証情報が混在することはありません。

各エイリアスが持てる認証情報ファミリーは1つで、認証モードは設定されたフィールドによって決まります。エイリアス内で異なるファミリーを混在させると、ValidationError が発生します。

設定された変数	解決される mode
_USERNAME + _PASSWORD	sgn（Breedbase /token 交換）
_BEARER_TOKEN	bearer
_API_KEY（および省略可能な _API_KEY_HEADER）	api_key
_OAUTH_CLIENT_ID + _OAUTH_CLIENT_SECRET（および省略可能な _OAUTH_TOKEN_URL）	oauth2
（未設定）	none

検出によって誤った方言が選択された場合は、BRAPI_<ALIAS>_DIALECT で方言アダプター（spec、brapi-test、breedbase、cassavabase、bms）を固定できます。auto を指定するか未設定にすると、自動検出されます。

# .env — attach write credentials to the built-in 'bti-cassava' alias
BRAPI_BTI_CASSAVA_USERNAME=alice
BRAPI_BTI_CASSAVA_PASSWORD=...
# (BASE_URL omitted — the 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

エージェントはその後、baseUrl、auth、プロンプト内のシークレットを指定せずに brapi_connect({ alias: 'bti-cassava' }) を呼び出すか、その呼び出しを省略します。どちらの場合も、alias: 'bti-cassava' を指定されたツールは、初回使用時に同じ方法で接続します。

組み込みエイリアス

これらの公開 BrAPI v2 エンドポイントは、設定なしで接続できます。オリエンテーション用エンベロープの attribution ブロックには、ライセンス、引用情報、ホームページが含まれています（Creative Commons Attribution）。

エイリアス	上流	ホスト機関	作物	備考
bti-cassava	cassavabase.org	Boyce Thompson Institute	キャッサバ	NextGen Cassava
bti-sweetpotato	sweetpotatobase.org	Boyce Thompson Institute	サツマイモ
bti-breedbase-demo	breedbase.org	Boyce Thompson Institute	デモ	サンプルデータのみ。オンボーディングとテスト用

レジストリには、匿名での読み取りが確認されたサーバーのみが登録されています。ログインが必要なサーバー（Triticeae Toolbox（T3）の小麦、オート麦、大麦のホストを含む）は、BRAPI_<ALIAS>_BASE_URL と認証情報を使って接続します（.env.example を参照してください）。

BRAPI_<ALIAS>_BASE_URL は組み込み URL を上書きします。たとえば、BRAPI_BTI_SWEETPOTATO_BASE_URL を使うと、bti-sweetpotato の接続先をステージングミラーに変更できます。BRAPI_<ALIAS>_USERNAME などを指定すると、組み込み URL に認証情報が追加されます。各 Breedbase インスタンスは独自のユーザーテーブルを持つため、書き込みアクセスにはインスタンスごとに別のアカウントが必要です。BRAPI_BUILTIN_ALIASES_DISABLED=bti-cassava,bti-breedbase-demo を設定すると、該当するエントリーが削除されます。

引用情報： 3つの組み込みエイリアスはすべて、Morales et al. 2022, "Breedbase: a digital ecosystem for modern plant breeding." G3 12(7): jkac078 を参照しています。doi:10.1093/g3journal/jkac078。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start            # transport from MCP_TRANSPORT_TYPE (stdio default)
  bun run start:stdio
  bun run start:http
  
  # Or run from source with hot reload
  bun --watch src/index.ts
  

• チェックとテストを実行する：

  bun run devcheck         # Lint, format, typecheck, security, changelog sync
  bun run test             # Vitest suite
  bun run lint:mcp         # Validate MCP definitions
  

Docker

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

イメージはデフォルトで HTTP トランスポート、stateful セッションモードを使用し、/var/log/brapi-mcp-server にログを出力します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

デプロイ構成

状態のスコープには、テナント単位、およびデフォルトでは MCP セッション単位の 2 種類があります。接続状態（登録済みエイリアスと交換済みのアップストリームトークン）と、データフレーム（df_<uuid> テーブル。バケット内で名前を知っている人なら誰でも使用できます）です。バケットの範囲は、次の 3 つの構成で決まります。

構成	設定	分離	適した用途
セッション単位（デフォルト）	MCP_AUTH_MODE=none + HTTP stateful + BRAPI_SESSION_ISOLATION=true	各 MCP セッションは独自の接続とキャンバスを持ちます。セッションなしのリクエストは、テナント全体で共有される名前空間を使用するため、brapi_connect は呼び出し元が指定した auth を auth_session_required で拒否します。キー不要の接続とオペレーターの環境認証情報は引き続き使用できます。	SSO を使用しないマルチユーザーホスティング
ユーザーごとの認証情報	MCP_AUTH_MODE=jwt または oauth（+ HTTP stateful）	各ユーザーの JWT tid クレームが独自のテナントになります。分離が有効な場合、セッションはその内部でスコープが分けられます。	機関 SSO を使用するマルチユーザーホスティング。最も強力な分離
共有ワークスペース	MCP_AUTH_MODE=none + BRAPI_SESSION_ISOLATION=false	すべての呼び出し元が、1 つのテナントの接続とキャンバスを共有します。	共有アップストリーム認証情報を使って、1 人の研究者が複数のエージェントを並行実行する場合

Stdio は常に単一セッションです。MCP プロトコルリビジョン 2026-07-28 のクライアントは、どのトランスポートでもセッションを持たないため、ユーザーごとの認証情報の構成以外では、共有テナントワークスペースに割り当てられます。この場合、エイリアスを再登録すると、その後の呼び出しでは、該当するすべての呼び出し元に対してエイリアスの参照先が変更されます。

ユーザーごとの認証が設定されていない HTTP では、brapi_dataframe_describe が名前なしでデータフレームを一覧表示できるのは、独自のセッションスコープ付きキャンバスを持つリクエストのみです。また、brapi_dataframe_query はすべての構成でシステムカタログの読み取りを拒否するため、既知の df_<uuid> 名を持たない呼び出し元が他の呼び出し元のテーブルを列挙することはできません。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() エントリーポイント：ツール（機能フラグで制御）、リソース、プロンプトを登録し、サービスを初期化します。
src/config	サーバー環境変数の解析（Zod）、エイリアスごとの認証情報解決、組み込みエイリアスレジストリ。
src/mcp-server/tools	ツール定義（*.tool.ts）と共有ヘルパー。接続、取得、分析、書き込み、raw パススルーにわたる 25 個のツールがあります。
src/mcp-server/resources	リソース定義（*.resource.ts）。
src/mcp-server/prompts	プロンプト定義（*.prompt.ts）。
src/services	BrAPI クライアント、方言アダプター、フィルターカタログ、キャンバスブリッジ、機能レジストリ、ISO 国コードリゾルバー、オントロジーリゾルバー、参照データキャッシュ、サーバーレジストリ。
tests/	src/ の構成に対応する単体テストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャのルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch は使用しません
• ロギングには ctx.log、テナントスコープのストレージには ctx.state を使用します。console や永続化レイヤーへの直接アクセスは使用しません
• 新しいツールは src/mcp-server/tools/definitions/index.ts の該当グループに追加します。src/index.ts は機能フラグで制御しながら各グループを構成します
• アップストリーム呼び出しはラップし、raw データを検証 → 正規化 → 出力スキーマに適合させて返します。不足しているフィールドを捏造してはいけません

貢献

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。