Rhythm Vibe MCP

节奏感mcp

MCP服务器，用于“氛围编码”音乐，采用LilyPond第一工作流和弹性回退。

完整文档（单本手册）： 文档/手册.md --运行/部署、愿景、架构、测试、类型、理论、UI历史、提示映射、云代理工作流。 指标： docs/README.md.

Rhythm Vibe Studio——后端+前端命令

可选：在另一个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部分.

文档

此服务器现在支持什么

• 从网络获取现有音乐资源(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 加诊断 message
• fallback 对象(RobustMusicFallback)包含：

- 模糊但可操作的事件数据 - 速记文本快照 - 警告继续下游任务

即使一个符号步骤失败，这也会使多步骤代理任务保持移动。

测试

单元测试遵循MCP服务器的最佳实践：进程内，默认情况下没有子进程或网络，对外部二进制文件（lilybond、ffmpeg）和HTTP进行模拟。运行：

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 获取最新代码。

cd C:\GitHub\rhythm-vibe-mcp
uv sync
uv run rhythm-vibe-mcp
# or: uvx --from . mcp-rhythm-vibe

需要时明确选择传输：

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).

可选附加功能（音频/转录、抓取）：

uv sync --extra audio --extra scrape

audio 通过Spotify Basic Pitch为音频->MIDI步骤启用ML转录。 如果没有安装额外的（或运行时失败），项目将尽最大努力 ffmpeg+自相关回退，因此音频工作流仍在运行。

节奏氛围工作室 （FastAPI+React）：请参阅 Rhythm Vibe Studio——后端+前端命令 此文件顶部的部分提供了确切的矩阵（单服务器vs Vite-dev）。最小API-only启动：

uv sync
uv run rhythm-vibe-mcp-webui --host 127.0.0.1 --port 7860

生产捆绑包路径：来自FastAPI的API路由和下的静态资产 src/rhythm_vibe_mcp/web/static/ 之后：

uv run python -m rhythm_vibe_mcp.web.build

如果您仍然需要旧版Gradio UI模块，请安装可选的额外模块：

uv sync --extra legacy_ui

工作室截图：

• docs/screenshots/rhythm-vibe-studio-overview.png

刷新顶部拥抱脸音乐空间 vendor/huggingface_spaces 并重新生成报告：

uv run rhythm-vibe-refresh-spaces --query music --top-n 5 --limit 100

可选清理过时的克隆空间文件夹：

uv run rhythm-vibe-refresh-spaces --query music --top-n 5 --prune

使用pip：

python -m venv .venv
. .venv/Scripts/Activate.ps1
pip install -e .
pip install -e ".[audio,scrape]"   # optional
rhythm-vibe-mcp

要在pip管理的环境中启动web UI，请执行以下操作：

pip install -e .
rhythm-vibe-mcp-webui

外部二进制文件/工具（推荐）

• lilypond 用于LilyPond->PDF/MIDI渲染
• ffmpeg 用于音频容器转换
• MuseScore CLI（高级雕刻/出口的未来路线扩展）

如果没有这些工具，服务器仍然会返回结构化的回退输出。

使用uvx运行（无PyPI发布）

该包不在PyPI上。从运行工具 本地项目路径 因此，uv从以下目录安装：

# From the project directory (recommended)
cd C:\GitHub\rhythm-vibe-mcp
uvx --from . mcp-rhythm-vibe

或者从任何使用绝对路径的地方：

uvx --from "C:/GitHub/rhythm-vibe-mcp" mcp-rhythm-vibe

做 不 使用 uvx mcp-rhythm-vibe 单独使用——在PyPI上查找包，将失败。

光标MCP配置（示例）

使用带有本地路径的uvx（推荐）：

{
  "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）：

{
  "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工具公开一个子命令（由工具模式生成）。

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 额外：

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+可选的身份验证流）