Skip to main content
Glama
conorluddy

XC-MCP: XCode CLI wrapper

by conorluddy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Copy Text to Simulator Clipboard

simctl-pbcopy
Idempotent

Copies text to an iOS simulator's clipboard to test paste operations, URL handling, and UIPasteboard APIs without manual interaction.

Instructions

simctl-pbcopy

Copy text to simulator's clipboard for testing paste operations and UIPasteboard APIs.

What it does

Copies text to the simulator's pasteboard (UIPasteboard.general), making it available for apps to access via standard pasteboard APIs. Useful for testing paste functionality without manual interaction.

Parameters

  • udid (string, required): Simulator UDID (from simctl-list)

  • text (string, required): Text to copy to clipboard

Returns

JSON response with:

  • Copy operation status

  • Text length and preview

  • Guidance for accessing pasteboard in app

Examples

Copy simple text

await simctlPbcopyTool({
  udid: 'device-123',
  text: 'Hello World'
})

Copy URL

await simctlPbcopyTool({
  udid: 'device-123',
  text: 'https://example.com/path?param=value'
})

Copy JSON data

await simctlPbcopyTool({
  udid: 'device-123',
  text: JSON.stringify({ key: 'value', number: 123 })
})

Common Use Cases

  1. Paste testing: Test text field paste functionality

  2. URL handling: Test app URL detection from clipboard

  3. Data import: Test importing data via clipboard

  4. Share functionality: Test receiving shared text content

  5. Clipboard monitoring: Test apps that monitor pasteboard changes

How Apps Access the Text

Apps can access the clipboard text using:

if let text = UIPasteboard.general.string {
    // Use the pasted text
}

Or for URLs:

if let url = UIPasteboard.general.url {
    // Handle the URL
}

Important Notes

  • Immediate availability: Text is available on pasteboard immediately

  • Simulator-specific: Each simulator has its own separate pasteboard

  • String only: Only supports string data (no images, files, or custom types)

  • Persistent: Clipboard content persists until overwritten or simulator resets

Error Handling

  • Empty text: Error if text string is empty

  • Simulator not found: Validates simulator exists in cache

  • Write failure: Reports if clipboard operation fails

Testing Workflow

  1. Copy text: simctl-pbcopy <udid> "Test text to paste"

  2. Launch app: simctl-launch <udid> <bundleId>

  3. Navigate to input: Use app to navigate to text field

  4. Test paste: App should detect clipboard content

  5. Take screenshot: simctl-io <udid> screenshot to verify paste

Use Cases by Category

Authentication Testing

  • Copy and paste email addresses

  • Copy and paste passwords (for test accounts only!)

  • Copy verification codes from clipboard

URL Handling

  • Copy URLs and test app deep link detection

  • Test universal link handling from clipboard

  • Verify URL parameter parsing

Data Import

  • Copy JSON/CSV data for import testing

  • Test clipboard-based data transfer

  • Verify data format validation

UX Testing

  • Test long-press paste menu appearance

  • Verify paste button states

  • Test clipboard change notifications

Clipboard Monitoring

Some apps monitor clipboard changes. To test this:

  1. Launch app first

  2. Copy text to clipboard

  3. App should detect and respond to clipboard change

  4. Take screenshot to verify UI update

Limitations

  • String data only: Cannot copy images, files, or custom types

  • No rich text: Only plain text is supported

  • No pasteboard metadata: Cannot set pasteboard change count or other metadata

  • Simulator scope: Clipboard is not shared with host macOS clipboard

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
textYes
udidYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv4.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations carry idempotentHint=true and destructiveHint=false, and the description adds substantial behavioral context: immediate pasteboard availability, simulator-specific clipboard isolation, string-only support, persistence until overwritten, and clear error-handling cases. It also discloses limitations such as no images, files, rich text, or pasteboard metadata.

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

Conciseness3/5

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

The description is well-structured with headers and front-loaded purpose, but it is considerably longer than needed. Sections like 'Common Use Cases' and 'Use Cases by Category' overlap, and the string-only limitation is repeated in multiple places, which affects conciseness even though the organization remains clear.

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?

The description fully covers inputs, output guidance, error handling, limitations, and realistic usage scenarios, including code snippets for how apps access the clipboard. With no output schema present, this description provides enough context for an agent to invoke the tool correctly and interpret results.

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 description coverage is 0%, so the description must fully compensate for undocumented parameters. It provides a 'Parameters' section explaining udid as the simulator UDID from simctl-list and text as the text to copy, reinforced by multiple concrete TypeScript examples including URL and JSON payloads.

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-resource pairing: 'Copy text to simulator's clipboard' for testing paste operations and UIPasteboard APIs. It clearly differentiates the tool's clipboard-specific role from other simctl siblings like simctl-launch or simctl-openurl.

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 extensive when-to-use context: testing paste functionality, URL handling, data import, and clipboard monitoring, with explicit testing workflows. It does not explicitly name alternatives or state when not to use this tool, so it misses the upper bound, but the use-case guidance is strong.

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