MiniMax MCP JS

Instructions

Implementation Reference

• src/mcp-server.ts:636-692 (registration)

  Registration of the 'query_video_generation' MCP tool including inline Zod schema for parameters (taskId, outputDirectory) and the handler function that calls VideoAPI.queryVideoGeneration and formats the MCP response.

  private registerQueryVideoGenerationTool(): void {
    this.server.tool(
      'query_video_generation',
      'Query the status of a video generation task.',
      {
        taskId: z
          .string()
          .describe('The Task ID to query. Should be the task_id returned by `generate_video` tool if `async_mode` is True.'),
        outputDirectory: COMMON_PARAMETERS_SCHEMA.outputDirectory,
      },
      async (params) => {
        try {
          // No need to update configuration from request parameters in stdio mode
          const result = await this.videoApi.queryVideoGeneration(params);
  
          if (result.status === 'Success') {
            if (this.config.resourceMode === RESOURCE_MODE_URL) {
              return {
                content: [
                  {
                    type: 'text',
                    text: `Success. Video URL: ${result.video_url}`, 
                  },
                ],
              };
            } else {
              return {
                content: [
                  {
                    type: 'text',
                    text: `Success. Video saved as: ${result.video_path}`,
                  },
                ],
              };
            }
          } else {
            return {
              content: [
                {
                  type: 'text',
                  text: `Video generation task is still processing: Task ID: ${params.taskId}.`,
                },
              ],
            };
          }
        } catch (error) {
          return {
            content: [
              {
                type: 'text',
                text: `Failed to query video generation: ${error instanceof Error ? error.message : String(error)}`,
              },
            ],
          };
        }
      },
    );

• src/api/video.ts:151-211 (handler)

  Core handler logic in VideoAPI class: queries MiniMax API /v1/query/video_generation for task status, retrieves file info if success, returns URL or downloads and saves the MP4 video file.

  async queryVideoGeneration(request: VideoGenerationQueryRequest): Promise<any> {
    const taskId = request.taskId;
  
    // Step 1: Get video generation status
    const response = await this.api.get<any>(`/v1/query/video_generation?task_id=${taskId}`);
    const status = response?.status;
    let fileId: string | null = null;
    if (status === 'Fail') {
      throw new MinimaxRequestError(`Video generation task failed, task ID: ${taskId}`);
    } else if (status === 'Success') {
      fileId = response?.file_id;
      if (!fileId) {
        throw new MinimaxRequestError(`File ID missing in success response, task ID: ${taskId}`);
      }
    } else {
      return {
        status,
      }
    }
  
    // Step 2: Get video result
    const fileResponse = await this.api.get<any>(`/v1/files/retrieve?file_id=${fileId}`);
    const downloadUrl = fileResponse?.file?.download_url;
  
    if (!downloadUrl) {
      throw new MinimaxRequestError(`Unable to get download URL for file ID: ${fileId}`);
    }
  
    // If URL mode, return URL directly
    const resourceMode = this.api.getResourceMode();
    if (resourceMode === RESOURCE_MODE_URL) {
      return {
        status,
        video_url: downloadUrl,
        task_id: taskId,
      };
    }
  
    // Step 3: Download and save video
    const outputPath = buildOutputFile(`video_${taskId}`, request.outputDirectory, 'mp4', true);
  
    try {
      const videoResponse = await requests.default.get(downloadUrl, { responseType: 'arraybuffer' });
  
      // Ensure directory exists
      const dirPath = path.dirname(outputPath);
      if (!fs.existsSync(dirPath)) {
        fs.mkdirSync(dirPath, { recursive: true });
      }
  
      // Save file
      fs.writeFileSync(outputPath, Buffer.from(videoResponse.data));
      return {
        status,
        video_path: outputPath,
        task_id: taskId,
      }
    } catch (error) {
      throw new MinimaxRequestError(`Failed to download or save video: ${String(error)}`);
    }
  }

• src/types/index.ts:47-49 (schema)

  TypeScript interface defining the input parameters for video generation query: taskId (string), inherits outputDirectory etc. from BaseToolRequest.

  export interface VideoGenerationQueryRequest extends BaseToolRequest {
    taskId: string;
  }

• src/services/media-service.ts:186-223 (helper)

  Wrapper method in MediaService that calls VideoAPI.queryVideoGeneration and formats REST response, used by mcp-rest-server.

  public async queryVideoGeneration(params: any): Promise<any> {
    this.checkInitialized();
    try {
      const result = await this.videoApi.queryVideoGeneration(params);
      if (result.status === 'Success') {
        if (this.config.resourceMode === RESOURCE_MODE_URL) {
          return {
          content: [
              {
                type: 'text',
                text: `Success. Video URL: ${result.video_url}`,
              },
            ],
          };
        } else {
          return {
            content: [
              {
                type: 'text',
                text: `Success. Video saved as: ${result.video_path}`,
              },
            ],
          };
        }
      } else {
        return {
          content: [
            {
              type: 'text',
              text: `Video generation task is still processing: Task ID: ${params.taskId}.`,
            },
          ],
        };
      }
    } catch (error) {
      throw this.wrapError('Failed to query video generation status', error);
    }
  }