rnxsim 0.1.365 → 0.1.366

package/src/mcp.ts

@@ -0,0 +1,791 @@
+import type { LogFilterOptions, LogLevel } from '../cli/commands/inspect/core'
+import type { PerformOptions, ResetOptions, SimStateOptions } from './bridge-contract'
+import type { SimClient, SimPerformStep, SimScreenshotOptions } from './sim-client'
+
+export type PerSimMcpToolName = 'state' | 'perform' | 'reset' | 'screenshot' | 'logs'
+
+export interface McpJsonSchema {
+  type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean'
+  description?: string
+  properties?: Readonly<Record<string, McpJsonSchema>>
+  required?: readonly string[]
+  additionalProperties?: boolean
+  items?: McpJsonSchema
+  oneOf?: readonly McpJsonSchema[]
+  enum?: readonly (string | number | boolean)[]
+  const?: string | number | boolean
+  minimum?: number
+  maximum?: number
+  minLength?: number
+  minItems?: number
+  maxItems?: number
+  uniqueItems?: boolean
+  default?: string | number | boolean
+}
+
+export interface PerSimMcpToolDefinition {
+  name: PerSimMcpToolName
+  description: string
+  inputSchema: McpJsonSchema
+}
+
+export interface PerSimMcpTextContent {
+  type: 'text'
+  text: string
+}
+
+export interface PerSimMcpToolResult {
+  content: PerSimMcpTextContent[]
+}
+
+export interface PerSimMcpTool extends PerSimMcpToolDefinition {
+  execute(input: unknown): Promise<PerSimMcpToolResult>
+}
+
+export interface PerSimMcpServerAdapter {
+  registerTool(tool: PerSimMcpTool): void
+}
+
+export class McpToolInputError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'McpToolInputError'
+  }
+}
+
+function strictObject(
+  properties: Readonly<Record<string, McpJsonSchema>>,
+  required: readonly string[] = [],
+): McpJsonSchema {
+  return {
+    type: 'object',
+    properties,
+    required,
+    additionalProperties: false,
+  }
+}
+
+function stepSchema(
+  type: SimPerformStep['type'],
+  properties: Readonly<Record<string, McpJsonSchema>> = {},
+  required: readonly string[] = [],
+): McpJsonSchema {
+  return strictObject(
+    {
+      type: { type: 'string', const: type },
+      ...properties,
+    },
+    ['type', ...required],
+  )
+}
+
+const coordinateSchema: McpJsonSchema = { type: 'number' }
+const pointerIdSchema: McpJsonSchema = { type: 'integer', minimum: 0 }
+const millisecondsSchema: McpJsonSchema = { type: 'integer', minimum: 0 }
+const nonEmptyStringSchema: McpJsonSchema = { type: 'string', minLength: 1 }
+
+const performStepSchema: McpJsonSchema = {
+  oneOf: [
+    stepSchema(
+      'touchDown',
+      { x: coordinateSchema, y: coordinateSchema, pointerId: pointerIdSchema },
+      ['x', 'y'],
+    ),
+    stepSchema(
+      'touchMove',
+      { x: coordinateSchema, y: coordinateSchema, pointerId: pointerIdSchema },
+      ['x', 'y'],
+    ),
+    stepSchema(
+      'touchUp',
+      { x: coordinateSchema, y: coordinateSchema, pointerId: pointerIdSchema },
+      ['x', 'y'],
+    ),
+    stepSchema('touchCancel', { pointerId: pointerIdSchema }),
+    stepSchema('tap', { x: coordinateSchema, y: coordinateSchema }, ['x', 'y']),
+    stepSchema('tapId', { id: nonEmptyStringSchema }, ['id']),
+    stepSchema('tapText', { text: nonEmptyStringSchema }, ['text']),
+    stepSchema(
+      'doubleTap',
+      { x: coordinateSchema, y: coordinateSchema, gapMs: millisecondsSchema },
+      ['x', 'y'],
+    ),
+    stepSchema(
+      'longPress',
+      {
+        x: coordinateSchema,
+        y: coordinateSchema,
+        durationMs: millisecondsSchema,
+      },
+      ['x', 'y'],
+    ),
+    stepSchema(
+      'drag',
+      {
+        fromX: coordinateSchema,
+        fromY: coordinateSchema,
+        toX: coordinateSchema,
+        toY: coordinateSchema,
+        steps: { type: 'integer', minimum: 1 },
+        stepMs: millisecondsSchema,
+      },
+      ['fromX', 'fromY', 'toX', 'toY'],
+    ),
+    stepSchema(
+      'pinch',
+      {
+        fromX1: coordinateSchema,
+        fromY1: coordinateSchema,
+        fromX2: coordinateSchema,
+        fromY2: coordinateSchema,
+        toX1: coordinateSchema,
+        toY1: coordinateSchema,
+        toX2: coordinateSchema,
+        toY2: coordinateSchema,
+        steps: { type: 'integer', minimum: 1 },
+        stepMs: millisecondsSchema,
+      },
+      ['fromX1', 'fromY1', 'fromX2', 'fromY2', 'toX1', 'toY1', 'toX2', 'toY2'],
+    ),
+    stepSchema(
+      'scroll',
+      {
+        id: nonEmptyStringSchema,
+        x: coordinateSchema,
+        y: coordinateSchema,
+        animated: { type: 'boolean' },
+      },
+      ['id'],
+    ),
+    stepSchema('type', { text: { type: 'string' } }, ['text']),
+    stepSchema('key', { key: nonEmptyStringSchema }, ['key']),
+    stepSchema('dismissKeyboard'),
+    stepSchema('wait', { ms: millisecondsSchema }, ['ms']),
+    stepSchema(
+      'waitFor',
+      { testID: nonEmptyStringSchema, timeoutMs: millisecondsSchema },
+      ['testID'],
+    ),
+    stepSchema('waitFor', { id: nonEmptyStringSchema, timeoutMs: millisecondsSchema }, [
+      'id',
+    ]),
+  ],
+}
+
+export const PER_SIM_MCP_TOOL_DEFINITIONS: Readonly<
+  Record<PerSimMcpToolName, PerSimMcpToolDefinition>
+> = {
+  state: {
+    name: 'state',
+    description:
+      'Capture the current app screenshot and UI tree in one call, with optional route, error, depth, and layer controls.',
+    inputSchema: strictObject({
+      screenshot: {
+        type: 'boolean',
+        default: true,
+        description: 'include the composed PNG screenshot',
+      },
+      tree: {
+        type: 'boolean',
+        default: true,
+        description: 'include the current UI tree',
+      },
+      route: { type: 'boolean', description: 'include route and navigation state' },
+      errors: { type: 'boolean', description: 'include recent runtime errors' },
+      depth: { type: 'integer', minimum: 0, description: 'maximum tree depth' },
+      layers: {
+        type: 'string',
+        enum: ['full', 'tenant', 'shell'],
+        description: 'screenshot layers to compose',
+      },
+      errorLimit: {
+        type: 'integer',
+        minimum: 0,
+        description: 'maximum recent error entries',
+      },
+    }),
+  },
+  perform: {
+    name: 'perform',
+    description:
+      'Execute an ordered interaction batch inside the current app so gesture timing does not depend on MCP round trips.',
+    inputSchema: strictObject(
+      {
+        steps: { type: 'array', items: performStepSchema, minItems: 1 },
+        stopOnError: {
+          type: 'boolean',
+          description: 'stop before starting the next step after a failure',
+        },
+        timeoutMs: {
+          type: 'integer',
+          minimum: 1,
+          description: 'batch progress deadline checked between steps',
+        },
+      },
+      ['steps'],
+    ),
+  },
+  reset: {
+    name: 'reset',
+    description:
+      'Clear data or full simulated install state for the current app and optionally relaunch it.',
+    inputSchema: strictObject({
+      strategy: {
+        type: 'string',
+        enum: ['data', 'full'],
+        default: 'data',
+        description: 'data clears app storage; full also clears install-scoped state',
+      },
+      relaunch: {
+        type: 'boolean',
+        default: true,
+        description: 'relaunch the app after clearing state',
+      },
+    }),
+  },
+  screenshot: {
+    name: 'screenshot',
+    description: 'Capture a PNG screenshot of the current app.',
+    inputSchema: strictObject({
+      layers: {
+        type: 'string',
+        enum: ['full', 'tenant', 'shell'],
+        description: 'screenshot layers to compose',
+      },
+      crop: strictObject(
+        {
+          x: coordinateSchema,
+          y: coordinateSchema,
+          w: { type: 'number', minimum: 0 },
+          h: { type: 'number', minimum: 0 },
+        },
+        ['x', 'y', 'w', 'h'],
+      ),
+    }),
+  },
+  logs: {
+    name: 'logs',
+    description:
+      'Read filtered app console logs and the recent merged runtime error buffer from the current app.',
+    inputSchema: strictObject({
+      limit: {
+        type: 'integer',
+        minimum: 1,
+        default: 50,
+        description: 'maximum filtered log entries',
+      },
+      levels: {
+        type: 'array',
+        items: { type: 'string', enum: ['log', 'info', 'warn', 'error', 'debug'] },
+        minItems: 1,
+        uniqueItems: true,
+        description: 'console levels to include',
+      },
+      filter: {
+        type: 'string',
+        minLength: 1,
+        description: 'case-insensitive message substring',
+      },
+      includeInternal: {
+        type: 'boolean',
+        default: false,
+        description: 'include RNX engine-internal log entries',
+      },
+      errorLimit: {
+        type: 'integer',
+        minimum: 1,
+        default: 20,
+        description: 'maximum merged runtime error entries',
+      },
+    }),
+  },
+}
+
+const PER_SIM_MCP_TOOL_ORDER: readonly PerSimMcpToolName[] = [
+  'state',
+  'perform',
+  'reset',
+  'screenshot',
+  'logs',
+]
+
+function validationFailure(path: string, expectation: string): never {
+  throw new McpToolInputError(`${path} ${expectation}`)
+}
+
+function validateMcpInput(value: unknown, schema: McpJsonSchema, path: string): void {
+  if (schema.oneOf) {
+    let matches = 0
+    for (const candidate of schema.oneOf) {
+      try {
+        validateMcpInput(value, candidate, path)
+        matches++
+      } catch (error) {
+        if (!(error instanceof McpToolInputError)) throw error
+      }
+    }
+    if (matches !== 1) validationFailure(path, 'must match exactly one allowed shape')
+    return
+  }
+
+  if (schema.const !== undefined && value !== schema.const) {
+    validationFailure(path, `must equal ${JSON.stringify(schema.const)}`)
+  }
+  if (schema.enum && !schema.enum.some((candidate) => candidate === value)) {
+    validationFailure(path, `must be one of ${schema.enum.join(', ')}`)
+  }
+
+  if (schema.type === 'object') {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      validationFailure(path, 'must be an object')
+    }
+    const properties = schema.properties ?? {}
+    for (const required of schema.required ?? []) {
+      if (!Object.prototype.hasOwnProperty.call(value, required)) {
+        validationFailure(`${path}.${required}`, 'is required')
+      }
+    }
+    for (const [key, child] of Object.entries(value)) {
+      const propertySchema = properties[key]
+      if (!propertySchema) {
+        if (schema.additionalProperties === false) {
+          validationFailure(`${path}.${key}`, 'is not allowed')
+        }
+        continue
+      }
+      validateMcpInput(child, propertySchema, `${path}.${key}`)
+    }
+    return
+  }
+
+  if (schema.type === 'array') {
+    if (!Array.isArray(value)) validationFailure(path, 'must be an array')
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      validationFailure(path, `must contain at least ${schema.minItems} item(s)`)
+    }
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+      validationFailure(path, `must contain at most ${schema.maxItems} item(s)`)
+    }
+    if (
+      schema.uniqueItems &&
+      new Set(value.map((entry) => JSON.stringify(entry))).size !== value.length
+    ) {
+      validationFailure(path, 'must contain unique items')
+    }
+    const itemSchema = schema.items
+    if (itemSchema) {
+      value.forEach((entry, index) =>
+        validateMcpInput(entry, itemSchema, `${path}[${index}]`),
+      )
+    }
+    return
+  }
+
+  if (schema.type === 'string') {
+    if (typeof value !== 'string') validationFailure(path, 'must be a string')
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      validationFailure(path, `must contain at least ${schema.minLength} character(s)`)
+    }
+    return
+  }
+
+  if (schema.type === 'number' || schema.type === 'integer') {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+      validationFailure(path, 'must be a finite number')
+    }
+    if (schema.type === 'integer' && !Number.isInteger(value)) {
+      validationFailure(path, 'must be an integer')
+    }
+    if (schema.minimum !== undefined && value < schema.minimum) {
+      validationFailure(path, `must be at least ${schema.minimum}`)
+    }
+    if (schema.maximum !== undefined && value > schema.maximum) {
+      validationFailure(path, `must be at most ${schema.maximum}`)
+    }
+    return
+  }
+
+  if (schema.type === 'boolean' && typeof value !== 'boolean') {
+    validationFailure(path, 'must be a boolean')
+  }
+}
+
+function isRecordValue(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function recordValue(value: unknown, path: string): Record<string, unknown> {
+  if (!isRecordValue(value)) {
+    validationFailure(path, 'must be an object')
+  }
+  return value
+}
+
+function stringValue(value: unknown, path: string): string {
+  if (typeof value !== 'string') validationFailure(path, 'must be a string')
+  return value
+}
+
+function numberValue(value: unknown, path: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    validationFailure(path, 'must be a finite number')
+  }
+  return value
+}
+
+function booleanValue(value: unknown, path: string): boolean {
+  if (typeof value !== 'boolean') validationFailure(path, 'must be a boolean')
+  return value
+}
+
+function optionalNumber(
+  record: Record<string, unknown>,
+  key: string,
+  path: string,
+): number | undefined {
+  return record[key] === undefined
+    ? undefined
+    : numberValue(record[key], `${path}.${key}`)
+}
+
+function optionalBoolean(
+  record: Record<string, unknown>,
+  key: string,
+  path: string,
+): boolean | undefined {
+  return record[key] === undefined
+    ? undefined
+    : booleanValue(record[key], `${path}.${key}`)
+}
+
+// the parsers below are the single owner of "untrusted JSON -> bridge-contract
+// argument". a transport in front of these tools (the RNX Cloud sim service's
+// HTTP and WebSocket routes) validates its own request bodies with them rather
+// than growing a second reader for the same shapes.
+export function parsePerformStep(value: unknown, index: number): SimPerformStep {
+  const path = `perform.steps[${index}]`
+  const step = recordValue(value, path)
+  const type = stringValue(step.type, `${path}.type`)
+  switch (type) {
+    case 'touchDown':
+    case 'touchMove':
+    case 'touchUp': {
+      const pointerId = optionalNumber(step, 'pointerId', path)
+      return {
+        type,
+        x: numberValue(step.x, `${path}.x`),
+        y: numberValue(step.y, `${path}.y`),
+        ...(pointerId === undefined ? {} : { pointerId }),
+      }
+    }
+    case 'touchCancel': {
+      const pointerId = optionalNumber(step, 'pointerId', path)
+      return { type, ...(pointerId === undefined ? {} : { pointerId }) }
+    }
+    case 'tap':
+      return {
+        type,
+        x: numberValue(step.x, `${path}.x`),
+        y: numberValue(step.y, `${path}.y`),
+      }
+    case 'tapId':
+      return { type, id: stringValue(step.id, `${path}.id`) }
+    case 'tapText':
+      return { type, text: stringValue(step.text, `${path}.text`) }
+    case 'doubleTap': {
+      const gapMs = optionalNumber(step, 'gapMs', path)
+      return {
+        type,
+        x: numberValue(step.x, `${path}.x`),
+        y: numberValue(step.y, `${path}.y`),
+        ...(gapMs === undefined ? {} : { gapMs }),
+      }
+    }
+    case 'longPress': {
+      const durationMs = optionalNumber(step, 'durationMs', path)
+      return {
+        type,
+        x: numberValue(step.x, `${path}.x`),
+        y: numberValue(step.y, `${path}.y`),
+        ...(durationMs === undefined ? {} : { durationMs }),
+      }
+    }
+    case 'drag': {
+      const steps = optionalNumber(step, 'steps', path)
+      const stepMs = optionalNumber(step, 'stepMs', path)
+      return {
+        type,
+        fromX: numberValue(step.fromX, `${path}.fromX`),
+        fromY: numberValue(step.fromY, `${path}.fromY`),
+        toX: numberValue(step.toX, `${path}.toX`),
+        toY: numberValue(step.toY, `${path}.toY`),
+        ...(steps === undefined ? {} : { steps }),
+        ...(stepMs === undefined ? {} : { stepMs }),
+      }
+    }
+    case 'pinch': {
+      const steps = optionalNumber(step, 'steps', path)
+      const stepMs = optionalNumber(step, 'stepMs', path)
+      return {
+        type,
+        fromX1: numberValue(step.fromX1, `${path}.fromX1`),
+        fromY1: numberValue(step.fromY1, `${path}.fromY1`),
+        fromX2: numberValue(step.fromX2, `${path}.fromX2`),
+        fromY2: numberValue(step.fromY2, `${path}.fromY2`),
+        toX1: numberValue(step.toX1, `${path}.toX1`),
+        toY1: numberValue(step.toY1, `${path}.toY1`),
+        toX2: numberValue(step.toX2, `${path}.toX2`),
+        toY2: numberValue(step.toY2, `${path}.toY2`),
+        ...(steps === undefined ? {} : { steps }),
+        ...(stepMs === undefined ? {} : { stepMs }),
+      }
+    }
+    case 'scroll': {
+      const x = optionalNumber(step, 'x', path)
+      const y = optionalNumber(step, 'y', path)
+      const animated = optionalBoolean(step, 'animated', path)
+      return {
+        type,
+        id: stringValue(step.id, `${path}.id`),
+        ...(x === undefined ? {} : { x }),
+        ...(y === undefined ? {} : { y }),
+        ...(animated === undefined ? {} : { animated }),
+      }
+    }
+    case 'type':
+      return { type, text: stringValue(step.text, `${path}.text`) }
+    case 'key':
+      return { type, key: stringValue(step.key, `${path}.key`) }
+    case 'dismissKeyboard':
+      return { type }
+    case 'wait':
+      return { type, ms: numberValue(step.ms, `${path}.ms`) }
+    case 'waitFor': {
+      const timeoutMs = optionalNumber(step, 'timeoutMs', path)
+      const selector =
+        step.testID === undefined
+          ? { id: stringValue(step.id, `${path}.id`) }
+          : { testID: stringValue(step.testID, `${path}.testID`) }
+      return {
+        type,
+        ...selector,
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+      }
+    }
+    default:
+      return validationFailure(`${path}.type`, 'is not a supported perform step')
+  }
+}
+
+export function parseStateOptions(value: unknown): SimStateOptions {
+  const input = recordValue(value, 'state')
+  const route = optionalBoolean(input, 'route', 'state')
+  const errors = optionalBoolean(input, 'errors', 'state')
+  const depth = optionalNumber(input, 'depth', 'state')
+  const errorLimit = optionalNumber(input, 'errorLimit', 'state')
+  const layers =
+    input.layers === undefined ? undefined : stringValue(input.layers, 'state.layers')
+  if (
+    layers !== undefined &&
+    layers !== 'full' &&
+    layers !== 'tenant' &&
+    layers !== 'shell'
+  ) {
+    return validationFailure('state.layers', 'must be full, tenant, or shell')
+  }
+  return {
+    screenshot: optionalBoolean(input, 'screenshot', 'state') ?? true,
+    tree: optionalBoolean(input, 'tree', 'state') ?? true,
+    ...(route === undefined ? {} : { route }),
+    ...(errors === undefined ? {} : { errors }),
+    ...(depth === undefined ? {} : { depth }),
+    ...(layers === undefined ? {} : { layers }),
+    ...(errorLimit === undefined ? {} : { errorLimit }),
+  }
+}
+
+interface ParsedPerformInput {
+  steps: SimPerformStep[]
+  options?: PerformOptions
+}
+
+function parsePerformInput(value: unknown): ParsedPerformInput {
+  const input = recordValue(value, 'perform')
+  if (!Array.isArray(input.steps)) validationFailure('perform.steps', 'must be an array')
+  const stopOnError = optionalBoolean(input, 'stopOnError', 'perform')
+  const timeoutMs = optionalNumber(input, 'timeoutMs', 'perform')
+  const hasOptions = stopOnError !== undefined || timeoutMs !== undefined
+  return {
+    steps: input.steps.map(parsePerformStep),
+    ...(hasOptions
+      ? {
+          options: {
+            ...(stopOnError === undefined ? {} : { stopOnError }),
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+          },
+        }
+      : {}),
+  }
+}
+
+function parseLogLevel(value: unknown, path: string): LogLevel {
+  const level = stringValue(value, path)
+  if (
+    level !== 'log' &&
+    level !== 'info' &&
+    level !== 'warn' &&
+    level !== 'error' &&
+    level !== 'debug'
+  ) {
+    return validationFailure(path, 'must be log, info, warn, error, or debug')
+  }
+  return level
+}
+
+interface ParsedLogsInput {
+  filterOptions: LogFilterOptions
+  limit: number
+  errorLimit: number
+}
+
+function parseLogsInput(value: unknown): ParsedLogsInput {
+  const input = recordValue(value, 'logs')
+  const levels = input.levels
+  if (levels !== undefined && !Array.isArray(levels)) {
+    validationFailure('logs.levels', 'must be an array')
+  }
+  const levelSet = levels
+    ? new Set(levels.map((level, index) => parseLogLevel(level, `logs.levels[${index}]`)))
+    : null
+  const filter =
+    input.filter === undefined ? null : stringValue(input.filter, 'logs.filter')
+  return {
+    filterOptions: {
+      level: levelSet,
+      filter,
+      showInternal: optionalBoolean(input, 'includeInternal', 'logs') ?? false,
+    },
+    limit: optionalNumber(input, 'limit', 'logs') ?? 50,
+    errorLimit: optionalNumber(input, 'errorLimit', 'logs') ?? 20,
+  }
+}
+
+export function parseResetOptions(value: unknown): ResetOptions {
+  const input = recordValue(value, 'reset')
+  const strategy =
+    input.strategy === undefined ? 'data' : stringValue(input.strategy, 'reset.strategy')
+  if (strategy !== 'data' && strategy !== 'full') {
+    return validationFailure('reset.strategy', 'must be data or full')
+  }
+  return {
+    strategy,
+    relaunch: optionalBoolean(input, 'relaunch', 'reset') ?? true,
+  }
+}
+
+export function parseScreenshotOptions(value: unknown): SimScreenshotOptions {
+  const input = recordValue(value, 'screenshot')
+  const layers =
+    input.layers === undefined
+      ? undefined
+      : stringValue(input.layers, 'screenshot.layers')
+  if (
+    layers !== undefined &&
+    layers !== 'full' &&
+    layers !== 'tenant' &&
+    layers !== 'shell'
+  ) {
+    return validationFailure('screenshot.layers', 'must be full, tenant, or shell')
+  }
+  const crop =
+    input.crop === undefined ? undefined : recordValue(input.crop, 'screenshot.crop')
+  return {
+    ...(layers === undefined ? {} : { layers }),
+    ...(crop === undefined
+      ? {}
+      : {
+          crop: {
+            x: numberValue(crop.x, 'screenshot.crop.x'),
+            y: numberValue(crop.y, 'screenshot.crop.y'),
+            w: numberValue(crop.w, 'screenshot.crop.w'),
+            h: numberValue(crop.h, 'screenshot.crop.h'),
+          },
+        }),
+  }
+}
+
+function stableJsonValue(value: unknown): unknown {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+    return value
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value))
+      throw new Error('MCP result contains a non-finite number')
+    return value
+  }
+  if (Array.isArray(value)) return value.map(stableJsonValue)
+  if (typeof value === 'object') {
+    const sorted: Record<string, unknown> = {}
+    for (const key of Object.keys(value).sort()) {
+      sorted[key] = stableJsonValue(Reflect.get(value, key))
+    }
+    return sorted
+  }
+  throw new Error(`MCP result contains unsupported ${typeof value} value`)
+}
+
+function textResult(value: unknown): PerSimMcpToolResult {
+  const text = JSON.stringify(stableJsonValue(value))
+  if (text === undefined) throw new Error('MCP result did not serialize to JSON')
+  return { content: [{ type: 'text', text }] }
+}
+
+type PerSimMcpHandler = (input: unknown) => Promise<unknown>
+
+function createPerSimMcpHandlers(
+  sim: SimClient,
+): Record<PerSimMcpToolName, PerSimMcpHandler> {
+  return {
+    state: async (input) => sim.state(parseStateOptions(input)),
+    perform: async (input) => {
+      const parsed = parsePerformInput(input)
+      return sim.perform(parsed.steps, parsed.options)
+    },
+    reset: async (input) => sim.reset(parseResetOptions(input)),
+    screenshot: async (input) => {
+      const result = await sim.screenshot(parseScreenshotOptions(input))
+      return { dataUrl: result.dataUrl }
+    },
+    logs: async (input) => {
+      const parsed = parseLogsInput(input)
+      const [logs, recentErrors] = await Promise.all([
+        sim.logs(parsed.filterOptions),
+        sim.errors(parsed.errorLimit),
+      ])
+      return { logs: logs.slice(-parsed.limit), recentErrors }
+    },
+  }
+}
+
+export function createPerSimMcpTools(sim: SimClient): PerSimMcpTool[] {
+  const handlers = createPerSimMcpHandlers(sim)
+  return PER_SIM_MCP_TOOL_ORDER.map((name) => {
+    const definition = PER_SIM_MCP_TOOL_DEFINITIONS[name]
+    return {
+      ...definition,
+      async execute(input: unknown): Promise<PerSimMcpToolResult> {
+        validateMcpInput(input, definition.inputSchema, name)
+        return textResult(await handlers[name](input))
+      },
+    }
+  })
+}
+
+export function registerPerSimMcpTools(
+  server: PerSimMcpServerAdapter,
+  sim: SimClient,
+): PerSimMcpTool[] {
+  const tools = createPerSimMcpTools(sim)
+  for (const tool of tools) server.registerTool(tool)
+  return tools
+}