validate required template fields

Author: kvz

packages/mcp-server/src/server.ts

@@ -2,6 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { CallToolResult, TextContent } from '@modelcontextprotocol/sdk/types.js'
 import type { CreateAssemblyParams, LintAssemblyInstructionsResult } from '@transloadit/node'
 import {
+  extractFieldNamesFromTemplate,
   getRobotHelp,
   listRobots,
   mergeTemplateContent,
@@ -411,6 +412,21 @@ const mergeImportOverrides = (
   return nextOverrides
 }
 
+const collectFieldNames = (templateContent: string): string[] => {
+  const names = extractFieldNamesFromTemplate(templateContent).map((field) => field.fieldName)
+  return Array.from(new Set(names))
+}
+
+const mergeFieldValues = (
+  templateFields: Record<string, unknown> | undefined,
+  argFields: Record<string, unknown> | undefined,
+): Record<string, unknown> => {
+  return {
+    ...(templateFields ?? {}),
+    ...(argFields ?? {}),
+  }
+}
+
 const getAssemblyIdFromUrl = (assemblyUrl: string): string => {
   const match = assemblyUrl.match(/\/assemblies\/([^/?#]+)/)
   if (!match) {
@@ -637,7 +653,9 @@ export const createTransloaditMcpServer = (
         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
 
         if (builtin_template) {
           const templateId = buildBuiltinTemplateId(builtin_template.slug, builtin_template.version)
@@ -651,29 +669,35 @@ export const createTransloaditMcpServer = (
           params.template_id = templateId
         }
 
-        if (hasUrlInputs) {
-          let analysis = analyzeSteps(isRecord(params.steps) ? params.steps : {})
-
-          if (params.template_id) {
-            templatePathHint = templatePathHint ?? 'instructions.template_id'
-            const template = await client.getTemplate(params.template_id)
-            allowStepsOverride = template.content.allow_steps_override !== false
-            try {
-              const merged = mergeTemplateContent(template.content, params)
-              mergedSteps = isRecord(merged.steps) ? (merged.steps 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
+        let analysis = analyzeSteps(isRecord(params.steps) ? params.steps : {})
+
+        if (params.template_id) {
+          templatePathHint = templatePathHint ?? 'instructions.template_id'
+          const template = await client.getTemplate(params.template_id)
+          allowStepsOverride = template.content.allow_steps_override !== false
+          try {
+            const merged = mergeTemplateContent(template.content, 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({
@@ -706,6 +730,31 @@ export const createTransloaditMcpServer = (
             }
           }
         }
+
+        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,

packages/mcp-server/test/e2e/template-inputs.test.ts

@@ -74,10 +74,24 @@ maybeDescribe('mcp-server template URL handling', { timeout: 60000 }, () => {
       },
     })
 
+    const fieldTemplate = await api.createTemplate({
+      name: `mcp-fields-${suffix}`,
+      template: {
+        steps: {
+          convert: {
+            robot: '/html/convert',
+            url: '${fields.prompt}',
+            result: true,
+          },
+        },
+      },
+    })
+
     templates.push(
       { id: importTemplate.id, name: importTemplate.name },
       { id: uploadTemplate.id, name: uploadTemplate.name },
       { id: noInputTemplate.id, name: noInputTemplate.name },
+      { id: fieldTemplate.id, name: fieldTemplate.name },
     )
   })
 
@@ -166,4 +180,41 @@ maybeDescribe('mcp-server template URL handling', { timeout: 60000 }, () => {
     const warnings = Array.isArray(payload.warnings) ? payload.warnings : []
     expect(warnings.some((warning) => warning.code === 'mcp_url_inputs_ignored')).toBe(true)
   })
+
+  it('errors when required fields are missing', async () => {
+    const result = await client.callTool({
+      name: 'transloadit_create_assembly',
+      arguments: {
+        instructions: {
+          template_id: templates[3]?.id,
+        },
+        fields: {
+          wrong: 'https://example.com',
+        },
+      },
+    })
+
+    const payload = parseToolPayload(result)
+    expect(payload.status).toBe('error')
+    const errors = Array.isArray(payload.errors) ? payload.errors : []
+    expect(errors.some((error) => error.code === 'mcp_missing_fields')).toBe(true)
+  })
+
+  it('accepts required fields referenced by the template', async () => {
+    const result = await client.callTool({
+      name: 'transloadit_create_assembly',
+      arguments: {
+        instructions: {
+          template_id: templates[3]?.id,
+        },
+        fields: {
+          prompt: 'https://example.com',
+        },
+        wait_for_completion: false,
+      },
+    })
+
+    const payload = parseToolPayload(result)
+    expect(payload.status).toBe('ok')
+  })
 })

packages/node/src/Transloadit.ts

@@ -69,6 +69,7 @@ export {
 export type { AssemblyStatus } from './alphalib/types/assemblyStatus.ts'
 export * from './apiTypes.ts'
 export { InconsistentResponseError, ApiError }
+export { extractFieldNamesFromTemplate } from './alphalib/stepParsing.ts'
 // Builtin templates replace the legacy golden template helpers.
 export { mergeTemplateContent } from './alphalib/templateMerge.ts'
 export type {