Transloadit MCP Server

Instructions

Implementation Reference

• packages/mcp-server/src/server.ts:649-902 (handler)

  The handler function for 'transloadit_create_assembly' which processes assembly creation, input files, template merging, and optionally waits for assembly completion.

  server.registerTool(
    'transloadit_create_assembly',
    {
      title: 'Create or resume an Assembly',
      description:
        'Create or resume an Assembly, optionally uploading files and waiting for completion.',
      inputSchema: createAssemblyInputSchema,
      outputSchema: createAssemblyOutputSchema,
    },
    async (
      {
        instructions,
        files,
        fields,
        wait_for_completion,
        wait_timeout_ms,
        upload_concurrency,
        upload_chunk_size,
        upload_behavior,
        expected_uploads,
        assembly_url,
      },
      extra,
    ) => {
      const liveClient = createLiveClient(options, extra)
      if ('error' in liveClient) return liveClient.error
      const { client } = liveClient
      const tempCleanups: Array<() => Promise<void>> = []
      const warnings: Array<{ code: string; message: string; hint?: string; path?: string }> = []
      let templatePathHint: string | undefined
  
      try {
        const fileInputs = files ?? []
        const urlInputs = fileInputs.filter((file) => file.kind === 'url')
        const hasUrlInputs = urlInputs.length > 0
        let inputFilesForPrep = fileInputs
        let params = parseInstructions(instructions) ?? ({} as CreateAssemblyParams)
        let allowStepsOverride = true
        let mergedInstructions: CreateAssemblyParams | undefined
        let mergedSteps: Record<string, unknown> | undefined
        let mergedFields: Record<string, unknown> | undefined
  
        let analysis = analyzeSteps(isRecord(params.steps) ? params.steps : {})
  
        if (params.template_id) {
          templatePathHint = templatePathHint ?? 'instructions.template_id'
          let template: Awaited<ReturnType<typeof client.getTemplate>>
          try {
            template = await client.getTemplate(params.template_id)
          } catch (error) {
            const isTemplateNotFound =
              (error instanceof ApiError && error.code === 'TEMPLATE_NOT_FOUND') ||
              getHttpStatusCode(error) === 404
  
            if (isTemplateNotFound) {
              const templateId = params.template_id
              const hint = isBuiltinTemplateId(templateId)
                ? 'Builtin template not found. Call transloadit_list_templates with include_builtin: "exclusively-latest" to discover builtins.'
                : 'Template not found. Call transloadit_list_templates to discover available templates.'
              return buildToolError('mcp_template_not_found', `Template not found: ${templateId}`, {
                path: templatePathHint,
                hint,
              })
            }
            throw error
          }
          allowStepsOverride = template.content.allow_steps_override !== false
          try {
            const merged = mergeTemplateContent(
              template.content,
              toAssemblyInstructionsInput(params),
            )
            mergedInstructions = merged as CreateAssemblyParams
            mergedSteps = isRecord(merged.steps) ? (merged.steps as Record<string, unknown>) : {}
            mergedFields = isRecord(merged.fields) ? (merged.fields as Record<string, unknown>) : {}
            analysis = analyzeSteps(mergedSteps)
          } catch (error) {
            if (error instanceof Error && error.message === 'TEMPLATE_DENIES_STEPS_OVERRIDE') {
              return buildToolError(
                'mcp_template_override_denied',
                'Template forbids step overrides; remove steps overrides or choose a different template.',
                { path: templatePathHint },
              )
            }
            throw error
          }
        } else {
          mergedInstructions = params
          mergedSteps = isRecord(params.steps) ? (params.steps as Record<string, unknown>) : {}
          mergedFields = isRecord(params.fields) ? (params.fields as Record<string, unknown>) : {}
        }
  
        if (hasUrlInputs) {
          if (!analysis.hasHttpImport && !analysis.requiresUpload) {
            inputFilesForPrep = fileInputs.filter((file) => file.kind !== 'url')
            warnings.push({
              code: 'mcp_url_inputs_ignored',
              message: 'URL inputs were ignored because the template does not require input files.',
              hint: 'If you meant to process a URL, use a template that imports URLs (e.g. builtin/serve-preview@0.0.1), or call transloadit_list_templates with include_builtin: "exclusively-latest" to discover builtins.',
              path: templatePathHint ?? 'instructions',
            })
          } else if (analysis.hasHttpImport) {
            if (!allowStepsOverride) {
              if (analysis.requiresUpload) {
                warnings.push({
                  code: 'mcp_template_import_override_denied',
                  message:
                    'Template forbids step overrides; URL inputs will be downloaded and uploaded via tus instead of /http/import.',
                  path: templatePathHint ?? 'instructions.template_id',
                })
              } else {
                return buildToolError(
                  'mcp_template_override_denied',
                  'Template forbids step overrides; URL inputs cannot be mapped to /http/import.',
                  { path: templatePathHint ?? 'instructions.template_id' },
                )
              }
            } else if (mergedSteps) {
              params.steps = mergeImportOverrides(
                mergedSteps,
                isRecord(params.steps) ? params.steps : undefined,
                analysis.importStepNames,
              ) as CreateAssemblyParams['steps']
            }
          }
        }
  
        if (mergedInstructions) {
          const fieldTemplateContent = JSON.stringify(mergedInstructions)
          const requiredFields = collectFieldNames(fieldTemplateContent)
          const providedFields = mergeFieldValues(
            mergedFields,
            isRecord(fields) ? (fields as Record<string, unknown>) : undefined,
          )
          const missingFields = requiredFields.filter((fieldName) => !(fieldName in providedFields))
          const effectiveMissing =
            hasUrlInputs && analysis.hasHttpImport
              ? missingFields.filter((fieldName) => fieldName !== 'input')
              : missingFields
  
          if (effectiveMissing.length > 0) {
            return buildToolError(
              'mcp_missing_fields',
              `Missing required fields: ${effectiveMissing.join(', ')}`,
              {
                path: 'fields',
                hint: 'Provide these field names under the fields argument.',
              },
            )
          }
        }
        const prep = await prepareInputFiles({
          inputFiles: inputFilesForPrep,
          params,
          fields,
          base64Strategy: 'tempfile',
          urlStrategy: 'import-if-present',
          maxBase64Bytes,
        }).catch((error) => {
          const message = error instanceof Error ? error.message : 'Invalid file input.'
          if (message.startsWith('Duplicate file field')) {
            return buildToolError('mcp_duplicate_field', message, { path: 'files' })
          }
          if (message.startsWith('Base64 payload exceeds')) {
            return buildToolError('mcp_base64_too_large', message, {
              hint: 'Use a URL import or path upload instead.',
            })
          }
          return buildToolError('mcp_invalid_args', message)
        })
        if ('content' in prep) {
          return prep
        }
        params = prep.params
        const filesMap = prep.files
        const uploadsMap = prep.uploads
        tempCleanups.push(...prep.cleanup)
  
        const totalFiles = Object.keys(filesMap).length + Object.keys(uploadsMap).length
        const uploadSummary: UploadSummary = {
          status: totalFiles > 0 ? 'complete' : 'none',
          total_files: totalFiles,
        }
  
        const timeout = wait_timeout_ms
        const waitForCompletion = wait_for_completion ?? false
        const uploadBehavior = upload_behavior ?? (waitForCompletion ? 'await' : 'background')
        const uploadConcurrency = upload_concurrency
        const chunkSize = upload_chunk_size
  
        let assembly: Awaited<ReturnType<typeof client.createAssembly>>
        try {
          assembly = assembly_url
            ? await client.resumeAssemblyUploads({
                assemblyUrl: assembly_url,
                files: filesMap,
                uploads: uploadsMap,
                waitForCompletion,
                timeout,
                uploadConcurrency,
                chunkSize,
                uploadBehavior,
              })
            : await client.createAssembly({
                params,
                files: filesMap,
                uploads: uploadsMap,
                waitForCompletion,
                timeout,
                uploadConcurrency,
                chunkSize,
                uploadBehavior,
                expectedUploads: expected_uploads,
              })
        } catch (error) {
          if (isErrnoException(error) && error.code === 'ENOENT') {
            return buildToolError('mcp_file_not_found', error.message, {
              hint: 'Path inputs only work when the MCP server can read local files. For hosted MCP, use url/base64 or upload via `npx -y @transloadit/node upload`.',
            })
          }
          throw error
        }
  
        if (assembly_url) {
          uploadSummary.resumed = true
        }
  
        if (totalFiles === 0) {
          uploadSummary.status = 'none'
        } else if (uploadBehavior === 'none') {
          uploadSummary.status = 'none'
        } else if (uploadBehavior === 'background') {
          uploadSummary.status = 'uploading'
        }
  
        if (isRecord(assembly.upload_urls)) {
          uploadSummary.upload_urls = assembly.upload_urls as Record<string, string>
        }
  
        const nextSteps = waitForCompletion
          ? []
          : ['transloadit_wait_for_assembly', 'transloadit_get_assembly_status']
  
        return buildToolResponse({
          status: 'ok',
          assembly,
          upload: uploadSummary,
          next_steps: nextSteps,
          warnings: warnings.length > 0 ? warnings : undefined,
        })
      } finally {
        await Promise.all(tempCleanups.map((cleanup) => cleanup()))
      }
    },

• packages/mcp-server/src/server.ts:155-166 (schema)

  Input validation schema for 'transloadit_create_assembly' using zod.

  const createAssemblyInputSchema = z.object({
    instructions: z.unknown().optional(),
    files: z.array(inputFileSchema).optional(),
    fields: z.record(z.string(), z.unknown()).optional(),
    wait_for_completion: z.boolean().optional(),
    wait_timeout_ms: z.number().int().positive().optional(),
    upload_concurrency: z.number().int().positive().optional(),
    upload_chunk_size: z.number().int().positive().optional(),
    upload_behavior: z.enum(['await', 'background', 'none']).optional(),
    expected_uploads: z.number().int().positive().optional(),
    assembly_url: z.string().optional(),
  })

• packages/mcp-server/src/server.ts:168-182 (schema)

  Output validation schema for 'transloadit_create_assembly' using zod.

  const createAssemblyOutputSchema = z.object({
    status: z.enum(['ok', 'error']),
    assembly: z.unknown().optional(),
    upload: z
      .object({
        status: z.enum(['none', 'uploading', 'complete']),
        total_files: z.number().int().nonnegative(),
        resumed: z.boolean().optional(),
        upload_urls: z.record(z.string(), z.string()).optional(),
      })
      .optional(),
    next_steps: z.array(z.string()).optional(),
    errors: z.array(toolMessageSchema).optional(),
    warnings: z.array(toolMessageSchema).optional(),
  })

• packages/mcp-server/src/server-card.ts:46-70 (registration)

  Registration/documentation of 'transloadit_create_assembly' in the server card definition.

  {
    name: 'transloadit_create_assembly',
    title: 'Create or resume an Assembly',
    description:
      'Create or resume an Assembly, optionally uploading files and waiting for completion.',
    inputSchema: {
      type: 'object',
      additionalProperties: false,
      properties: {
        instructions: { type: ['object', 'array', 'string', 'number', 'boolean', 'null'] },
        files: {
          type: 'array',
          items: { type: 'object' },
        },
        fields: { type: 'object' },
        wait_for_completion: { type: 'boolean' },
        wait_timeout_ms: { type: 'number' },
        upload_concurrency: { type: 'number' },
        upload_chunk_size: { type: 'number' },
        upload_behavior: { type: 'string', enum: ['await', 'background', 'none'] },
        expected_uploads: { type: 'number' },
        assembly_url: { type: 'string' },
      },
    },
  },