内容
# makid-mcp
一个用于查询和安全编辑 [MAKID](https://www.makidapp.com) 音乐目录数据库的 [MCP](https://modelcontextprotocol.io) 服务器。这样，AI 助手（或您通过 AI 助手）可以通过语音而不是手写的 SQL 来标记、分类、键控和分类您的项目库。
[MAKID](https://www.makidapp.com)（由 Templar Labs LLC 开发）帮助 Ableton Live 制作者在单个工作空间中组织项目、混音和笔记。这是一个独立的、非官方的工具，不隶属于 Templar Labs，也未得到其认可。
## 功能
MAKID 将您的项目、曲目、流派、标签和状态存储在本地 [Prisma](https://www.prisma.io) 管理的 SQLite 数据库中。您可以对这些数据执行许多操作，但 GUI 操作速度较慢：“显示我所有未分类且 BPM 小于 100 的项目”，“标记所有这些 *Dark*”，“设置这 12 个草图的键”。手动操作需要编写原始 SQL 并确保细节完全正确 - Prisma 的 ISO-8601 时间戳格式、小写流派、大写标签、有效键值、幂等连接行。如果操作错误，数据将偏移。
`makid-mcp` 将这些操作暴露为一组小型 MCP 工具，并内置规则。读取操作通过只读连接进行；每次写入操作都会自动备份，然后在单个事务中运行，拒绝破坏数据库结构。
## 功能特点
- **查询** 项目，支持组合过滤器（流派、标签、状态、层级、进度、键、BPM 范围、名称）。
- **查看** 项目的完整详细信息 - 曲目、键、速度、Ableton Live 版本、关联。
- **统计** 用于标签传递：未标记 / 未分类 / 无键项目的数量，以及层级 / 进度 / 键的分布。
- **编辑** 安全：分配/删除流派、标签（带 `#RRGGBB` 颜色）和状态；设置曲目的键；编辑层级 / 进度 / 备注；管理标签目录。
- **格式正确的写入**：ISO-8601 时间戳、小写流派、大写标签、验证键（MAKID 的固定 24 值集）- 所有这些都自动强制执行。
- **安全第一**：自动预写入备份、保留幂等连接插入、外部键强制执行、仅 SELECT 的原始查询逃生口，以及当 MAKID 运行时发出警告（或硬阻止）。
## 需求
- 安装了 [MAKID](https://www.makidapp.com) 的 macOS（针对 0.7.2 架构构建）。
- Python 3.11+。
## 安装
```bash
git clone https://github.com/ecarter/makid-mcp.git
cd makid-mcp
pip install -e .
```
### 在 MCP 客户端中注册
将以下内容添加到客户端的 MCP 配置中（例如 Claude Code 的 `~/.claude/settings.json`）- 通过安装的控制台脚本：
```json
{
"mcpServers": {
"makid": { "command": "makid-mcp" }
}
}
```
或者直接指向模块：
```json
{
"mcpServers": {
"makid": { "command": "python", "args": ["-m", "makid_mcp.server"] }
}
}
```
参见 [`examples/claude_mcp_config.json`](examples/claude_mcp_config.json)。
## 配置
所有配置项均为可选，通过环境变量设置：
| 变量名 | 默认值 | 用途 |
| --- | --- | --- |
| `MAKID_DB_PATH` | `~/Library/Application Support/makid/MAKID.db` | 数据库路径。 |
| `MAKID_BACKUP_DIR` | 数据库旁边 | 预写备份写入的位置。 |
| `MAKID_BACKUP_KEEP` | `10` | 保留的备份数量（较旧的备份会被修剪）。 |
| `MAKID_BLOCK_WHEN_RUNNING` | 关闭 | 如果设置（`1`/`true`），则在 MAKID 运行时拒绝写入。 |
## 工具
| 工具 | 类型 | 描述 |
| --- | --- | --- |
| `list_projects` | 读取 | 按流派/标签/状态/层级/进度/键/BPM/名称过滤项目。 |
| `get_project` | 读取 | 获取一个项目的完整详细信息（按 ID 或名称）。 |
| `list_genres` / `list_tags` / `list_statuses` | 读取 | 带有使用计数器的目录条目。 |
| `stats` | 读取 | 总数、分布和未标记/未分类/无键计数。 |
| `query_sql` | 读取 | 运行单个只读 `SELECT`（拒绝写入）。 |
| `assign_genre` / `remove_genre` | 写入 | 流派成员资格（如果流派不存在则创建）。 |
| `rename_genre` / `delete_unused_genre` | 写入 | 流派目录管理（重命名会合并到现有的目标）。 |
| `assign_tag` / `remove_tag` | 写入 | 标签成员资格（创建标签，可选颜色）。 |
| `assign_status` / `remove_status` | 写入 | 状态成员资格。 |
| `set_key` | 写入 | 设置曲目的键（MAKID 的 24 个值之一）。 |
| `set_project_field` | 写入 | 编辑 `tier`、`progress` 或 `editorNotes`。 |
| `create_tag` / `recolor_tag` / `delete_unused_tag` | 写入 | 标签目录管理。 |
| `list_backups` / `restore_backup` | 读取/写入 | 列出和回滚到预写入快照。 |
## 安全性和备份
- 每次写入操作 **首先备份数据库** 到 `MAKID.db.bak-YYYYMMDD-HHMMSS`，并修剪到最新的 `MAKID_BACKUP_KEEP`。`restore_backup` 回滚（并且首先快照，因此可逆转）。
- MAKID 写入相同的数据库，因此并发编辑是 **最后写入者获胜**。服务器在每次写入时都会警告 MAKID 运行时；设置 `MAKID_BLOCK_WHEN_RUNNING=1` 可以完全禁止写入。
- **标签更改** 可能不会立即显示，直到您右键单击 → 在 MAKID 中重新同步或重新启动（应用程序缓存标签调色板）。流派和键更改实时显示。每个标签工具都会返回此提醒。
## 工作原理
```
MCP 客户端
│ 工具调用
▼
server.py ──► 安全防护 ──► 备份 ──► 单个写入事务 ──► 仓库（SQL）
│ │
└────────────── 只读连接 ───────────────────────────────────┘
```
- `validators.py` 保持 MAKID 格式的每个写入值。
- `db.py` 将只读连接与事务写入连接分开，并保护原始 SQL 工具。
- `backup.py` / `safety.py` 处理快照和运行应用程序的检测。
- `repository.py` 是 SQL 层；`server.py` 是薄的 MCP 工具表面。
## 开发
```bash
pip install -e ".[dev]"
pytest # 测试运行在合成夹具上 - 不需要真正的数据库
ruff check .
```
## 状态
v0.1.0。读取和写入工具已实现，并通过合成的 MAKID 形状的夹具进行测试。
## 限制
- 构建针对 **MAKID 0.7.2** 架构；未来的 MAKID 版本可能会更改表/列。
- 仅支持单个本地数据库（不支持 MAKID 云同步）。
- `editorNotes` 以纯文本写入；MAKID 还保留富文本 `editorNotesState`，因此此处设置的备注可能会在应用程序中以纯文本渲染。
- 标签可见性需要 MAKID 重新同步/重启（参见上文）。
## 许可证
MIT © E. T. Carter。 不属于 MAKID 或 Templar Labs LLC。
