MCP 播放控制
让支持 MCP 的 AI 客户端读取播放状态并控制 Scopify 桌面端的播放。
Scopify 桌面端内置一个只监听本机的 MCP（Model Context Protocol）服务。支持 MCP 的客户端连接后，可以查询当前播放状态，并在你授权的范围内控制播放、切歌、跳转和调节音量。
仅桌面端提供
MCP 服务由 Electron 主进程运行，Web 版没有这项能力。服务默认关闭，需要在设置中手动启用。
快速开始
- 打开 设置 → 桌面端，找到「本地 MCP」区域，启用「启用本地 MCP」。
- 在「客户端凭据」中查看并复制客户端配置。
- 把配置粘贴到你的 MCP 客户端。客户端需要支持 Streamable HTTP 传输。
- 回到设置页点击「测试 MCP 连接」，确认服务可用。
复制出来的配置使用标准的 mcpServers 结构，连接地址为本机回环地址，并携带 Bearer 令牌：
{
"mcpServers": {
"scopify": {
"type": "http",
"url": "http://127.0.0.1:31927/mcp",
"headers": { "Authorization": "Bearer <your-token>" }
}
}
}端口默认是 31927，可以在设置中修改。令牌请以设置页生成的配置为准，不要自己编造或提交到仓库。
设置项
| 设置 | 说明 |
|---|---|
| 启用本地 MCP | 总开关，默认关闭。关闭后服务立即停止。 |
| 监听端口 | 默认 31927。端口被占用时服务不会启动，也不会影响播放器本身。 |
| 受控能力 | 逐项勾选客户端可以执行的操作，见下文。 |
| 测试 MCP 连接 | 发送真实的 initialize 与 tools/list 请求，确认服务可用。 |
| 重启服务 | 使用已保存的配置重新启动本地服务。 |
| 客户端凭据 | 查看并复制客户端配置，或重新生成令牌；重新生成后旧令牌立即失效。 |
可用工具
当前暴露的是刻意收窄的一组播放工具：
| 工具 | 类型 | 说明 |
|---|---|---|
get_playback_status | 只读 | 当前播放状态、进度、时长和音量，时间单位为毫秒。 |
get_now_playing | 只读 | 当前歌曲的简要信息。不包含歌词、音源地址或凭据。 |
play | 控制 | 继续播放。 |
pause | 控制 | 暂停播放。 |
toggle_playback | 控制 | 切换播放与暂停。 |
next_track | 控制 | 播放下一首。 |
previous_track | 控制 | 播放上一首。 |
seek | 控制 | 跳转到指定位置，参数 positionMs 为毫秒。 |
set_volume | 控制 | 设置音量，参数 volume 范围 0–100。 |
权限模型
主进程会对每一次工具调用检查权限，工具说明只是给 AI 客户端看的提示，并不起限制作用。权限共 9 项：
| 分组 | 能力 |
|---|---|
| 读取 | playback.read.status、playback.read.track |
| 控制 | playback.control.play、.pause、.toggle、.next、.previous、.seek、.volume |
默认只授予 playback.read（读取）。要让客户端控制播放，需要在「受控能力」中显式勾选对应项。旧版本配置里的粗粒度 playback.read 与 playback.control 仍然有效，并会覆盖对应分组下的全部细项。
安全边界
- 仅本机访问：服务只监听
127.0.0.1，局域网和外网无法连接。 - 令牌认证：每个请求必须携带
Authorization: Bearer <token>，缺失或错误返回401。 - 来源检查：Host 只接受
localhost与127.0.0.1，以防 DNS 重绑定；带有非本机 Origin 的浏览器请求会被拒绝（403）。普通 MCP 客户端不发送 Origin，不受影响。 - 凭据安全存储：令牌由 Electron 主进程通过系统加密服务（
safeStorage）加密保存，不会写入配置文件，也不会出现在界面状态里；系统加密服务不可用时不会创建持久令牌。 - 会话上限：同时最多 8 个会话，空闲 30 分钟后自动回收。
- 调用审计：每次工具调用都会记录工具名、结果和耗时，不记录请求内容。
- 真实回执：控制类操作会等待播放器的真实回执再返回，而不是只报告「已发送」。
常见问题
连接被拒绝或超时：确认设置中已启用、状态为监听中；端口被占用时服务不会启动，请换一个端口。
返回 401：令牌已被重新生成。请回到设置页复制最新的客户端配置。
工具返回「不可用」：播放器当前没有可控制的会话，或者对应能力没有被授权。