list_captions

Instructions

Implementation Reference

• src/tools/captions.ts:50-77 (registration)

  Registers the 'list_captions' tool on the MCP server with its schema and handler.

  server.tool(
    "list_captions",
    "List caption tracks on a video with their language, name, status, and whether they are drafts.",
    listCaptionsSchema,
    async (args) => {
      const res = await client.listCaptions(args.video_id);
      if (res.items.length === 0) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Video ${args.video_id} has no caption tracks.`,
            },
          ],
        };
      }
      const lines = [
        `Found ${res.items.length} caption track(s):`,
        ...res.items.map((c) => {
          const s = c.snippet ?? {};
          const draft = s.isDraft ? " [draft]" : "";
          const kind = s.trackKind ? ` (${s.trackKind})` : "";
          return `  ${c.id} — ${s.language ?? "?"} "${s.name ?? ""}"${kind} [${s.status ?? "?"}]${draft}`;
        }),
      ];
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

• src/tools/captions.ts:38-40 (schema)

  Zod schema defining the input for list_captions: requires a video_id string.

  const listCaptionsSchema = {
    video_id: z.string().describe("Video ID to list captions for."),
  };

• src/tools/captions.ts:54-76 (handler)

  Handler that calls client.listCaptions(video_id) and formats the response into a human-readable text listing of caption tracks.

  async (args) => {
    const res = await client.listCaptions(args.video_id);
    if (res.items.length === 0) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Video ${args.video_id} has no caption tracks.`,
          },
        ],
      };
    }
    const lines = [
      `Found ${res.items.length} caption track(s):`,
      ...res.items.map((c) => {
        const s = c.snippet ?? {};
        const draft = s.isDraft ? " [draft]" : "";
        const kind = s.trackKind ? ` (${s.trackKind})` : "";
        return `  ${c.id} — ${s.language ?? "?"} "${s.name ?? ""}"${kind} [${s.status ?? "?"}]${draft}`;
      }),
    ];
    return { content: [{ type: "text" as const, text: lines.join("\n") }] };
  },

• src/youtube/client.ts:276-290 (helper)

  Client helper method that calls the YouTube Data API v3 /captions endpoint with snippet part and videoId to retrieve caption track metadata.

  listCaptions(videoId: string): Promise<{
    items: Array<{
      id: string;
      snippet?: {
        name?: string;
        language?: string;
        status?: string;
        isDraft?: boolean;
        lastUpdated?: string;
        trackKind?: string;
      };
    }>;
  }> {
    return this.dataGet("/captions", { part: "snippet", videoId });
  }

• src/server.ts:51-55 (registration)

  Import and call to registerCaptionTools which wires up the list_captions tool.

    registerCaptionTools(s, youtube);
    registerShortsTools(s, youtube);
    registerBridgeTools(s, youtube, comfyui, config.comfyUIDefaultCkpt);
    return s;
  };