Instruction file imported from PoBruno/mcp-unreal-agent (.github/instructions/mcp-tools.instructions.md). Copyright stays with the author.

MCP tool contract

Apply to any file under Tools/src/tools/. Mirror of .claude/rules/mcp-tools.md. This is the tool contract — it is the agent-facing API.

Required output shape

export type ToolResult<T = unknown> = {
  ok: boolean;
  data?: T;
  refs?: Record<string, string | string[]>;
  nextSteps?: string[];
  warnings?: string[];
  errorCode?: string;
};

Error code registry

Add new codes here AND in .claude/rules/mcp-tools.md. Keep both files in sync.

Input validation with Zod

Every tool registers with a Zod schema:

import { z } from "zod";

server.tool(
  "bp_set_variable",
  "Set a variable's default value on a Blueprint class. Returns the updated value and signals if a recompile is needed.",
  {
    blueprintId: z.string().describe("Blueprint asset path or ID from refs"),
    variableName: z.string(),
    value: z.union([z.string(), z.number(), z.boolean()]),
  },
  async ({ blueprintId, variableName, value }) => {
    // implementation
  }
);

• Every parameter gets .describe() with what the agent needs to know.
• Optional parameters use .optional(), never | undefined in the type.
• IDs accepted as opaque strings — never tightly typed as BlueprintId<"uuid">. The agent passes back whatever refs it got.

ID chaining

refs use the EXACT key the consuming tool accepts as input (ADR-009) so refs.blueprint feeds the next tool's blueprint param verbatim; the <entity>Id name is an alias.

When designing a new tool, look at the call site flow:

1. What does the agent know before calling this? (those are inputs)
2. What does the agent need next? (those become refs + nextSteps)

Tool descriptions

The description string is what the agent reads when deciding to call the tool. Write for the agent:

• ✅ "Compile a Blueprint and return any errors. Call after mutations that change the graph or class layout."
• ❌ "Compiles BP" (too terse)
• ❌ "This tool will compile a Blueprint asset using FKismetEditorUtilities::CompileBlueprint via SEH-wrapped C++ handler returning errors as structured payload" (implementation noise, wastes tokens)

Keep under 200 chars for simple tools. Use multi-line structured descriptions for complex tools with multiple modes (dryRun, etc.).

Tests are mandatory

Every new tool gets an integration test at Tools/test/tools/<tool-name>.test.ts. Use the bootstrap from Tools/test/bootstrap.ts which spawns a temp UE project + commandlet. Patterns at Tools/test/helpers.ts.

Test cases required:

• Happy path with valid inputs.
• Each errorCode branch reachable from input validation or domain failure.
• Idempotency where applicable (calling twice yields same result).
• Cleanup — tests must not leak assets to the temp project's persistent state.