Skip to content

Commit 87b2154

Browse files
cameroncookecameroncooke
committed
Add canonical AGENTS.md
1 parent 281e10d commit 87b2154

3 files changed

Lines changed: 192 additions & 191 deletions

File tree

‎.cursorrules‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
CLAUDE.md
1+
AGENTS.md

‎AGENTS.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
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 diagnostic # Diagnostic 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 84+ 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/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/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/PLUGIN_DEVELOPMENT.md
126+
127+
### Operating Modes
128+
129+
XcodeBuildMCP has two modes to manage its extensive toolset, controlled by the `XCODEBUILDMCP_DYNAMIC_TOOLS` environment variable.
130+
131+
#### Static Mode (Default)
132+
- **Environment**: `XCODEBUILDMCP_DYNAMIC_TOOLS=false` or unset.
133+
- **Behavior**: All tools are loaded at startup. This provides immediate access to the full toolset but uses a larger context window.
134+
135+
#### Dynamic Mode (AI-Powered)
136+
- **Environment**: `XCODEBUILDMCP_DYNAMIC_TOOLS=true`.
137+
- **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.
138+
139+
#### Claude Code Compatibility Workaround
140+
- **Detection**: Automatic detection when running under Claude Code.
141+
- **Purpose**: Workaround for Claude Code's MCP specification violation where it only displays the first content block in tool responses.
142+
- **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.
143+
144+
### Core Architecture Layers
145+
1. **MCP Transport**: stdio protocol communication
146+
2. **Plugin Discovery**: Automatic tool AND resource registration system
147+
3. **MCP Resources**: URI-based data access (e.g., `xcodebuildmcp://simulators`)
148+
4. **Tool Implementation**: Self-contained workflow modules
149+
5. **Shared Utilities**: Command execution, build management, validation
150+
6. **Types**: Shared interfaces and Zod schemas
151+
152+
For more information see @docs/ARCHITECTURE.md
153+
154+
## Testing
155+
156+
The project enforces a strict **Dependency Injection (DI)** testing philosophy.
157+
158+
- **NO Vitest Mocking**: The use of `vi.mock()`, `vi.fn()`, `vi.spyOn()`, etc., is **completely banned**.
159+
- **Executors**: All external interactions (like running commands or accessing the file system) are handled through injectable "executors".
160+
- `CommandExecutor`: For running shell commands.
161+
- `FileSystemExecutor`: For file system operations.
162+
- **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.
163+
164+
This approach ensures that tests are robust, easy to maintain, and verify the actual integration between components without being tightly coupled to implementation details.
165+
166+
For complete guidelines, refer to @docs/TESTING.md.
167+
168+
## Release Process
169+
170+
Follow standardized development workflow with feature branches, structured pull requests, and linear commit history. **Never push to main directly or force push without permission.**
171+
172+
For complete guidelines, refer to @docs/RELEASE_PROCESS.md
173+
174+
## Useful external resources
175+
176+
### Model Context Protocol
177+
178+
https://modelcontextprotocol.io/llms-full.txt
179+
180+
### MCP Specification
181+
182+
https://modelcontextprotocol.io/specification
183+
184+
### MCP Inspector
185+
186+
https://github.com/modelcontextprotocol/inspector
187+
188+
### MCP Client SDKs
189+
190+
https://github.com/modelcontextprotocol/typescript-sdk

‎CLAUDE.md‎

Lines changed: 0 additions & 190 deletions
This file was deleted.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)