XcodeBuildMCP

This file provides guidance to AI assisants (Claude Code, Cursor etc) when working with code in this repository. ## Project Overview XcodeBuildMCP is a Model Context Protocol (MCP) server providing standardized tools for AI assistants to interact with Xcode projects, iOS simulators, devices, and Apple development workflows. It's a TypeScript/Node.js project that runs as a stdio-based MCP server. ## Common Commands ### Build & Development ```bash npm run build # Compile TypeScript with tsup, generates version info npm run dev # Watch mode development npm run bundle:axe # Bundle axe CLI tool for simulator automation (needed when using local MCP server) npm run test # Run complete Vitest test suite npm run test:watch # Watch mode testing npm run lint # ESLint code checking npm run lint:fix # ESLint code checking and fixing npm run format:check # Prettier code checking npm run format # Prettier code formatting npm run typecheck # TypeScript type checking npm run inspect # Run interactive MCP protocol inspector npm run doctor # Doctor CLI ``` ### Development with Reloaderoo **Reloaderoo** (v1.1.2+) provides CLI-based testing and hot-reload capabilities for XcodeBuildMCP without requiring MCP client configuration. #### Quick Start **CLI Mode (Testing & Development):** ```bash # List all tools npx reloaderoo inspect list-tools -- node build/index.js # Call any tool npx reloaderoo inspect call-tool list_devices --params '{}' -- node build/index.js # Get server information npx reloaderoo inspect server-info -- node build/index.js # List and read resources npx reloaderoo inspect list-resources -- node build/index.js npx reloaderoo inspect read-resource "xcodebuildmcp://devices" -- node build/index.js ``` **Proxy Mode (MCP Client Integration):** ```bash # Start persistent server for MCP clients npx reloaderoo proxy -- node build/index.js # With debug logging npx reloaderoo proxy --log-level debug -- node build/index.js # Then ask AI: "Please restart the MCP server to load my changes" ``` #### All CLI Inspect Commands Reloaderoo provides 8 inspect subcommands for comprehensive MCP server testing: ```bash # Server capabilities and information npx reloaderoo inspect server-info -- node build/index.js # Tool management npx reloaderoo inspect list-tools -- node build/index.js npx reloaderoo inspect call-tool <tool_name> --params '<json>' -- node build/index.js # Resource access npx reloaderoo inspect list-resources -- node build/index.js npx reloaderoo inspect read-resource "<uri>" -- node build/index.js # Prompt management npx reloaderoo inspect list-prompts -- node build/index.js npx reloaderoo inspect get-prompt <name> --args '<json>' -- node build/index.js # Connectivity testing npx reloaderoo inspect ping -- node build/index.js ``` #### Advanced Options ```bash # Custom working directory npx reloaderoo inspect list-tools --working-dir /custom/path -- node build/index.js # Timeout configuration npx reloaderoo inspect call-tool slow_tool --timeout 60000 --params '{}' -- node build/index.js # Use timeout configuration if needed npx reloaderoo inspect server-info --timeout 60000 -- node build/index.js # Debug logging (use proxy mode for detailed logging) npx reloaderoo proxy --log-level debug -- node build/index.js ``` #### Key Benefits - ✅ **No MCP Client Setup**: Direct CLI access to all 84+ tools - ✅ **Raw JSON Output**: Perfect for AI agents and programmatic use - ✅ **Hot-Reload Support**: `restart_server` tool for MCP client development - ✅ **Claude Code Compatible**: Automatic content block consolidation - ✅ **8 Inspect Commands**: Complete MCP protocol testing capabilities - ✅ **Universal Compatibility**: Works on any system via npx For complete documentation, examples, and troubleshooting, see @docs/RELOADEROO.md ## Architecture Overview ### Plugin-Based MCP architecture XcodeBuildMCP uses the concept of configuration by convention for MCP exposing and running MCP capabilities like tools and resources. This means to add a new tool or resource, you simply create a new file in the appropriate directory and it will be automatically loaded and exposed to MCP clients. #### Tools Tools are the core of the MCP server and are the primary way to interact with the server. They are organized into directories by their functionality and are automatically loaded and exposed to MCP clients. For more information see @docs/PLUGIN_DEVELOPMENT.md #### Resources Resources are the secondary way to interact with the server. They are used to provide data to tools and are organized into directories by their functionality and are automatically loaded and exposed to MCP clients. For more information see @docs/PLUGIN_DEVELOPMENT.md ### Operating Modes XcodeBuildMCP has two modes to manage its extensive toolset, controlled by the `XCODEBUILDMCP_DYNAMIC_TOOLS` environment variable. #### Static Mode (Default) - **Environment**: `XCODEBUILDMCP_DYNAMIC_TOOLS=false` or unset. - **Behavior**: All tools are loaded at startup. This provides immediate access to the full toolset but uses a larger context window. #### Dynamic Mode (AI-Powered) - **Environment**: `XCODEBUILDMCP_DYNAMIC_TOOLS=true`. - **Behavior**: Only the `discover_tools` tool is available initially. You can use this tool by providing a natural language task description. The server then uses an LLM call (via MCP Sampling) to identify the most relevant workflow group and dynamically loads only those tools. This conserves context window space. #### Claude Code Compatibility Workaround - **Detection**: Automatic detection when running under Claude Code. - **Purpose**: Workaround for Claude Code's MCP specification violation where it only displays the first content block in tool responses. - **Behavior**: When Claude Code is detected, multiple content blocks are automatically consolidated into a single text response, separated by `---` dividers. This ensures all information (including test results and stderr warnings) is visible to Claude Code users. ### Core Architecture Layers 1. **MCP Transport**: stdio protocol communication 2. **Plugin Discovery**: Automatic tool AND resource registration system 3. **MCP Resources**: URI-based data access (e.g., `xcodebuildmcp://simulators`) 4. **Tool Implementation**: Self-contained workflow modules 5. **Shared Utilities**: Command execution, build management, validation 6. **Types**: Shared interfaces and Zod schemas For more information see @docs/ARCHITECTURE.md ## Testing The project enforces a strict **Dependency Injection (DI)** testing philosophy. - **NO Vitest Mocking**: The use of `vi.mock()`, `vi.fn()`, `vi.spyOn()`, etc., is **completely banned**. - **Executors**: All external interactions (like running commands or accessing the file system) are handled through injectable "executors". - `CommandExecutor`: For running shell commands. - `FileSystemExecutor`: For file system operations. - **Testing Logic**: Tests import the core `...Logic` function from a tool file and pass in a mock executor (`createMockExecutor` or `createMockFileSystemExecutor`) to simulate different outcomes. This approach ensures that tests are robust, easy to maintain, and verify the actual integration between components without being tightly coupled to implementation details. For complete guidelines, refer to @docs/TESTING.md. ## TypeScript Import Standards This project uses **TypeScript file extensions** (`.ts`) for all relative imports to ensure compatibility with native TypeScript runtimes. ### Import Rules - ✅ **Use `.ts` extensions**: `import { tool } from './tool.ts'` - ✅ **Use `.ts` for re-exports**: `export { default } from '../shared/tool.ts'` - ✅ **External packages use `.js`**: `import { McpServer } from '@camsoft/mcp-sdk/server/mcp.js'` - ❌ **Never use `.js` for internal files**: `import { tool } from './tool.js'` ← ESLint error ### Benefits 1. **Future-proof**: Compatible with native TypeScript runtimes (Bun, Deno, Node.js --loader) 2. **IDE Experience**: Direct navigation to source TypeScript files 3. **Consistency**: Import path matches the actual file you're editing 4. **Modern Standard**: Aligns with TypeScript 4.7+ `allowImportingTsExtensions` ### ESLint Enforcement The project automatically enforces this standard: ```bash npm run lint # Will catch .js imports for internal files ``` This ensures all new code follows the `.ts` import pattern and maintains compatibility with both current and future TypeScript execution environments. ## Release Process Follow standardized development workflow with feature branches, structured pull requests, and linear commit history. **Never push to main directly or force push without permission.** For complete guidelines, refer to @docs/RELEASE_PROCESS.md ## Useful external resources ### Model Context Protocol https://modelcontextprotocol.io/llms-full.txt ### MCP Specification https://modelcontextprotocol.io/specification ### MCP Inspector https://github.com/modelcontextprotocol/inspector ### MCP Client SDKs https://github.com/modelcontextprotocol/typescript-sdk