Forge MCP

forge-mcp

直接通过任何支持 MCP 的 Agent（Claude Desktop、Cursor 等）编写、编译、运行并提交生成式音乐 E-- 配方。 forge-mcp 将 Forge E-- 库的笔记目录和保险库作为 MCP 服务公开，并端到端打通编写流程：Agent 从目录中选择一个芯片，起草配方，验证其是否能解析，在沙箱中运行，预览生成的产物，并将完成的配方提交到保险库笔记。目前已提供全部 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 使用的本地保险库目录。默认值：~/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 库笔记；每个条目都包含 Agent 调用它所需的 E-- 签名。
• forge_read_notes_in_vault({filter?}) — 列出保险库笔记，并附带 has_recipe 和 recipe_version 摘要。由本地文件系统遍历提供支持（CW-MCP-2-E）。

编写（确定性操作——不使用 LLM，不写入保险库）：

• forge_compile_recipe({source}) — 将配方转换为 Python。返回编译后的源码和未解析的插槽数量，或包含行号/列号的结构化解析错误（依据 drain CW-recipe-parser-line-info）。
• forge_run_recipe({source, domains?}) — 编译配方，并在受资源限制的服务端沙箱中执行。返回简短预览和一个 run_id；可通过 forge-artifact:// 资源访问产物（MusicXML / MIDI / PNG）。
• forge_get_run_result({run_id}) — 获取先前运行的完整 stdout/stderr 和产物清单。保留 7 天，按 Bearer 隔离。

提交：

• forge_commit_recipe({source, note_id, expected_version?}) — 将配方保存到保险库笔记（按分面更新——Description、Python 和 frontmatter 均逐字节保留）。递增笔记 frontmatter 中的 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 对应的配方正文（仅适用于由 git 跟踪的保险库；否则返回“历史记录不可用”文本）。

身份验证

forge-mcp 本身不会验证令牌——forge-transpile 是唯一可信来源（由 FORGE_TRANSPILE_SECRET 保护）。每个请求的 Authorization: Bearer <token> 标头都会原样转发；forge-transpile 返回的 401 或 403 会以 isError: true 形式呈现，并附上 Agent 可读的可操作消息（drain CW-MCP-1-B）。

forge-mcp 端的令牌轮换无需停机：在 forge-transpile 上更改 FORGE_TRANSPILE_SECRET，更新 MCP 客户端的标头，即可完成。旧令牌会在下一个请求时失效，并返回清晰的拒绝消息。

相关仓库

• forge — E-- 解析器、转译器和核心音乐库。根据 CW-MCP-2-A 架构，forge-mcp 引用了 forge/recipe/ 的一个快照；forge-transpile 仓库中的 scripts/check-recipe-drift.sh 会检测差异。
• forge-transpile — 提供 /compile / /run / /catalog 等接口的 FastAPI 服务，forge-mcp 的工具会通过该服务执行转译和沙箱运行。Vault 的读取和提交都在本地进行，不会访问 forge-transpile。
• forge-client-obsidian — 同一创作流程中的 Obsidian 插件。forge-mcp 会写入插件读取和渲染的同一个 Vault；两者共用笔记文件格式。