Get robot parameter help

Instructions

Implementation Reference

• packages/mcp-server/src/server.ts:973-1044 (registration)

  Registers the 'transloadit_get_robot_help' tool with the MCP server, including input/output schemas and the handler closure.

  server.registerTool(
    'transloadit_get_robot_help',
    {
      title: 'Get robot parameter help',
      description: 'Returns a robot summary and parameter details.',
      inputSchema: getRobotHelpInputSchema,
      outputSchema: getRobotHelpOutputSchema,
    },
    ({ robot_name, robot_names }) => {
      const splitComma = (value: string): string[] =>
        value
          .split(',')
          .map((part) => part.trim())
          .filter(Boolean)
  
      const prefersSingle =
        typeof robot_name === 'string' && robot_name.trim() !== '' && !robot_name.includes(',')
  
      const requested =
        robot_names && robot_names.length > 0
          ? robot_names
          : robot_name
            ? splitComma(robot_name)
            : []
  
      if (requested.length === 0) {
        return buildToolError('mcp_missing_args', 'Provide robot_name or robot_names.')
      }
  
      const robots: Array<{
        name: string
        summary: string
        required_params: unknown[]
        optional_params: unknown[]
        examples?: unknown[]
      }> = []
      const notFound: string[] = []
  
      for (const name of requested) {
        if (!isKnownRobot(name)) {
          notFound.push(name)
          continue
        }
        const help = getRobotHelp({
          robotName: name,
          detailLevel: 'full',
        })
  
        robots.push({
          name: help.name,
          summary: help.summary,
          required_params: help.requiredParams,
          optional_params: help.optionalParams,
          examples: help.examples,
        })
      }
  
      if (prefersSingle) {
        return buildToolResponse({
          status: 'ok',
          robot: robots[0],
          not_found: notFound.length > 0 ? notFound : undefined,
        })
      }
  
      return buildToolResponse({
        status: 'ok',
        robots,
        not_found: notFound.length > 0 ? notFound : undefined,
      })
    },
  )

• packages/mcp-server/src/server.ts:981-1043 (handler)

  Handler function that accepts robot_name/robot_names, looks up robot help via getRobotHelp(), and returns results (single or multiple robots) with not_found reporting.

  ({ robot_name, robot_names }) => {
    const splitComma = (value: string): string[] =>
      value
        .split(',')
        .map((part) => part.trim())
        .filter(Boolean)
  
    const prefersSingle =
      typeof robot_name === 'string' && robot_name.trim() !== '' && !robot_name.includes(',')
  
    const requested =
      robot_names && robot_names.length > 0
        ? robot_names
        : robot_name
          ? splitComma(robot_name)
          : []
  
    if (requested.length === 0) {
      return buildToolError('mcp_missing_args', 'Provide robot_name or robot_names.')
    }
  
    const robots: Array<{
      name: string
      summary: string
      required_params: unknown[]
      optional_params: unknown[]
      examples?: unknown[]
    }> = []
    const notFound: string[] = []
  
    for (const name of requested) {
      if (!isKnownRobot(name)) {
        notFound.push(name)
        continue
      }
      const help = getRobotHelp({
        robotName: name,
        detailLevel: 'full',
      })
  
      robots.push({
        name: help.name,
        summary: help.summary,
        required_params: help.requiredParams,
        optional_params: help.optionalParams,
        examples: help.examples,
      })
    }
  
    if (prefersSingle) {
      return buildToolResponse({
        status: 'ok',
        robot: robots[0],
        not_found: notFound.length > 0 ? notFound : undefined,
      })
    }
  
    return buildToolResponse({
      status: 'ok',
      robots,
      not_found: notFound.length > 0 ? notFound : undefined,
    })
  },

• packages/mcp-server/src/server.ts:99-104 (schema)

  Zod input schema for get_robot_help: optional robot_name (string), robot_names (array of strings), and backward-compat detail_level.

  const getRobotHelpInputSchema = z.object({
    robot_name: z.string().optional(),
    robot_names: z.array(z.string()).optional(),
    // Backward compatible input; ignored on purpose (we always return full docs).
    detail_level: z.enum(['summary', 'params', 'examples']).optional(),
  })

• packages/mcp-server/src/server.ts:121-131 (schema)

  Zod output schema for get_robot_help: status, optional single robot, optional robots array, and optional not_found array.

  const getRobotHelpOutputSchema = z
    .object({
      status: z.enum(['ok', 'error']),
      // For backward compatibility, we still return `robot` for single-robot requests via `robot_name`.
      robot: robotHelpOutputSchema.optional(),
      robots: z.array(robotHelpOutputSchema).optional(),
      not_found: z.array(z.string()).optional(),
    })
    .refine((value) => value.status !== 'ok' || value.robot || value.robots, {
      message: 'Expected robot or robots for ok status.',
    })

• packages/node/src/robots.ts:288-317 (helper)

  Core helper function getRobotHelp() that resolves robot meta and schema to build a RobotHelp object with name, summary, params, and examples.

  export const getRobotHelp = (options: RobotHelpOptions): RobotHelp => {
    const detailLevel = options.detailLevel ?? 'summary'
    const { byPath, byName } = getMetaIndex()
    const schemaIndex = getSchemaIndex()
  
    const path = resolveRobotPath(options.robotName)
    const meta = byPath.get(path) ?? byName.get(options.robotName) ?? null
    const summary = meta ? selectSummary(meta) : `Robot ${path}`
    const schema = schemaIndex.get(path)
    const params = schema ? getRobotParams(schema) : { required: [], optional: [] }
  
    const help: RobotHelp = {
      name: path,
      summary,
      requiredParams: detailLevel === 'params' || detailLevel === 'full' ? params.required : [],
      optionalParams: detailLevel === 'params' || detailLevel === 'full' ? params.optional : [],
    }
  
    if ((detailLevel === 'examples' || detailLevel === 'full') && meta?.example_code) {
      const snippet = isRecord(meta.example_code) ? meta.example_code : {}
      help.examples = [
        {
          description: meta.example_code_description ?? 'Example',
          snippet,
        },
      ]
    }
  
    return help
  }