Forge MCP

forge-mcp

MCP 対応エージェント（Claude Desktop、Cursor、…）から、生成音楽の E-- Recipe を直接作成、コンパイル、実行、コミットできます。 forge-mcp は Forge E-- ライブラリのノートカタログと Vault を MCP サーバーとして公開し、エージェントがカタログからチップを選び、Recipe を作成し、解析できることを確認し、サンドボックスで実行して成果物をプレビューし、完成した Recipe を Vault のノートにコミットするまでの作成ワークフローをエンドツーエンドで完結させます。6 つのツールをすべて今すぐ利用できます。

[library note catalog] → [compile] → [run] → [commit] → [vault note with recipe_version bump]

Claude Code へのインストール

最速の方法 — Claude Code が forge-mcp を stdio サブプロセスとして起動します。詳しい手順はdocs/claude-code-install.mdをご覧ください。

# 1. Install from PyPI (https://pypi.org/project/forge-recipe-mcp/)
pip install forge-recipe-mcp

# 2. Fetch your Bearer once and export
export FORGE_MCP_BEARER=$(jq -r '.transpileServiceToken' \
  ~/forge-vaults/bluh/.obsidian/plugins/forge-client-obsidian/data.json)

# 3. Register with Claude Code
claude mcp add forge-mcp \
  -e FORGE_MCP_BEARER=$FORGE_MCP_BEARER \
  -e FORGE_TRANSPILE_URL=https://forge.thecodingarena.com \
  -e FORGE_VAULT_PATH=$HOME/forge-vaults/bluh \
  -e FORGE_MCP_TRANSPORT=stdio \
  -- forge-mcp

# 4. Start Claude Code and ask "list the notes in my forge music library."

インストール（その他のクライアント）

詳しい手順（Claude Desktop の設定、forge-transpile の Bearer 取得、動作確認、トラブルシューティング）：docs/install.md。

簡単な方法：

# From source (pip + editable install for development)
pip install -e ".[dev]"
python -m forge_mcp.server

# Docker
docker build -t forge-mcp:latest .
docker run --rm -p 8765:8765 \
    -e FORGE_TRANSPILE_URL=https://forge.thecodingarena.com \
    -e FORGE_VAULT_PATH=/path/to/your/vault \
    forge-mcp:latest

環境変数：

• FORGE_TRANSPILE_URL — forge-transpile サービスのベース URL。デフォルト：http://localhost:8000。
• FORGE_VAULT_PATH — forge_read_notes_in_vault と forge_commit_recipe で使用するローカル Vault ディレクトリ。デフォルト：~/forge-vaults/bluh。
• FORGE_MCP_HOST — バインドするホスト。デフォルト：0.0.0.0。
• FORGE_MCP_PORT — バインドするポート。デフォルト：8765。
• FORGE_MCP_BEARER — 開発時のフォールバック専用。リクエストごとの Bearer 抽出が通常の方法です（CW-MCP-1-B）。この環境変数は、受信リクエストに Authorization ヘッダーがない場合にのみ使用されます。本番環境では設定しないでください。

Claude Desktop の設定

~/Library/Application Support/Claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "forge-mcp": {
      "url": "http://localhost:8765/mcp",
      "headers": {
        "Authorization": "Bearer <your-forge-transpile-token>"
      }
    }
  }
}

Bearer を取得します。

jq -r '.transpileServiceToken' \
    ~/forge-vaults/bluh/.obsidian/plugins/forge-client-obsidian/data.json

ツール

読み取り（副作用なし）：

• forge_read_note_catalog({domain?}) — Forge ライブラリのノートを一覧表示します。各項目には、エージェントが呼び出すために必要な E-- シグネチャが含まれます。
• forge_read_notes_in_vault({filter?}) — Vault のノートを、has_recipe と recipe_version の概要とともに一覧表示します。ローカルファイルシステムを走査して取得します（CW-MCP-2-E）。

作成（決定的 — LLM も Vault への書き込みも不要）：

• forge_compile_recipe({source}) — Recipe → Python。コンパイル済みソースと未解決スロット数、または行番号と列番号を含む構造化された解析エラーを返します（drain CW-recipe-parser-line-info に準拠）。
• forge_run_recipe({source, domains?}) — リソース制限付きのサーバーサンドボックスでコンパイルして実行します。短いプレビューと run_id を返します。成果物（MusicXML／MIDI／PNG）は forge-artifact:// リソースから取得できます。
• forge_get_run_result({run_id}) — 過去の実行結果の標準出力／標準エラー全文と成果物マニフェストを取得します。保持期間は 7 日間で、Bearer ごとに分離されます。

コミット：

• forge_commit_recipe({source, note_id, expected_version?}) — Recipe を Vault のノートに保存します（ファセット単位で更新し、Description、Python、フロントマターはバイト単位でそのまま保持されます）。ノートのフロントマターにある recipe_version を更新します。expected_version による楽観的同時実行制御に対応しています。バージョンが競合すると、期待値と現在の値を含む isError:true を返します。

リソース

• forge-note:///{domain}/{name} — ライブラリノートの内容。
• forge-artifact:///{run_id}/{artifact_name} — 実行成果物をオンデマンドでバイナリ取得します。テキスト形式の MIME は text で、バイナリは base64 の blob で返されます。
• forge-recipe:///{note_id}/v{n} — 指定した recipe_version の Recipe 本文（Git で追跡されている Vault のみ対応。それ以外では「履歴は利用できません」というテキストを返します）。

認証

forge-mcp はトークン自体を検証しません。正とする認証情報は forge-transpile が管理します（FORGE_TRANSPILE_SECRET で保護されています）。各リクエストの Authorization: Bearer <token> ヘッダーはそのまま転送されます。forge-transpile から 401 または 403 が返ると、エージェントが読める実行可能なメッセージとともに isError: true として通知されます（drain CW-MCP-1-B）。

forge-mcp 側でのトークンローテーションはダウンタイムなしで行えます。forge-transpile の FORGE_TRANSPILE_SECRET を変更し、MCP クライアントのヘッダーを更新すれば完了です。古いトークンは次のリクエストから明確な拒否メッセージとともに無効になります。

関連リポジトリ

• forge — E-- パーサーとトランスパイラー、およびコア音楽ライブラリです。forge-mcp は CW-MCP-2-A アーキテクチャに従って forge/recipe/ のスナップショットを同梱します。差分は forge-transpile リポジトリの scripts/check-recipe-drift.sh で検出されます。
• forge-transpile — forge-mcp のツールがトランスパイルおよびサンドボックス実行の処理をプロキシする、/compile、/run、/catalog などを提供する FastAPI サービスです。Vault の読み取りとコミットはローカルで行われ、forge-transpile にはアクセスしません。
• forge-client-obsidian — 同じ制作ワークフローにおける Obsidian プラグイン側です。forge-mcp はプラグインが読み取り・レンダリングするものと同じ Vault に書き込みます。どちらも同じノートファイル形式を使用します。