Skip to main content
Glama
conorluddy

XC-MCP: XCode CLI wrapper

by conorluddy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Record Test Step

test-record-step

Record a named step in a test session by capturing a screenshot and accessibility tree snapshot, saving them with metadata to a persistent session directory for structured testing evidence.

Instructions

test-record-step

Record a single named step in a test session, capturing a screenshot and accessibility tree snapshot.

What it does

Maintains a persistent session directory under ~/.xc-mcp/test-recordings/<sessionName>/ (override root with env var XC_MCP_RECORDINGS_DIR). Each call:

  1. Creates the session directory + steps.json on first call

  2. Captures a screenshot via xcrun simctl io <udid|booted> screenshot

  3. Captures an accessibility tree via idb ui describe-all (tolerates idb absence)

  4. Appends a step record to steps.json with sequential index (001, 002, …)

Session layout:

~/.xc-mcp/test-recordings/<sessionName>/
  steps.json          – session metadata + all step records
  screenshots/        – NNN-<label>.png per step
  accessibility/      – NNN-<label>.json per step (idb NDJSON or error stub)
  report.md           – generated by test-record-report

Parameters

  • sessionName (string, required): Unique session identifier (used as directory name)

  • label (string, required): Human-readable description of this step

  • udid (string, optional): Simulator UDID — defaults to booted

  • metadata (object, optional): Arbitrary key-value pairs attached to step record

  • assertion (string, optional): Assertion description recorded with step

Returns

JSON with { sessionName, stepIndex, label, screenshot, accessibilityFile, elementCount, timestampMs } plus guidance for next steps.

Examples

Record first step

await testRecordStepTool({ sessionName: "login-flow", label: "App launched" })

Step with assertion and metadata

await testRecordStepTool({
  sessionName: "login-flow",
  label: "Login succeeded",
  assertion: "Home screen is visible",
  metadata: { user: "test@example.com", env: "staging" }
})

Specific simulator

await testRecordStepTool({
  sessionName: "login-flow",
  label: "Credentials entered",
  udid: "device-123"
})

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
udidNo
labelYesHuman description of this step
metadataNo
assertionNo
sessionNameYesRecording session name

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv4.1.0

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the sparse annotations, the description discloses substantial side effects: it creates directories and steps.json, appends sequential step records, captures screenshots via simctl, tolerates idb absence, respects XC_MCP_RECORDINGS_DIR, and defaults udid to booted. This gives the agent a detailed model of what will happen on each call, which is far more than the annotations alone provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with 'What it does', session layout, parameter list, return shape, and examples. Each section carries needed information, and the opening sentence front-loads the core purpose. Nothing feels redundant or filler; the detail is warranted for a stateful tool with side effects.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and five parameters with nested objects, the description is remarkably complete. It explains persistent storage layout, step numbering, the exact return JSON fields, environment override, error tolerance for idb, and provides three usage examples covering typical scenarios. An agent has enough to invoke the tool correctly without additional investigation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 40%, but the description compensates by defining every parameter: sessionName is a unique directory name, label is human-readable, udid defaults to booted, metadata is arbitrary key-value pairs, and assertion is a recorded description. Examples show realistic combinations, which significantly adds meaning beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Record a single named step in a test session, capturing a screenshot and accessibility tree snapshot.' It clearly differentiates this tool from siblings by explaining the persistent session directory and explicitly noting that report.md is generated by test-record-report, so an agent can distinguish recording steps from generating reports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use the tool: during a test session to record individual steps with screenshot and accessibility data. It also references test-record-report as the tool that generates report.md, which implies the division of labor. However, it does not explicitly state 'use X instead when...' or list exclusion conditions, so it falls just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools