generalize template URL import injection

Author: kvz

packages/mcp-server/README.md

@@ -95,6 +95,9 @@ the request body stays small and no extra MCP/LLM token budget is consumed.
   and avoids large inline payloads (the transfer happens out-of-band).
 - If instructions already contain an `/http/import` step, the MCP server sets/overrides its `url`.
   - If multiple URLs and a single `/http/import` step exists, it supplies a `url` array.
+- Templates (builtin or custom) should expose an `imported` step that the template uses as input.
+  When you pass `template_id` (or `builtin_template`) and URL inputs, the MCP server injects an
+  `/http/import` step named `imported` and fills its `url` value(s).
 
 ## Local vs hosted file access
 

packages/mcp-server/src/server.ts

@@ -334,6 +334,12 @@ const isNonEmptyString = (value: unknown): value is string =>
 const isErrnoException = (value: unknown): value is NodeJS.ErrnoException =>
   isRecord(value) && typeof value.code === 'string'
 
+const isHttpImportStep = (value: unknown): value is Record<string, unknown> =>
+  isRecord(value) && value.robot === '/http/import'
+
+const hasHttpImportStep = (steps: Record<string, unknown>): boolean =>
+  Object.values(steps).some((step) => isHttpImportStep(step))
+
 const getAssemblyIdFromUrl = (assemblyUrl: string): string => {
   const match = assemblyUrl.match(/\/assemblies\/([^/?#]+)/)
   if (!match) {
@@ -526,17 +532,45 @@ export const createTransloaditMcpServer = (
       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 hasUrlInputs = fileInputs.some((file) => file.kind === 'url')
         let params = parseInstructions(instructions) ?? ({} as CreateAssemblyParams)
 
         if (builtin_template) {
           const templateId = buildBuiltinTemplateId(builtin_template.slug, builtin_template.version)
           const overrides = builtin_template.overrides
-          params = (overrides && isRecord(overrides) ? overrides : {}) as CreateAssemblyParams
+          const baseParams = (
+            overrides && isRecord(overrides) ? { ...overrides } : {}
+          ) as CreateAssemblyParams
+
+          templatePathHint = 'builtin_template.slug'
+          params = baseParams
           params.template_id = templateId
         }
+
+        if (hasUrlInputs && params.template_id) {
+          const steps = isRecord(params.steps) ? { ...params.steps } : {}
+          if (!hasHttpImportStep(steps)) {
+            const imported = isRecord(steps.imported)
+              ? (steps.imported as Record<string, unknown>)
+              : {}
+            steps.imported = {
+              ...imported,
+              robot: '/http/import',
+            }
+            params.steps = steps
+            warnings.push({
+              code: 'mcp_imported_step',
+              message:
+                'URL inputs with template_id require a step named "imported" that the template uses as input. The MCP server injected /http/import into that step.',
+              path: templatePathHint ?? 'instructions.template_id',
+            })
+          }
+        }
         const prep = await prepareInputFiles({
           inputFiles: fileInputs,
           params,
@@ -634,6 +668,7 @@ export const createTransloaditMcpServer = (
           assembly,
           upload: uploadSummary,
           next_steps: nextSteps,
+          warnings: warnings.length > 0 ? warnings : undefined,
         })
       } finally {
         await Promise.all(tempCleanups.map((cleanup) => cleanup()))

packages/mcp-server/test/e2e/builtin-templates-import.test.ts

@@ -0,0 +1,40 @@
+import type { Client } from '@modelcontextprotocol/sdk/client'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { createMcpClient, parseToolPayload } from './mcp-client.ts'
+
+describe('mcp-server builtin template imports', { timeout: 20000 }, () => {
+  let client: Client
+
+  beforeAll(async () => {
+    client = await createMcpClient()
+  })
+
+  afterAll(async () => {
+    await client?.close()
+  })
+
+  it('injects an imported /http/import step for URL inputs', async () => {
+    const result = await client.callTool({
+      name: 'transloadit_create_assembly',
+      arguments: {
+        builtin_template: { slug: 'builtin/encode-hls-video' },
+        files: [
+          {
+            kind: 'url',
+            field: 'video',
+            url: 'https://demos.transloadit.com/66/01604e7d0248109df8c7cc0f8daef8/snowflake.jpg',
+          },
+        ],
+        wait_for_completion: false,
+      },
+    })
+
+    const payload = parseToolPayload(result)
+    expect(payload.status).toBe('ok')
+
+    const warnings = Array.isArray(payload.warnings) ? payload.warnings : []
+    expect(warnings.length).toBeGreaterThan(0)
+    const imported = warnings.find((warning) => warning.code === 'mcp_imported_step')
+    expect(imported).toBeTruthy()
+  })
+})