Tool Authoring

Add, modify, or remove a tool end to end.

A tool change usually touches more than one file. Keep the implementation, manifest metadata, structured output schema, fixtures, and generated docs aligned in the same change.

If you are new to the architecture, this page leans on a few terms that are defined in full in Core terms. The short version: a tool is one user-visible action exposed through MCP and CLI; the handler is the function that performs the work and writes its outcome onto the call context; the manifest is the YAML file that declares the tool's metadata (names, schema reference, exposure rules) without containing the implementation; fragments are progress events the handler emits while running; the structured output is the canonical JSON result the handler sets at the end of the call.

Mental model#

The final structured result is the canonical output. Rendered text is derived from that result, fragments, and runtime-specific rendering rules. See Tool Lifecycle for the runtime model and Output Formats for the response shape.

Adding a new tool#

1. Pick streaming or non-streaming#

Use the simpler non-streaming path unless the user needs live progress. Do not add a streaming path for a short query just because another tool uses one.

2. Create the implementation#

Create the implementation under src/mcp/tools/<workflow>/<tool>.ts. A normal tool exports a Zod schema shape and a handler created with createTypedTool(...).

Minimal non-streaming shape:

import * as z from 'zod';
import type { NonStreamingExecutor } from '../../../types/tool-execution.ts';
import type { CommandExecutor } from '../../../utils/execution/index.ts';
import { getDefaultCommandExecutor } from '../../../utils/execution/index.ts';
import { createTypedTool, getHandlerContext } from '../../../utils/typed-tool-factory.ts';

const listWidgetsSchema = z.object({
  enabled: z.boolean().optional(),
});

type ListWidgetsParams = z.infer<typeof listWidgetsSchema>;
type WidgetListResult = {
  kind: 'widget-list';
  didError: boolean;
  error: string | null;
  widgets: Array<{ name: string }>;
};

export function createListWidgetsExecutor(
  executor: CommandExecutor,
): NonStreamingExecutor<ListWidgetsParams, WidgetListResult> {
  return async () => {
    const response = await executor(['xcrun', 'widgetctl', 'list', '--json'], 'List Widgets', false);

    if (!response.success) {
      return { kind: 'widget-list', didError: true, error: response.error ?? 'List failed', widgets: [] };
    }

    return { kind: 'widget-list', didError: false, error: null, widgets: JSON.parse(response.output) };
  };
}

export async function list_widgetsLogic(
  params: ListWidgetsParams,
  executor: CommandExecutor,
): Promise<void> {
  const ctx = getHandlerContext();
  const result = await createListWidgetsExecutor(executor)(params);

  ctx.structuredOutput = {
    result,
    schema: 'xcodebuildmcp.output.widget-list',
    schemaVersion: '1',
  };
}

export const schema = listWidgetsSchema.shape;
export const handler = createTypedTool(listWidgetsSchema, list_widgetsLogic, getDefaultCommandExecutor);

For session-default-aware tools, follow the existing createSessionAwareTool(...) pattern used by build and test tools. The public schema can hide parameters that session defaults provide, while the internal schema still validates the fully merged argument set.

3. Define or reuse the domain result#

Prefer an existing domain result when it fits. Common schema IDs include:

Create a new schema only when no existing schema accurately describes the payload. The schema validates the full structured response, not only the data object. Published schema versions use integer strings such as "1" and "2".

4. Create the tool manifest#

Create manifests/tools/<tool_id>.yaml. The id must match the filename without .yaml, and module points to the implementation path under src/ without an extension.

id: list_widgets
module: mcp/tools/simulator/list_widgets
names:
  mcp: list_widgets
  cli: list-widgets
description: List available widgets.
availability:
  mcp: true
  cli: true
annotations:
  title: List Widgets
  readOnlyHint: true
  destructiveHint: false
  openWorldHint: false
outputSchema:
  schema: xcodebuildmcp.output.widget-list
  version: "1"

5. Register the tool in a workflow#

Add the tool ID to one or more workflow manifests:

id: simulator
tools:
  - list_sims
  - list_widgets

A tool can appear in multiple workflows, but it should have one tool manifest. Workflow selection and predicates decide which runtimes expose it.

6. Validate docs and schemas#

If you add, remove, or change tool metadata, run:

npm run docs:check

If the tool produces structured output, also run:

npm run test:schema-fixtures
npx vitest run src/core/__tests__/structured-output-schema.test.ts

7. Add fixtures#

Add or update representative fixtures under:

Regenerate snapshots only after you understand the behavior change:

npm run test:snapshots:update 2>&1 | tee /tmp/snapshot-update.txt

Streaming tools#

A streaming tool emits live progress fragments while it runs, then sets one canonical ctx.structuredOutput at the end. The mechanism is ctx.emit(fragment), where fragment is one of the kinds in the closed AnyFragment union defined in src/types/domain-fragments.ts:

ctx.emit is typed against this union. If your tool needs a streaming shape that does not fit any existing fragment, you have to add it: define the new fragment interfaces in src/types/domain-fragments.ts, extend AnyFragment, and update the renderer to format the new shape. That is a real architectural change, not a per-tool concern. Reach for it only after confirming an existing fragment family does not fit.

Three patterns cover every streaming tool currently in the codebase. Pick the one that matches what your tool is doing.

Pattern 1: Raw subprocess transcript (CLI raw mode only)#

When the value of a streaming tool is replaying a subprocess's stdout/stderr in real time (for example, simctl log stream) and nothing more, the standard executor (getDefaultCommandExecutor()) emits TranscriptFragment events automatically via async-local storage. The handler does not call ctx.emit itself. Structurally it looks identical to a non-streaming handler:

import * as z from 'zod';
import type { CommandExecutor } from '../../../utils/execution/index.ts';
import { getDefaultCommandExecutor } from '../../../utils/execution/index.ts';
import { createTypedTool, getHandlerContext } from '../../../utils/typed-tool-factory.ts';

const watchLogsSchema = z.object({
  simulatorId: z.string(),
});

type WatchLogsParams = z.infer<typeof watchLogsSchema>;
type WatchLogsResult = {
  kind: 'log-stream';
  didError: boolean;
  error: string | null;
  exitCode: number | null;
};

export async function watch_logsLogic(
  params: WatchLogsParams,
  executor: CommandExecutor,
): Promise<void> {
  const ctx = getHandlerContext();
  const response = await executor(
    ['xcrun', 'simctl', 'spawn', params.simulatorId, 'log', 'stream'],
    'Watch Simulator Logs',
    false,
  );

  ctx.structuredOutput = {
    result: {
      kind: 'log-stream',
      didError: !response.success,
      error: response.error ?? null,
      exitCode: response.exitCode ?? null,
    },
    schema: 'xcodebuildmcp.output.log-stream',
    schemaVersion: '1',
  };
}

export const schema = watchLogsSchema.shape;
export const handler = createTypedTool(watchLogsSchema, watch_logsLogic, getDefaultCommandExecutor);

The catch: the transcript-emitter context is only registered by CLI --output raw mode (src/cli/register-tool-commands.ts). In CLI text, JSON, JSONL, and MCP modes, the executor's transcript emissions are silently dropped. Use this pattern when raw subprocess replay in raw mode is genuinely all the tool needs to do — typically debugging-oriented tools.

Pattern 2: Typed domain fragments#

When the user benefits from structured progress events that work across all output modes — phase markers, warnings, test failures — the handler emits existing fragment shapes directly through ctx.emit:

ctx.emit({
  kind: 'test-result',
  fragment: 'test-failure',
  operation: 'TEST',
  test: 'MyAppTests.testLoginFlow',
  message: 'Expected status 200, got 401',
  durationMs: 1240,
});

Each kind has a fixed set of fragment discriminators in src/types/domain-fragments.ts. The render layer already knows how to format each shape for MCP text, CLI text, and JSONL.

Streaming output from a still-running subprocess is a separate concern: the standard executor() awaits the subprocess to completion before returning, so it does not expose live output to the handler. To read stdout/stderr line-by-line as it arrives, use getDefaultInteractiveSpawner() from src/utils/execution/. The spawner returns an InteractiveProcess whose process.stdout / process.stderr streams the handler can attach to and emit fragments from as output is parsed.

Pattern 3: The xcodebuild pipeline (build, build-run, and test tools only)#

Tools that wrap xcrun xcodebuild — build_sim, build_device, build_macos, the build_run_* family, test_sim, test_device, test_macos, and the Swift Package equivalents — go through a shared pipeline in src/utils/xcodebuild-pipeline.ts. The pipeline spawns xcodebuild, parses its stdout into typed BuildStageFragment, CompilerDiagnosticFragment, and BuildSummaryFragment events, captures the full build log to disk, and aggregates the run into a canonical domain result. Each tool plugs into it through five helpers:

export async function build_widgetLogic(
  params: BuildWidgetParams,
  executor: CommandExecutor,
): Promise<void> {
  const ctx = getHandlerContext();
  const prepared = await prepareBuildWidgetExecution(params, executor);

  ctx.emit(createBuildInvocationFragment('build-result', 'BUILD', prepared.invocationRequest));

  const executionContext = createStreamingExecutionContext(ctx);
  const executeBuildWidget = createBuildWidgetExecutor(executor, prepared);
  const result = await executeBuildWidget(params, executionContext);

  setXcodebuildStructuredOutput(ctx, 'build-result', result);
}

Build-like results must include request in the final result. Do not rely on the streamed invocation fragment for final rendering, --output json, or MCP structuredContent.

Working reference: src/mcp/tools/simulator/build_sim.ts.

Use this pipeline only when the tool wraps xcodebuild. For any other long-running subprocess tool, use Pattern 1 or Pattern 2.

Modifying a tool#

Deleting a tool#

Use a deletion checklist. Tool removal affects user-visible surfaces.

1. Remove the tool ID from every workflow manifest.
2. Delete manifests/tools/<tool>.yaml.
3. Delete the implementation file if no other code imports it.
4. Delete tests that only cover that tool.
5. Delete MCP, CLI, and JSON fixtures for that tool.
6. Run npm run docs:check.
7. Run npm run typecheck, npm test, and npm run test:schema-fixtures.

Do not delete a shared schema just because one tool stopped using it. Schemas are published contracts. Remove one only when it is unpublished or clearly unused after checking consumers.

Common mistakes#

• Adding an implementation without a matching tool manifest.
• Adding a tool manifest without adding the tool ID to a workflow manifest.
• Setting ctx.structuredOutput without manifest outputSchema metadata.
• Emitting fragments from a non-streaming tool.
• Using createStreamingExecutionContext(...) in a non-streaming tool.
• Relying on streamed fragments for final JSON data.
• Changing JSON payload shape without updating schemas and JSON fixtures.
• Updating snapshots before understanding why they changed.
• Preserving legacy fallback behavior instead of making the requested path canonical.

Related#

• Tool Lifecycle, streaming, fragments, results, and rendering
• Output Formats, CLI JSON and MCP structuredContent responses
• Testing, unit, snapshot, schema, and pre-commit rules
• Tools Reference, generated catalog of exposed tools