节奏感mcp
MCP服务器,用于“氛围编码”音乐,采用LilyPond第一工作流和弹性回退。
> 完整文档(单本手册): 文档/手册.md --运行/部署、愿景、架构、测试、类型、理论、UI历史、提示映射、云代理工作流。 指标: docs/README.md.
Rhythm Vibe Studio——后端+前端命令
| 目标 | 跑什么 |
|---|---|
生产方式(一台服务器) --FastAPI服务 /api/* 以及已建成的SPA |
uv sync --extra dev --extra scrape 然后 uv run python -m rhythm_vibe_mcp.web.build 然后 uv run rhythm-vibe-mcp-webui --host 127.0.0.1 --port 7860 ->打开 http://127.0.0.1:7860 |
| 开发(热重载) -维生素+单独的API | 航站楼A:
uv run rhythm-vibe-mcp-webui --host 127.0.0.1 --port 7860 — B航站楼:
cd frontend && pnpm install && pnpm dev (或 cd frontend && npm install && npm run dev)->用户界面位于 http://127.0.0.1:5173 (代理 /api 到端口 7860) |
可选:在另一个API点Vite frontend/.env.development.local -> VITE_STUDIO_API_ORIGIN=http://host:port.
远程静态用户界面 (GitHub页面等):设置 VITE_STUDIO_API_ORIGIN 在构建时将您的公共FastAPI源。 Cloudflare工作人员: 建造 frontend/dist,部署 cloudflare/ 与牧马人(STUDIO_API_ORIGIN 秘密)。细节: docs/HANDBOOK.md第1部分.
文档
| 文档 | 描述 |
|---|---|
| 文档/手册.md | 主要参考 --如何运行一切(MCP、Studio、Vite、测试、托管)、愿景、架构、web UI研究、实现图、测试、类型、理论、云代理 |
| docs/README.md | 手册中的简短TOC+链接 |
存根文件(docs/VISION_AND_SPECIFICATION.md, ARCHITECTURE.md,…) |
重定向到手册部分(旧链接仍然有效) |
此服务器现在支持什么
- 从网络获取现有音乐资源(
fetch_music_from_web). - 在常见音乐格式之间转换(
convert_music)尽最大努力路由: - 符号:
lilypond,musicxml,midi,abc,pdf - 音频容器:
wav,mp3,m4a - 退路:
json_fallback - 音频/文件到工作表的工作流程(
audio_or_file_to_sheet)使用转录/转化链。 - 用半音转换歌曲(
transpose_song). - Musescore API代理(
musescore_api)与: - 尽可能在不登录的情况下使用公共端点
- 通过env登录令牌(
MUSESCORE_API_TOKEN)或会话工具(set_musescore_auth_token) - 当严格的LilyPond或转换器步骤失败时,具有强大的回退行为。
基于文本的典型社交速记
对于“Reddit/电话速记”,此服务器处理 ABC记数法 作为主要的通用文本格式,
随着 ChordPro 作为次要线索表的简写。
工具:
normalize_reddit_music_text:将非正式文本规范化为一个健壮的基于事件的回退模型。
为什么选择这个:
- ABC结构紧凑,在评论/聊天中易于人类打字。
- ABC具有广泛的工具支持,并很好地映射到正式的符号管道。
- ChordPro广泛用于快速和弦+歌词交流。
错误处理模型
当严格转换失败时(例如LilyPond编译错误),服务器返回:
ok=false加诊断messagefallback对象(RobustMusicFallback)包含:- 模糊但可操作的事件数据
- 速记文本快照
- 警告继续下游任务
即使一个符号步骤失败,这也会使多步骤代理任务保持移动。
测试
单元测试遵循MCP服务器的最佳实践:进程内,默认情况下没有子进程或网络,对外部二进制文件(lilybond、ffmpeg)和HTTP进行模拟。运行:```bash
uv sync --extra dev
uv run pytest tests -v
uv run pytest tests --cov=src/rhythm_vibe_mcp --cov-report=term-missing
- **conftest.py**:用于临时工作目录、示例LilyPond/ABC/CordPro/MIDI/MusicXML文件和环境隔离的夹具。
- **test_models.py**, **test_utils.py**, **test_fallbacks.py**:模型、格式检测和回退逻辑的纯单元测试。
- **test_converters.py**:使用参数化路线和模拟二进制文件进行转换和路线规划。
- **test_musescore.py**, **test_web_fetch.py**:API和带有模拟httpx的下载逻辑。
- **test_server_tools.py**:通过直接调用工具函数进行工具契约测试(JSON输出、错误处理)。
- **test_mcp_integration.py**:MCP协议层(list_tools、call_tool)正在处理中。
使用 `-m "not integration"` 跳过任何标记为集成的测试(如果稍后添加)。
要验证所有工具是否返回符合规范的JSON,请运行完整套件;固定装置 `tests/fixtures/` (例如。 `sample.abc`, `minimal.mid`)用于基于文件的工具。
## 快速入门
**紫外线(推荐):**
从项目目录运行,以便安装的包使用源代码(`src/`).跑 `uv sync` 获取最新代码。```bash
cd C:\GitHub\rhythm-vibe-mcp
uv sync
uv run rhythm-vibe-mcp
# or: uvx --from . mcp-rhythm-vibe
需要时明确选择传输:```bash
uv run rhythm-vibe-mcp --transport stdio
uv run rhythm-vibe-mcp --transport streamable-http --host 127.0.0.1 --port 8000
uv run rhythm-vibe-mcp --transport sse --host 127.0.0.1 --port 8000
支持的传输: `stdio`, `streamable-http`, `sse` (`http` 被接受为的别名 `streamable-http`).
可选附加功能(音频/转录、抓取):```bash
uv sync --extra audio --extra scrape
audio 通过Spotify Basic Pitch为音频->MIDI步骤启用ML转录。
如果没有安装额外的(或运行时失败),项目将尽最大努力
ffmpeg+自相关回退,因此音频工作流仍在运行。
节奏氛围工作室 (FastAPI+React):请参阅 Rhythm Vibe Studio——后端+前端命令 此文件顶部的部分提供了确切的矩阵(单服务器vs Vite-dev)。最小API-only启动:```bash
uv sync
uv run rhythm-vibe-mcp-webui --host 127.0.0.1 --port 7860
生产捆绑包路径:来自FastAPI的API路由和下的静态资产 `src/rhythm_vibe_mcp/web/static/` 之后:```bash
uv run python -m rhythm_vibe_mcp.web.build
如果您仍然需要旧版Gradio UI模块,请安装可选的额外模块:```bash
uv sync --extra legacy_ui
工作室截图:
- `docs/screenshots/rhythm-vibe-studio-overview.png`
刷新顶部拥抱脸音乐空间 `vendor/huggingface_spaces` 并重新生成报告:```bash
uv run rhythm-vibe-refresh-spaces --query music --top-n 5 --limit 100
可选清理过时的克隆空间文件夹:```bash
uv run rhythm-vibe-refresh-spaces --query music --top-n 5 --prune
**使用pip:**```bash
python -m venv .venv
. .venv/Scripts/Activate.ps1
pip install -e .
pip install -e ".[audio,scrape]" # optional
rhythm-vibe-mcp
要在pip管理的环境中启动web UI,请执行以下操作:```bash
pip install -e .
rhythm-vibe-mcp-webui
## 外部二进制文件/工具(推荐)
- `lilypond` 用于LilyPond->PDF/MIDI渲染
- `ffmpeg` 用于音频容器转换
- `MuseScore` CLI(高级雕刻/出口的未来路线扩展)
如果没有这些工具,服务器仍然会返回结构化的回退输出。
## 使用uvx运行(无PyPI发布)
该包不在PyPI上。从运行工具 **本地项目路径** 因此,uv从以下目录安装:```bash
# From the project directory (recommended)
cd C:\GitHub\rhythm-vibe-mcp
uvx --from . mcp-rhythm-vibe
或者从任何使用绝对路径的地方:```bash
uvx --from "C:/GitHub/rhythm-vibe-mcp" mcp-rhythm-vibe
做 **不** 使用 `uvx mcp-rhythm-vibe` 单独使用——在PyPI上查找包,将失败。
## 光标MCP配置(示例)
使用带有本地路径的uvx(推荐):```json
{
"mcpServers": {
"rhythm-vibe-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["--from", ".", "mcp-rhythm-vibe"],
"env": { "RHYTHM_VIBE_MCP_DIR": "C:/GitHub/rhythm-vibe-mcp" },
"cwd": "C:/GitHub/rhythm-vibe-mcp"
}
}
}
替代方案(来自venv的Python):```json
{
"mcpServers": {
"rhythm-vibe-mcp": {
"command": "python",
"args": ["-m", "rhythm_vibe_mcp.server"],
"cwd": "c:/GitHub/rhythm-vibe-mcp"
}
}
}
## CLI(直接工具命令)
`rhythm-vibe-mcp-cli` / `rhythmvibe-cli` 为每个MCP工具公开一个子命令(由工具模式生成)。```bash
uvx --from . --with-editable . rhythmvibe-cli --help
uvx --from . --with-editable . rhythmvibe-cli healthcheck
uvx --from . --with-editable . rhythmvibe-cli analyze-audio-performance --input-ref "cello_samples/New Recording 31_formats/New Recording 31.opus"
uvx --from . --with-editable . rhythmvibe-cli batch-convert-audio --input-ref "cello_samples"
uvx --from . --with-editable . rhythmvibe-cli audio-or-file-to-sheet --input-ref "cello_samples/New Recording 31.m4a" --prefer-output lilypond
用于ML转录 basic_pitch,安装 audio 额外:bash
uvx --python 3.11 --from ".[audio]" --with-editable . --with "setuptools<81" rhythmvibe-cli audio-or-file-to-sheet --input-ref "cello_samples/New Recording 31.m4a" --prefer-output lilypond
当前刀具表面
healthcheck()--workdir、artifacts_dir、MuseScore env+会话令牌标志、二进制可用性(lilybond、ffmpeg)和支持的格式列表fetch_music_from_web(url)plan_music_conversion(input_format, output_format)convert_music(input_ref, output_format)audio_or_file_to_sheet(input_ref, prefer_output="pdf")transpose_song(input_ref, semitones, output_format="musicxml")normalize_reddit_music_text(text, title="reddit_vibe_idea")convert_text_notation_to_lily_or_fallback(text, target_format="lilypond", title="text_notation_piece")compose_story_lily(prompt, title="Theme", tempo_bpm=56, instrument="Solo", clef=null, midi_instrument=null, output_format="lilypond")batch_convert_audio(input_ref)analyze_audio_performance(input_ref)set_musescore_auth_token(token)musescore_api(endpoint, method="GET", payload_json="{}", base_url="")
关于“任何/所有转换组合”的注释
该架构旨在支持全矩阵转换,但有些路由依赖于外部引擎。
当直接路由尚不存在时,服务器会发出回退输出和诊断,而不是硬故障。
计划扩建区域:
- 具有多步中间格式的路线规划器
- 更丰富的音频评分转录和量化选择
- 更深入的MuseScore集成路线(CLI+公共API+可选的身份验证流)