player_play

Instructions

Implementation Reference

• index.js:322-341 (schema)

  Tool definition and input schema for player_play: accepts path (string, required) and append (boolean, optional).

  {
    name: "player_play",
    description:
      "Open and play a media file or URL. If mpv is not running, it will be launched automatically.",
    inputSchema: {
      type: "object",
      properties: {
        path: {
          type: "string",
          description: "Absolute file path or URL (http/https/rtmp etc.)",
        },
        append: {
          type: "boolean",
          description: "Append to current playlist instead of replacing it",
          default: false,
        },
      },
      required: ["path"],
    },
  },

• index.js:505-529 (handler)

  Handler for player_play: ensures mpv is running, loads the file (replacing or appending to playlist), focuses the window for video files, and ensures playback is not paused.

  case "player_play": {
    await ensureMpv();
    const flag = args.append ? "append-play" : "replace";
    await mpv("loadfile", [args.path, flag]);
  
    // If it's a video file, bring mpv window to foreground
    const VIDEO_EXTS = new Set([
      "mp4","mkv","avi","mov","wmv","flv","webm","m4v",
      "mpg","mpeg","ts","rmvb","3gp","ogv","hevc"
    ]);
    const ext = args.path.split(".").pop().toLowerCase().split("?")[0];
    if (VIDEO_EXTS.has(ext)) {
      // Wait for mpv to open the video window, then restore + focus
      await new Promise((r) => setTimeout(r, 800));
      await mpv("focus").catch(() => null);
      spawn("powershell", ["-NoProfile", "-NonInteractive", "-Command",
        "(New-Object -ComObject Shell.Application).Windows() | ForEach-Object { if ($_.FullName -like '*mpv*') { $_.Visible = $true } };" +
        "$wshell = New-Object -ComObject wscript.shell;" +
        "$wshell.AppActivate('mpv')"
      ], { detached: true, stdio: "ignore" }).unref();
    }
  
    await setProperty("pause", false);
    return ok(`Playing: ${args.path}`);
  }

• index.js:724-728 (registration)

  MCP server request handlers: ListToolsRequestSchema returns the TOOLS array (which includes player_play), and CallToolRequestSchema dispatches to handleTool which handles the player_play case.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
  
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
    return handleTool(name, args || {});

• index.js:222-223 (helper)

  Helper function that sends IPC commands to mpv via named pipe; used by the player_play handler to send 'loadfile' and 'focus' commands.

  async function mpv(command, args = []) {
    return ipcCommand({ command: [command, ...args], request_id: reqId++ });

• index.js:243-269 (helper)

  Helper that ensures mpv is running before playback; starts mpv with IPC server if not already running, used by player_play handler.

  async function ensureMpv(filePath = null) {
    const running = await isMpvRunning();
    if (running) return { started: false };
  
    const args = [
      "--input-ipc-server=" + PIPE_PATH,
      "--idle=yes",
      "--keep-open=yes",
      "--no-terminal",
    ];
    if (filePath) args.push(filePath);
  
    const proc = spawn(MPV_BINARY, args, {
      detached: true,
      stdio: "ignore",
      windowsHide: false,
    });
    proc.unref();
  
    // Wait for pipe to be ready
    for (let i = 0; i < 20; i++) {
      await new Promise((r) => setTimeout(r, 250));
      if (await isMpvRunning()) return { started: true };
    }
    throw new Error(
      "mpv failed to start. Make sure mpv is installed and in PATH, or set MPV_PATH environment variable."
    );