|
1 | | -This file provides guidance to AI assisants (Claude Code, Cursor etc) when working with code in this repository. |
2 | | - |
3 | | -## Project Overview |
4 | | - |
5 | | -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. |
6 | | - |
7 | | -## Common Commands |
8 | | - |
9 | | -### Build & Development |
10 | | -```bash |
11 | | -npm run build # Compile TypeScript with tsup, generates version info |
12 | | -npm run dev # Watch mode development |
13 | | -npm run bundle:axe # Bundle axe CLI tool for simulator automation (needed when using local MCP server) |
14 | | -npm run test # Run complete Vitest test suite |
15 | | -npm run test:watch # Watch mode testing |
16 | | -npm run lint # ESLint code checking |
17 | | -npm run lint:fix # ESLint code checking and fixing |
18 | | -npm run format:check # Prettier code checking |
19 | | -npm run format # Prettier code formatting |
20 | | -npm run typecheck # TypeScript type checking |
21 | | -npm run inspect # Run interactive MCP protocol inspector |
22 | | -npm run doctor # Doctor CLI |
23 | | -``` |
24 | | - |
25 | | -### Development with Reloaderoo |
26 | | - |
27 | | -**Reloaderoo** (v1.1.2+) provides CLI-based testing and hot-reload capabilities for XcodeBuildMCP without requiring MCP client configuration. |
28 | | - |
29 | | -#### Quick Start |
30 | | - |
31 | | -**CLI Mode (Testing & Development):** |
32 | | -```bash |
33 | | -# List all tools |
34 | | -npx reloaderoo inspect list-tools -- node build/index.js |
35 | | - |
36 | | -# Call any tool |
37 | | -npx reloaderoo inspect call-tool list_devices --params '{}' -- node build/index.js |
38 | | - |
39 | | -# Get server information |
40 | | -npx reloaderoo inspect server-info -- node build/index.js |
41 | | - |
42 | | -# List and read resources |
43 | | -npx reloaderoo inspect list-resources -- node build/index.js |
44 | | -npx reloaderoo inspect read-resource "xcodebuildmcp://devices" -- node build/index.js |
45 | | -``` |
46 | | - |
47 | | -**Proxy Mode (MCP Client Integration):** |
48 | | -```bash |
49 | | -# Start persistent server for MCP clients |
50 | | -npx reloaderoo proxy -- node build/index.js |
51 | | - |
52 | | -# With debug logging |
53 | | -npx reloaderoo proxy --log-level debug -- node build/index.js |
54 | | - |
55 | | -# Then ask AI: "Please restart the MCP server to load my changes" |
56 | | -``` |
57 | | - |
58 | | -#### All CLI Inspect Commands |
59 | | - |
60 | | -Reloaderoo provides 8 inspect subcommands for comprehensive MCP server testing: |
61 | | - |
62 | | -```bash |
63 | | -# Server capabilities and information |
64 | | -npx reloaderoo inspect server-info -- node build/index.js |
65 | | - |
66 | | -# Tool management |
67 | | -npx reloaderoo inspect list-tools -- node build/index.js |
68 | | -npx reloaderoo inspect call-tool <tool_name> --params '<json>' -- node build/index.js |
69 | | - |
70 | | -# Resource access |
71 | | -npx reloaderoo inspect list-resources -- node build/index.js |
72 | | -npx reloaderoo inspect read-resource "<uri>" -- node build/index.js |
73 | | - |
74 | | -# Prompt management |
75 | | -npx reloaderoo inspect list-prompts -- node build/index.js |
76 | | -npx reloaderoo inspect get-prompt <name> --args '<json>' -- node build/index.js |
77 | | - |
78 | | -# Connectivity testing |
79 | | -npx reloaderoo inspect ping -- node build/index.js |
80 | | -``` |
81 | | - |
82 | | -#### Advanced Options |
83 | | - |
84 | | -```bash |
85 | | -# Custom working directory |
86 | | -npx reloaderoo inspect list-tools --working-dir /custom/path -- node build/index.js |
87 | | - |
88 | | -# Timeout configuration |
89 | | -npx reloaderoo inspect call-tool slow_tool --timeout 60000 --params '{}' -- node build/index.js |
90 | | - |
91 | | -# Use timeout configuration if needed |
92 | | -npx reloaderoo inspect server-info --timeout 60000 -- node build/index.js |
93 | | - |
94 | | -# Debug logging (use proxy mode for detailed logging) |
95 | | -npx reloaderoo proxy --log-level debug -- node build/index.js |
96 | | -``` |
97 | | - |
98 | | -#### Key Benefits |
99 | | - |
100 | | -- ✅ **No MCP Client Setup**: Direct CLI access to all tools |
101 | | -- ✅ **Raw JSON Output**: Perfect for AI agents and programmatic use |
102 | | -- ✅ **Hot-Reload Support**: `restart_server` tool for MCP client development |
103 | | -- ✅ **Claude Code Compatible**: Automatic content block consolidation |
104 | | -- ✅ **8 Inspect Commands**: Complete MCP protocol testing capabilities |
105 | | -- ✅ **Universal Compatibility**: Works on any system via npx |
106 | | - |
107 | | -For complete documentation, examples, and troubleshooting, see @docs/dev/RELOADEROO.md |
108 | | - |
109 | | -## Architecture Overview |
110 | | - |
111 | | -### Plugin-Based MCP architecture |
112 | | - |
113 | | -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. |
114 | | - |
115 | | -#### Tools |
116 | | - |
117 | | -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. |
118 | | - |
119 | | -For more information see @docs/dev/PLUGIN_DEVELOPMENT.md |
120 | | - |
121 | | -#### Resources |
122 | | - |
123 | | -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. |
124 | | - |
125 | | -For more information see @docs/dev/PLUGIN_DEVELOPMENT.md |
126 | | - |
127 | | -### Tool Registration |
128 | | - |
129 | | -XcodeBuildMCP loads tools at startup. To limit the toolset, set `XCODEBUILDMCP_ENABLED_WORKFLOWS` to a comma-separated list of workflow directory names (for example: `simulator,project-discovery`). The `session-management` workflow is always auto-included since other tools depend on it. |
130 | | - |
131 | | -#### Claude Code Compatibility Workaround |
132 | | -- **Detection**: Automatic detection when running under Claude Code. |
133 | | -- **Purpose**: Workaround for Claude Code's MCP specification violation where it only displays the first content block in tool responses. |
134 | | -- **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. |
135 | | - |
136 | | -### Core Architecture Layers |
137 | | -1. **MCP Transport**: stdio protocol communication |
138 | | -2. **Plugin Discovery**: Automatic tool AND resource registration system |
139 | | -3. **MCP Resources**: URI-based data access (e.g., `xcodebuildmcp://simulators`) |
140 | | -4. **Tool Implementation**: Self-contained workflow modules |
141 | | -5. **Shared Utilities**: Command execution, build management, validation |
142 | | -6. **Types**: Shared interfaces and Zod schemas |
143 | | - |
144 | | -For more information see @docs/dev/ARCHITECTURE.md |
145 | | - |
146 | | -## Testing |
147 | | - |
148 | | -The project enforces a strict **Dependency Injection (DI)** testing philosophy. |
149 | | - |
150 | | -- **NO Vitest Mocking**: The use of `vi.mock()`, `vi.fn()`, `vi.spyOn()`, etc., is **completely banned**. |
151 | | -- **Executors**: All external interactions (like running commands or accessing the file system) are handled through injectable "executors". |
152 | | - - `CommandExecutor`: For running shell commands. |
153 | | - - `FileSystemExecutor`: For file system operations. |
154 | | -- **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. |
155 | | - |
156 | | -This approach ensures that tests are robust, easy to maintain, and verify the actual integration between components without being tightly coupled to implementation details. |
157 | | - |
158 | | -For complete guidelines, refer to @docs/dev/TESTING.md. |
159 | | - |
160 | | -## TypeScript Import Standards |
161 | | - |
162 | | -This project uses **TypeScript file extensions** (`.ts`) for all relative imports to ensure compatibility with native TypeScript runtimes. |
163 | | - |
164 | | -### Import Rules |
165 | | - |
166 | | -- ✅ **Use `.ts` extensions**: `import { tool } from './tool.ts'` |
167 | | -- ✅ **Use `.ts` for re-exports**: `export { default } from '../shared/tool.ts'` |
168 | | -- ✅ **External packages use `.js`**: `import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'` |
169 | | -- ❌ **Never use `.js` for internal files**: `import { tool } from './tool.js'` ← ESLint error |
170 | | - |
171 | | -### Benefits |
172 | | - |
173 | | -1. **Future-proof**: Compatible with native TypeScript runtimes (Bun, Deno, Node.js --loader) |
174 | | -2. **IDE Experience**: Direct navigation to source TypeScript files |
175 | | -3. **Consistency**: Import path matches the actual file you're editing |
176 | | -4. **Modern Standard**: Aligns with TypeScript 4.7+ `allowImportingTsExtensions` |
177 | | - |
178 | | -### ESLint Enforcement |
179 | | - |
180 | | -The project automatically enforces this standard: |
181 | | - |
182 | | -```bash |
183 | | -npm run lint # Will catch .js imports for internal files |
184 | | -``` |
185 | | - |
186 | | -This ensures all new code follows the `.ts` import pattern and maintains compatibility with both current and future TypeScript execution environments. |
187 | | - |
188 | | -## Release Process |
189 | | - |
190 | | -Follow standardized development workflow with feature branches, structured pull requests, and linear commit history. **Never push to main directly or force push without permission.** |
191 | | - |
192 | | -For complete guidelines, refer to @docs/dev/RELEASE_PROCESS.md |
193 | | - |
194 | | -## Useful external resources |
195 | | - |
196 | | -### Model Context Protocol |
197 | | - |
198 | | -https://modelcontextprotocol.io/llms-full.txt |
199 | | - |
200 | | -### MCP Specification |
201 | | - |
202 | | -https://modelcontextprotocol.io/specification |
203 | | - |
204 | | -### MCP Inspector |
205 | | - |
206 | | -https://github.com/modelcontextprotocol/inspector |
207 | | - |
208 | | -### MCP Client SDKs |
209 | | - |
210 | | -https://github.com/modelcontextprotocol/typescript-sdk |
| 1 | +# Development Rules |
| 2 | + |
| 3 | +## Code Quality |
| 4 | +- No `any` types unless absolutely necessary |
| 5 | +- Check node_modules for external API type definitions instead of guessing |
| 6 | +- **NEVER use inline imports** - no `await import("./foo.js")`, no `import("pkg").Type` in type positions, no dynamic imports for types. Always use standard top-level imports. |
| 7 | +- NEVER remove or downgrade code to fix type errors from outdated dependencies; upgrade the dependency instead |
| 8 | +- Always ask before removing functionality or code that appears to be intentional |
| 9 | +- Follow TypeScript best practices |
| 10 | + |
| 11 | +## Commands |
| 12 | +- NEVER commit unless user asks |
| 13 | + |
| 14 | +## GitHub |
| 15 | +When reading issues: |
| 16 | +- Always read all comments on the issue |
| 17 | +- |
| 18 | +## Tools |
| 19 | +- GitHub CLI for issues/PRs |
| 20 | +- |
| 21 | +## Style |
| 22 | +- Keep answers short and concise |
| 23 | +- No emojis in commits, issues, PR comments, or code |
| 24 | +- No fluff or cheerful filler text |
| 25 | +- Technical prose only, be kind but direct (e.g., "Thanks @user" not "Thanks so much @user!") |
| 26 | + |
| 27 | +## Docs |
| 28 | +- If modifying or adding/removing tools run `npm run docs:update` to update the TOOLS.md file, never edit this file directly. |
| 29 | +- |
| 30 | +### Changelog |
| 31 | +Location: `CHANGELOG.md` |
| 32 | + |
| 33 | +#### Format |
| 34 | +Use these sections under `## [Unreleased]`: |
| 35 | +- `### Added` - New features |
| 36 | +- `### Changed` - Changes to existing functionality |
| 37 | +- `### Fixed` - Bug fixes |
| 38 | +- `### Removed` - Removed features |
| 39 | +- |
| 40 | +#### Rules |
| 41 | +- Before adding entries, read the full `[Unreleased]` section to see which subsections already exist |
| 42 | +- New entries ALWAYS go under `## [Unreleased]` section |
| 43 | +- Append to existing subsections (e.g., `### Fixed`), do not create duplicates |
| 44 | +- NEVER modify already-released version sections (e.g., `## [0.12.2]`) |
| 45 | +- Each version section is immutable once released |
| 46 | +- |
| 47 | +#### Attribution |
| 48 | +- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/cameroncook/XcodeBuildMCP/issues/123))` |
| 49 | +- **External contributions**: `Added feature X ([#456](https://github.com/cameroncook/XcodeBuildMCP/pull/456) by [@username](https://github.com/username))` |
| 50 | + |
| 51 | +## **CRITICAL** Tool Usage Rules **CRITICAL** |
| 52 | +- NEVER use sed/cat to read a file or a range of a file. Always use the native read tool. |
| 53 | +- You MUST read every file you modify in full before editing. |
0 commit comments