内容
# kobox
<p align="center">
<img src="assets/kobox-poster.png" alt="Kobox — 与Claude对话，操控K.O. II" width="100%">
</p>
<p align="center">
<img src="https://img.shields.io/badge/python-3.9%2B-3776AB" alt="python 3.9+">
<img src="https://img.shields.io/badge/MCP-stdio_server-111" alt="MCP stdio 服务器">
<img src="https://img.shields.io/badge/license-MIT-green" alt="MIT 许可证">
</p>
通过与Claude对话来操控您的**Teenage Engineering EP-133 K.O. II**。kobox是一个小型 [MCP](https://modelcontextprotocol.io) 服务器，可以将纯语言转换为MIDI信号——触发音垫、创建节奏、播放音阶——直接发送到硬件设备。
> "连接到我的K.O. II，然后在A组上播放一个升序的C小调五声音阶。"
这行得通。您也可以要求一个16步的节奏、单个音符或11种音阶中的任何一种旋律。
---
## 安装 — 简便方法（Claude Code）
您不需要了解任何Python知识，Claude会为您处理设置。
1. 通过USB将K.O. II连接到您的计算机并打开它。
2. 将此仓库的URL粘贴到**Claude Code**中，然后说：**"为我安装这个MCP。"** 它会读取[`CLAUDE.md`](CLAUDE.md)并自行处理环境、依赖项、注册和连接检查。
3. 重新启动Claude Code，然后说**"连接到我的K.O. II"**并开始播放。
## 安装 — 一行命令（如果您已经使用`uv`）
```bash
uvx --from git+https://github.com/yangyue1974/kobox kobox
```
然后将您的MCP客户端指向命令`uvx --from git+https://github.com/yangyue1974/kobox kobox`。
## Claude Desktop
桌面版无法运行设置命令。请在安装了Claude Code的机器上安装一次，然后将`claude mcp get kobox`显示的命令和绝对路径复制到Desktop的MCP服务器配置中。
---
## 可以说的话
| 您说的话 | kobox会做的事情 |
| --- | --- |
| "连接到我的K.O. II" | 自动检测并打开EP-133 MIDI端口 |
| "触发B组上标记为5的音垫" | 触发`B5`音垫 |
| "播放一个16步的节奏，使用A组的音垫A.、A0和A1" | 按时序播放节奏 |
| "在A组上播放一个升序的C大调音阶" | 按音阶播放旋律 |
| "播放C3，然后是F#4" | 发送原始音符 |
| "我可以播放哪些音阶？" | 列出所有11种音阶 |
## 工具
| 工具 | 用途 |
| --- | --- |
| `connect` · `disconnect` | 打开/关闭设备（自动检测EP-133） |
| `list_ports` | 列出可用的MIDI输出端口 |
| `trigger_pad` | 通过标记触发音垫（`A.`、`A1`、`D9`……） |
| `play_note` | 播放MIDI音符编号或名称（`C3`、`F#4`） |
| `play_pattern` | 播放一系列按时间排序的音符 |
| `play_scale` | 按音阶播放旋律——11种音阶，任意根音 |
| `list_scales` | 列出支持的音阶及其音程 |
| `device_info` | 报告设备的音符映射和音垫布局 |
## 音垫如何命名
音垫引用是**组字母**（A–D）加上**音垫上标记的符号**——不是1到12的索引。在每个组内，标签从最低音符开始向上排列：
```
. 0 enter 1 2 3 4 5 6 7 8 9
```
因此，`A.`是A组最低的音垫，而`A1`是标记为“1”的音垫（第四个音垫）。四个组分别位于自己的八度带中：A = MIDI 36–47，B = 48–59，C = 60–71，D = 72–83。这是在实际硬件上测量的，而不是猜测的。
## kobox不做的事情
- **它不假装知道您的声音。** 每个K.O. II加载的样本都不同，因此kobox通过位置寻址音垫，从不假装知道音垫听起来是什么样子的。
- **它不切换声音。** 在当前的固件中，MIDI程序更改不会更改音垫的声音——因此没有工具可以伪造它。
## 要求
一个Teenage Engineering EP-133 K.O. II，一根USB电缆，以及Claude Code或`uv`。Python和MIDI后端在设置过程中为您安装。
## 许可证
MIT — 请参见[`LICENSE`](LICENSE)。
