内容
# 标签MCP — TuxGuitar 中的人工智能音乐家
标签MCP 将 MCP 兼容的人工智能客户端（Claude Code、OpenAI Codex、Google Antigravity/Gemini、xAI Grok、Claude Desktop 等）连接到 [TuxGuitar](https://tuxguitar.app) 中当前打开的乐谱。人工智能可以**作曲、编曲、聆听自己的作品、批评并修改** — 就像音乐家在工作室一样，而不是一次性生成器。
*嵌入式聊天窗口在 TuxGuitar 中实时编曲：快速操作模板、模型选择器和合成管道（生成riff、检查hook、互锁鼓、低音）实时流式传输到工作室记录。*
- **Rust 服务**（`crates/`）：MCP 服务器、标准化乐谱模型、音乐理论引擎（音阶、和弦、指法、生成、批评）和音频“耳朵”（渲染 + DSP 分析）。
- **Java 插件**（`tuxguitar-mcp-bridge/`）：一个薄的桥梁，位于 TuxGuitar 内部，通过 localhost 套接字公开实时乐谱，并通过 TuxGuitar 自己的操作/撤销系统应用编辑。
文档：[PLAN.md](PLAN.md)（架构）· [docs/PROTOCOL.md](docs/PROTOCOL.md)（桥梁协议）· [docs/ROADMAP.md](docs/ROADMAP.md)（下一步）。
## 人工智能耳朵的精炼循环
该项目的核心：与其假设生成的音乐听起来不错，不如让人工智能迭代 —
1. **作曲** 一个riff/编曲（或读取用户编写的内容）
2. **评估** — `tuxguitar_evaluate` 评估每个轨道：节奏一致性、切分、主题发展（字面 vs. 变体重复）、每小节紧张度曲线、和谐节奏、休息份额、机器人动力学和无聊检测、跨轨道冲突、调/音阶、人工智能伪影的人类感觉检查和通过-通过趋势
3. **聆听** — `tuxguitar_render_and_listen` 通过 TuxGuitar 自己的音色字体渲染真实的混音（无头 MIDI -> fluidsynth -> WAV -> DSP：响度、剪辑、频谱平衡、安静孔）；
`tuxguitar_listen_stems` 渲染**每个轨道隔离** 以便听到哪个乐器引起问题
4. **修复** 顶级问题与编辑工具 — 每个编辑首先预览，修订检查，并落在 TuxGuitar 的撤销栈中
5. **重复**，讲述每个通道 — 撤销栈是版本历史（一个 Cmd+Z per 通道）
在循环周围是作曲乐器：**Riff DNA** （提取一个riff的身份并演化它而不是复制），**riff演化**（通过突变世代爬坡一个riff，由人工智能耳朵评分），**主题跟踪**（跨章节的音乐记忆：重述，变化，倒置，片段主题；呼叫和响应检测），**hook检查**（一个批评家，其唯一工作是拒绝令人遗忘的riff），**现实检查**（不可能的伸展，弦破坏弯曲），**难度分析器**（1-10带有原因，疲劳和拾取模拟），**制作人笔记**（编曲级建议），**风格匹配**（“是什么让这个听起来像死亡金属？”），流派**混合**（“60％死亡金属，40％ Doom”），和**情感目标**（“平静，不安，攻击，胜利”检查对抗测量的紧张曲线）。
## 工具表面（59 种工具 + 3 种提示）
| 区域 | 工具 |
|---|---|
| 状态和阅读 | `get_bridge_status`，`get_score_summary`，`get_measures`，`get_selection` |
| 人工智能耳朵 | `evaluate`（完整记分卡；可选`style`目标，`tension_target`弧线，`emotion_target`旅程），`render_and_listen`（完整混音 + 每小节级别 + A/B增量vs. 上一个版本），`listen_stems`（每轨道，带有自动说明） |
| 编曲 | `generate_transitions`（鼓点填充，渐强，乐队停止在章节边界 - 之前每个标记一次如果要求），`ornament`（风格特异性发音通道：颤音，滑动，捏挤啸音，装饰音，颤音转换），`plan_harmony`（情绪或学位进展与语音引导判决和踏板警告），`apply_harmony`（编写计划为重型/半/全音阶），`generate_lead`（lick-cell独奏线：轮廓弧，问题/答案措辞，难度上限），`diff_measures`（音乐git-diff在两个范围之间），`checkpoint`（riff家谱：命名快照与分支树，恢复任何祖先） |
| 作曲智能 | `generate_riff`（约束引导的波束搜索：节奏单元字母表，音阶音空间，强调/踢统一，同步窗口，AABA'形式，可选紧张/情绪弧与根和弦在短语结尾，风格提示从您的播放器笔记 - 确定性），`riff_dna`（主题/节奏单元/音阶/技术/能量身份；`save_as`建立个人DNA库），`evolve_riff`（N世代突变爬坡，人工智能耳朵适应度），`track_themes`（主题记忆跨章节+呼叫和响应），`hook_check`（可记忆性门：通过或拒绝带有原因），`check_realism`（不可能或尴尬的吉他写作），`analyze_difficulty`（1-10带有原因，疲劳模型，拾取模拟），`producer_notes`（编曲建议），`style_match`（音乐实际上相似的风格） |
| 分析 | `analyze_arrangement`，`detect_key_and_scale`（44音阶目录包括弗里吉亚主导，hirajoshi，...），`detect_chords`，`explain_selection`，`style_guide`（16流派量规：音阶，调音，米，章节，情绪，难度，避免列表，评估目标，乐器角色；流派交叉混合语法；为您自己的播放器笔记提供服务从`~/.tuxguitar-mcp/styles/*.md`-指板词汇，规则，甚至完全自定义的风格 - 参见`docs/styles/README.md`） |
| 写作 | `replace_measures`（和弦，tuplets，双声部，捏谐波，弯曲曲线，颤音拨弦，琶音，装饰音），`transpose`，`humanize`（抖动+ groove感觉：驱动，落后，口袋），`copy_measures`，`vary_riff`（9种变换：位移，逆行，倒置，八度，增，减，踏板音填充，多节奏分组，动力学交换，和弦琶音），`rebar`（将一个riff倒入不同的时间签名 - 小节线移动，音符保持其流动），`import_midi`（MIDI->优化选项卡） |
| 指法 | `optimize_fingering` — 和弦感知的DP，带有解释，指板范围约束，成本预设（`metal`） |
| 生成 | `generate_bassline`（根锚检测，声音字体安全寄存器），`generate_harmony`（3rds/6ths，任何目录音阶），`generate_counterline`（在riff的间隙中回答旋律，相反运动，强拍和谐），`generate_drums`（风格：摇滚，金属-咕噜，朋克，半拍，爆裂，d-拍；节拍感知；`target_track`每章节的节奏），`generate_interlock`（从riff本身派生的鼓：踢与强调的统一） |
| 结构 | `create_track`（预设包括7弦A标准，低音谱号，percussion），`change_tuning`，`set_tempo`，`set_time_signature`（奇数米），`set_key_signature`，`insert_measures`，`delete_measures`，`set_repeat`（循环），`set_marker` |
| 传输和练习 | `play`，`play_from`，`stop`，`toggle_metronome`，`toggle_count_in` |
| 文件 | `save_copy`，`export`（多轨MIDI，吉他专业版，...） |
| 历史 | `undo`，`redo` |
**MCP提示**（一键工作流）：`compose`（样式/键/条->完整作曲和精炼会话），`refine`（对打开的乐谱进行N次人工智能耳朵通道），和`band`（五种个性 - 作曲家，评论家，制作人，吉他手，听众 - 每种都有自己的工具，投票，并应用赢得的修复）。对于真正的的东西 - 五个独立的模型实例与单独的上下文和可选的不同模型每个角色 - 运行`python3 scripts/band_session.py`（env `TABMCP_BAND_MODELS="critic=opus,listener=haiku"`； `--roles`/`--no-apply`限定会话）；一个制作人椅子实例应用投票更改，分钟登陆`~/.tuxguitar-mcp/band-minutes.txt`。
（所有工具名称都带有`tuxguitar_`前缀。）
安全模型：每个变异工具都是**两步**（预览->确认绑定到预览修订），**修订检查**（过时写入拒绝），**原子**，和**可撤销** - 包括自动追加措施和生成的轨道。一个金色线格式装置在CI中保护Rust <-> Java协议免受意外更改。
## TabBench：作曲评估
riff战斗在`bench/`中正式化为一个可重复的基准：一个规范的简报（`bench/prompt.md`），一个客观的裁判（`bench/judge.py`- 100点评分标准超过风格匹配，音阶，发展配额，钩子，结构，清洁度，人类感觉和混音），和迄今为止的结果（`bench/TABBENCH.md`）。任何MCP-capable代理都可以进入：新鲜的乐谱，相同的简报，一个客户端一次，盲耳投票与小组一起。两次非正式的轮次已经有记录 - Gemini参加了第一轮，Claude参加了第二轮，使用升级的工具包。
## 嵌入式聊天：TuxGuitar中的人工智能音乐家
插件0.9.0添加工具->“TabMCP：AI音乐聊天” - 一个聊天窗口位于TuxGuitar中，由无头Claude Code支持。输入“给我写一个A弗里吉亚调的d-beat诗节”，回复流式传输到面板，而工具调用击中同一个TuxGuitar的乐谱；工具活动实时显示（[工具]生成_riff ...），每个编辑保持可撤销，会话在消息之间继续（新建会话重置它）。
要求：Claude Code已安装。`~/.tuxguitar-mcp/chat.properties`中的可选配置：
```properties
claude.path=/opt/homebrew/bin/claude # 自动检测时省略
claude.model=opus # 默认：您的CLI默认值
tabmcp.path=/Users/you/.cargo/bin/tabmcp
allowed.tools=mcp__tuxguitar # 自动批准的工具集
```
一次只能有一个桥接客户端：关闭其他AI会话时，嵌入式聊天正在作曲。
## 快速入门
要求：macOS与TuxGuitar 2.x安装，Rust工具链，JDK 11+，Maven；`brew install fluid-synth`用于音频耳朵。
```sh
# 1. 构建+安装插件（每次插件更新一次）
scripts/install-tuxguitar-deps.sh "/Applications/<your TuxGuitar>.app" # 一次
（ cd tuxguitar-mcp-bridge && mvn package ）
cp tuxguitar-mcp-bridge/target/tuxguitar-mcp-bridge.jar \
"/Applications/<your TuxGuitar>.app/Contents/MacOS/share/plugins/"
# 2. 安装MCP服务器二进制文件
cargo install --path crates/tabmcp-server # ~/.cargo/bin/tabmcp
# 3. 使用您的AI客户端注册 - 请参见下面
```
### 使用您的AI客户端注册
TabMCP是客户端无关的：任何MCP-capable代理都可以与其一起创作（我们运行riff战斗）。在每个地方注册相同的命令 - **`~/.cargo/bin/tabmcp serve`** 通过stdio：
**Claude Code**
```sh
claude mcp add tuxguitar -- ~/.cargo/bin/tabmcp serve
```
**OpenAI Codex CLI**
```sh
codex mcp add tuxguitar -- ~/.cargo/bin/tabmcp serve
```
（位于`~/.codex/config.toml`；使用`codex mcp list`检查）
**Google Antigravity** （Gemini）：在IDE中打开**Manage MCP Servers -> Open MCP Config** （代理面板的`...`菜单）并添加：
```json
{
"mcpServers": {
"tuxguitar": { "command": "/Users/<you>/.cargo/bin/tabmcp", "args": ["serve"] }
}
}
```
然后点击**刷新** - 应该出现“tuxguitar，59种工具已启用”。 `agy`CLI从`~/.gemini/config/mcp_config.json`读取相同的形状。
**xAI Grok CLI**：添加相同的`mcpServers` JSON块到Grok的MCP配置（`grok mcp add`或其设置文件的`mcpServers`部分，具体取决于您的构建 - 请查看`grok --help`）。任何支持MCP stdio的客户端都可以使用相同的`command`/`args`对。
一次只能使用一个客户端：桥接器服务一个连接，因此在切换创作者时关闭或空闲其他AI会话。
启动TuxGuitar，然后在客户端的新会话中尝试：
> *"编写一个E小调的8小节金属riff，并带有捏音，生成低音和鼓，并使用AI Ear循环精炼，直到记分卡干净 - 并让我听每一次通过。*
## 开发
```sh
cargo test --workspace # Rust套件包括客户端<->模拟器测试
（ cd tuxguitar-mcp-bridge && mvn test ） # Java测试对抗真实TG罐
scripts/dev-reload.sh # 重建插件 + 重启TuxGuitar + 等待
tabmcp doctor # 连接性 + 乐谱摘要
tabmcp bridge-sim # 在没有TuxGuitar的情况下开发Rust端
```
CI：GitHub Actions运行Rust的fmt/clippy/tests，并从源码构建TuxGuitar 2.0.1（缓存）以编译和测试Java插件。
## 安全
环形套接字；`~/.tuxguitar-mcp/bridge.json`中的32字节随机令牌（0600发现文件）；不通过电线接受文件路径或命令（导出通过TuxGuitar自己的对话框进行；渲染使用`~/.tuxguitar-mcp/`下的固定临时路径）。
## 许可证
- Rust工作区：MIT OR Apache-2.0
- `tuxguitar-mcp-bridge/`：LGPL-2.1（链接到TuxGuitar，它是LGPL-2.1）
