IRCAM Amplify MCP Server

Instructions

Implementation Reference

• src/tools/check-job-status.ts:38-92 (handler)

  The handler function that executes the core logic of the check_job_status tool: validates the job_id, queries the IRCAM API for status, formats the response with status, progress, results (for stem separation), or errors.

  export async function handleCheckJobStatus(
    args: Record<string, unknown>
  ): Promise<JobStatusOutput> {
    const jobId = args.job_id as string;
  
    // Validate input
    const validation = validateJobId(jobId);
    if (!validation.valid) {
      throw validation.error;
    }
  
    // Call IRCAM Job Status API
    const url = buildApiUrl(`${IRCAM_API_CONFIG.ENDPOINTS.JOB_STATUS}/${jobId}`);
    const response = await httpGet<IrcamJobStatusResponse>(url);
  
    if (!response.ok || !response.data) {
      throw response.error || formatError('JOB_NOT_FOUND', 'Job not found');
    }
  
    const job = response.data;
  
    // Build job state response
    const result: JobStatusOutput = {
      status: job.status,
      progress: job.progress,
    };
  
    // Add result if completed (assuming stem separation result)
    if (job.status === 'completed' && job.result) {
      const stemResult = job.result as {
        stems?: {
          vocals?: { url: string };
          drums?: { url: string };
          bass?: { url: string };
          other?: { url: string };
        };
      };
  
      if (stemResult.stems) {
        result.result = {
          vocals_url: stemResult.stems.vocals?.url || '',
          drums_url: stemResult.stems.drums?.url || '',
          bass_url: stemResult.stems.bass?.url || '',
          other_url: stemResult.stems.other?.url || '',
        } as StemSeparationResult;
      }
    }
  
    // Add error if failed
    if (job.status === 'failed' && job.error) {
      result.error = job.error;
    }
  
    return result;
  }

• src/tools/check-job-status.ts:17-33 (schema)

  The Tool object definition for check_job_status, including name, description, and inputSchema for MCP tool listing and validation.

  export const checkJobStatusTool: Tool = {
    name: 'check_job_status',
    description:
      'Check the status of an async processing job. ' +
      'Use this to monitor jobs returned by separate_stems and other async operations. ' +
      'Returns job status (pending, processing, completed, failed), progress percentage, and results when completed.',
    inputSchema: {
      type: 'object',
      properties: {
        job_id: {
          type: 'string',
          description: 'The job ID returned by an async operation',
        },
      },
      required: ['job_id'],
    },
  };

• src/index.ts:37-43 (registration)

  Registration of checkJobStatusTool in the TOOLS array, used by MCP server for listTools requests.

  const TOOLS = [
    analyzeMusicTool,
    separateStemsTool,
    detectAiMusicTool,
    analyzeLoudnessTool,
    checkJobStatusTool,
  ];

• src/index.ts:48-54 (registration)

  Mapping of tool name 'check_job_status' to its handler function handleCheckJobStatus in the TOOL_HANDLERS object, used for tool call execution.

  const TOOL_HANDLERS: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
    analyze_music: handleAnalyzeMusic,
    separate_stems: handleSeparateStems,
    detect_ai_music: handleDetectAiMusic,
    analyze_loudness: handleAnalyzeLoudness,
    check_job_status: handleCheckJobStatus,
  };

• src/types/mcp-tools.ts:159-172 (schema)

  TypeScript type definitions for JobStatusInput and JobStatusOutput used in the check_job_status tool for input/output validation and typing.

  /**
   * Input pour vérification de statut
   */
  export interface JobStatusInput {
    /** ID du job à vérifier */
    job_id: string;
  }
  
  /**
   * Output de check_job_status
   * Le type du result dépend de l'opération originale
   */
  export type JobStatusOutput = JobState<StemSeparationResult>;