Muse Dash Mod MCP

一个面向 Muse Dash 模组开发的本地 MCP（Model Context Protocol）服务器，使用 Python + FastMCP 编写，任何支持本地 stdio MCP 传输的客户端都可以连接。

功能

• 项目脚手架：封装固定版本 MuseDash.Mod.Template 1.0.4，创建 C# / .NET 6 Muse Dash 模组项目
• 开发知识库：提供 MelonLoader、Harmony、IL2CPP、MuseDashMirror、模板参数和构建部署文档
• 构建与部署：编译模组、诊断本机环境；明确调用 deploy_mod 才会复制 DLL 到游戏 Mods
• 社区参考：只读检索 MDMods 仓库和源码文件

环境要求

• Windows
• Python 3.10+
• .NET SDK 8（模板生成的项目目标为 net6.0）
• Muse Dash + MelonLoader 0.6.1
• MD_DIRECTORY 环境变量指向游戏目录，例如：

$env:MD_DIRECTORY = 'G:\Steam\steamapps\common\Muse Dash'

服务器也会尝试探测常见 Steam 安装路径，并支持 MUSE_DASH_PATH 作为备用变量。

安装

cd C:\path\to\musedash-mod-mcp
.venv\Scripts\python.exe -m pip install -e .

如果还没有虚拟环境：

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .

可选：设置 GITHUB_TOKEN（或 GH_TOKEN）以提高 GitHub API 限额。

通用 MCP 启动方式

服务器使用标准本地 stdio transport。直接运行：

$env:PYTHONPATH = 'C:\path\to\musedash-mod-mcp\src'
C:\path\to\musedash-mod-mcp\.venv\Scripts\python.exe -m musedash_mod_mcp.server

客户端配置通常包含以下字段：

• command：Python 可执行文件的绝对路径
• args：["-m", "musedash_mod_mcp.server"]
• cwd：项目根目录
• env.PYTHONPATH：项目的 src 目录

不同客户端的配置文件和 JSON 外壳名称不同，请以对应客户端的 MCP 设置页面/文档为准。下面是常见客户端采用的配置对象示例：

{
  "musedash-mod": {
    "command": "C:\\path\\to\\musedash-mod-mcp\\.venv\\Scripts\\python.exe",
    "args": ["-m", "musedash_mod_mcp.server"],
    "cwd": "C:\\path\\to\\musedash-mod-mcp",
    "env": {
      "PYTHONPATH": "C:\\path\\to\\musedash-mod-mcp\\src"
    }
  }
}

工具

工具	作用
create_mod_project	创建模组项目并填充作者/版本元数据
build_mod	隔离构建并返回 DLL、错误和日志；不会写入真实 Mods
deploy_mod	构建后显式、原子地复制主 DLL 到真实 Mods 目录
launch_game	启动 MuseDash.exe（仅在用户明确要求时调用）
get_environment_info	检查游戏、MelonLoader、dotnet、模板和已安装 DLL
list_modding_docs	列出内置文档主题
get_modding_doc	读取一个主题
search_mdmods_repos	搜索 MDMods 仓库
get_mdmods_repo_file	读取 MDMods 仓库中的文本文件

此外还提供 knowledge://musedash/{topic} resources 和 new_mod_workflow prompt。

本地测试

$env:PYTHONPATH = "$PWD\src"
.venv\Scripts\python.exe tests\smoke_test.py

端到端测试建议使用临时输出目录。模板默认的空 Patches/Patch.cs 是示例占位符，若要直接编译空项目，请设置 patching=false，或先填写真实的 Harmony 目标类型和方法。

安全边界

• search_mdmods_repos 和 get_mdmods_repo_file 只读访问 GitHub。
• build_mod 使用外部临时目录作为模板复制目标，并清除 MD_DIRECTORY；它不是任意 MSBuild 项目的安全沙箱，仍应只构建可信项目。
• deploy_mod 会覆盖 Mods 中同名 DLL，使用前应确认目标路径。
• launch_game 会启动外部游戏进程，应在用户明确要求后调用。