Skip to main content
Glama
conorluddy

XC-MCP: XCode CLI wrapper

by conorluddy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Get App Container Path

simctl-get-app-container
Read-onlyIdempotent

Get the file system path to an iOS app's container (bundle, data, or group) on a simulator to inspect files, databases, and preferences for debugging.

Instructions

simctl-get-app-container

Access iOS app file system containers for inspection and debugging.

What it does

Retrieves the file system path to an app's container directories on a simulator, enabling direct access to app bundle, data directories, and shared group containers for debugging and testing.

Why you'd use it

  • Debug data access: Inspect app Documents and Library folders

  • File inspection: View database files, preferences, and cached data

  • Testing validation: Confirm app writes data to correct locations

  • Container types: Access bundle (app binary), data (Documents/Library), and group (shared) containers

Parameters

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

  • bundleId (string, required): App bundle ID (e.g., com.example.MyApp)

  • containerType (string, optional): Container type - bundle, data, or group (default: data)

Container Types

  • bundle: App binary and resources (read-only)

  • data: App's Documents and Library directories (read-write)

  • group: Shared containers for app groups (read-write)

Returns

JSON response with:

  • Container path for file system access

  • Container type information

  • Guidance for accessing and inspecting files

  • Simulator state and validation

Examples

Get app data container path

await simctlGetAppContainerTool({
  udid: 'ABC-123-DEF',
  bundleId: 'com.example.MyApp'
})

Get app bundle path

await simctlGetAppContainerTool({
  udid: 'ABC-123-DEF',
  bundleId: 'com.example.MyApp',
  containerType: 'bundle'
})

Common Use Cases

  1. Debugging data persistence: Access app's Documents folder to inspect saved files

  2. Database inspection: View SQLite database files and validate schema

  3. Preferences debugging: Check UserDefaults plist files

  4. Cache validation: Verify cached data is stored correctly

  5. Bundle inspection: Access app binary and embedded resources

Error Handling

  • App not installed: Returns error if app is not installed on simulator

  • Invalid bundle ID: Validates bundle ID format (must contain '.')

  • Simulator not found: Validates simulator exists in cache

  • Container access failure: Reports if container cannot be accessed

Next Steps After Getting Container Path

  1. View files: cd "<container-path>" && ls -la

  2. Open in Finder: open "<container-path>/Documents"

  3. Find files: find "<container-path>" -type f | head -20

  4. Inspect specific file: cat "<container-path>/Documents/data.json"

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
udidYes
bundleIdYes
containerTypeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv1.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description builds on this by detailing container type access semantics (bundle read-only, data/group read-write), error handling for missing apps or invalid bundle IDs, and a 'Returns' section describing the JSON response. This adds valuable behavioral context beyond the annotations without contradicting them.

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?

Although lengthy, the description is well-structured with headings, code examples, and error handling. It front-loads the core purpose and every section (Why, Parameters, Container Types, Returns, Examples, Use Cases, Error Handling) earns its place by providing actionable information. The length is justified given the lack of schema descriptions and output schema.

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?

For a tool with 3 parameters, no schema descriptions, and no output schema, this description is remarkably complete. It covers purpose, parameter semantics, container types, return value shape, error conditions, and even next steps for using the returned path. An agent can invoke this tool reliably without needing additional context.

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%, but the description fully compensates with a dedicated 'Parameters' section explaining each parameter's type, requirement, default, and examples. It also expands the containerType enum with a 'Container Types' section defining bundle, data, and group. All parameters are documented in meaningful detail.

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 action: 'Retrieves the file system path to an app's container directories on a simulator.' It names the exact resource (app container directories) and the verb (retrieves), and distinguishes itself from siblings like simctl-container by emphasizing path retrieval for inspection and debugging. 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 a 'Why you'd use it' section and 'Common Use Cases' listing concrete scenarios like inspecting Documents and Library folders, checking databases, and validating writes. However, it never explicitly names alternative tools or states when not to use this tool, so it lacks the explicit exclusions/alternatives needed for 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