get_asr_task

Instructions

Implementation Reference

• src/index.js:173-188 (schema)

  Tool schema/registration for 'get_asr_task' — defines the tool name, description, annotations (ASR_POLL: readOnly, non-idempotent, not openWorld), and inputSchema requiring a 'task_id' string. This is the inline registration of the tool in the TOOLS array.

    name: "get_asr_task",
    description:
      "Poll the status of an ASR task created by transcribe_video. Returns one of `queued`, `downloading`, `transcribing`, `finalizing`, `done`, or `failed`. When status is `done`, includes the full transcript with timestamps. Recommended polling interval: 3-5 seconds. Free — does not consume credits.",
    annotations: { title: "Get ASR Task Status", ...ANN.ASR_POLL },
    inputSchema: {
      type: "object",
      properties: {
        task_id: {
          type: "string",
          description: "Task ID returned by transcribe_video.",
          minLength: 1,
        },
      },
      required: ["task_id"],
    },
  },

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

  Generic handler that proxies ALL tool calls (including get_asr_task) to the upstream MCP server via callUpstream(). The CallToolRequestSchema handler forwards request.params.name (the tool name) and request.params.arguments to the upstream URL with a Bearer token.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
  
  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 — the actual helper that forwards tool calls to https://api.subdownload.com/mcp via JSON-RPC. It sends the tool name and arguments as a 'tools/call' request with the API key as a Bearer token, then returns the result or throws on error.

  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:443-446 (registration)

  MCP Server instantiation and tool capability declaration — creates the Server with name 'subdownload' and version '1.0.0', declaring the 'tools' capability so the SDK handles tool-related requests.

  const server = new Server(
    { name: "subdownload", version: "1.0.0" },
    { capabilities: { tools: {} } }
  );

• src/index.js:150-171 (helper)

  Sibling tool 'transcribe_video' which creates the ASR tasks that get_asr_task polls. Important context: transcribe_video returns task_id, and get_asr_task accepts that task_id to poll for results.

    name: "transcribe_video",
    description:
      "Start an asynchronous AI ASR (Whisper) transcription of a YouTube video. Returns immediately with a task_id and estimated_wait_seconds; the actual transcription runs in the background. Poll status with get_asr_task. Use this when fetch_transcript returned NO_CAPTIONS or when the video has no captions. Costs 5 credits, debited only on successful completion.",
    annotations: { title: "Transcribe YouTube Video (Async)", ...ANN.ASR_START },
    inputSchema: {
      type: "object",
      properties: {
        video_url: {
          type: "string",
          description:
            "YouTube URL (watch, youtu.be, shorts, or embed form). Full URL preferred.",
          minLength: 5,
        },
        lang: {
          type: "string",
          description:
            "Optional language hint (ISO 639-1, e.g. 'en', 'zh'). Omit to auto-detect.",
        },
      },
      required: ["video_url"],
    },
  },