ym-mcp-wangyi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# ym-mcp-wangyi
+
+网易云音乐 MCP。读取本机已登录的官方客户端 Cookie（MMKV / CEF），搜索歌曲，并用 `orpheus://` 协议让客户端播放 / 切歌。
+
+需要 **Node.js 22+**（CEF Cookie 回退使用内置 `node:sqlite`）。不依赖 OpenCLI。
+
+官方桌面端在 **macOS** 和 **Windows**。播放走系统协议打开器，不绑定某个进程名。
+
+## 终端测试（CLI）
+
+```bash
+pnpm install
+pnpm build
+
+# 1) 先开启桌面端控制通道（会重启网易云；只需做一次，直到你手动关掉客户端）
+node dist/index.js launch
+
+# 2) 再测播放
+node dist/index.js status
+node dist/index.js search 许巍 --limit 5
+node dist/index.js play 蓝莲花
+node dist/index.js queue
+node dist/index.js next
+node dist/index.js prev
+```
+
+`status` 里看 `cdp_ok: true` 后，play/next/prev 才会真正驱动桌面端。  
+仅 `orpheus://` 不够：桌面端要用 base64 命令，可靠切歌还需 CDP（`--remote-debugging-port`）。
+
+无参数时进入 MCP stdio 模式（给 Cursor 用）。
+
+## Cursor
+
+```json
+{
+  "mcpServers": {
+    "ym-mcp-wangyi": {
+      "command": "npx",
+      "args": ["-y", "ym-mcp-wangyi"]
+    }
+  }
+}
+```
+
+本地开发可写成：
+
+```json
+{
+  "mcpServers": {
+    "ym-mcp-wangyi": {
+      "command": "node",
+      "args": ["/绝对路径/ym-wangyi-music/dist/index.js"]
+    }
+  }
+}
+```
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `wangyi_status` | 安装 / 运行 / 登录 / CDP / 队列 |
+| `wangyi_launch` | 以 CDP 端口启动/重启客户端 |
+| `wangyi_search` | 搜索 |
+| `wangyi_play` | 播放（id 或关键词） |
+| `wangyi_queue` | 客户端队列 |
+| `wangyi_next` / `wangyi_prev` | 队列切歌 |
+
+播放优先走 CDP（`playing/play` / `jump2Track`）；不可用时回退桌面 `orpheus://` base64 命令（macOS `open -a NeteaseMusic` / Windows `cmd start`）。
+
+## 平台说明
+
+- **macOS**：优先读 `~/Library/Containers/com.netease.163music/Data/Documents/storage/mmkv.default`（也兼容 Application Support 路径）。
+- **Windows**：扫描 `%APPDATA%` / `%LOCALAPPDATA%` 下 `NetEase` / `CloudMusic` 等目录的 `mmkv.default`；若只有 CEF Cookie 密文，会用 `Local State` + DPAPI 解密。
+- 播放控制依赖本地 CDP（默认 `127.0.0.1:9223`）。请先 `launch`；`status.cdp_ok` 为 true 后再 play/next/prev。
+- 队列优先读 CDP 实时状态；否则回退客户端 `playingList` 缓存 + 本地 last-play。
+
+先安装并登录一次官方桌面端，再 `launch` → `play`。

package/dist/index.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { asToolError, ToolError } from "./lib/errors.js";
+import { getStatus } from "./lib/status.js";
+import { searchTracks } from "./lib/api.js";
+import { playTrackById } from "./lib/play.js";
+import { readPlayerQueue, skipPlayerQueue } from "./lib/queue.js";
+import { launchWithCdp } from "./lib/cdp.js";
+const TOOLS = [
+    {
+        name: "wangyi_status",
+        description: "检查网易云音乐是否安装、是否在运行、是否已登录、CDP 控制通道与队列是否可用（macOS / Windows）",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "wangyi_launch",
+        description: "以本地 CDP 调试端口重启/启动网易云桌面端；play/next/prev 真正控播放前需要先做一次",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "wangyi_search",
+        description: "用网易云音乐搜索歌曲，返回 id/title/artist/album",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "搜索词" },
+                limit: { type: "number", description: "最多返回条数，默认 10" },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "wangyi_play",
+        description: "在官方客户端播放：纯数字当 song id，否则搜索后播第 N 首（优先 CDP，回退 orpheus://）",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "song id 或搜索词" },
+                index: { type: "number", description: "搜索结果第几首，从 1 开始，默认 1" },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "wangyi_queue",
+        description: "读取网易云音乐当前播放队列（优先 CDP 实时状态，否则读本地缓存）",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "wangyi_next",
+        description: "播放下一首（优先 CDP 客户端切歌）",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+    {
+        name: "wangyi_prev",
+        description: "播放上一首（优先 CDP 客户端切歌）",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    },
+];
+function textResult(data, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        isError,
+    };
+}
+function argString(args, key) {
+    const value = args?.[key];
+    return value == null ? "" : String(value);
+}
+function argNumber(args, key) {
+    const value = args?.[key];
+    if (value == null || value === "")
+        return undefined;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : undefined;
+}
+export async function callTool(name, args) {
+    switch (name) {
+        case "wangyi_status":
+            return getStatus();
+        case "wangyi_launch":
+            return launchWithCdp();
+        case "wangyi_search": {
+            const query = argString(args, "query").trim();
+            const limit = Math.max(1, Math.min(50, Math.round(argNumber(args, "limit") || 10)));
+            const tracks = await searchTracks(query, limit);
+            return { ok: true, tracks };
+        }
+        case "wangyi_play": {
+            const query = argString(args, "query").trim();
+            const index = Math.max(1, Math.round(argNumber(args, "index") || 1));
+            if (/^\d+$/.test(query)) {
+                const url = await playTrackById(query);
+                return { ok: true, status: "playing", id: query, url };
+            }
+            const tracks = await searchTracks(query, Math.max(index, 10));
+            if (!tracks.length)
+                throw new ToolError("EMPTY_RESULT", `没有搜到「${query}」`);
+            const track = tracks[index - 1];
+            if (!track)
+                throw new ToolError("EMPTY_RESULT", `只有 ${tracks.length} 条结果，没有第 ${index} 首`);
+            const url = await playTrackById(track.id, track.title);
+            return { ok: true, status: "playing", ...track, url };
+        }
+        case "wangyi_queue":
+            return { ok: true, ...(await readPlayerQueue()) };
+        case "wangyi_next":
+            return { ok: true, ...(await skipPlayerQueue(1)) };
+        case "wangyi_prev":
+            return { ok: true, ...(await skipPlayerQueue(-1)) };
+        default:
+            throw new ToolError("UNKNOWN_TOOL", `未知工具 ${name}`);
+    }
+}
+function printJson(data, isError = false) {
+    const text = JSON.stringify(data, null, 2);
+    if (isError)
+        console.error(text);
+    else
+        console.log(text);
+}
+function parseCliArgs(argv) {
+    const [cmd, ...rest] = argv;
+    const args = {};
+    const positionals = [];
+    for (let i = 0; i < rest.length; i++) {
+        const token = rest[i];
+        if (token === "--limit" || token === "--index") {
+            const key = token.slice(2);
+            args[key] = Number(rest[++i]);
+        }
+        else if (token.startsWith("--")) {
+            throw new ToolError("INVALID_ARGS", `未知参数 ${token}`);
+        }
+        else {
+            positionals.push(token);
+        }
+    }
+    if (positionals.length)
+        args.query = positionals.join(" ");
+    return { cmd, args };
+}
+async function runCli(argv) {
+    const { cmd, args } = parseCliArgs(argv);
+    const toolMap = {
+        status: "wangyi_status",
+        launch: "wangyi_launch",
+        search: "wangyi_search",
+        play: "wangyi_play",
+        queue: "wangyi_queue",
+        next: "wangyi_next",
+        prev: "wangyi_prev",
+    };
+    if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+        console.log(`ym-mcp-wangyi — 网易云音乐 MCP / CLI
+
+用法:
+  ym-mcp-wangyi                  # MCP stdio（给 Cursor 用）
+  ym-mcp-wangyi status
+  ym-mcp-wangyi launch           # 重要：以 CDP 重启客户端，之后才能真正控播放
+  ym-mcp-wangyi search <关键词> [--limit N]
+  ym-mcp-wangyi play <id|关键词> [--index N]
+  ym-mcp-wangyi queue
+  ym-mcp-wangyi next
+  ym-mcp-wangyi prev
+
+首次使用播放控制前请先 launch。需要本机已安装并登录网易云桌面端（macOS / Windows）。
+`);
+        return 0;
+    }
+    const tool = toolMap[cmd];
+    if (!tool) {
+        printJson({ ok: false, code: "UNKNOWN_TOOL", error: `未知命令 ${cmd}`, hint: "用 help 查看用法" }, true);
+        return 1;
+    }
+    try {
+        const result = await callTool(tool, args);
+        printJson(result);
+        return 0;
+    }
+    catch (err) {
+        printJson(asToolError(err).toJSON(), true);
+        return 1;
+    }
+}
+async function runMcp() {
+    const server = new Server({ name: "ym-mcp-wangyi", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...TOOLS] }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        try {
+            const result = await callTool(request.params.name, request.params.arguments);
+            return textResult(result);
+        }
+        catch (err) {
+            const toolErr = asToolError(err);
+            return textResult(toolErr.toJSON(), true);
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length > 0) {
+        const code = await runCli(argv);
+        process.exit(code);
+    }
+    await runMcp();
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/lib/api.js

@@ -0,0 +1,83 @@
+import { SEARCH_URL, USER_AGENT } from "./paths.js";
+import { loadCookies } from "./cookies.js";
+import { ToolError } from "./errors.js";
+function formatDuration(ms) {
+    const total = Math.round(Number(ms || 0) / 1000);
+    if (!total)
+        return "";
+    const m = Math.floor(total / 60);
+    const s = String(total % 60).padStart(2, "0");
+    return `${m}:${s}`;
+}
+function artistNames(artists) {
+    if (!Array.isArray(artists))
+        return "";
+    return artists
+        .map((a) => (a && typeof a === "object" && "name" in a ? String(a.name || "") : ""))
+        .filter(Boolean)
+        .join(", ");
+}
+export function mapSearchTracks(payload, limit) {
+    const root = payload && typeof payload === "object" ? payload : {};
+    const result = root.result && typeof root.result === "object" ? root.result : root;
+    const songs = Array.isArray(result.songs) ? result.songs : [];
+    const rows = [];
+    for (const item of songs) {
+        if (rows.length >= limit)
+            break;
+        if (!item || typeof item !== "object")
+            continue;
+        const song = item;
+        const id = song.id;
+        const name = song.name;
+        if (!id || !name)
+            continue;
+        const artists = song.ar || song.artists;
+        const album = (song.al || song.album);
+        rows.push({
+            id: String(id),
+            title: String(name),
+            artist: artistNames(artists),
+            album: String(album?.name || ""),
+            duration: formatDuration(song.dt ?? song.duration),
+        });
+    }
+    return rows;
+}
+export async function searchTracks(query, limit = 10) {
+    const q = query.trim();
+    if (!q)
+        throw new ToolError("INVALID_ARGS", "query 不能为空");
+    const cookies = loadCookies();
+    const body = new URLSearchParams({
+        s: q,
+        type: "1",
+        limit: String(Math.max(1, Math.min(50, limit))),
+        offset: "0",
+    });
+    const headers = {
+        Accept: "*/*",
+        "Content-Type": "application/x-www-form-urlencoded",
+        "User-Agent": USER_AGENT,
+        Referer: "https://music.163.com/",
+    };
+    if (cookies.header)
+        headers.Cookie = cookies.header;
+    const res = await fetch(SEARCH_URL, { method: "POST", headers, body });
+    const text = await res.text();
+    if (!text) {
+        throw new ToolError("API_ERROR", "搜索接口返回空", "确认网络可用，或先在客户端登录后再试");
+    }
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        throw new ToolError("API_ERROR", "搜索接口不是 JSON", text.slice(0, 200));
+    }
+    const code = payload?.code;
+    if (code != null && code !== 200) {
+        throw new ToolError("API_ERROR", `搜索失败 code=${code}`, text.slice(0, 200));
+    }
+    return mapSearchTracks(payload, limit);
+}

package/dist/lib/bplist.js

@@ -0,0 +1,224 @@
+/**
+ * Minimal binary plist parser for NetEase MMKV cookie archives (NSKeyedArchiver).
+ * Only supports the object types we need: dict / array / string / data / uid / number / bool.
+ */
+export class UID {
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+}
+function readUInt(buf, offset, size) {
+    if (size === 1)
+        return buf.readUInt8(offset);
+    if (size === 2)
+        return buf.readUInt16BE(offset);
+    if (size === 4)
+        return buf.readUInt32BE(offset);
+    if (size === 8) {
+        const big = buf.readBigUInt64BE(offset);
+        if (big > BigInt(Number.MAX_SAFE_INTEGER))
+            throw new Error("plist int too large");
+        return Number(big);
+    }
+    throw new Error(`unsupported uint size ${size}`);
+}
+export function parseBplist(input) {
+    if (input.subarray(0, 8).toString("ascii") !== "bplist00") {
+        throw new Error("not a binary plist");
+    }
+    const trailer = input.subarray(input.length - 32);
+    const offsetSize = trailer.readUInt8(6);
+    const objectRefSize = trailer.readUInt8(7);
+    const numObjects = Number(trailer.readBigUInt64BE(8));
+    const topObject = Number(trailer.readBigUInt64BE(16));
+    const offsetTableOffset = Number(trailer.readBigUInt64BE(24));
+    const offsets = [];
+    for (let i = 0; i < numObjects; i++) {
+        offsets.push(readUInt(input, offsetTableOffset + i * offsetSize, offsetSize));
+    }
+    const cache = new Map();
+    const parseObject = (index) => {
+        if (cache.has(index))
+            return cache.get(index);
+        const offset = offsets[index];
+        const marker = input.readUInt8(offset);
+        const type = marker & 0xf0;
+        const info = marker & 0x0f;
+        let value;
+        switch (type) {
+            case 0x00:
+                if (info === 0x00)
+                    value = null;
+                else if (info === 0x08)
+                    value = false;
+                else if (info === 0x09)
+                    value = true;
+                else
+                    value = null;
+                break;
+            case 0x10: {
+                const size = 1 << info;
+                if (size === 8)
+                    value = Number(input.readBigInt64BE(offset + 1));
+                else if (size === 1)
+                    value = input.readInt8(offset + 1);
+                else if (size === 2)
+                    value = input.readInt16BE(offset + 1);
+                else if (size === 4)
+                    value = input.readInt32BE(offset + 1);
+                else
+                    throw new Error(`bad int size ${size}`);
+                break;
+            }
+            case 0x20: {
+                const size = 1 << info;
+                value = size === 4 ? input.readFloatBE(offset + 1) : input.readDoubleBE(offset + 1);
+                break;
+            }
+            case 0x30: {
+                // date: 8-byte float seconds since 2001-01-01
+                value = input.readDoubleBE(offset + 1);
+                break;
+            }
+            case 0x40: {
+                let length = info;
+                let dataOffset = offset + 1;
+                if (info === 0x0f) {
+                    const lenMarker = input.readUInt8(dataOffset);
+                    dataOffset += 1;
+                    const lenSize = 1 << (lenMarker & 0x0f);
+                    length = readUInt(input, dataOffset, lenSize);
+                    dataOffset += lenSize;
+                }
+                value = Uint8Array.from(input.subarray(dataOffset, dataOffset + length));
+                break;
+            }
+            case 0x50:
+            case 0x60: {
+                let length = info;
+                let dataOffset = offset + 1;
+                if (info === 0x0f) {
+                    const lenMarker = input.readUInt8(dataOffset);
+                    dataOffset += 1;
+                    const lenSize = 1 << (lenMarker & 0x0f);
+                    length = readUInt(input, dataOffset, lenSize);
+                    dataOffset += lenSize;
+                }
+                if (type === 0x50) {
+                    value = input.subarray(dataOffset, dataOffset + length).toString("ascii");
+                }
+                else {
+                    value = input.subarray(dataOffset, dataOffset + length * 2).toString("utf16le");
+                    // bplist stores UTF-16BE
+                    const be = input.subarray(dataOffset, dataOffset + length * 2);
+                    const swapped = Buffer.alloc(be.length);
+                    for (let i = 0; i < be.length; i += 2) {
+                        swapped[i] = be[i + 1];
+                        swapped[i + 1] = be[i];
+                    }
+                    value = swapped.toString("utf16le");
+                }
+                break;
+            }
+            case 0x80: {
+                value = new UID(readUInt(input, offset + 1, info + 1));
+                break;
+            }
+            case 0xa0:
+            case 0xc0: {
+                let length = info;
+                let dataOffset = offset + 1;
+                if (info === 0x0f) {
+                    const lenMarker = input.readUInt8(dataOffset);
+                    dataOffset += 1;
+                    const lenSize = 1 << (lenMarker & 0x0f);
+                    length = readUInt(input, dataOffset, lenSize);
+                    dataOffset += lenSize;
+                }
+                const arr = [];
+                // placeholder first so recursive refs work
+                cache.set(index, arr);
+                for (let i = 0; i < length; i++) {
+                    const ref = readUInt(input, dataOffset + i * objectRefSize, objectRefSize);
+                    arr.push(parseObject(ref));
+                }
+                return arr;
+            }
+            case 0xd0: {
+                let length = info;
+                let dataOffset = offset + 1;
+                if (info === 0x0f) {
+                    const lenMarker = input.readUInt8(dataOffset);
+                    dataOffset += 1;
+                    const lenSize = 1 << (lenMarker & 0x0f);
+                    length = readUInt(input, dataOffset, lenSize);
+                    dataOffset += lenSize;
+                }
+                const dict = {};
+                cache.set(index, dict);
+                const keyRefs = [];
+                const valRefs = [];
+                for (let i = 0; i < length; i++) {
+                    keyRefs.push(readUInt(input, dataOffset + i * objectRefSize, objectRefSize));
+                }
+                for (let i = 0; i < length; i++) {
+                    valRefs.push(readUInt(input, dataOffset + length * objectRefSize + i * objectRefSize, objectRefSize));
+                }
+                for (let i = 0; i < length; i++) {
+                    const key = parseObject(keyRefs[i]);
+                    dict[String(key)] = parseObject(valRefs[i]);
+                }
+                return dict;
+            }
+            default:
+                throw new Error(`unsupported plist type 0x${type.toString(16)}`);
+        }
+        cache.set(index, value);
+        return value;
+    };
+    return parseObject(topObject);
+}
+export function resolveUid(objects, value) {
+    let cur = value;
+    const seen = new Set();
+    while (cur instanceof UID) {
+        if (seen.has(cur.data))
+            throw new Error("UID cycle");
+        seen.add(cur.data);
+        cur = objects[cur.data];
+    }
+    return cur;
+}
+export function nsDictionary(objects, value) {
+    const resolved = resolveUid(objects, value);
+    if (!resolved || typeof resolved !== "object" || Array.isArray(resolved) || resolved instanceof UID || resolved instanceof Uint8Array) {
+        return {};
+    }
+    const rec = resolved;
+    const keys = rec["NS.keys"];
+    const vals = rec["NS.objects"];
+    if (!Array.isArray(keys) || !Array.isArray(vals) || keys.length !== vals.length)
+        return {};
+    const out = {};
+    for (let i = 0; i < keys.length; i++) {
+        const key = resolveUid(objects, keys[i]);
+        if (typeof key === "string")
+            out[key] = resolveUid(objects, vals[i]);
+    }
+    return out;
+}
+export function parseKeyedArchive(buf) {
+    const archive = parseBplist(buf);
+    if (!archive || typeof archive !== "object" || Array.isArray(archive)) {
+        throw new Error("invalid archive root");
+    }
+    const rec = archive;
+    const objects = rec["$objects"];
+    const top = rec["$top"];
+    if (!Array.isArray(objects) || !top || typeof top !== "object" || Array.isArray(top)) {
+        throw new Error("invalid keyed archive");
+    }
+    const topRec = top;
+    return { objects, root: nsDictionary(objects, topRec.root) };
+}