潮汐周期MCP服务器
项目介绍
🌀 TidalCycles MCP Server
通过自然对话控制TidalCycles进行实时编码
此MCP（模型上下文协议）服务器使Claude能够通过自然对话控制TidalCycles，创建强大的AI辅助实时编码体验，用于算法音乐创作。
✨ 特性
- 🎵 通过对话式AI评估TidalCycles模式
- 📊 状态感知 - Claude知道当前正在播放的内容
- 🕰️ 模式历史 - 跟踪并回忆之前的模式
- 🎛️ 通道管理 - 独奏、静音或关闭特定通道
- 💬 自然对话 - 使用英语与Claude讨论你的音乐
- 🔄 实时反馈 - 即时模式评估
- 🚀 双传输模式：stdio用于Claude桌面版 + WebSocket用于外部客户端
- 🌐 网络可访问 - Web UI和远程客户端可通过WebSocket连接
- 🔄 自动恢复 - 坚固的GHCi进程管理，自动重连
📋 先决条件
在安装之前，请确保你拥有：
-
TidalCycles - 从 tidalcycles.org 安装
- 包括GHCi（Glasgow Haskell编译器交互模式）
- Haskell Stack 或 Cabal
-
SuperCollider + SuperDirt - 音频输出所需
- 从 supercollider.github.io 下载
- 安装SuperDirt：在SuperCollider中运行
Quarks.install("SuperDirt") - 安装样本：
Quarks.install("Dirt-Samples")
-
Claude Desktop - 从 claude.ai 获取
-
Node.js 18+ - 运行MCP服务器
- 从 nodejs.org 下载
- 验证：
node --version
🚀 快速开始
1. 安装
# 克隆仓库
git clone https://github.com/yourusername/tidal-mcp-server.git
cd tidal-mcp-server
# 安装依赖
npm install
# 构建服务器
npm run build
2. 启动SuperCollider
打开SuperCollider并运行：
// 启动SuperDirt
SuperDirt.start;
// 验证是否正在监听
// 应该看到："SuperDirt: listening to Tidal on port 57120"
3. 配置Claude Desktop
在你的Claude Desktop配置文件中添加以下内容：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
文件模式（推荐稳定性）：
{
"mcpServers": {
"tidal": {
"command": "node",
"args": [
"/absolute/path/to/tidal-mcp-server/dist/index.js"
],
"env": {
"TIDAL_FILE": "/absolute/path/to/tidal-mcp-server/tidal-mcp-output.tidal"
}
}
}
}
直接GHCi模式（实验性 - 不重启）：
{
"mcpServers": {
"tidal": {
"command": "node",
"args": [
"/absolute/path/to/tidal-mcp-server/dist/index.js"
],
"env": {
"TIDAL_FILE": "/absolute/path/to/tidal-mcp-server/tidal-mcp-output.tidal",
"TIDAL_USE_GHCI": "true",
"TIDAL_BOOT_PATH": "/absolute/path/to/tidal-mcp-server/BootTidal.hs",
"GHCI_PATH": "/usr/local/bin/ghci"
}
}
}
}
找到你的ghci路径：
which ghci
# 使用这个路径作为GHCI_PATH
用实际安装路径替换 /absolute/path/to/。
4. 文件监控设置（仅限文件模式）
对于文件模式，你需要监视输出文件并在TidalCycles中评估它：
选项A：使用watchexec（推荐）
# 安装watchexec
brew install watchexec # macOS
# 或
cargo install watchexec-cli # 任何带有Rust的系统
# 监视并自动重新加载模式
cd /path/to/tidal-mcp-server
watchexec --restart -w tidal-mcp-output.tidal \
"ghci -ghci-script BootTidal.hs -ghci-script tidal-mcp-output.tidal"
选项B：使用你的编辑器
在支持TidalCycles的首选编辑器中打开 tidal-mcp-output.tidal 并手动评估Claude写入的模式。
5. 开始使用
- 重启Claude Desktop 加载MCP服务器
- 开始新的对话
- 制作音乐！
你：创建一个有趣的鼓点模式
Claude：[调用tidal_eval]
我会创建一个同步的放克节奏：
d1 $ sound "bd ~ bd ~ bd ~ ~ ~"
你：添加贝斯线
Claude：[调用d2上的tidal_eval]
添加了一个有节奏感的贝斯线：
d2 $ sound "bass2*8" # n "0 3 5 7"
🎹 使用示例
基本模式
你：播放一个简单的鼓点
你：让它更快
你：添加一些踩镲声
你：现在正在播放什么？
高级创作
你：创建一个带有欧几里得节奏的故障节拍
你：添加一个带有滤波扫过的摇摆贝斯线
你：在上面叠加一些氛围垫
你：让整个作品更稀疏
实时表演
你：独奏通道d2
你：恢复所有
你：静音
你：显示我最后评估的5个模式
🛠️ 可用工具
MCP服务器向Claude暴露了这些工具：
tidal_eval
在特定通道（d1-d9）上评估TidalCycles模式。
参数：
channel: 字符串（d1-d9）pattern: 字符串（不带d1 $前缀的TidalCycles代码）
示例：
{
"channel": "d1",
"pattern": "sound \"bd sd bd sd\" # gain \"1.2\""
}
tidal_hush
立即停止所有当前播放的模式。
tidal_silence
优雅地停止特定通道。
参数：
channel: 字符串（d1-d9）
tidal_get_state
获取所有通道的当前状态 - 正在播放的内容及其开始时间。
tidal_solo
独奏特定通道，静音其他所有通道。
参数：
channel: 字符串（d1-d9）
tidal_unsolo
独奏后恢复所有通道。
tidal_get_history
获取当前会话中的模式历史。
参数：
limit: 数字（可选，默认值：10）
📁 项目结构
tidal-mcp-server/
├── src/
│ ├── index.ts # 主MCP服务器实现
│ └── websocket-transport.ts # WebSocket传输层
├── dist/ # 编译后的JavaScript输出
├── BootTidal.hs # TidalCycles初始化
├── tidal-mcp-output.tidal # 生成的模式输出文件
├── start-websocket.sh # WebSocket服务器启动脚本
├── test-websocket-client.js # WebSocket连接测试
├── examples.tidal # 示例模式
├── WEBSOCKET-USAGE.md # WebSocket设置和使用指南
├── package.json # Node.js依赖
├── tsconfig.json # TypeScript配置
├── README.md # 本文档
├── QUICKSTART.md # 快速参考指南
├── CONTRIBUTING.md # 贡献指南
└── LICENSE # MIT许可证
🎨 使用场景
实时表演
- 在算法狂欢派对期间即时生成模式
- 快速迭代和实验
- 当卡住时紧急生成模式
- AI辅助即兴创作
学习与探索
- 让Claude解释TidalCycles概念
- 为特定技巧生成示例模式
- 探索新的节奏和和声想法
- 通过对话学习
创作
- 快速原型化音乐想法
- 生成模式变体
- 与AI协作创作
- 构建复杂的分层安排
🔧 架构
┌─────────┐ ┌──────────────┐ ┌──────────────┐
│ Claude │ ◄─MCP─► │ MCP Server │ ◄─────► │ TidalCycles │
│ AI │ │ (Node.js) │ │ (GHCi) │
└─────────┘ └──────────────┘ └──────────────┘
│ │
│ (文件模式) │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ .tidal文件 │ │ SuperCollider│
│ (监视) │ │ SuperDirt │
└──────────────┘ └──────────────┘
流程：
- 你以自然语言与Claude交谈
- Claude使用MCP工具生成Tidal代码
- MCP服务器要么：
- 文件模式：将代码写入
.tidal文件 → 文件监视器评估它 - 直接模式：直接发送到运行的GHCi进程
- 文件模式：将代码写入
- TidalCycles/GHCi发送OSC消息到SuperDirt
- SuperCollider/SuperDirt播放音频
🐛 故障排除
"MCP服务器未连接"
- 检查
claude_desktop_config.json中的路径是否绝对 - 配置更改后重启Claude Desktop
- 检查Node.js版本：
node --version（需要18+） - 检查Claude Desktop中的MCP服务器日志
"模式未播放"（文件模式）
- 确保SuperCollider正在运行：
SuperDirt.start - 验证文件监视器（watchexec）正在运行
- 检查TIDAL_FILE路径是否正确
- 尝试手动在编辑器中评估文件
"模式未播放"（直接GHCi模式）
- 检查ghci是否在PATH中：
which ghci - 验证配置中的GHCI_PATH与
which ghci匹配 - 检查MCP服务器日志是否有"GHCi/TidalCycles已启动并连接"
- 确保只有一个GHCi实例在运行
"spawn ghci ENOENT"
- GHCi不在PATH中
- 设置GHCI_PATH环境变量为完整路径
- 在macOS上使用ghcup：通常为
/Users/username/.ghcup/bin/ghci
"找不到样本" / 空的声音库
- 在SuperCollider中安装Dirt-Samples：
Quarks.install("Dirt-Samples"); // 重新编译（Cmd+K） SuperDirt.start; - 验证：
~dirt.soundLibrary.buffers.keys.do({|x| x.postln});
"延迟"消息在SuperCollider中
- 在快速节奏（丛林/DnB）中正常
- 如果严重（>1秒），重启SuperDirt
- 检查系统音频设置
- 减少模式复杂度
停止MCP服务器后音乐继续播放
- 模式在SuperCollider中运行，独立于MCP服务器
- 在SuperCollider中停止：
s.freeAll; - 或在任何GHCi/Tidal会话中：
hush - 杀死所有ghci进程：
pkill -9 ghci
🚧 已知限制
- 文件模式：每次更改都会重启GHCi（导致短暂的音频中断）
- 直接GHCi模式：实验性，可能存在边缘情况
- 无视觉反馈：模式变化在编辑器中不可见（文件模式）
- 单实例：不能同时运行多个MCP服务器
- 无撤销：模式变化是即时的且无法撤销
🗺️ 发展路线图
✅ 已完成功能
- 直接GHCi集成 - 无需文件监视即可实时评估模式
- WebSocket传输 - 网络可访问的服务器供Web UI和协作使用
- 健壮的错误处理 - GHCi进程恢复和连接监控
- 会话日志 - 带时间戳的完整模式历史
🚀 下一步（优先功能）
-
MIDI控制器输入 - 物理旋钮/推子控制Tidal参数
- 易于映射的MIDI学习模式
- 支持流行的控制器（Push，Launchpad等）
- 复杂参数自动化的宏控件
-
模式版本控制 - 类似Git的历史记录
- 分支的撤销/重做系统
- 保存/恢复快照
- 比较模式版本
-
基于浏览器的UI - 实时模式可视化
- 实时波形显示
- 通道时间轴视图
- WebSocket集成以支持多个UI
🌟 高级功能
-
实时音频分析 - AI获得音频反馈
- 频率分析以指导模式选择
- 节拍检测以同步节奏
- 幅度监测以平衡混音
-
AI模式建议 - 上下文感知推荐
- 基于机器学习的模式生成
- 风格特定建议（Techno，Ambient，Breaks）
- 自动补充模式创建
-
多用户协作 - 实时编码会话
- 多个用户控制不同的通道
- 轮流即兴模式
- 共享模式库
🎨 创意整合
-
Hydra视觉整合 - 反应式视觉效果
- 从音频模式自动生成视觉效果
- 与节拍事件同步的视觉效果
- 与音频一起实时视觉编码
-
DAW整合 - 专业工作流程
- MIDI输出到硬件合成器
- Tidal会话的音频录制
- 时间轴同步与Ableton Live/Logic
-
AI创作工具 - 高级创意
- 生成完整的曲目结构
- 风格转换
- 和声分析和建议
🤝 贡献
欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。
贡献者快速入门：
# 克隆并设置
git clone https://github.com/yourusername/tidal-mcp-server.git
cd tidal-mcp-server
npm install
# 开发模式（自动重建）
npm run dev
# 运行测试
npm test
# 为生产构建
npm run build
📚 资源
📄 许可证
MIT 许可证 - 详情见 LICENSE 文件。
🙏 致谢
- Alex McLean (yaxu) 创建了TidalCycles
- TOPLAP和算法狂欢社区 提供了实时编码文化
- Anthropic 提供了模型上下文协议和Claude
- 所有使用计算机制作奇怪音乐的人
📞 支持
- 问题：GitHub Issues
- 讨论：GitHub Discussions
- TidalCycles 社区：Discord
为实时编码社区制作的 🌀
去吧，制造一些算法噪音吧！