cratedigger (Frank Burmo)

火山口引爆器


用于音乐库的MCP服务器——通过任何与MCP兼容的AI助手（Claude Code、Claude Desktop、Cursor、GitHub Copilot等）使用自然语言查找并修复ID3/Vorbis标签问题。

特性

• 扫描 您的音乐库（MP3、FLAC、M4A、AAC、OGG、Opus、WMA、WAV），并将元数据索引到本地SQLite数据库中
• 增量扫描 --仅重新读取自上次扫描以来已更改的文件
• 检测标签问题 每个文件和每个专辑（缺少字段、没有封面、专辑中年份/专辑艺术家不一致）
• 写入标签 通过TagLib——每次写入后自动更新数据库
• MusicBrainz查找 为录制和相册查找正确的元数据
• 批量修复 --在一个提示中对数百个文件应用标记更改

先决条件

• Node.js≥20
• 用于本机插件的C++构建工具链(better-sqlite3, node-taglib-sharp)

- macOS：Xcode命令行工具(xcode-select --install) - Linux： build-essential python3 - 窗户： windows构建工具 或Visual Studio生成工具

安装

git clone https://github.com/FrankBurmo/cratedigger
cd cratedigger
npm install
npm run build

配置

复制 .env.example 到 .env 并填写您的值：

# Required
MUSIC_LIBRARY_PATH=/path/to/your/music
DB_PATH=/home/user/.local/share/cratedigger/library.db
MB_CONTACT_EMAIL=your@email.com

# Optional
MB_APP_NAME=cratedigger
MB_APP_VERSION=1.0.0
SCAN_ON_STARTUP=true
LOG_LEVEL=info

MB_CONTACT_EMAIL 是必需的 MusicBrainz API政策.

跑步

# Development (no build step needed, uses tsx)
npm run dev

# Production
npm run build
npm start

连接到AI代理

装箱机是标准配置 主控程序 stdio服务器，可与任何兼容MCP的客户端配合使用。将下面的占位符路径替换为您的实际绝对路径 dist/index.js 以及你的音乐库。

克劳德代码（CLI）

将服务器添加到项目的 .mcp.json （已在此仓库中提供——只需填写路径）：

{
  "mcpServers": {
    "cratedigger": {
      "command": "node",
      "args": ["/absolute/path/to/cratedigger/dist/index.js"],
      "env": {
        "MUSIC_LIBRARY_PATH": "/path/to/your/music",
        "DB_PATH": "/home/user/.local/share/cratedigger/library.db",
        "MB_CONTACT_EMAIL": "your@email.com"
      }
    }
  }
}

或者在CLI中全局注册：

claude mcp add cratedigger -e MUSIC_LIBRARY_PATH=/path/to/your/music \
  -e DB_PATH=/home/user/.local/share/cratedigger/library.db \
  -e MB_CONTACT_EMAIL=your@email.com \
  -- node /absolute/path/to/cratedigger/dist/index.js

克劳德桌面

编辑操作系统的配置文件：

{
  "mcpServers": {
    "cratedigger": {
      "command": "node",
      "args": ["/absolute/path/to/cratedigger/dist/index.js"],
      "env": {
        "MUSIC_LIBRARY_PATH": "/path/to/your/music",
        "DB_PATH": "/home/user/.local/share/cratedigger/library.db",
        "MB_CONTACT_EMAIL": "your@email.com"
      }
    }
  }
}

光标

创建或编辑 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （项目范围）：

{
  "mcpServers": {
    "cratedigger": {
      "command": "node",
      "args": ["/absolute/path/to/cratedigger/dist/index.js"],
      "env": {
        "MUSIC_LIBRARY_PATH": "/path/to/your/music",
        "DB_PATH": "/home/user/.local/share/cratedigger/library.db",
        "MB_CONTACT_EMAIL": "your@email.com"
      }
    }
  }
}

VS代码/GitHub副本

编辑 .vscode/mcp.json （已在此回购中提供）：

{
  "servers": {
    "cratedigger": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/cratedigger/dist/index.js"],
      "env": {
        "MUSIC_LIBRARY_PATH": "/path/to/your/music",
        "DB_PATH": "/home/user/.local/share/cratedigger/library.db",
        "MB_CONTACT_EMAIL": "your@email.com"
      }
    }
  }
}

示例提示

连接后，您的AI助手可以直接调用这些工具：

*“扫描我的库，向我显示所有缺少专辑艺术家标签的曲目”* *“查找并非所有曲目都有相同年份的所有专辑”* *“在MusicBrainz上查找Daft Punk的Discovery的正确元数据”* *“将Discovery专辑中的所有曲目的专辑艺术家设置为'Daft Punk'”*

MCP工具

可检测的问题类型

missing_title · missing_artist · missing_album · missing_albumartist · missing_year · missing_tracknumber · missing_genre · no_cover · inconsistent_albumartist · inconsistent_year · missing_mb_trackid

项目结构

src/
├── index.ts              # Entrypoint — starts the MCP server
├── server.ts             # Tool registration
├── config.ts             # Zod-validated environment config
├── types.ts              # Shared TypeScript types
├── db/
│   ├── schema.ts         # SQLite DDL and initDb()
│   └── queries.ts        # All SQL operations (no inline SQL elsewhere)
├── scanner/
│   ├── extract.ts        # Tag reading (music-metadata) + per-file issue detection
│   └── scan.ts           # Library scan orchestration + album-level issue detection
├── tagger/
│   └── write.ts          # Tag writing (node-taglib-sharp) + DB sync
├── musicbrainz/
│   └── lookup.ts         # MusicBrainz REST API wrapper
└── tools/                # One file per MCP tool
    ├── scan_library.ts
    ├── find_issues.ts
    ├── get_track.ts
    ├── search_tracks.ts
    ├── fix_tag.ts
    ├── bulk_fix.ts
    └── lookup_musicbrainz.ts

许可证

Apache许可证2.0