# 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](https://github.com/MDMods) 仓库和源码文件

## 环境要求

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

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

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

## 安装

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

如果还没有虚拟环境：

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

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

## 通用 MCP 启动方式

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

```powershell
$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 设置页面/文档为准。下面是常见客户端采用的配置对象示例：

```json
{
  "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。

## 本地测试

```powershell
$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` 会启动外部游戏进程，应在用户明确要求后调用。