Vivarium MCP サーバ (@aletheia-works/vivarium-mcp) は Model Context Protocol の stdio トランスポート経由で 5 つのツールを提供します: list_recipes、get_recipe、 lookup_verdict、match_error、 verify_branch_fix。 エージェント側からカタログを検索し、特定レシピのメタデータを取得し、 Layer 2 / 3 の verdict スナップショットを読み、候補修正の検証フローを 組み立てられます。

JSR / npm への初回公開は現時点で意図的に保留中です。 Vivarium 全体およびサーバ機能サーフェスがまだ熟していない段階で公開すると、 まだ動かしたいインタフェースを v1 として固定してしまうため。 公開時期は維持者が別途アナウンスします。それまでは ローカルクローン経由で動かすパスが標準です。

git clone https://github.com/aletheia-works/vivarium.git
cd vivarium/packages/mcp-server
bun install
bun run build
# → dist/index.js が出来る（クライアントが起動するエントリポイント）

dist/index.js の絶対パスを控えておきます。 MCP クライアント側の設定で、node 経由でこのファイルを起動する形になります。

MCP サーバの登録は、どのクライアントでも本質的に「command と args の組」を JSON で渡す形です:

{
"mcpServers": {
  "vivarium": {
    "command": "node",
    "args": ["/abs/path/to/vivarium/packages/mcp-server/dist/index.js"]
  }
}
}

この snippet を貼る場所がクライアントごとに違うだけです:

MCP クライアント側の正典のドキュメントは modelcontextprotocol.io/clients にあります。各クライアントの設定ファイルパスは更新されることがあるので、 迷ったら本家を参照してください。

• list_recipes(layer?, project?, q?) — カタログをフィルタして列挙。layer は 1/2/3 の整数、 project は上流プロジェクト名（"pandas"等）、 q は slug / project / title 横断の部分文字列検索。

• get_recipe(slug) — 1 つのレシピの全メタデータ （title / project / issue / page URL / verdict snapshot URL / GitHub source URL）。 slug が見つからなければ { found: false, error }。

• lookup_verdict(slug) — Layer 1 は { kind: "live", page_url, note }（verdict はブラウザ実行時に出る）、 Layer 2 / 3 は { kind: "snapshot", snapshot: { verdict, exit_code, image_digest, stdout, stderr_tail, ... } }。

• match_error(text, limit?) — エラー文字列・スタックトレースから 機械的トークンマッチで候補レシピをスコア順で返す。LLM もファジーマッチも使わず、 symptom / tags / project / slug への完全一致で重みづけ。

• verify_branch_fix(slug, fix_url? | fix_source?) — 候補修正を検証するための足場ヘルパー（実行エンジンではない）。 Layer 1 は Path A — レシピページに ?fix_url= / ?fix= を 事前読み込みした compare_url を返す。Layer 2 / 3 は Path B — gh workflow run branch-fix-verdict.yml コマンドと /repro/compare deep-link を返す。フルウォークスルーは 「ブランチ修正を検証する」。

match_error のスコアリングは 「エラーからレシピを探す」 ページとビット同一です。MCP 経由でも UI 経由でも同じ候補順が出ます。

• dist/index.js が無い。 bun run build を流していない場合に起きる。 packages/mcp-server 直下で bun install && bun run build を 1 度走らせる必要があります。

• 絶対パスでないと一部クライアントが見つけられない。 ホームディレクトリ短縮表記や相対パスは展開されないことがあります。 $HOME/code/vivarium/... ではなく /Users/<you>/code/vivarium/.../dist/index.js のようにフルパスで書きます。

• レシピが古い気がする。 サーバは https://aletheia-works.github.io/vivarium/api/recipes.json を 5 分 TTL でキャッシュ、ネット切断時は build-time の snapshot にフォールバック。 最新を強制したいときは MCP サーバを再起動するのが早いです。

• Layer 1 の verdict が「snapshot じゃない」と言われる。 Layer 1 はブラウザでの実行が確定の場で、サーバ側にスナップショットを置かない設計 （Contract v1）。 エージェントには kind: "live" の page_url を提示して、 ブラウザで開いて確認させるのが正規ルートです。