list_playlist_videos

Instructions

Implementation Reference

• src/index.js:273-292 (registration)

  Tool 'list_playlist_videos' is registered in the TOOLS array with its metadata, description, annotations, and inputSchema. It accepts 'playlist' (required for first page) and 'continuation' (pagination token) parameters.

  {
    name: "list_playlist_videos",
    description:
      "List videos in a YouTube playlist in order, with pagination. Returns video metadata and position within the playlist. Works for any public or unlisted playlist exposed by its URL/ID.",
    annotations: { title: "List Playlist Videos", ...ANN.YT_READ },
    inputSchema: {
      type: "object",
      properties: {
        playlist: {
          type: "string",
          description:
            "Playlist URL or ID (typically starts with 'PL', 'UU', 'LL', or 'FL'). Required for the first page.",
        },
        continuation: {
          type: "string",
          description: "Pagination token from a previous response's `continuation` field. Omit for the first page.",
        },
      },
    },
  },

• src/index.js:450-462 (handler)

  The CallToolRequestSchema handler forwards any tool call (including 'list_playlist_videos') to the upstream MCP server via callUpstream, which posts to the remote endpoint with the Bearer token.

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      return await callUpstream(
        request.params.name,
        request.params.arguments || {}
      );
    } catch (err) {
      return {
        content: [{ type: "text", text: err.message || String(err) }],
        isError: true,
      };
    }
  });

• src/index.js:408-441 (helper)

  The callUpstream function is the generic helper that forwards tool calls (by name and arguments) to the upstream MCP endpoint. It handles JSON response parsing and error reporting.

  async function callUpstream(name, args) {
    if (!API_KEY) {
      throw new Error(
        "SUBDOWNLOAD_API_KEY env var is not set. Get one at https://subdownload.com/account, then run with -e SUBDOWNLOAD_API_KEY=<your-key>."
      );
    }
    const res = await fetch(UPSTREAM_URL, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Accept: "application/json, text/event-stream",
        Authorization: `Bearer ${API_KEY}`,
      },
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: Date.now(),
        method: "tools/call",
        params: { name, arguments: args },
      }),
    });
    const text = await res.text();
    let body;
    try {
      body = JSON.parse(text);
    } catch {
      throw new Error(
        `Upstream returned non-JSON response (HTTP ${res.status}): ${text.slice(0, 200)}`
      );
    }
    if (body.error) {
      throw new Error(body.error.message || JSON.stringify(body.error));
    }
    return body.result;
  }

• src/index.js:278-291 (schema)

  Input schema for list_playlist_videos: accepts 'playlist' (string, URL or ID like PL..., UU..., LL..., FL...) and 'continuation' (string, pagination token). No required fields (since continuation can be used alone).

  inputSchema: {
    type: "object",
    properties: {
      playlist: {
        type: "string",
        description:
          "Playlist URL or ID (typically starts with 'PL', 'UU', 'LL', or 'FL'). Required for the first page.",
      },
      continuation: {
        type: "string",
        description: "Pagination token from a previous response's `continuation` field. Omit for the first page.",
      },
    },
  },