使用说明

Strudel MCP-Strudel的模型上下文协议集成

该项目提供了一个MCP（模型上下文协议）服务器，使LLM能够与果馅饼 -Tidal Cycles模式语言的JavaScript端口，用于实时编码音乐。

概述

Strudel MCP允许大型语言模型（LLM）：

通过自然语言命令执行Strudel模式
检索当前模式状态
通过Context7集成获取Strudel文档
访问浏览器开发工具进行调试

建筑

┌─────────────┐    MCP     ┌──────────────┐    WebSocket    ┌─────────────┐
│   LLM       │ ◄──────► │ strudel-mcp  │ ◄─────────────► │  Strudel    │
│  (Qwen/     │  Protocol │   Server     │   Communication│  REPL/      │
│  etc.)      │           │ (Node.js ✨) │                │  Frontend   │
└─────────────┘           └──────────────┘                └─────────────┘

服务器选项

Node.js服务器

cd server-node
npm install
npm run dev

组件

strudel-mcp（Node.js）：带WebSocket通信的MCP服务器
WebSocket服务器：处理MCP和Strudel之间的双向通信
前端：具有同步功能的基于Web的Strudel界面
上下文7集成Strudel文档的外部文档服务

原始Strudel项目

该项目基于最初的Strudel项目并受到其启发：

原始存储库: https://github.com/tidalcycles/strudel
主要来源: https://codeberg.org/uzu/strudel （科德伯格镜）
官方网站: https://strudel.cc
文档: https://strudel.cc/docs

备注:

这 source_of_strudel/ 目录克隆自 https://codeberg.org/uzu/strudel 2025年10月12日，供发展参考。
这两个目录都是本地开发参考不包含在此GitHub存储库中。

许可证

该项目遵循AGPL-3.0许可证，与最初的Strudel项目一致。看许可证文件以获取详细信息。

特性

MCP工具

execute_strudel_code -执行Strudel模式
get_current_pattern -获取当前活动模式
get_strudel_knowledge -内置Strudel文档和知识库

同步功能

广播频道API：跨选项卡模式同步
实时更新：跨多个选项卡/窗口的即时模式更改
错误处理：强大的错误恢复和回退机制

快速开始

先决条件

丁腈橡胶（>=1.0） -推荐运行时间
支持WebSocket和Web Audio API的现代浏览器

备注：此项目针对Bun进行了优化。虽然它适用于Node.js，但我们强烈建议使用Bun以获得更好的性能和开发人员体验。

安装

克隆仓库:

git clone https://github.com/utenadev/strudel-mcp.git
cd strudel-mcp

安装服务器依赖项:
```
cd server-node
bun install
cd ..
```
安装前端依赖项:
```
cd frontend
bun install
cd ..
```

启动服务器:

# Terminal 1: Start MCP + WebSocket server
cd server-node
bun run dev

# Terminal 2: Start frontend
cd frontend
bun run dev

运行测试:
```
cd frontend
bun run test  # 23 tests
```

使用LLM

Qwen3编码器+Qwen代码（需要MCP配置）

创建 .qwen/settings.json 在项目根目录中：

生产（内置版本）:

{
  "mcpServers": {
    "strudel-mcp": {
      "command": "node",
      "args": ["server-node/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

开发（npm-dev）:

{
  "mcpServers": {
    "strudel-mcp": {
      "command": "npm", 
      "args": ["run", "dev"],
      "cwd": "server-node",
      "env": {
        "NODE_ENV": "development",
        "DEBUG": "true"
      }
    }
  }
}

此存储库中提供的预构建设置：

.qwen/settings.json -生产就绪
.qwen/settings.dev.json -开发模式

先生产： cd server-node && npm run build

Gemini CLI（需要MCP配置）

配置 ~/.gemini/settings.json:

{
  "selectedAuthType": "gemini-api-key",
  "theme": "Dracula",
  "mcpServers": {
    "strudel-mcp": {
      "command": "node",
      "args": ["/path/to/strudel-mcp/server-node/dist/index.js"],
      "cwd": "/path/to/strudel-mcp/server-node"
    }
  }
}

先构建： cd server-node && npm run build

证实 /mcp Gemini CLI中的命令

克劳德桌面（需要MCP配置）

配置Claude桌面设置：

打开克劳德桌面→ 设置→ 开发者→ 编辑配置
添加到 mcpServers:

{
  "mcpServers": {
    "strudel-mcp": {
      "command": "node",
      "args": ["/path/to/strudel-mcp/server-node/dist/index.js"],
      "cwd": "/path/to/strudel-mcp/server-node"
    }
  }
}

重新启动克劳德桌面
验证新聊天中是否有可用的工具

GitHub副本（需要MCP配置）

在GitHub Copilot的VS代码（v1.99+）中：

打开设置→ 扩展→ GitHub Copilot
启用“副驾驶中的MCP服务器”策略
使用GitHub MCP注册表或手动配置

{
  "mcpServers": {
    "strudel-mcp": {
      "command": "node",
      "args": ["/path/to/strudel-mcp/server-node/dist/index.js"],
      "cwd": "/path/to/strudel-mcp/server-node"
    }
  }
}

备注：替换 /path/to/strudel-mcp 使用您的实际存储库路径

发展

项目结构

strudel-mcp/
├── server-node/               # Node.js MCP server
│   ├── src/
│   │   ├── index.ts          # Main server entry
│   │   ├── mcp/              # MCP protocol handlers
│   │   ├── websocket/        # WebSocket manager
│   │   └── utils/            # Utilities (logger, config)
│   ├── test/                 # Server tests
│   ├── package.json          # Dependencies
│   └── tsconfig.json         # TypeScript config
├── frontend/                  # React-based Strudel interface
│   ├── src/
│   │   ├── App.tsx           # Main application component
│   │   ├── hooks/            # React hooks (useStrudel, useWebSocket)
│   │   ├── presets/          # Genre-based pattern presets
│   │   ├── types/            # TypeScript type declarations
│   │   └── test/             # Frontend tests
│   ├── package.json          # Dependencies
│   └── vitest.config.ts      # Test configuration
├── docs/                      # Documentation
├── source_of_strudel/         # Strudel source reference (git submodule)
└── images/                    # Screenshots and assets

关键技术

运行时：Bun（推荐）
后端：TypeScript+Express+@modelcontextprotocol/sdk
前端：React+TypeScript+Vite
音频：Strudel包（@Strudel/core、@Strudel/webaudio、@Strudel/转译器）
沟通：WebSocket协议
测试：Vitest+React测试库

贡献

复刻仓库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

开发指南

遵循现有的代码风格和约定
添加适当的错误处理
更新新功能的文档
测试跨浏览器兼容性

路线图

[]增强了跨多个选项卡的模式同步
[]改进了错误处理和恢复
[]用于高级模式操作的其他LLM工具
[]性能优化
[]移动浏览器支持
[]扩展插件系统

api参考

WebSocket端点

ws://localhost:8081/ws?type=mcp -MCP客户端连接
ws://localhost:8081/ws?type=strudel -Strudel前端连接

MCP工具参考

execute_strudel_code

执行Strudel模式代码

{
  "name": "execute_strudel_code",
  "arguments": {
    "code": "s('bd hh sd oh').fast(2)"
  }
}

get_current模式

获取当前正在执行的模式

{
  "name": "get_current_pattern",
  "arguments": {}
}

get_trudel_知识

内置Strudel文档

{
  "name": "get_strudel_knowledge",
  "arguments": {
    "topic": "basics",
    "query": "drum patterns"
  }
}

可用主题: basics, patterns, effects, troubleshooting

故障排除

常见问题

WebSocket连接失败
- 确保端口8081可用
- 检查防火墙设置
- 验证服务器和前端是否正在运行
音频未播放
- 检查浏览器音频权限
- 确保用户交互启动的音频上下文
- 验证Web Audio API支持
MCP连接问题
- 验证MCP服务器是否正在运行
- 检查LLM客户端配置
- 确保stdio通信正常工作

日志记录

服务器日志：控制台输出
前端日志：浏览器开发人员控制台
WebSocket日志：具有详细模式的服务器控制台

致谢

Strudel原始团队：创造一个令人惊叹的实时编码环境
潮汐循环社区：模式语言灵感
MCP贡献者：适用于模型上下文协议标准

许可证

此项目根据AGPL-3.0许可证获得许可-请参阅许可证详细信息，与原始Strudel项目一致。