Skip to main content
Glama
conorluddy

XC-MCP: XCode CLI wrapper

by conorluddy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Add Media to Simulator

simctl-addmedia

Add images or videos to an iOS simulator's photo library for testing photo pickers, PHPhotoLibrary access, and media playback.

Instructions

simctl-addmedia

Add media files (photos and videos) to a simulator's photo library for testing.

What it does

Adds image or video files to the simulator's Photos app, making them available for apps to access via PHPhotoLibrary or UIImagePickerController APIs.

Parameters

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

  • mediaPath (string, required): Path to image or video file

Supported Formats

Images: jpg, jpeg, png, heic, gif, bmp Videos: mp4, mov, avi, mkv

Returns

JSON response with:

  • Media addition status

  • Media type and format detected

  • Guidance for viewing in Photos app and adding more media

Examples

Add image to photo library

await simctlAddmediaTool({
  udid: 'device-123',
  mediaPath: '/path/to/photo.jpg'
})

Add video to photo library

await simctlAddmediaTool({
  udid: 'device-123',
  mediaPath: '/path/to/video.mp4'
})

Common Use Cases

  1. Photo picker testing: Add test images for UIImagePickerController testing

  2. PHPhotoLibrary testing: Populate library for photo access API testing

  3. Image processing: Add images to test filters, crops, and transformations

  4. Video playback: Add videos to test AVPlayer integration

  5. Camera roll simulation: Populate library to simulate real user photo collection

Important Notes

  • File must exist: Validates file exists before attempting to add

  • Format validation: Only supported image/video formats are accepted

  • Simulator state: Works on both booted and shutdown simulators

  • Photos app: Media appears in simulator's Photos app immediately

  • Metadata: Original file metadata (EXIF, date, etc.) is preserved

Error Handling

  • File not found: Error if media file path doesn't exist

  • Unsupported format: Error if file extension is not in supported list

  • Simulator not found: Validates simulator exists in cache

  • Addition failure: Reports simctl errors if media cannot be added

Next Steps After Adding Media

  1. View in Photos app: simctl-launch <udid> com.apple.mobileslideshow

  2. Test photo picker: Launch your app and open UIImagePickerController

  3. Add more media: Repeat with different images/videos

  4. Test PHPhotoLibrary: Use PHPhotoLibrary.requestAuthorization() in your app

Testing Workflow

  1. Grant photo permissions: simctl-privacy <udid> <bundleId> grant photos

  2. Add test media: simctl-addmedia <udid> /path/to/photo.jpg

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

  4. Test photo access: Verify app can read from photo library

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

Tips

  • Test image formats: Add different image formats (JPEG, PNG, HEIC) to test compatibility

  • Test video formats: Add various video formats (MP4, MOV) to test playback

  • Large files: Be aware that adding large video files may take time

  • Batch addition: Add multiple files to simulate realistic photo library

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
udidYes
mediaPathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv4.1.0

TDQS

A4.3/5.0
Behavior4/5

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

The description discloses several behavioral traits beyond the sparse annotations: it validates file existence, restricts to supported formats, works on both booted and shutdown simulators, preserves metadata, and details error conditions. Annotations only indicate non-readOnly, non-idempotent, non-destructive; the description adds operational nuance that helps the agent predict side effects.

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 long and multi-sectional, covering parameters, formats, returns, examples, use cases, notes, error handling, next steps, workflow, and tips. It is well-structured with headers and front-loaded with the core purpose, but it repeats overlapping content (e.g., 'Common Use Cases' vs. 'Testing Workflow') and includes many optional tips. It earns a 3 because it is comprehensive but not concise.

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 the absence of an output schema and low schema parameter coverage, the description is exceptionally complete. It explains the return format (JSON with status, type, and guidance), error handling for each failure mode, examples, and a full testing workflow. An agent has everything needed to call the tool correctly and understand its effects.

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

Parameters4/5

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

The input schema provides no descriptions for either parameter (0% coverage). The description compensates by explaining each parameter explicitly: 'udid (string, required): Simulator UDID (from simctl-list)' and 'mediaPath (string, required): Path to image or video file,' and further lists supported formats. This gives the agent the meaning it cannot derive from the 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 'Add media files (photos and videos) to a simulator's photo library for testing,' which is a specific verb+resource action. It clearly states what the tool does and is unique among siblings—no other sibling tool adds media to the simulator. The scope is unambiguous.

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 provides rich usage context through 'Common Use Cases' (photo picker testing, PHPhotoLibrary testing, etc.) and a 'Testing Workflow' that shows when to use this tool in a sequence (e.g., after granting photo permissions). It does not explicitly mention alternatives because none exist in the sibling list, so the guidance is sufficient without exclusions.

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