From 4f67ce6587ac8352aebb2444c08e6f77c511ef13 Mon Sep 17 00:00:00 2001 From: Cameron Cooke Date: Mon, 5 Jan 2026 22:41:50 +0000 Subject: [PATCH] Restructure and improve docs --- .smithery/index.cjs | 4 +- AGENTS.md | 12 +- README-ext.md | 316 ------------------ README.md | 25 +- docs/CONFIGURATION.md | 58 ++++ docs/DEMOS.md | 15 + docs/DEVICE_CODE_SIGNING.md | 18 + docs/GETTING_STARTED.md | 73 ++++ docs/OVERVIEW.md | 23 ++ docs/PRIVACY.md | 20 ++ docs/README.md | 26 ++ docs/SESSION_DEFAULTS.md | 26 ++ docs/TROUBLESHOOTING.md | 37 ++ docs/{ => dev}/ARCHITECTURE.md | 6 +- docs/{ => dev}/CODE_QUALITY.md | 4 +- docs/{ => dev}/CONTRIBUTING.md | 16 +- docs/{ => dev}/ESLINT_TYPE_SAFETY.md | 0 docs/{ => dev}/MANUAL_TESTING.md | 3 +- docs/{ => dev}/NODEJS_2025.md | 0 docs/{ => dev}/PLUGIN_DEVELOPMENT.md | 6 +- docs/dev/README.md | 26 ++ docs/{ => dev}/RELEASE_PROCESS.md | 0 docs/{ => dev}/RELOADEROO.md | 0 .../{ => dev}/RELOADEROO_FOR_XCODEBUILDMCP.md | 0 .../RELOADEROO_XCODEBUILDMCP_PRIMER.md | 0 docs/{ => dev}/SMITHERY.md | 0 docs/{ => dev}/TESTING.md | 0 .../TEST_RUNNER_ENV_IMPLEMENTATION_PLAN.md | 0 docs/{ => dev}/ZOD_MIGRATION_GUIDE.md | 0 .../{ => dev}/session-aware-migration-todo.md | 2 +- docs/{ => dev}/session_management_plan.md | 0 scripts/check-code-patterns.js | 4 +- src/utils/command.ts | 4 +- 33 files changed, 373 insertions(+), 351 deletions(-) delete mode 100644 README-ext.md create mode 100644 docs/CONFIGURATION.md create mode 100644 docs/DEMOS.md create mode 100644 docs/DEVICE_CODE_SIGNING.md create mode 100644 docs/GETTING_STARTED.md create mode 100644 docs/OVERVIEW.md create mode 100644 docs/PRIVACY.md create mode 100644 docs/README.md create mode 100644 docs/SESSION_DEFAULTS.md create mode 100644 docs/TROUBLESHOOTING.md rename docs/{ => dev}/ARCHITECTURE.md (98%) rename docs/{ => dev}/CODE_QUALITY.md (98%) rename docs/{ => dev}/CONTRIBUTING.md (94%) rename docs/{ => dev}/ESLINT_TYPE_SAFETY.md (100%) rename docs/{ => dev}/MANUAL_TESTING.md (99%) rename docs/{ => dev}/NODEJS_2025.md (100%) rename docs/{ => dev}/PLUGIN_DEVELOPMENT.md (99%) create mode 100644 docs/dev/README.md rename docs/{ => dev}/RELEASE_PROCESS.md (100%) rename docs/{ => dev}/RELOADEROO.md (100%) rename docs/{ => dev}/RELOADEROO_FOR_XCODEBUILDMCP.md (100%) rename docs/{ => dev}/RELOADEROO_XCODEBUILDMCP_PRIMER.md (100%) rename docs/{ => dev}/SMITHERY.md (100%) rename docs/{ => dev}/TESTING.md (100%) rename docs/{ => dev}/TEST_RUNNER_ENV_IMPLEMENTATION_PLAN.md (100%) rename docs/{ => dev}/ZOD_MIGRATION_GUIDE.md (100%) rename docs/{ => dev}/session-aware-migration-todo.md (98%) rename docs/{ => dev}/session_management_plan.md (100%) diff --git a/.smithery/index.cjs b/.smithery/index.cjs index d8e78b44..801bfe99 100644 --- a/.smithery/index.cjs +++ b/.smithery/index.cjs @@ -41,11 +41,11 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs. This test is trying to use the default command executor instead of a mock. Fix: Pass createMockExecutor() as the commandExecutor parameter in your test. Example: await plugin.handler(args, createMockExecutor({success: true}), mockFileSystem) -See docs/TESTING.md for proper testing patterns.`);return mJe}function Ir(){if(process.env.VITEST==="true")throw new Error(`\u{1F6A8} REAL FILESYSTEM EXECUTOR DETECTED IN TEST! \u{1F6A8} +See docs/dev/TESTING.md for proper testing patterns.`);return mJe}function Ir(){if(process.env.VITEST==="true")throw new Error(`\u{1F6A8} REAL FILESYSTEM EXECUTOR DETECTED IN TEST! \u{1F6A8} This test is trying to use the default filesystem executor instead of a mock. Fix: Pass createMockFileSystemExecutor() as the fileSystemExecutor parameter in your test. Example: await plugin.handler(args, mockCmd, createMockFileSystemExecutor()) -See docs/TESTING.md for proper testing patterns.`);return hJe}var hre,gre,_re,hJe,hs=O(()=>{"use strict";hre=require("child_process"),gre=require("fs"),_re=require("os");Go();hJe={async mkdir(t,e){await(await import("fs/promises")).mkdir(t,e)},async readFile(t,e="utf8"){return await(await import("fs/promises")).readFile(t,e)},async writeFile(t,e,r="utf8"){await(await import("fs/promises")).writeFile(t,e,r)},async cp(t,e,r){await(await import("fs/promises")).cp(t,e,r)},async readdir(t,e){return await(await import("fs/promises")).readdir(t,e)},async rm(t,e){await(await import("fs/promises")).rm(t,e)},existsSync(t){return(0,gre.existsSync)(t)},async stat(t){return await(await import("fs/promises")).stat(t)},async mkdtemp(t){return await(await import("fs/promises")).mkdtemp(t)},tmpdir(){return(0,_re.tmpdir)()}}});var ze=O(()=>{"use strict";hs()});function Lt(t){return{type:"text",text:t}}function g2(t,e){return{type:"image",data:t,mimeType:e}}var Dn=O(()=>{"use strict"});function Sre(){return gJe}function MI(){let t=process.env.XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS;if(!t)return!1;let e=t.trim().toLowerCase();return["1","true","yes","on"].includes(e)}function Jh(t){let e={};for(let[r,n]of Object.entries(t??{})){if(n==null)continue;let o=r.startsWith("TEST_RUNNER_")?r:`TEST_RUNNER_${r}`;e[o]=n}return e}var vre,_2,gJe,Xh=O(()=>{"use strict";vre=require("child_process");Go();_2=class{isRunningUnderClaudeCode(){if(process.env.VITEST==="true")return!1;if(process.env.CLAUDECODE==="1"||process.env.CLAUDE_CODE_ENTRYPOINT==="cli")return!0;try{let e=process.ppid;if(e&&(0,vre.execSync)(`ps -o command= -p ${e}`,{encoding:"utf8",timeout:1e3}).trim().includes("claude"))return!0}catch(e){A("debug",`Failed to detect parent process: ${e}`)}return!1}},gJe=new _2});function le(t,e=!1){return{content:[{type:"text",text:t}],isError:e}}function DI(t,e){return(e?e.existsSync(t):yre.existsSync(t))?{isValid:!0}:{isValid:!1,errorResponse:le(`File not found: '${t}'. Please check the path and try again.`,!0)}}function Sp(t){if(!Sre().isRunningUnderClaudeCode()||!t.content||t.content.length<=1)return t;let r=[];if(t.content.forEach((o,i)=>{o.type==="text"&&(i>0&&r.length>0&&r.push(` +See docs/dev/TESTING.md for proper testing patterns.`);return hJe}var hre,gre,_re,hJe,hs=O(()=>{"use strict";hre=require("child_process"),gre=require("fs"),_re=require("os");Go();hJe={async mkdir(t,e){await(await import("fs/promises")).mkdir(t,e)},async readFile(t,e="utf8"){return await(await import("fs/promises")).readFile(t,e)},async writeFile(t,e,r="utf8"){await(await import("fs/promises")).writeFile(t,e,r)},async cp(t,e,r){await(await import("fs/promises")).cp(t,e,r)},async readdir(t,e){return await(await import("fs/promises")).readdir(t,e)},async rm(t,e){await(await import("fs/promises")).rm(t,e)},existsSync(t){return(0,gre.existsSync)(t)},async stat(t){return await(await import("fs/promises")).stat(t)},async mkdtemp(t){return await(await import("fs/promises")).mkdtemp(t)},tmpdir(){return(0,_re.tmpdir)()}}});var ze=O(()=>{"use strict";hs()});function Lt(t){return{type:"text",text:t}}function g2(t,e){return{type:"image",data:t,mimeType:e}}var Dn=O(()=>{"use strict"});function Sre(){return gJe}function MI(){let t=process.env.XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS;if(!t)return!1;let e=t.trim().toLowerCase();return["1","true","yes","on"].includes(e)}function Jh(t){let e={};for(let[r,n]of Object.entries(t??{})){if(n==null)continue;let o=r.startsWith("TEST_RUNNER_")?r:`TEST_RUNNER_${r}`;e[o]=n}return e}var vre,_2,gJe,Xh=O(()=>{"use strict";vre=require("child_process");Go();_2=class{isRunningUnderClaudeCode(){if(process.env.VITEST==="true")return!1;if(process.env.CLAUDECODE==="1"||process.env.CLAUDE_CODE_ENTRYPOINT==="cli")return!0;try{let e=process.ppid;if(e&&(0,vre.execSync)(`ps -o command= -p ${e}`,{encoding:"utf8",timeout:1e3}).trim().includes("claude"))return!0}catch(e){A("debug",`Failed to detect parent process: ${e}`)}return!1}},gJe=new _2});function le(t,e=!1){return{content:[{type:"text",text:t}],isError:e}}function DI(t,e){return(e?e.existsSync(t):yre.existsSync(t))?{isValid:!0}:{isValid:!1,errorResponse:le(`File not found: '${t}'. Please check the path and try again.`,!0)}}function Sp(t){if(!Sre().isRunningUnderClaudeCode()||!t.content||t.content.length<=1)return t;let r=[];if(t.content.forEach((o,i)=>{o.type==="text"&&(i>0&&r.length>0&&r.push(` --- `),r.push(o.text))}),r.length===0)return t;let n=r.join("");return{...t,content:[{type:"text",text:n}]}}var yre,Qh=O(()=>{"use strict";yre=W(require("fs"),1);Go();Dn();Xh()});function ge(t,e){let r=e?` Details: ${e}`:"";return{content:[{type:"text",text:`Error: ${t}${r}`}],isError:!0}}var eg,Ka,at,v2,gt,sr,yp=O(()=>{"use strict";eg=class t extends Error{constructor(e){super(e),this.name="XcodeBuildMCPError",Object.setPrototypeOf(this,t.prototype)}},Ka=class t extends eg{constructor(r,n){super(r);this.paramName=n;this.name="ValidationError",Object.setPrototypeOf(this,t.prototype)}},at=class t extends eg{constructor(r,n){super(r);this.originalError=n;this.name="SystemError",Object.setPrototypeOf(this,t.prototype)}},v2=class t extends eg{constructor(e){super(e),this.name="ConfigurationError",Object.setPrototypeOf(this,t.prototype)}},gt=class t extends eg{constructor(r,n,o,i){super(r);this.command=n;this.axeOutput=o;this.simulatorId=i;this.name="AxeError",Object.setPrototypeOf(this,t.prototype)}};sr=class t extends v2{constructor(r,n){super(r);this.details=n;this.name="DependencyError",Object.setPrototypeOf(this,t.prototype)}}});var hr=O(()=>{"use strict";Qh();yp()});var S2,gs,tg=O(()=>{"use strict";Go();S2=class{defaults={};setDefaults(e){this.defaults={...this.defaults,...e},A("info",`[Session] Defaults updated: ${Object.keys(e).join(", ")}`)}clear(e){if(e==null){this.defaults={},A("info","[Session] All defaults cleared");return}if(e.length===0){A("info","[Session] No keys provided to clear; no changes made");return}for(let r of e)delete this.defaults[r];A("info",`[Session] Defaults cleared: ${e.join(", ")}`)}get(e){return this.defaults[e]}getAll(){return{...this.defaults}}},gs=new S2});function Ht(t,e,r){return async n=>{try{let o=t.parse(n);return await e(o,r())}catch(o){if(o instanceof DP){let i=`Invalid parameters: diff --git a/AGENTS.md b/AGENTS.md index e7881092..133c4664 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,7 +104,7 @@ npx reloaderoo proxy --log-level debug -- node build/index.js - ✅ **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 +For complete documentation, examples, and troubleshooting, see @docs/dev/RELOADEROO.md ## Architecture Overview @@ -116,13 +116,13 @@ XcodeBuildMCP uses the concept of configuration by convention for MCP exposing a 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 +For more information see @docs/dev/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 +For more information see @docs/dev/PLUGIN_DEVELOPMENT.md ### Tool Registration @@ -141,7 +141,7 @@ XcodeBuildMCP loads tools at startup. To limit the toolset, set `XCODEBUILDMCP_E 5. **Shared Utilities**: Command execution, build management, validation 6. **Types**: Shared interfaces and Zod schemas -For more information see @docs/ARCHITECTURE.md +For more information see @docs/dev/ARCHITECTURE.md ## Testing @@ -155,7 +155,7 @@ The project enforces a strict **Dependency Injection (DI)** testing philosophy. 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. +For complete guidelines, refer to @docs/dev/TESTING.md. ## TypeScript Import Standards @@ -189,7 +189,7 @@ This ensures all new code follows the `.ts` import pattern and maintains compati 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 +For complete guidelines, refer to @docs/dev/RELEASE_PROCESS.md ## Useful external resources diff --git a/README-ext.md b/README-ext.md deleted file mode 100644 index fddc034b..00000000 --- a/README-ext.md +++ /dev/null @@ -1,316 +0,0 @@ -XcodeBuild MCP - -A Model Context Protocol (MCP) server that provides Xcode-related tools for integration with AI assistants and other MCP clients. - -## Table of contents - -- [Overview](#overview) -- [Why?](#why) -- [Features](#features) - - [Xcode project management](#xcode-project-management) - - [Swift Package Manager](#swift-package-manager) - - [Simulator management](#simulator-management) - - [Device management](#device-management) - - [App utilities](#app-utilities) - - [MCP Resources](#mcp-resources) -- [Getting started](#getting-started) - - [Prerequisites](#prerequisites) - - [One click install](#one-click-install) - - [Manual installation](#manual-installation) - - [Specific client installation instructions](#specific-client-installation-instructions) - - [OpenAI Codex CLI](#openai-codex-cli) - - [Claude Code CLI](#claude-code-cli) -- [Incremental build support](#incremental-build-support) -- [Workflow Selection](#workflow-selection) -- [Session-aware opt-out](#session-aware-opt-out) -- [Code Signing for Device Deployment](#code-signing-for-device-deployment) -- [Troubleshooting](#troubleshooting) - - [Doctor Tool](#doctor-tool) -- [Privacy](#privacy) - - [What is sent to Sentry?](#what-is-sent-to-sentry) - - [Opting Out of Sentry](#opting-out-of-sentry) -- [Demos](#demos) - - [Autonomously fixing build errors in Cursor](#autonomously-fixing-build-errors-in-cursor) - - [Utilising the new UI automation and screen capture features](#utilising-the-new-ui-automation-and-screen-capture-features) - - [Building and running iOS app in Claude Desktop](#building-and-running-ios-app-in-claude-desktop) -- [Contributing](#contributing) - -## Overview - -XcodeBuildMCP is a Model Context Protocol (MCP) server that exposes Xcode operations as tools and resources for AI assistants and other MCP clients. Built with a modern plugin architecture, it provides a comprehensive set of self-contained tools organized into workflow-based directories, plus MCP resources for efficient data access, enabling programmatic interaction with Xcode projects, simulators, devices, and Swift packages through a standardized interface. - -![xcodebuildmcp2](https://github.com/user-attachments/assets/8961d5db-f7ed-4e60-bbb8-48bfd0bc1353) -Using Cursor to build, install, and launch an app on the iOS simulator while capturing logs at run-time. - -## Why? - -The XcodeBuild MCP tool exists primarily to streamline and standardise interaction between AI agents and Xcode projects. By providing dedicated tools for common Xcode operations, it removes reliance on manual or potentially incorrect command-line invocations. - -This ensures a reliable and efficient development process, allowing agents to seamlessly leverage Xcode's capabilities while reducing the risk of configuration errors. - -Critically, this MCP enables AI agents to independently validate code changes by building projects, inspecting errors, and iterating autonomously. In contrast to user-driven tools like Sweetpad, XcodeBuild MCP empowers agents to automate these workflows effectively. - -## Features - -The XcodeBuildMCP server provides the following tool capabilities: - -### Xcode project management -- **Discover Projects**: Xcode projects and workspaces discovery -- **Build Operations**: Platform-specific build tools for macOS, iOS simulator, and iOS device targets -- **Project Information**: Tools to list schemes and show build settings for Xcode projects and workspaces -- **Clean Operations**: Clean build products using xcodebuild's native clean action -- **Incremental build support**: Lightning fast builds using incremental build support (experimental, opt-in required) -- **Project Scaffolding**: Create new iOS and macOS projects from modern templates with workspace + SPM package architecture, customizable bundle identifiers, deployment targets, and device families - -### Swift Package Manager -- **Build Packages**: Build Swift packages with configuration and architecture options -- **Run Tests**: Execute Swift package test suites with filtering and parallel execution -- **Run Executables**: Execute package binaries with timeout handling and background execution support -- **Process Management**: List and stop long-running executables started with Swift Package tools -- **Clean Artifacts**: Remove build artifacts and derived data for fresh builds - -### Simulator management -- **Simulator Control**: List, boot, and open simulators -- **App Lifecycle**: Complete app management - install, launch, and stop apps on simulators -- **Log Capture**: Capture run-time logs from a simulator -- **UI Automation**: Interact with simulator UI elements -- **Screenshot**: Capture screenshots from a simulator -- **Video Capture**: Start/stop simulator video capture to MP4 (AXe v1.1.0+) - -### Device management -- **Device Discovery**: List connected physical Apple devices over USB or Wi-Fi -- **App Lifecycle**: Complete app management - build, install, launch, and stop apps on physical devices -- **Testing**: Run test suites on physical devices with detailed results and cross-platform support -- **Log Capture**: Capture console output from apps running on physical Apple devices -- **Wireless Connectivity**: Support for devices connected over Wi-Fi networks - -### App utilities -- **Bundle ID Extraction**: Extract bundle identifiers from app bundles across all Apple platforms -- **App Lifecycle Management**: Complete app lifecycle control across all platforms - - Launch apps on simulators, physical devices, and macOS - - Stop running apps with process ID or bundle ID management - - Process monitoring and control for comprehensive app management - -### MCP Resources - -For clients that support MCP resources XcodeBuildMCP provides efficient URI-based data access: - -- **Simulators Resource** (`xcodebuildmcp://simulators`): Direct access to available iOS simulators with UUIDs and states -- **Devices Resource** (`xcodebuildmcp://devices`): Direct access to connected physical Apple devices with UDIDs and states -- **Doctor Resource** (`xcodebuildmcp://doctor`): Direct access to environment information such as Xcode version, macOS version, and Node.js version - -## Getting started - -### Prerequisites - -- macOS 14.5 or later -- Xcode 16.x or later -- Node 18.x or later - -> Video capture requires the bundled AXe binary (v1.1.0+). Run `npm run bundle:axe` once locally before using `record_sim_video`. This is not required for unit tests. - -Configure your MCP client - -#### One click install - -If you're using Curor or VS Code you can use one the below quick install links to install XcodeBuildMCP. - -[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=XcodeBuildMCP&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IC15IHhjb2RlYnVpbGRtY3BAbGF0ZXN0IiwiZW52Ijp7IklOQ1JFTUVOVEFMX0JVSUxEU19FTkFCTEVEIjoiZmFsc2UiLCJYQ09ERUJVSUxETUNQX1NFTlRSWV9ESVNBQkxFRCI6ImZhbHNlIn19) - -[Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=XcodeBuildMCP&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%5D%7D) - -[Install in VS Code Insiders](https://insiders.vscode.dev/redirect/mcp/install?name=XcodeBuildMCP&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%5D%7D&quality=insiders) - -#### Manual installation - -Most MCP clients (Cursor, VS Code, Windsurf, Claude Desktop etc) have standardised on the following JSON configuration format, just add the the following to your client's JSON configuration's `mcpServers` object: - -```json -"XcodeBuildMCP": { - "command": "npx", - "args": [ - "-y", - "xcodebuildmcp@latest" - ] -} -``` - -#### Specific client installation instructions - -##### OpenAI Codex CLI - -Codex uses a toml configuration file to configure MCP servers. To configure XcodeBuildMCP with [OpenAI's Codex CLI](https://github.com/openai/codex), add the following configuration to your Codex CLI config file: - -```toml -[mcp_servers.XcodeBuildMCP] -command = "npx" -args = ["-y", "xcodebuildmcp@latest"] -env = { "INCREMENTAL_BUILDS_ENABLED" = "false", "XCODEBUILDMCP_SENTRY_DISABLED" = "false" } -``` - -If you see tool calls timing out in Codex (for example, `timed out awaiting tools/call after 60s`), increase the Codex tool timeout in your config: - -```toml -tool_timeout_sec = 600 -``` - -For more information see [OpenAI Codex MCP Server Configuration](https://github.com/openai/codex/blob/main/docs/config.md#connecting-to-mcp-servers) documentation. - -##### Claude Code CLI - -To use XcodeBuildMCP with [Claude Code](https://code.anthropic.com), you can add it via the command line: - -```bash -# Add XcodeBuildMCP server to Claude Code -claude mcp add XcodeBuildMCP npx xcodebuildmcp@latest - -# Or with environment variables -claude mcp add XcodeBuildMCP npx xcodebuildmcp@latest -e INCREMENTAL_BUILDS_ENABLED=false -e XCODEBUILDMCP_SENTRY_DISABLED=false -``` - -> [!IMPORTANT] -> Please note that XcodeBuildMCP will request xcodebuild to skip macro validation. This is to avoid errors when building projects that use Swift Macros. - -## Incremental build support - -XcodeBuildMCP includes experimental support for incremental builds. This feature is disabled by default and can be enabled by setting the `INCREMENTAL_BUILDS_ENABLED` environment variable to `true`: - -To enable incremental builds, set the `INCREMENTAL_BUILDS_ENABLED` environment variable to `true`: - -Example MCP configuration: -```json -"XcodeBuildMCP": { - ... - "env": { - "INCREMENTAL_BUILDS_ENABLED": "true" - } -} -``` - -> [!IMPORTANT] -> Please note that incremental builds support is currently highly experimental and your mileage may vary. Please report any issues you encounter to the [issue tracker](https://github.com/cameroncooke/XcodeBuildMCP/issues). - -## Workflow Selection - -By default, XcodeBuildMCP loads all tools at startup. If you want a smaller tool surface for a specific workflow, set `XCODEBUILDMCP_ENABLED_WORKFLOWS` to a comma-separated list of workflow directory names. The `session-management` workflow is always auto-included since other tools depend on it. - -Example MCP client configuration: -```json -"XcodeBuildMCP": { - ... - "env": { - "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,device,project-discovery" - } -} -``` - -**Available Workflows:** -- `device` (7 tools) - iOS Device Development -- `simulator` (12 tools) - iOS Simulator Development -- `simulator-management` (5 tools) - Simulator Management -- `swift-package` (6 tools) - Swift Package Manager -- `project-discovery` (5 tools) - Project Discovery -- `macos` (6 tools) - macOS Development -- `ui-testing` (11 tools) - UI Testing & Automation -- `logging` (4 tools) - Log Capture & Management -- `project-scaffolding` (2 tools) - Project Scaffolding -- `utilities` (1 tool) - Project Utilities -- `doctor` (1 tool) - System Doctor - -## Session-aware opt-out - -By default, XcodeBuildMCP uses a session-aware mode: the LLM (or client) sets shared defaults once (simulator, device, project/workspace, scheme, etc.), and all tools reuse them—similar to choosing a scheme and simulator in Xcode’s UI so you don’t repeat them on every action. This cuts context bloat not just in each call payload, but also in the tool schemas themselves (those parameters don’t have to be described on every tool). - -If you prefer the older, explicit style where each tool requires its own parameters, set `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS=true`. This restores the legacy schemas with per-call parameters while still honoring any session defaults you choose to set. - -Example MCP client configuration: -```json -"XcodeBuildMCP": { - ... - "env": { - "XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS": "true" - } -} -``` - -Leave this unset for the streamlined session-aware experience; enable it to force explicit parameters on each tool call. - -## Code Signing for Device Deployment - -For device deployment features to work, code signing must be properly configured in Xcode **before** using XcodeBuildMCP device tools: - -1. Open your project in Xcode -2. Select your project target -3. Go to "Signing & Capabilities" tab -4. Configure "Automatically manage signing" and select your development team -5. Ensure a valid provisioning profile is selected - -> **Note**: XcodeBuildMCP cannot configure code signing automatically. This initial setup must be done once in Xcode, after which the MCP device tools can build, install, and test apps on physical devices. - -## Troubleshooting - -If you encounter issues with XcodeBuildMCP, the doctor tool can help identify the problem by providing detailed information about your environment and dependencies. - -### Doctor Tool - -The doctor tool is a standalone utility that checks your system configuration and reports on the status of all dependencies required by XcodeBuildMCP. It's particularly useful when reporting issues. - -```bash -# Run the doctor tool using npx -npx --package xcodebuildmcp@latest xcodebuildmcp-doctor -``` - -The doctor tool will output comprehensive information about: - -- System and Node.js environment -- Xcode installation and configuration -- Required dependencies (xcodebuild, AXe, etc.) -- Environment variables affecting XcodeBuildMCP -- Feature availability status - -When reporting issues on GitHub, please include the full output from the doctor tool to help with troubleshooting. - -## Privacy - -This project uses [Sentry](https://sentry.io/) for error monitoring and diagnostics. Sentry helps us track issues, crashes, and unexpected errors to improve the reliability and stability of XcodeBuildMCP. - -### What is sent to Sentry? -- Only error-level logs and diagnostic information are sent to Sentry by default. -- Error logs may include details such as error messages, stack traces, and (in some cases) file paths or project names. You can review the sources in this repository to see exactly what is logged. - -### Opting Out of Sentry -- If you do not wish to send error logs to Sentry, you can opt out by setting the environment variable `XCODEBUILDMCP_SENTRY_DISABLED=true`. - -Example MCP client configuration: -```json -"XcodeBuildMCP": { - ... - "env": { - "XCODEBUILDMCP_SENTRY_DISABLED": "true" - } -} -``` - -## Demos - -### Autonomously fixing build errors in Cursor -![xcodebuildmcp3](https://github.com/user-attachments/assets/173e6450-8743-4379-a76c-de2dd2b678a3) - -### Utilising the new UI automation and screen capture features - -![xcodebuildmcp4](https://github.com/user-attachments/assets/17300a18-f47a-428a-aad3-dc094859c1b2) - -### Building and running iOS app in Claude Desktop -https://github.com/user-attachments/assets/e3c08d75-8be6-4857-b4d0-9350b26ef086 - -## Contributing - -[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/node->=18.x-brightgreen.svg)](https://nodejs.org/) - -Contributions are welcome! Here's how you can help improve XcodeBuildMCP. - -See our documentation for development: -- [CONTRIBUTING](docs/CONTRIBUTING.md) - Contribution guidelines and development setup -- [CODE_QUALITY](docs/CODE_QUALITY.md) - Code quality standards, linting, and architectural rules -- [TESTING](docs/TESTING.md) - Testing principles and patterns -- [ARCHITECTURE](docs/ARCHITECTURE.md) - System architecture and design principles \ No newline at end of file diff --git a/README.md b/README.md index a86b5f0e..910b7694 100644 --- a/README.md +++ b/README.md @@ -77,14 +77,29 @@ npx -y @smithery/cli@latest install cameroncooke/xcodebuildmcp --client client-n For more installation options see: [Smithery XcodeBuildMCP](https://smithery.ai/server/cameroncooke/xcodebuildmcp). ->[!NOTE] -> XcodeBuildMCP requires Node 18.x or later and Xcode 16.x or later to be installed. +## Requirements -## View the full Readme +- macOS 14.5 or later +- Xcode 16.x or later +- Node.js 18.x or later -To read the full Readme with manual installation instructions, configuration options, feature list and demos click the link below. +## Notes -[View the full Readme](README-ext.md) +- XcodeBuildMCP requests xcodebuild to skip macro validation to avoid errors when building projects that use Swift Macros. +- Device tools require code signing to be configured in Xcode. See [docs/DEVICE_CODE_SIGNING.md](docs/DEVICE_CODE_SIGNING.md). + +## Privacy + +XcodeBuildMCP uses Sentry for error telemetry. For more information or to opt out of error telemetry see [docs/PRIVACY.md](docs/PRIVACY.md). + +## Documentation + +- Getting started: [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) +- Configuration and options: [docs/CONFIGURATION.md](docs/CONFIGURATION.md) +- Tools reference: [docs/TOOLS.md](docs/TOOLS.md) +- Troubleshooting: [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) +- Privacy: [docs/PRIVACY.md](docs/PRIVACY.md) +- Contributing: [docs/dev/CONTRIBUTING.md](docs/dev/CONTRIBUTING.md) ## Licence diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 00000000..ac9d3b11 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,58 @@ +# Configuration + +XcodeBuildMCP is configured through environment variables provided by your MCP client. Here is a single example showing how to add options to a typical MCP config: + +```json +"XcodeBuildMCP": { + "command": "npx", + "args": ["-y", "xcodebuildmcp@latest"], + "env": { + "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,device,project-discovery", + "INCREMENTAL_BUILDS_ENABLED": "false", + "XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS": "false", + "XCODEBUILDMCP_SENTRY_DISABLED": "false" + } +} +``` + +## Workflow selection + +By default, XcodeBuildMCP loads all tools at startup. If you want a smaller tool surface for a specific workflow, set `XCODEBUILDMCP_ENABLED_WORKFLOWS` to a comma-separated list of workflow directory names. The `session-management` workflow is always auto-included since other tools depend on it. + +**Available workflows:** +- `device` (7 tools) - iOS Device Development +- `simulator` (12 tools) - iOS Simulator Development +- `simulator-management` (5 tools) - Simulator Management +- `swift-package` (6 tools) - Swift Package Manager +- `project-discovery` (5 tools) - Project Discovery +- `macos` (6 tools) - macOS Development +- `ui-testing` (11 tools) - UI Testing & Automation +- `logging` (4 tools) - Log Capture & Management +- `project-scaffolding` (2 tools) - Project Scaffolding +- `utilities` (1 tool) - Project Utilities +- `doctor` (1 tool) - System Doctor + +## Incremental build support + +XcodeBuildMCP includes experimental support for incremental builds. This feature is disabled by default and can be enabled by setting the `INCREMENTAL_BUILDS_ENABLED` environment variable to `true`. + +> [!IMPORTANT] +> Incremental builds are highly experimental and your mileage may vary. Please report issues to the [issue tracker](https://github.com/cameroncooke/XcodeBuildMCP/issues). + +## Session-aware opt-out + +By default, XcodeBuildMCP uses a session-aware mode: the LLM (or client) sets shared defaults once (simulator, device, project/workspace, scheme, etc.), and all tools reuse them. This cuts context bloat not just in each call payload, but also in the tool schemas themselves. + +If you prefer the older, explicit style where each tool requires its own parameters, set `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS=true`. This restores the legacy schemas with per-call parameters while still honoring any session defaults you choose to set. + +Leave this unset for the streamlined session-aware experience; enable it to force explicit parameters on each tool call. + +## Sentry telemetry opt-out + +If you do not wish to send error logs to Sentry, set `XCODEBUILDMCP_SENTRY_DISABLED=true`. + +## Related docs +- Session defaults: [SESSION_DEFAULTS.md](SESSION_DEFAULTS.md) +- Tools reference: [TOOLS.md](TOOLS.md) +- Privacy and telemetry: [PRIVACY.md](PRIVACY.md) +- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) diff --git a/docs/DEMOS.md b/docs/DEMOS.md new file mode 100644 index 00000000..80bd1b12 --- /dev/null +++ b/docs/DEMOS.md @@ -0,0 +1,15 @@ +# Demos + +## Autonomously fixing build errors in Cursor +![xcodebuildmcp3](https://github.com/user-attachments/assets/173e6450-8743-4379-a76c-de2dd2b678a3) + +## Utilising the new UI automation and screen capture features +![xcodebuildmcp4](https://github.com/user-attachments/assets/17300a18-f47a-428a-aad3-dc094859c1b2) + +## Building and running iOS app in Claude Desktop +https://github.com/user-attachments/assets/e3c08d75-8be6-4857-b4d0-9350b26ef086 + +## Related docs +- Getting started: [GETTING_STARTED.md](GETTING_STARTED.md) +- Tools reference: [TOOLS.md](TOOLS.md) +- Session defaults: [SESSION_DEFAULTS.md](SESSION_DEFAULTS.md) diff --git a/docs/DEVICE_CODE_SIGNING.md b/docs/DEVICE_CODE_SIGNING.md new file mode 100644 index 00000000..f6bd7292 --- /dev/null +++ b/docs/DEVICE_CODE_SIGNING.md @@ -0,0 +1,18 @@ +# Device Code Signing + +For device deployment features to work, code signing must be configured in Xcode before using XcodeBuildMCP device tools. + +## One-time setup in Xcode +1. Open your project in Xcode. +2. Select your project target. +3. Open the "Signing & Capabilities" tab. +4. Enable "Automatically manage signing" and select your development team. +5. Ensure a valid provisioning profile is selected. + +## What XcodeBuildMCP can and cannot do +- Can build, install, launch, and test once signing is configured. +- Cannot configure code signing automatically. + +## Related docs +- Tools reference: [TOOLS.md](TOOLS.md) +- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md new file mode 100644 index 00000000..d9e3cea5 --- /dev/null +++ b/docs/GETTING_STARTED.md @@ -0,0 +1,73 @@ +# Getting Started + +## Prerequisites +- macOS 14.5 or later +- Xcode 16.x or later +- Node.js 18.x or later + +## Install options + +### Smithery (recommended) +```bash +npx -y @smithery/cli@latest install cameroncooke/xcodebuildmcp --client client-name +``` + +### One click install +If you are using Cursor or VS Code you can use the quick install links below. + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=XcodeBuildMCP&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IC15IHhjb2RlYnVpbGRtY3BAbGF0ZXN0IiwiZW52Ijp7IklOQ1JFTUVOVEFMX0JVSUxEU19FTkFCTEVEIjoiZmFsc2UiLCJYQ09ERUJVSUxETUNQX1NFTlRSWV9ESVNBQkxFRCI6ImZhbHNlIn19) + +[Install in VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=XcodeBuildMCP&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%5D%7D) + +[Install in VS Code Insiders](https://insiders.vscode.dev/redirect/mcp/install?name=XcodeBuildMCP&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22xcodebuildmcp%40latest%22%5D%7D&quality=insiders) + +### Manual installation +Most MCP clients use JSON configuration. Add the following to your client configuration under `mcpServers`: + +```json +"XcodeBuildMCP": { + "command": "npx", + "args": [ + "-y", + "xcodebuildmcp@latest" + ] +} +``` + +## Client-specific configuration + +### OpenAI Codex CLI +Codex uses TOML for MCP configuration. Add this to your Codex CLI config file: + +```toml +[mcp_servers.XcodeBuildMCP] +command = "npx" +args = ["-y", "xcodebuildmcp@latest"] +env = { "INCREMENTAL_BUILDS_ENABLED" = "false", "XCODEBUILDMCP_SENTRY_DISABLED" = "false" } +``` + +If you see tool calls timing out (for example, `timed out awaiting tools/call after 60s`), increase the timeout: + +```toml +tool_timeout_sec = 600 +``` + +For more info see the OpenAI Codex configuration docs: +https://github.com/openai/codex/blob/main/docs/config.md#connecting-to-mcp-servers + +### Claude Code CLI +```bash +# Add XcodeBuildMCP server to Claude Code +claude mcp add XcodeBuildMCP npx xcodebuildmcp@latest + +# Or with environment variables +claude mcp add XcodeBuildMCP npx xcodebuildmcp@latest -e INCREMENTAL_BUILDS_ENABLED=false -e XCODEBUILDMCP_SENTRY_DISABLED=false +``` + +Note: XcodeBuildMCP requests xcodebuild to skip macro validation to avoid Swift Macro build errors. + +## Next steps +- Configuration options: [CONFIGURATION.md](CONFIGURATION.md) +- Session defaults and opt-out: [SESSION_DEFAULTS.md](SESSION_DEFAULTS.md) +- Tools reference: [TOOLS.md](TOOLS.md) +- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md new file mode 100644 index 00000000..b32646e4 --- /dev/null +++ b/docs/OVERVIEW.md @@ -0,0 +1,23 @@ +# Overview + +XcodeBuildMCP is a Model Context Protocol (MCP) server that exposes Xcode operations as tools and resources for AI assistants and other MCP clients. It uses a plugin-based architecture with workflow groups so clients can access Xcode projects, simulators, devices, and Swift packages through a standard interface. + +## Why it exists +- Standardizes Xcode interactions for AI agents instead of ad-hoc command lines. +- Reduces configuration errors by providing purpose-built tools. +- Enables agents to build, inspect errors, and iterate autonomously. + +## What it can do +- Xcode project discovery, build, test, and clean. +- Simulator and device app lifecycle management. +- Swift Package Manager build, test, and run. +- UI automation, screenshots, and video capture. +- Log capture and system diagnostics. + +See the full tool catalog in [TOOLS.md](TOOLS.md). + +## Next steps +- Get started: [GETTING_STARTED.md](GETTING_STARTED.md) +- Configure options: [CONFIGURATION.md](CONFIGURATION.md) +- Tools reference: [TOOLS.md](TOOLS.md) +- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md new file mode 100644 index 00000000..652f658c --- /dev/null +++ b/docs/PRIVACY.md @@ -0,0 +1,20 @@ +# Privacy + +XcodeBuildMCP uses Sentry for error monitoring and diagnostics. This helps track crashes and unexpected errors to improve reliability. + +## What is sent to Sentry +- Error-level logs and diagnostic information only. +- Error logs may include error messages, stack traces, and in some cases file paths or project names. + +## Opting out +To disable error telemetry, set: + +```json +"env": { + "XCODEBUILDMCP_SENTRY_DISABLED": "true" +} +``` + +## Related docs +- Configuration options: [CONFIGURATION.md](CONFIGURATION.md) +- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..b639733e --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ +# XcodeBuildMCP Documentation + +## Start here +- [Getting started](GETTING_STARTED.md) +- [Configuration and options](CONFIGURATION.md) +- [Tools reference (all workflows/tools)](TOOLS.md) +- [Troubleshooting and doctor](TROUBLESHOOTING.md) +- [Privacy and telemetry](PRIVACY.md) +- [Demos](DEMOS.md) + +## User guides +- [Product overview and rationale](OVERVIEW.md) +- [Session defaults and opt-out](SESSION_DEFAULTS.md) +- [Device code signing notes](DEVICE_CODE_SIGNING.md) + +## Developer docs +- [Developer documentation index](dev/README.md) +- [Contributing guide](dev/CONTRIBUTING.md) +- [Architecture](dev/ARCHITECTURE.md) +- [Testing](dev/TESTING.md) +- [Code quality rules](dev/CODE_QUALITY.md) +- [Plugin development](dev/PLUGIN_DEVELOPMENT.md) +- [Release process](dev/RELEASE_PROCESS.md) + +## Generated docs +- [TOOLS.md](TOOLS.md) is generated by `scripts/update-tools-docs.ts`. diff --git a/docs/SESSION_DEFAULTS.md b/docs/SESSION_DEFAULTS.md new file mode 100644 index 00000000..917b3e8c --- /dev/null +++ b/docs/SESSION_DEFAULTS.md @@ -0,0 +1,26 @@ +# Session Defaults + +By default, XcodeBuildMCP uses a session-aware mode. The client sets shared defaults once (simulator, device, project/workspace, scheme, etc.) and all tools reuse them. This reduces schema size and repeated payloads. + +## How it works +- Call `session_set_defaults` once at the start of a workflow. +- Tools reuse those defaults automatically. +- Use `session_show_defaults` to inspect current values. +- Use `session_clear_defaults` to clear values when switching contexts. + +See the session-management tools in [TOOLS.md](TOOLS.md). + +## Opting out +If you prefer explicit parameters on every tool call, set: + +```json +"env": { + "XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS": "true" +} +``` + +This restores the legacy schemas with per-call parameters while still honoring any defaults you choose to set. + +## Related docs +- Configuration options: [CONFIGURATION.md](CONFIGURATION.md) +- Tools reference: [TOOLS.md](TOOLS.md) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 00000000..d044fdd5 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,37 @@ +# Troubleshooting + +## Quick triage +- Run the doctor tool and include output when filing issues. +- Confirm Xcode and Command Line Tools are installed. +- Verify required workflows are enabled in configuration. +- Check simulator/device availability and permissions. + +## Doctor tool +The doctor tool checks system configuration and reports on all dependencies required by XcodeBuildMCP. + +```bash +npx --package xcodebuildmcp@latest xcodebuildmcp-doctor +``` + +It reports on: +- System and Node.js environment +- Xcode installation and configuration +- Required dependencies (xcodebuild, AXe, etc.) +- Environment variables affecting XcodeBuildMCP +- Feature availability status + +> [!NOTE] +> You can also ask you agent to run the doctor tool which will provide a more representative output. + +## Common issues + +### Tool timeouts +Some clients have short tool timeouts. If you see timeouts, increase the client timeout (for example, `tool_timeout_sec = 600` in Codex). + +### Missing tools +If tools do not appear, verify `XCODEBUILDMCP_ENABLED_WORKFLOWS` includes the required workflow groups. + +## Related docs +- Configuration options: [CONFIGURATION.md](CONFIGURATION.md) +- Tools reference: [TOOLS.md](TOOLS.md) +- Privacy and telemetry: [PRIVACY.md](PRIVACY.md) diff --git a/docs/ARCHITECTURE.md b/docs/dev/ARCHITECTURE.md similarity index 98% rename from docs/ARCHITECTURE.md rename to docs/dev/ARCHITECTURE.md index 0655827c..51ea4463 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/dev/ARCHITECTURE.md @@ -262,7 +262,7 @@ This pattern ensures that: ### MCP Resources System -XcodeBuildMCP provides dual interfaces: traditional MCP tools and efficient MCP resources for supported clients. Resources are located in `src/mcp/resources/` and are automatically discovered **at build time**. The build process generates `src/core/generated-resources.ts`, which contains dynamic loaders for each resource, improving startup performance. For more details on creating resources, see the [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md). +XcodeBuildMCP provides dual interfaces: traditional MCP tools and efficient MCP resources for supported clients. Resources are located in `src/mcp/resources/` and are automatically discovered **at build time**. The build process generates `src/core/generated-resources.ts`, which contains dynamic loaders for each resource, improving startup performance. For more details on creating resources, see the [Plugin Development Guide](PLUGIN_DEVELOPMENT.md). #### Resource Architecture @@ -411,7 +411,7 @@ Not all parts are required for every tool. For example, `swift_package_build` ha XcodeBuildMCP uses a strict **Dependency Injection (DI)** pattern for testing, which completely bans the use of traditional mocking libraries like Vitest's `vi.mock` or `vi.fn`. This ensures that tests are robust, maintainable, and verify the actual integration between components. -For detailed guidelines, see the [Testing Guide](docs/TESTING.md). +For detailed guidelines, see the [Testing Guide](TESTING.md). ### Test Structure Example @@ -499,7 +499,7 @@ bundled/ ## Extension Guidelines -This project is designed to be extensible. For comprehensive instructions on creating new tools, workflow groups, and resources, please refer to the dedicated [**Plugin Development Guide**](docs/PLUGIN_DEVELOPMENT.md). +This project is designed to be extensible. For comprehensive instructions on creating new tools, workflow groups, and resources, please refer to the dedicated [**Plugin Development Guide**](PLUGIN_DEVELOPMENT.md). The guide covers: - The auto-discovery system architecture. diff --git a/docs/CODE_QUALITY.md b/docs/dev/CODE_QUALITY.md similarity index 98% rename from docs/CODE_QUALITY.md rename to docs/dev/CODE_QUALITY.md index 274f5ab1..b3a56b40 100644 --- a/docs/CODE_QUALITY.md +++ b/docs/dev/CODE_QUALITY.md @@ -35,7 +35,7 @@ The project uses a comprehensive ESLint setup that covers: ### ESLint Rules -For detailed ESLint rules and rationale, see [ESLINT_RULES.md](./ESLINT_RULES.md). +For detailed ESLint rules and rationale, see [ESLINT_TYPE_SAFETY.md](ESLINT_TYPE_SAFETY.md). ### Running ESLint @@ -300,4 +300,4 @@ If migration tooling reports incorrect status: 2. **IDE Integration**: Create VS Code extension for real-time checking 3. **Performance Metrics**: Add build and test performance tracking 4. **Complexity Analysis**: Add code complexity metrics -5. **Documentation Linting**: Add documentation quality checks \ No newline at end of file +5. **Documentation Linting**: Add documentation quality checks diff --git a/docs/CONTRIBUTING.md b/docs/dev/CONTRIBUTING.md similarity index 94% rename from docs/CONTRIBUTING.md rename to docs/dev/CONTRIBUTING.md index 82aec783..fc77060b 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/dev/CONTRIBUTING.md @@ -201,9 +201,9 @@ Running the XcodeBuildMCP server with the environmental variable `XCODEBUILDMCP_ Before making changes, please familiarize yourself with: - [ARCHITECTURE.md](ARCHITECTURE.md) - Comprehensive architectural overview -- [CLAUDE.md](CLAUDE.md) - AI assistant guidelines and testing principles -- [TOOLS.md](TOOLS.md) - Complete tool documentation -- [TOOL_OPTIONS.md](TOOL_OPTIONS.md) - Tool configuration options +- [CLAUDE.md](../../CLAUDE.md) - AI assistant guidelines and testing principles +- [TOOLS.md](../TOOLS.md) - Complete tool documentation +- [CONFIGURATION.md](../CONFIGURATION.md) - Tool configuration options ### Code Quality Requirements @@ -215,7 +215,7 @@ Before making changes, please familiarize yourself with: ### Testing Standards -All contributions must adhere to the testing standards outlined in the [**XcodeBuildMCP Plugin Testing Guidelines (docs/TESTING.md)**](docs/TESTING.md). This is the canonical source of truth for all testing practices. +All contributions must adhere to the testing standards outlined in the [**XcodeBuildMCP Plugin Testing Guidelines (TESTING.md)**](TESTING.md). This is the canonical source of truth for all testing practices. **Key Principles (Summary):** - **No Vitest Mocking**: All forms of `vi.mock`, `vi.fn`, `vi.spyOn`, etc., are strictly forbidden. @@ -223,7 +223,7 @@ All contributions must adhere to the testing standards outlined in the [**XcodeB - **Test Production Code**: Tests must import and execute the actual tool logic, not mock implementations. - **Comprehensive Coverage**: Tests must cover input validation, command generation, and output processing. -Please read [docs/TESTING.md](docs/TESTING.md) in its entirety before writing tests. +Please read [TESTING.md](TESTING.md) in its entirety before writing tests. ### Pre-Commit Checklist @@ -253,7 +253,7 @@ npm test ## Plugin Development -For comprehensive instructions on creating new tools and workflow groups, see our dedicated [Plugin Development Guide](docs/PLUGIN_DEVELOPMENT.md). +For comprehensive instructions on creating new tools and workflow groups, see our dedicated [Plugin Development Guide](PLUGIN_DEVELOPMENT.md). The plugin development guide covers: - Auto-discovery system architecture @@ -270,7 +270,7 @@ The plugin development guide covers: 4. Create comprehensive tests using `createMockExecutor()` 5. Add workflow metadata if creating new workflow group -See [PLUGIN_DEVELOPMENT.md](docs/PLUGIN_DEVELOPMENT.md) for complete details. +See [PLUGIN_DEVELOPMENT.md](PLUGIN_DEVELOPMENT.md) for complete details. ### Working with Project Templates @@ -351,4 +351,4 @@ For major changes or new features, please open an issue first to discuss your pr ## Code of Conduct -Please follow our [Code of Conduct](CODE_OF_CONDUCT.md) and community guidelines. +Please follow our [Code of Conduct](../../CODE_OF_CONDUCT.md) and community guidelines. diff --git a/docs/ESLINT_TYPE_SAFETY.md b/docs/dev/ESLINT_TYPE_SAFETY.md similarity index 100% rename from docs/ESLINT_TYPE_SAFETY.md rename to docs/dev/ESLINT_TYPE_SAFETY.md diff --git a/docs/MANUAL_TESTING.md b/docs/dev/MANUAL_TESTING.md similarity index 99% rename from docs/MANUAL_TESTING.md rename to docs/dev/MANUAL_TESTING.md index 7b1ff02c..cee3b565 100644 --- a/docs/MANUAL_TESTING.md +++ b/docs/dev/MANUAL_TESTING.md @@ -277,6 +277,7 @@ Must capture and document these values for dependent tools: 1. **Build the server**: `npm run build` 2. **Install jq**: `brew install jq` (required for JSON parsing) 3. **System Requirements**: macOS with Xcode installed, connected devices/simulators optional +4. **AXe video capture (optional)**: run `npm run bundle:axe` before using `record_sim_video` in local tests (not required for unit tests) ## Step-by-Step Testing Process @@ -746,4 +747,4 @@ jq --arg tool "TOOL_NAME" '.tools[] | select(.name == $tool) | .description' /tm - Mark tool as "failed - empty response" in task list - Continue with next tool in sequence -This systematic approach ensures comprehensive, accurate testing using programmatic discovery and validation of all XcodeBuildMCP functionality through the MCP interface exclusively. \ No newline at end of file +This systematic approach ensures comprehensive, accurate testing using programmatic discovery and validation of all XcodeBuildMCP functionality through the MCP interface exclusively. diff --git a/docs/NODEJS_2025.md b/docs/dev/NODEJS_2025.md similarity index 100% rename from docs/NODEJS_2025.md rename to docs/dev/NODEJS_2025.md diff --git a/docs/PLUGIN_DEVELOPMENT.md b/docs/dev/PLUGIN_DEVELOPMENT.md similarity index 99% rename from docs/PLUGIN_DEVELOPMENT.md rename to docs/dev/PLUGIN_DEVELOPMENT.md index 9754b6f9..15f1f5e7 100644 --- a/docs/PLUGIN_DEVELOPMENT.md +++ b/docs/dev/PLUGIN_DEVELOPMENT.md @@ -673,7 +673,7 @@ npm run inspect ### Critical Documentation Maintenance -**Every time you add, change, move, edit, or delete a tool, you MUST review and update the `docs/TOOLS.md` file to reflect the current state of the codebase.** +**Every time you add, change, move, edit, or delete a tool, you MUST review and update the [TOOLS.md](../TOOLS.md) file to reflect the current state of the codebase.** ### Documentation Update Process @@ -694,7 +694,7 @@ This command: #### 2. Ignore Shared Groups in Documentation -When updating `docs/TOOLS.md`: +When updating [TOOLS.md](../TOOLS.md): - **Ignore `*-shared` directories** (e.g., `simulator-shared`, `device-shared`, `macos-shared`) - These are implementation details, not user-facing workflow groups @@ -746,7 +746,7 @@ Each tool must be listed individually with its actual description from the tool #### 6. Validation Checklist -After updating `docs/TOOLS.md`: +After updating [TOOLS.md](../TOOLS.md): - [ ] Tool counts match actual filesystem counts (from tree command) - [ ] Each tool has its own bullet point (one tool per line) diff --git a/docs/dev/README.md b/docs/dev/README.md new file mode 100644 index 00000000..1f15d544 --- /dev/null +++ b/docs/dev/README.md @@ -0,0 +1,26 @@ +# Developer Documentation + +## Getting started for contributors +- [Contributing guide](CONTRIBUTING.md) +- [Code quality standards](CODE_QUALITY.md) +- [Testing guidelines](TESTING.md) +- [Architecture overview](ARCHITECTURE.md) + +## Build and tooling +- [ESLint and type safety](ESLINT_TYPE_SAFETY.md) +- [Node.js and runtime notes](NODEJS_2025.md) +- [Smithery integration notes](SMITHERY.md) + +## Release and maintenance +- [Release process](RELEASE_PROCESS.md) +- [Manual testing](MANUAL_TESTING.md) + +## Deep dives and plans +- [Plugin development](PLUGIN_DEVELOPMENT.md) +- [Reloaderoo docs](RELOADEROO.md) +- [Reloaderoo primer](RELOADEROO_XCODEBUILDMCP_PRIMER.md) +- [Reloaderoo for XcodeBuildMCP](RELOADEROO_FOR_XCODEBUILDMCP.md) +- [Zod migration guide](ZOD_MIGRATION_GUIDE.md) +- [Test runner env plan](TEST_RUNNER_ENV_IMPLEMENTATION_PLAN.md) +- [Session management plan](session_management_plan.md) +- [Session-aware migration todo](session-aware-migration-todo.md) diff --git a/docs/RELEASE_PROCESS.md b/docs/dev/RELEASE_PROCESS.md similarity index 100% rename from docs/RELEASE_PROCESS.md rename to docs/dev/RELEASE_PROCESS.md diff --git a/docs/RELOADEROO.md b/docs/dev/RELOADEROO.md similarity index 100% rename from docs/RELOADEROO.md rename to docs/dev/RELOADEROO.md diff --git a/docs/RELOADEROO_FOR_XCODEBUILDMCP.md b/docs/dev/RELOADEROO_FOR_XCODEBUILDMCP.md similarity index 100% rename from docs/RELOADEROO_FOR_XCODEBUILDMCP.md rename to docs/dev/RELOADEROO_FOR_XCODEBUILDMCP.md diff --git a/docs/RELOADEROO_XCODEBUILDMCP_PRIMER.md b/docs/dev/RELOADEROO_XCODEBUILDMCP_PRIMER.md similarity index 100% rename from docs/RELOADEROO_XCODEBUILDMCP_PRIMER.md rename to docs/dev/RELOADEROO_XCODEBUILDMCP_PRIMER.md diff --git a/docs/SMITHERY.md b/docs/dev/SMITHERY.md similarity index 100% rename from docs/SMITHERY.md rename to docs/dev/SMITHERY.md diff --git a/docs/TESTING.md b/docs/dev/TESTING.md similarity index 100% rename from docs/TESTING.md rename to docs/dev/TESTING.md diff --git a/docs/TEST_RUNNER_ENV_IMPLEMENTATION_PLAN.md b/docs/dev/TEST_RUNNER_ENV_IMPLEMENTATION_PLAN.md similarity index 100% rename from docs/TEST_RUNNER_ENV_IMPLEMENTATION_PLAN.md rename to docs/dev/TEST_RUNNER_ENV_IMPLEMENTATION_PLAN.md diff --git a/docs/ZOD_MIGRATION_GUIDE.md b/docs/dev/ZOD_MIGRATION_GUIDE.md similarity index 100% rename from docs/ZOD_MIGRATION_GUIDE.md rename to docs/dev/ZOD_MIGRATION_GUIDE.md diff --git a/docs/session-aware-migration-todo.md b/docs/dev/session-aware-migration-todo.md similarity index 98% rename from docs/session-aware-migration-todo.md rename to docs/dev/session-aware-migration-todo.md index 0aee3a22..2da02f59 100644 --- a/docs/session-aware-migration-todo.md +++ b/docs/dev/session-aware-migration-todo.md @@ -2,7 +2,7 @@ _Audit date: October 6, 2025_ -Reference: `docs/session_management_plan.md` +Reference: [session_management_plan.md](session_management_plan.md) ## Utilities - [x] `src/mcp/tools/utilities/clean.ts` — session defaults: `projectPath`, `workspacePath`, `scheme`, `configuration`. diff --git a/docs/session_management_plan.md b/docs/dev/session_management_plan.md similarity index 100% rename from docs/session_management_plan.md rename to docs/dev/session_management_plan.md diff --git a/scripts/check-code-patterns.js b/scripts/check-code-patterns.js index a1aa1dd3..2f896766 100755 --- a/scripts/check-code-patterns.js +++ b/scripts/check-code-patterns.js @@ -17,7 +17,7 @@ * 4. NO handler signature violations (handlers must have exact MCP SDK signatures) * 5. NO handler testing violations (test logic functions, not handlers directly) * - * For comprehensive code quality documentation, see docs/CODE_QUALITY.md + * For comprehensive code quality documentation, see docs/dev/CODE_QUALITY.md * * Note: General code quality rules (TypeScript, ESLint) are handled by other tools. * This script only enforces XcodeBuildMCP-specific architectural patterns. @@ -810,4 +810,4 @@ function main() { process.exit(hasViolations || mixed.length > 0 ? 1 : 0); } -main(); \ No newline at end of file +main(); diff --git a/src/utils/command.ts b/src/utils/command.ts index 27924a20..2e35f4f5 100644 --- a/src/utils/command.ts +++ b/src/utils/command.ts @@ -203,7 +203,7 @@ export function getDefaultCommandExecutor(): CommandExecutor { `This test is trying to use the default command executor instead of a mock.\n` + `Fix: Pass createMockExecutor() as the commandExecutor parameter in your test.\n` + `Example: await plugin.handler(args, createMockExecutor({success: true}), mockFileSystem)\n` + - `See docs/TESTING.md for proper testing patterns.`, + `See docs/dev/TESTING.md for proper testing patterns.`, ); } return defaultExecutor; @@ -220,7 +220,7 @@ export function getDefaultFileSystemExecutor(): FileSystemExecutor { `This test is trying to use the default filesystem executor instead of a mock.\n` + `Fix: Pass createMockFileSystemExecutor() as the fileSystemExecutor parameter in your test.\n` + `Example: await plugin.handler(args, mockCmd, createMockFileSystemExecutor())\n` + - `See docs/TESTING.md for proper testing patterns.`, + `See docs/dev/TESTING.md for proper testing patterns.`, ); } return defaultFileSystemExecutor;