xc-mcp/dist/tools/docs-registry.d.ts

MCP server that wraps Xcode command-line tools for iOS/macOS development workflows

/**
 * Central registry of all tool documentation.
 *
 * This file imports documentation constants from all tool implementations
 * and provides a unified map for the get-tool-docs MCP tool.
 *
 * Documentation is embedded as TypeScript constants to ensure it's
 * bundled with the npm package (no external .md file dependencies).
 */
export declare const SCREENSHOT_SAVE_DOCS = "\n# screenshot-save\n\n\uD83D\uDCF8 **File-Based Screenshot Alias** - Save screenshots/videos to files via simctl-io.\n\n## Overview\n\n`screenshot-save` is a convenience alias for the file-based variant of `simctl-io`. Use this when you want to save screenshots or videos to disk files. For inline base64 screenshots optimized for vision models, use the `screenshot` tool instead.\n\n## Relationship to Other Tools\n\n- **screenshot-save** \u2192 Saves to file (uses `simctl-io`)\n- **screenshot** \u2192 Returns inline base64 with coordinate metadata (uses `simctl-screenshot-inline`)\n- **simctl-io** \u2192 Direct access to I/O operations (screenshots, videos, both file-based)\n\n## When to Use\n\n**Use screenshot-save when:**\n- You need to save screenshots to specific file paths\n- Recording videos for later playback\n- Building test artifacts for CI/CD pipelines\n- Creating screenshot archives\n\n**Use screenshot instead when:**\n- Working with AI vision models (Claude, GPT-4V)\n- Need coordinate transformation metadata for UI automation\n- Want immediate inline image analysis\n- Token efficiency is important (half-size default)\n\n## Parameters\n\nAll parameters are passed directly to `simctl-io`:\n\n- **udid** (optional): Simulator UDID (auto-detects if not provided)\n- **operation**: \"screenshot\" or \"video\"\n- **appName** (optional): App name for semantic naming (e.g., \"MyApp\")\n- **screenName** (optional): Screen/view name (e.g., \"LoginScreen\")\n- **state** (optional): UI state (e.g., \"Empty\", \"Filled\", \"Loading\")\n- **outputPath** (optional): Custom output file path\n- **codec** (optional): Video codec for recordings (h264, hevc, prores)\n\n## Examples\n\n### Basic Screenshot\n```typescript\n{\n  \"tool\": \"screenshot-save\",\n  \"arguments\": {\n    \"operation\": \"screenshot\"\n  }\n}\n```\n\n### Semantic Screenshot Naming\n```typescript\n{\n  \"tool\": \"screenshot-save\",\n  \"arguments\": {\n    \"operation\": \"screenshot\",\n    \"appName\": \"MyApp\",\n    \"screenName\": \"LoginScreen\",\n    \"state\": \"Empty\"\n  }\n}\n// Saves to: MyApp_LoginScreen_Empty_2025-01-24.png\n```\n\n### Custom Output Path\n```typescript\n{\n  \"tool\": \"screenshot-save\",\n  \"arguments\": {\n    \"operation\": \"screenshot\",\n    \"outputPath\": \"/tmp/my-screenshot.png\"\n  }\n}\n```\n\n### Video Recording\n```typescript\n{\n  \"tool\": \"screenshot-save\",\n  \"arguments\": {\n    \"operation\": \"video\",\n    \"codec\": \"h264\"\n  }\n}\n```\n\n## Returns\n\nFile path to saved screenshot/video with success confirmation.\n\nExample response:\n```json\n{\n  \"success\": true,\n  \"filePath\": \"/path/to/MyApp_LoginScreen_Empty_2025-01-24.png\",\n  \"operation\": \"screenshot\",\n  \"guidance\": [\n    \"Screenshot saved successfully\",\n    \"File: /path/to/MyApp_LoginScreen_Empty_2025-01-24.png\",\n    \"Use 'screenshot' tool for inline base64 variant with coordinate metadata\"\n  ]\n}\n```\n\n## Related Tools\n\n- **screenshot**: Inline base64 screenshots with vision model optimization\n- **simctl-io**: Direct I/O operations (supports both screenshot and video)\n- **simctl-addmedia**: Add images/videos to simulator photo library\n\n## Implementation Note\n\nThis tool is registered as an alias in `src/index.ts` and delegates directly to the `simctl-io` tool implementation. It exists for clarity and convenience - the name makes the file-based behavior explicit.\n\n## Notes\n\n- Auto-detects booted simulator if udid not provided\n- Semantic naming helps organize test artifacts\n- Video recording runs until stopped (Ctrl+C)\n- Screenshots saved as PNG by default\n- File paths are absolute and returned in response\n";
export declare const RTFM_DOCS = "\n# rtfm\n\n\uD83D\uDCD6 **Read The Manual** - Progressive disclosure documentation system for all XC-MCP tools.\n\n## Overview\n\nThe rtfm tool provides access to comprehensive documentation for any of the 28 consolidated tools in this MCP server (v2.0+). This implements progressive disclosure: tool descriptions in the main list include full documentation (~18.7k tokens total for optimal agent understanding), while rtfm provides additional context and examples on demand.\n\n**Version History:**\n- v1.x: 51 individual tools (~3,000-7,850 tokens depending on approach)\n- v2.0+: 28 consolidated tools (~18.7k tokens) - Comprehensive docs for optimal reasoning\n\n## Why rtfm?\n\n**Problem Solved**: Tool documentation was originally stored in .md files within the src/ directory, which wouldn't be available in the published npm package (only dist/ is included in package.json \"files\" field).\n\n**Solution**: Documentation is now embedded as TypeScript constants in each tool file, bundled into the compiled JavaScript, and accessible via this rtfm tool. This ensures documentation is always available, whether in development or in the published npm package.\n\n## Parameters\n\n- **toolName** (optional): Name of specific tool to get documentation for\n  - Examples: \"xcodebuild-build\", \"simctl-device\", \"idb-app\", \"cache\", \"persistence\"\n  - Case-sensitive, must match exact tool registration name\n- **categoryName** (optional): Browse tools in a specific category\n  - Examples: \"build\", \"simulator\", \"app\", \"idb\", \"cache\", \"system\"\n  - Omit both parameters to see all categories\n\n## Examples\n\n```typescript\n// Get documentation for consolidated simulator device tool\nrtfm({ toolName: \"simctl-device\" })\n\n// Get documentation for consolidated app management tool\nrtfm({ toolName: \"idb-app\" })\n\n// Browse all tools in the cache category\nrtfm({ categoryName: \"cache\" })\n\n// View all categories (no parameters)\nrtfm({})\n```\n\n## Migration from v1.x to v2.0\n\n**Old individual tools are now consolidated into single tools with operation parameters:**\n\n- `simctl-boot`, `simctl-shutdown`, `simctl-create`, `simctl-delete`, `simctl-erase`, `simctl-clone`, `simctl-rename` \u2192 **simctl-device** (operation enum)\n- `simctl-install`, `simctl-uninstall`, `simctl-launch`, `simctl-terminate` \u2192 **simctl-app** (operation enum)\n- `idb-install`, `idb-uninstall`, `idb-launch`, `idb-terminate` \u2192 **idb-app** (operation enum)\n- `cache-get-stats`, `cache-get-config`, `cache-set-config`, `cache-clear` \u2192 **cache** (operation enum)\n- `persistence-enable`, `persistence-disable`, `persistence-status` \u2192 **persistence** (operation enum)\n- `idb-targets` extended with `idb-connect` and `idb-disconnect` operations\n\nFor detailed examples and parameter specifications for each operation, use `rtfm({ toolName: \"simctl-device\" })` etc.\n\n## Response Format\n\n### Success Response\nReturns full markdown documentation including:\n- Tool description and purpose\n- Advantages over direct CLI usage\n- Parameter specifications with types and descriptions\n- Usage examples\n- Related tools\n- Common patterns and best practices\n\n### Tool Not Found Response\nIf toolName doesn't match any registered tool:\n- Error message with the attempted tool name\n- Suggestions based on partial matches (up to 5)\n- Complete list of all available tools\n\nExample:\n```\nNo documentation found for tool: \"simctl-boo\"\n\nDid you mean one of these?\n  - simctl-boot\n  - simctl-shutdown\n\nAvailable tools (28 total):\n  - xcodebuild-*\n  - simctl-*\n  - idb-*\n  - cache\n  - persistence\n  - rtfm\n```\n\n## Available Tool Categories (v2.0)\n\n**Xcodebuild Tools (7)**\n- xcodebuild-version, xcodebuild-list, xcodebuild-showsdks\n- xcodebuild-build, xcodebuild-clean, xcodebuild-test\n- xcodebuild-get-details\n\n**Simctl Lifecycle Tools (6)**\n- simctl-list, simctl-get-details, **simctl-device** (consolidated: boot/shutdown/create/delete/erase/clone/rename)\n- simctl-suggest, simctl-health-check\n\n**Simctl App Management Tools (3)**\n- **simctl-app** (consolidated: install/uninstall/launch/terminate)\n- simctl-get-app-container, simctl-openurl\n\n**Simctl I/O & Testing Tools (7)**\n- simctl-io, simctl-addmedia, simctl-privacy, simctl-push\n- simctl-pbcopy, simctl-status-bar, screenshot\n\n**IDB Tools (6)**\n- **idb-targets** (extended: list/describe/focus/connect/disconnect)\n- idb-ui-tap, idb-ui-input, idb-ui-gesture, idb-ui-describe, idb-list-apps\n- **idb-app** (consolidated: install/uninstall/launch/terminate)\n\n**Cache Management Tools (2)**\n- list-cached-responses\n- **cache** (consolidated: get-stats/get-config/set-config/clear)\n\n**Persistence Tools (1)**\n- **persistence** (consolidated: enable/disable/status)\n\n**Documentation Tool (1)**\n- rtfm (this tool!)\n\n## Implementation Details\n\n### Documentation Storage\nEach tool file exports a `TOOL_NAME_DOCS` constant containing its full documentation in markdown format:\n\n```typescript\n// Example from src/tools/simctl/boot.ts\nexport const SIMCTL_BOOT_DOCS = `\n# simctl-boot\n...\n`;\n```\n\n### Central Registry\nAll documentation constants are imported and mapped in `src/tools/docs-registry.ts`:\n\n```typescript\nexport const TOOL_DOCS: Record<string, string> = {\n  'simctl-boot': SIMCTL_BOOT_DOCS,\n  'xcodebuild-build': XCODEBUILD_BUILD_DOCS,\n  // ... 49 more tools\n};\n```\n\n### Progressive Disclosure Pattern\n1. Tool list shows concise descriptions (~300-400 tokens)\n2. Each description ends with: \"\uD83D\uDCD6 Use rtfm with toolName: '{name}' for full documentation.\"\n3. Full documentation accessed only when explicitly requested via rtfm\n4. Prevents token overflow while maintaining comprehensive documentation access\n\n## Benefits\n\n\u2705 **Self-contained**: No external file dependencies\n\u2705 **NPM package ready**: Documentation bundled in compiled JavaScript\n\u2705 **Token efficient**: Progressive disclosure keeps default views concise\n\u2705 **Always available**: Works in development and production\n\u2705 **Type-safe**: TypeScript constants with proper typing\n\u2705 **Searchable**: Fuzzy matching with suggestions for typos\n\u2705 **Comprehensive**: Full documentation including examples and parameters\n\n## Common Use Cases\n\n**Explore available tools**:\n```typescript\n// Intentionally use invalid tool name to see full list\nrtfm({ toolName: \"help\" })\n```\n\n**Learn specific tool usage**:\n```typescript\nrtfm({ toolName: \"simctl-boot\" })\n```\n\n**Understand tool parameters**:\n```typescript\nrtfm({ toolName: \"xcodebuild-build\" })\n```\n\n**Find related tools**:\n```typescript\n// Search by category prefix\nrtfm({ toolName: \"simctl\" })  // Shows simctl-* suggestions\n```\n\n## Related Tools\n\n- **list-cached-responses**: View cached progressive disclosure responses\n- **cache-get-stats**: Monitor cache performance and usage\n\n## Notes\n\n- Tool names are case-sensitive and must match exact registration names\n- Fuzzy matching provides suggestions for close matches\n- Documentation format is consistent markdown across all tools\n- Each tool's documentation is independently maintained in its source file\n- The TOOL_DOCS registry is automatically updated when tools are added/removed\n";
export declare const RTFM_DOCS_MINI = "Get tool documentation. Use rtfm({ toolName: \"rtfm\" }) for docs.";
export declare const SCREENSHOT_SAVE_DOCS_MINI = "Save screenshot to file. Use rtfm({ toolName: \"screenshot-save\" }) for docs.";
/**
 * Tool categories for progressive discovery
 */
export declare const TOOL_CATEGORIES: Record<string, string[]>;
export declare const CATEGORY_DESCRIPTIONS: Record<string, {
    name: string;
    description: string;
}>;
/**
 * Get all tools in a category
 */
export declare function getToolsByCategory(categoryKey: string): string[] | undefined;
/**
 * Get category key for a tool name
 */
export declare function getCategoryForTool(toolName: string): string | undefined;
/**
 * Get all category keys
 */
export declare function getAllCategories(): string[];
/**
 * Map of tool names to their full documentation.
 * Tool names match the MCP tool registration names.
 */
export declare const TOOL_DOCS: Record<string, string>;
//# sourceMappingURL=docs-registry.d.ts.map