Structured Output

Instructions

Implementation Reference

• src/tools/structured.ts:35-141 (handler)

  The core handler function `executeStructured` that executes the structured output tool logic: validates schema, reads files, invokes Claude CLI with --json-schema, and parses structured_output from Claude's response.

  export async function executeStructured(input: StructuredInput): Promise<StructuredResult> {
    const { prompt, files = [], timeout, sessionId, noSessionPersistence, maxBudgetUsd } = input;
    const model = resolveModel("structured", input.model);
  
    const schemaBytes = Buffer.byteLength(input.schema);
    if (schemaBytes > MAX_SCHEMA_SIZE) {
      throw new Error(`Schema too large: ${schemaBytes} bytes (max ${MAX_SCHEMA_SIZE})`);
    }
  
    let parsedSchema: object;
    try {
      parsedSchema = JSON.parse(input.schema) as object;
    } catch {
      throw new Error("Invalid schema: not valid JSON");
    }
  
    const imageFiles = files.filter((f) => isImageFile(f));
    if (imageFiles.length > 0) {
      throw new Error("Structured tool does not support image files (text only)");
    }
  
    if (files.length > MAX_FILES) {
      throw new Error(`Too many files: ${files.length} (max ${MAX_FILES})`);
    }
  
    const cwd = await resolveCwd(input.workingDirectory);
  
    const fileContents = files.length > 0 ? await readFiles(files, cwd) : [];
    const fullPrompt = assemblePrompt(prompt, fileContents);
    const useStdin = fullPrompt.length > STDIN_THRESHOLD || files.length > 0;
    const effectiveTimeout = clampTimeout(timeout, 60_000);
  
    const args = buildClaudeArgs({
      model,
      fallbackModel: getFallbackModel(),
      maxBudgetUsd: resolveMaxBudget(maxBudgetUsd),
      sessionId,
      noSessionPersistence,
      jsonSchema: JSON.stringify(parsedSchema),
      prompt: useStdin ? undefined : fullPrompt,
    });
  
    const result = await spawnClaude({ args, cwd, stdin: useStdin ? fullPrompt : undefined, timeout: effectiveTimeout });
  
    const filesIncluded = fileContents.filter((f) => !f.skipped).map((f) => f.path);
    const filesSkipped = fileContents.filter((f) => f.skipped).map((f) => `${f.path}: ${f.skipped}`);
  
    if (result.timedOut) {
      return {
        response: `Structured query timed out after ${effectiveTimeout / 1000}s.`,
        valid: false,
        model,
        filesIncluded,
        filesSkipped,
        timedOut: true,
      };
    }
  
    const parsed = parseClaudeOutput(result.stdout, result.stderr);
    checkAndThrow(result, parsed);
  
    // Claude CLI places --json-schema output in the structured_output field.
    // Use key-existence check (not truthy) to handle scalar values like false, 0, "", null.
    const raw = parsed.raw as Record<string, unknown> | undefined;
    if (raw && "structured_output" in raw) {
      return {
        response: JSON.stringify(raw.structured_output),
        valid: true,
        model,
        sessionId: parsed.sessionId,
        totalCostUsd: parsed.totalCostUsd,
        usage: parsed.usage,
        filesIncluded,
        filesSkipped,
        timedOut: false,
      };
    }
  
    // Fall back to extracting JSON from the response text
    const extracted = extractJson(parsed.response);
    if (!extracted) {
      return {
        response: parsed.response,
        valid: false,
        errors: "Could not extract JSON from response",
        model,
        sessionId: parsed.sessionId,
        totalCostUsd: parsed.totalCostUsd,
        usage: parsed.usage,
        filesIncluded,
        filesSkipped,
        timedOut: false,
      };
    }
  
    return {
      response: extracted.raw,
      valid: true,
      model,
      sessionId: parsed.sessionId,
      totalCostUsd: parsed.totalCostUsd,
      usage: parsed.usage,
      filesIncluded,
      filesSkipped,
      timedOut: false,
    };
  }

• src/tools/structured.ts:10-20 (schema)

  `StructuredInput` interface defining the input schema for the structured tool: prompt, schema (JSON Schema string), files, model, sessionId, noSessionPersistence, workingDirectory, timeout, maxBudgetUsd.

  export interface StructuredInput {
    prompt: string;
    schema: string;
    files?: string[];
    model?: string;
    sessionId?: string;
    noSessionPersistence?: boolean;
    workingDirectory?: string;
    timeout?: number;
    maxBudgetUsd?: number;
  }

• src/tools/structured.ts:22-33 (schema)

  `StructuredResult` interface defining the output shape: response, valid, errors, model, sessionId, totalCostUsd, usage, filesIncluded, filesSkipped, timedOut.

  export interface StructuredResult {
    response: string;
    valid: boolean;
    errors?: string;
    model?: string;
    sessionId?: string;
    totalCostUsd?: number;
    usage?: ClaudeUsage;
    filesIncluded: string[];
    filesSkipped: string[];
    timedOut: boolean;
  }

• src/index.ts:145-230 (registration)

  Registration of the 'structured' tool via server.registerTool() with Zod input schema, annotations, and the async handler that calls executeStructured and formats the result.

  server.registerTool(
    "structured",
    {
      title: "Structured Output",
      description: structuredDescription,
      inputSchema: {
        prompt: z.string().describe("What to generate or extract"),
        schema: z.string().describe("JSON Schema as a JSON string"),
        files: z
          .array(z.string())
          .optional()
          .describe("Text file paths to include as context"),
        model: z.string().optional().describe("Model alias or full Claude model name"),
        sessionId: z
          .string()
          .optional()
          .describe("Claude session ID to resume with --resume"),
        noSessionPersistence: z
          .boolean()
          .optional()
          .describe("Disable session persistence for ephemeral print calls"),
        workingDirectory: z
          .string()
          .optional()
          .describe("Working directory for file resolution and CLI execution"),
        timeout: z
          .number()
          .optional()
          .describe("Timeout in milliseconds (default: 60000)"),
        maxBudgetUsd: z
          .number()
          .positive()
          .optional()
          .describe("Maximum cost budget in USD for this call (passed to --max-budget-usd)"),
      },
      annotations: structuredAnnotations,
    },
    async (input) => {
      const start = Date.now();
      try {
        const result = await executeStructured(input);
  
        const sessionId = result.sessionId ?? input.sessionId;
        if (sessionId) {
          persist(sessionStore, sessionId, result);
        }
  
        const meta = buildMeta({
          durationMs: Date.now() - start,
          model: result.model,
          sessionId: result.sessionId,
          totalCostUsd: result.totalCostUsd,
          usage: result.usage,
          timedOut: result.timedOut,
        });
  
        if (!result.valid) {
          return {
            content: [{ type: "text" as const, text: `Error: ${result.errors ?? "Invalid response"}` }],
            isError: true,
            _meta: meta,
          };
        }
  
        const content: Array<{ type: "text"; text: string }> = [
          { type: "text", text: result.response },
        ];
  
        const textMeta: string[] = [];
        if (result.filesIncluded.length > 0) textMeta.push(`Files: ${result.filesIncluded.join(", ")}`);
        if (result.timedOut) textMeta.push("(timed out)");
        if (textMeta.length > 0) {
          content.push({ type: "text", text: textMeta.join("\n") });
        }
  
        return { content, _meta: meta };
      } catch (e) {
        console.error("[structured]", e);
        return {
          content: [{ type: "text" as const, text: `Error: ${getErrorMessage(e)}` }],
          isError: true,
          _meta: buildMeta({ durationMs: Date.now() - start }),
        };
      }
    },
  );

• src/utils/model.ts:1-8 (helper)

  Model resolution configuration: 'structured' is listed as a ToolName type and defaults to 'sonnet' model.

  export type ToolName = "query" | "structured" | "search" | "ping";
  
  const DEFAULT_MODELS: Record<ToolName, string> = {
    query: "sonnet",
    structured: "sonnet",
    search: "sonnet",
    ping: "haiku",
  };