transcribe_get_job

Instructions

Implementation Reference

• src/index.ts:364-391 (registration)

  Registration and input schema for the transcribe_get_job tool in the MCP tools list definition.

      {
        name: "transcribe_get_job",
        description:
          "Poll an async transcription job created by transcribe-audio.",
        inputSchema: {
          $schema: "https://json-schema.org/draft/2020-12/schema",
          type: "object",
          properties: {
            job_id: { type: "string" },
            as_text: { type: "boolean" },
          },
          required: ["job_id"],
          additionalProperties: false,
        },
      },
      {
        name: "transcribe_cancel_job",
        description: "Cancel an async transcription job (best-effort).",
        inputSchema: {
          $schema: "https://json-schema.org/draft/2020-12/schema",
          type: "object",
          properties: { job_id: { type: "string" } },
          required: ["job_id"],
          additionalProperties: false,
        },
      },
    ],
  }));

• src/index.ts:1002-1029 (handler)

  Handler for transcribe_get_job: retrieves a job from TranscribeJobManager and returns completed result (formatted) or current job status.

  private async handleTranscribeGetJob(args: {
    job_id: string;
    as_text?: boolean;
  }): Promise<{ content: Array<{ type: string; text: string }> }> {
    const job = this.transcribeJobManager.getJob(args.job_id);
    if (job.status === "completed" && job.result) {
      return {
        content: [
          {
            type: "text",
            text: this.formatTranscriptionPayload(
              job.result,
              args.as_text,
              false,
            ),
          },
        ],
      };
    }
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(job, null, 2),
        },
      ],
    };
  }

• src/transcribe-job-manager.ts:83-101 (handler)

  TranscribeJobManager.getJob() - retrieves async job status/result used by handleTranscribeGetJob.

  getJob(id: string): {
    status: JobStatus | "unknown";
    result?: StructuredTranscriptionResult;
    error?: string;
  } {
    this.gcOldJobs();
    const job = this.jobs.get(id);
    if (!job) return { status: "unknown", error: "Unknown job_id" };
    if (job.status === "processing") {
      return { status: "processing" };
    }
    if (job.status === "cancelled") {
      return { status: "cancelled", error: "Job was cancelled." };
    }
    if (job.status === "failed") {
      return { status: "failed", error: job.error || "Job failed." };
    }
    return { status: "completed", result: job.result };
  }

• src/index.ts:368-377 (schema)

  Input schema for transcribe_get_job: requires job_id (string), optional as_text (boolean).

  inputSchema: {
    $schema: "https://json-schema.org/draft/2020-12/schema",
    type: "object",
    properties: {
      job_id: { type: "string" },
      as_text: { type: "boolean" },
    },
    required: ["job_id"],
    additionalProperties: false,
  },

• src/index.ts:799-821 (helper)

  Helper used by handleTranscribeGetJob to format completed job result as text with timestamps, plain text, or JSON.

  private formatTranscriptionPayload(
    payload: StructuredTranscriptionResult | TranscribeAsyncQueued,
    asText: boolean | undefined,
    includeTimestamps: boolean | undefined,
  ): string {
    if ("job_id" in payload) {
      return JSON.stringify(payload, null, 2);
    }
    if (asText) {
      if (includeTimestamps) {
        return this.formatTranscript(
          payload.segments.map((segment) => ({
            text: segment.text,
            start: segment.start,
            duration: Math.max(0, segment.end - segment.start),
          })),
          true,
        );
      }
      return payload.text;
    }
    return JSON.stringify(payload, null, 2);
  }