get_video_status

Instructions

Implementation Reference

• src/tool-handlers/generate-video.ts:405-460 (handler)

  The main handler function that executes the get_video_status tool logic. It takes a GetVideoStatusToolRequest, validates video_id, optionally resolves save_path, polls the video job status via apiClient.pollVideoJob(), and returns the result (completed, failed, or still running).

  export async function handleGetVideoStatus(
    request: { params: { arguments: GetVideoStatusToolRequest } },
    apiClient: OpenRouterAPIClient,
  ) {
    const args = request.params.arguments ?? ({} as GetVideoStatusToolRequest);
    const id = args.video_id?.trim();
    if (!id) return toolError(ErrorCode.INVALID_INPUT, 'video_id is required.');
  
    // Pre-resolve save_path so the poll surfaces a fast error before hitting OpenRouter.
    let safeSavePath: string | null = null;
    if (args.save_path) {
      try {
        safeSavePath = await resolveSafeOutputPath(args.save_path);
      } catch (err) {
        if (err instanceof UnsafeOutputPathError) return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
        return toolErrorFrom(ErrorCode.INTERNAL, err);
      }
    }
  
    let status: VideoJobStatus;
    try {
      status = await apiClient.pollVideoJob(id);
    } catch (err) {
      return classifyUpstreamError(err, 'get_video_status.poll');
    }
  
    if (status.status === 'failed') {
      return toolError(ErrorCode.JOB_FAILED, extractJobError(status), { video_id: id });
    }
    if (status.status === 'completed') {
      try {
        const { content, _meta } = await finalizeCompletedJob(apiClient, status, safeSavePath);
        return { content, _meta };
      } catch (err) {
        if (err instanceof UnsafeOutputPathError) return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
        return toolErrorFrom(ErrorCode.UPSTREAM_HTTP, err, 'Download');
      }
    }
    return {
      content: [
        {
          type: 'text' as const,
          text: `Video ${id} status: ${status.status}${
            typeof status.progress === 'number' ? ` (progress=${status.progress})` : ''
          }`,
        },
      ],
      isError: false as const,
      _meta: {
        code: ErrorCode.JOB_STILL_RUNNING,
        video_id: id,
        last_status: status.status,
        progress: status.progress,
      },
    };
  }

• src/tool-handlers/generate-video.ts:40-44 (schema)

  TypeScript interface defining the input schema for get_video_status: requires video_id (string), with optional save_path and polling_url.

  export interface GetVideoStatusToolRequest {
    video_id: string;
    save_path?: string;
    polling_url?: string;
  }

• src/tool-handlers.ts:440-462 (registration)

  Registration of the get_video_status tool definition including its name, description, annotations, and inputSchema for the MCP server's ListToolsRequestSchema handler.

  {
    name: 'get_video_status',
    description:
      'Resume a previously submitted video generation job by id. Returns the latest status; if completed, ' +
      'downloads the video (and saves it when save_path is provided).',
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
    },
    inputSchema: {
      type: 'object',
      properties: {
        video_id: { type: 'string', description: 'Job id from a previous generate_video call.' },
        save_path: {
          type: 'string',
          description:
            'Optional save path (applies when the job is already completed).',
        },
      },
      required: ['video_id'],
    },
  },

• src/tool-handlers.ts:526-530 (registration)

  Case in the CallToolRequestSchema handler that dispatches 'get_video_status' requests to handleGetVideoStatus, wrapping args with GetVideoStatusToolRequest type.

  case 'get_video_status':
    return handleGetVideoStatus(
      wrapToolArgs(args as GetVideoStatusToolRequest | undefined),
      this.apiClient,
    );

• src/tool-handlers.ts:20-23 (helper)

  Import of handleGetVideoStatus and GetVideoStatusToolRequest from the generate-video module into the main tool-handlers file.

  import {
    handleGenerateVideo,
    handleGetVideoStatus,
  } from './tool-handlers/generate-video.js';