Strudel-MCP

# Strudel-MCP > **社区项目 — 与 Strudel 或 TidalCycles 团队无关。** > 这是一个独立的 **模型上下文协议** 服务器，适用于 Strudel。"Strudel" 指的是上游项目 <https://strudel.cc>；在命名性合理使用下以描述性使用。运行时获取的所有 Strudel 代码均由上游项目在 AGPL-3.0-or-later 下分发，不在此处重新分发。 一个模型上下文协议服务器，为 LLMs 提供对 [Strudel](https://strudel.cc) 的深入了解 — [TidalCycles](https://tidalcycles.org) 的 JavaScript 端口，用于实时编码音乐。让 Claude（或任何支持 MCP 的模型）能够编写、验证和运行可运行的 Strudel 模式，而无需记住整个 API。 MCP 是 **知识优先** 的：LLM 编写 Strudel 代码，10 个工具为其提供参考数据、创作模板、音乐理论助手、静态校验器、回放交接器，支持任意长度的模式，音频样本下载和音频分析。 --- ## 功能 - **10 个专注的工具**，涵盖文档、示例、声音、音乐理论、创作、验证、回放、持久的代码片段库、音频样本下载和音频分析 - **预编译的知识库** — 无运行时网络调用，无速率限制，无文档漂移 - **支持任意长度的模式** — 自动回落到本地 HTML 文件，使用 `@strudel/repl`（来自 unpkg 的内联 Web 组件包）当 base64 共享 URL 超过约 2000 个字符的 Markdown/浏览器上限时 - **11 种流派模板**（house、techno、hip-hop、trap、dnb、jazz、ambient、psytrance、lofi、rock、hardbass），具有专业深度的模式：侧链鸭子通过轨道路由、滤波器信封（lpenv）、摆动/人性化通过 `.late()`、变化通过 `every`/`sometimesBy`/`ply`/`degradeBy`、分层低音和流派特定的鼓模式 - **84 个文档化的函数** 和 **80 个文档化的效果** — 涵盖现代 Strudel API，包括发音/琶音、滤波器/音高信封、轨道路由、鸭子、相位器/颤音/振动、FM 合成和失真类型 - **209 个声音条目** — 71 个鼓机银行、48 个 GM 乐器、27 个污音样本类别、20 个 VCSL 乐器、16 个合成器、14 个样本库、13 个鼓声 - **34 个精选示例模式**，演示真正的 Strudel 习语：侧链泵送、语音琶音、酸滤波器信封、Amen 破碎、欧几里得多节奏、Dub 延迟、Perlin 噪声调制、分层 Reese 低音、Nightcore 带有 Supersaw + 分层低音 - **音频下载 + 分析** — `strudel_sample` 通过 `yt-dlp` 从 YouTube/SoundCloud/URL 拉取音频，在本地提供 CORS 以便 Strudel 播放；`strudel_analyze` 运行基于 librosa 的 BPM/关键/和弦提取，并渲染 3 面板频谱图 PNG - **跨度感知静态校验器**，了解字符串、注释、模板文字、转义序列、比例规格、和弦符号、欧几里得节奏和 Strudel 的微记号 - **音乐理论助手** — 24 个音阶/模式（包括弗里吉亚主导音、匈牙利小调、Hirajoshi、Insen、双谐波），和弦符号解析器带有临时记号和扩展，罗马数字进行解析器带有正确的根位置发音 - **零运行时 npm 依赖**，除了 `@modelcontextprotocol/sdk` 和 `zod` — 音频下载和分析使用可选的系统工具（`yt-dlp`，Python + librosa）通过 `spawn` 调用 - **无 Playwright，无无头浏览器，无外部服务** — `open: true` 使用平台的原生打开器（`xdg-open` / `open` / `start`） --- ## 安装 需要 **Node ≥20**。与 `bun` 或 `npm` 配合使用。 ```bash git clone https://github.com/Takyon236/Strudel-MCP.git cd Strudel-MCP bun install # 或：npm install bun run build # 或：npm run build ``` 输出到 `dist/index.js`。 ### 可选的系统依赖 10 个工具中的两个调用系统二进制文件。只有在使用这些工具时才安装它们 — 其余的 MCP 无需它们即可工作。 | 工具 | 需要 | 为什么 | |---|---|---| | `strudel_sample` | [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) | YouTube 和 SoundCloud 下载。直接 HTTPS URL 无需此工具。 | | `strudel_analyze` | Python 3 + `librosa` + `matplotlib` + `numpy` | BPM / 关键 / 和弦提取和频谱图渲染。 | 通过包管理器安装 `yt-dlp`（`pip install yt-dlp`，`brew install yt-dlp`，`apt install yt-dlp` 等）和 Python 栈： ```bash pip install librosa matplotlib numpy ``` MCP 在调用时探测这些工具，如果它们缺失，会返回明确的错误 — 启动时不会失败。 --- ## 配置 ### Claude Desktop 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）/ `%APPDATA%\Claude\claude_desktop_config.json`（Windows）/ `~/.config/Claude/claude_desktop_config.json`（Linux）： ```json { "mcpServers": { "strudel": { "command": "node", "args": ["/绝对路径/到/Strudel-MCP/dist/index.js"] } } } ``` 重启 Claude Desktop — 10 个工具出现在锤子菜单中。 ### Claude Code ```bash claude mcp add strudel node /绝对路径/到/Strudel-MCP/dist/index.js ``` 或直接编辑 `~/.claude/mcp.json`，采用与上述相同的 JSON 形状。 ### 开发（无构建步骤） ```json { "mcpServers": { "strudel": { "command": "bunx", "args": ["tsx", "/绝对路径/到/Strudel-MCP/src/index.ts"] } } } ``` --- ## 工具 | 工具 | 目的 | |---|---| | `strudel_docs` | 查询 Strudel 函数、效果、类别或概念（微记号） | | `strudel_examples` | 精选的可运行示例模式，按标签或样式搜索 | | `strudel_sounds` | 鼓声、鼓机银行、合成振荡器、样本库、GM 乐器 | | `strudel_theory` | 音阶、和弦符号和罗马数字进行，解析为 Strudel 语法 | | `strudel_compose` | 从流派模板生成可运行模式 | | `strudel_validate` | Strudel 模式的静态解析和校验 | | `strudel_run` | 将模式编码为 `strudel.cc/#` URL **或** 编写本地 HTML 嵌入文件 | | `strudel_library` | 持久的本地代码片段存储：保存 / 加载 / 列出 / 删除 | | `strudel_sample` | 从 YouTube/SoundCloud/URL 下载音频，在本地提供 CORS 以便 Strudel 播放 | | `strudel_analyze` | 从音频中提取 BPM、关键、和弦、节拍网格 + 生成频谱图 PNG | ### `strudel_run` 交接策略 `strudel_run` 根据大小选择如何将模式交给 Strudel： | 策略 | 何时 | 输出 | |---|---|---| | `url` | 代码 ≤1200 个字符（自动）或显式 | `strudel.cc/#<base64>` 共享 URL | | `embed` | 代码 >1200 个字符（自动）或显式 | `~/.strudel-mcp/exports/<name>.html` 处的 HTML 文件 | | `auto` | 默认 — 根据大小选择 | — | 1200 个字符的阈值校准，以便 URL 保持在 ~2000 个字符以下，在 base64 + URL 编码 + `https://strudel.cc/#` 前缀之后 — 经验上限，超过后 Markdown 链接渲染会损坏。 `embed` HTML 文件使用 [`@strudel/repl@1.2.7`](https://www.npmjs.com/package/@strudel/repl) 从 unpkg CDN 加载 — **内联** Web 组件（不是 `@strudel/embed`，一个围绕 `strudel.cc` 的薄 iframe 包装器，它继承了 URL 长度限制）。该包包括 CodeMirror、Strudel 转译器、WebAudio 输出和预烘焙，自动加载污音样本、音色字体和鼓机。模式代码写入 `<script type="application/strudel-pattern">` 持有者；一个小的启动程序等待 `customElements.whenDefined('strudel-editor')`，创建 `<strudel-editor>`，设置其 `code` 属性从持有者，并将其附加到 `#repl-root` 容器，调整大小以填充视口。`Ctrl+Enter` 播放，`Ctrl+.` 停止。 **无 URL 长度限制。无外部服务。** 参见 `src/lib/encode.ts::generatePlayerHtml` 以获取真实源。 ### 导出目录 嵌入式 HTML 文件位于 `~/.strudel-mcp/exports/`。覆盖为 `STRUDEL_MCP_EXPORTS=/path/to/dir`。 ### 库目录 代码片段位于 `~/.strudel-mcp/library/`。覆盖为 `STRUDEL_MCP_LIBRARY=/path/to/dir`。 --- ## 使用示例 ### 为我制作一个 House 节拍 > **您：** 给我一个 124 BPM 的 House 节拍，A 小调，带有鼓、低音和合成器主导。 Claude 调用 `strudel_compose` → 生成一个具有四分之四节奏的踢鼓（通过 `duckorbit` 侧链）、带有摆动的离拍节奏的帽子、低音带有滤波器信封 (`lpenv`)、带有 `sometimesBy` 变化的 epiano 主导和带有缓慢滤波器扫描的垫。将其通过 `strudel_validate`，为您提供一个可播放的 URL 来自 `strudel_run`。 ### `.lpf` 到底是什么？ > **您：** Strudel 中的 `.lpf` 参数范围是多少？ Claude 调用 `strudel_docs`，参数为 `{topic: "lpf"}` → 返回签名、类别、范围（20–20000，典型 200–8000）、别名 (`cutoff`、`ctf`、`lp`)、摘要和带有信号调制的示例。 ### 如何在 Strudel 中进行侧链？ > **您：** 如何让低音跟随踢鼓？ Claude 调用 `strudel_docs`，参数为 `{topic: "duckorbit"}` → 学习轨道路由和鸭子参数，然后编写一个带有 `s("bd*4").duckorbit(1)` 和 `.orbit(1)` 上的低音的模式。 ### 给我一个 F 大调的 ii-V-I 进行 > **您：** 给我一个 F 大调的 ii-V-I 进行，转换为 Strudel 代码。 Claude 调用 `strudel_theory`，参数为 `{action: "progression", progression: "ii-V-I", scale: "F3:major"}` → 返回和弦符号（Gm、C、F）、它们的根位置音符和一个可粘贴的 `note("...")` 模式。 ### 保存那个节拍 > **您：** 将其保存为 "my_house_groove"。 Claude 调用 `strudel_library`，参数为 `{action: "save", name: "my_house_groove", code: "..."}` → 写入 `~/.strudel-mcp/library/my_house_groove.json`。 --- ## 开发 ```bash bun install # 依赖 bun run dev # 在 tsx 下运行 MCP 进行本地开发 bun run build # 编译到 dist/ bun run typecheck # 严格的 TypeScript，要求 0 个错误 bun test # 完整的测试套件 ``` ### 项目结构 ``` src/ index.ts # McpServer + 工具注册 tools/ # 每个工具一个文件（10 个文件：docs、examples、sounds、theory、compose、validate、run、library、sample、analyze） knowledge/ # 预编译的参考数据 functions.ts # FunctionDoc[] （84 个条目） effects.ts # EffectDoc[] （80 个条目） sounds.ts # 鼓声 / 银行 / 合成器 / GM / VCSL / 污音 / 样本库（209 个条目） scales.ts # 音阶定义 + parseRoot + notesInScale（24 个音阶） minispec.ts # 微记号规则 + 概述（18 条规则） examples.ts # 精选的可运行模式示例（34 个条目） lib/ encode.ts # code2hash / hash2code / generatePlayerHtml（自包含的 HTML via @strudel/repl） validate.ts # 跨度感知静态校验器 theory.ts # 和弦解析器 + 罗马数字解析器 library.ts # 代码片段持久性 + 导出 HTML sampleServer.ts # 本地 HTTP 服务器，带有 CORS、yt-dlp 集成、/play REPL 端点 analyzer.ts # 启动 scripts/analyze.py（librosa）进行 BPM/关键/和弦分析 scripts/ analyze.py # 基于 librosa 的音频分析（BPM、关键、和弦、频谱图） tests/ # bun test 套件 ``` 有关完整的设计文档，包括工具逐一的原理、校验器内部实现和约定，请参见 [CLAUDE.md](./CLAUDE.md)。 --- ## 贡献 欢迎提出问题和 PR。请参见 [CONTRIBUTING.md](./CONTRIBUTING.md)，了解工作流程、代码样式以及如何扩展工具表面或知识库。完整的设计文档包含工具逐一的原理，在 [CLAUDE.md](./CLAUDE.md) 中。 --- ## 致谢 - [Strudel](https://strudel.cc) 由 [Felix Roos](https://github.com/felixroos) 和 Strudel 贡献者 — 此 MCP 驱动的实时编码语言 - [TidalCycles](https://tidalcycles.org) 由 Alex McLean — Strudel 移植的模式语言 - [Model Context Protocol](https://modelcontextprotocol.io) 由 Anthropic — 此服务器所讲的协议 ## 许可证 GNU Affero General Public License v3.0 或更高版本（AGPL-3.0-or-later）— 参见 [LICENSE](./LICENSE)。 strudel-mcp 建立在并生成交接到 [Strudel](https://github.com/tidalcycles/strudel)，它本身根据 AGPL-3.0-or-later 许可。 该项目继承该许可以尊重上游条款。参见 [NOTICE](./NOTICE) 以获取致谢。