refactor(architecture): separate server, test, and pure utils to fix CI errors

Author: cameroncooke

README.md

@@ -362,7 +362,7 @@ This project uses [Sentry](https://sentry.io/) for error monitoring and diagnost
 - 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 `SENTRY_DISABLED=true`.
+- 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
@@ -375,7 +375,7 @@ Example MCP client configuration:
         "xcodebuildmcp@latest"
       ],
       "env": {
-        "SENTRY_DISABLED": "true"
+        "XCODEBUILDMCP_SENTRY_DISABLED": "true"
       }        
     }
   }

docs/TOOLS.md

@@ -1,12 +1,12 @@
 # XcodeBuildMCP Tools Reference
 
-XcodeBuildMCP provides 61 tools organized into 12 workflow groups for comprehensive Apple development workflows.
+XcodeBuildMCP provides 59 tools organized into 12 workflow groups for comprehensive Apple development workflows.
 
 ## Key Changes (v1.11+)
 
 **Unified Tool Architecture**: Tools that previously had separate variants (e.g., `build_sim_id`, `build_sim_name`) have been consolidated into unified tools that accept either parameter using XOR validation.
 
-**XOR Parameter Pattern**: Many tools now use mutually exclusive parameters (e.g., `simulatorId` OR `simulatorName`, never both) enforced via Zod schema refinements. This reduces the total tool count from ~85 to 61 while maintaining full functionality.
+**XOR Parameter Pattern**: Many tools now use mutually exclusive parameters (e.g., `simulatorId` OR `simulatorName`, never both) enforced via Zod schema refinements. This reduces the total tool count from ~85 to 59 while maintaining full functionality.
 
 ## Workflow Groups
 
@@ -27,21 +27,19 @@ XcodeBuildMCP provides 61 tools organized into 12 workflow groups for comprehens
 - `test_device` - Runs tests for an Apple project or workspace on a physical device (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro) using xcodebuild test and parses xcresult output. Provide exactly one of projectPath or workspacePath.
 
 ### iOS Simulator Development (`simulator`)
-**Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. Build, test, deploy, and interact with iOS apps on simulators. (13 tools)
+**Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. Build, test, deploy, and interact with iOS apps on simulators. (11 tools)
 
 - `boot_sim` - Boots an iOS simulator. After booting, use open_sim() to make the simulator visible.
-- `build_run_simulator` - Builds and runs an app from a project or workspace on a specific simulator by UUID or name. Provide exactly one of projectPath or workspacePath, and exactly one of simulatorId or simulatorName.
-- `build_simulator` - Builds an app from a project or workspace for a specific simulator by UUID or name. Provide exactly one of projectPath or workspacePath, and exactly one of simulatorId or simulatorName.
-- `get_simulator_app_path` - Gets the app bundle path for a simulator by UUID or name using either a project or workspace file.
+- `build_run_sim` - Builds and runs an app from a project or workspace on a specific simulator by UUID or name. Provide exactly one of projectPath or workspacePath, and exactly one of simulatorId or simulatorName.
+- `build_sim` - Builds an app from a project or workspace for a specific simulator by UUID or name. Provide exactly one of projectPath or workspacePath, and exactly one of simulatorId or simulatorName.
+- `get_sim_app_path` - Gets the app bundle path for a simulator by UUID or name using either a project or workspace file.
 - `install_app_sim` - Installs an app in an iOS simulator.
 - `launch_app_logs_sim` - Launches an app in an iOS simulator and captures its logs.
-- `launch_app_sim` - Launches an app in an iOS simulator. If simulator window isn't visible, use open_sim() first. IMPORTANT: You MUST provide both the simulatorUuid and bundleId parameters. Note: You must install the app in the simulator before launching. The typical workflow is: build → install → launch. Example: launch_app_sim({ simulatorUuid: 'YOUR_UUID_HERE', bundleId: 'com.example.MyApp' })
-- `launch_app_sim_name` - Launches an app in an iOS simulator by simulator name. If simulator window isn't visible, use open_sim() first. IMPORTANT: You MUST provide both the simulatorName and bundleId parameters. Note: You must install the app in the simulator before launching. The typical workflow is: build → install → launch. Example: launch_app_sim_name({ simulatorName: 'iPhone 16', bundleId: 'com.example.MyApp' })
+- `launch_app_sim` - Launches an app in an iOS simulator by UUID or name. If simulator window isn't visible, use open_sim() first. or launch_app_sim({ simulatorName: 'iPhone 16', bundleId: 'com.example.MyApp' })
 - `list_sims` - Lists available iOS simulators with their UUIDs.
 - `open_sim` - Opens the iOS Simulator app.
-- `stop_app_sim` - Stops an app running in an iOS simulator. Requires simulatorUuid and bundleId.
-- `stop_app_sim_name` - Stops an app running in an iOS simulator by simulator name. IMPORTANT: You MUST provide both the simulatorName and bundleId parameters.
-- `test_simulator` - Runs tests on a simulator by UUID or name using xcodebuild test and parses xcresult output. Works with both Xcode projects (.xcodeproj) and workspaces (.xcworkspace).
+- `stop_app_sim` - Stops an app running in an iOS simulator by UUID or name. or stop_app_sim({ simulatorName: "iPhone 16", bundleId: "com.example.MyApp" })
+- `test_sim` - Runs tests on a simulator by UUID or name using xcodebuild test and parses xcresult output. Works with both Xcode projects (.xcodeproj) and workspaces (.xcworkspace).
 
 ### Log Capture & Management (`logging`)
 **Purpose**: Log capture and management tools for iOS simulators and physical devices. Start, stop, and analyze application and system logs during development and testing. (4 tools)
@@ -56,7 +54,7 @@ XcodeBuildMCP provides 61 tools organized into 12 workflow groups for comprehens
 
 - `build_macos` - Builds a macOS app using xcodebuild from a project or workspace. Provide exactly one of projectPath or workspacePath. Example: build_macos({ projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyScheme' })
 - `build_run_macos` - Builds and runs a macOS app from a project or workspace in one step. Provide exactly one of projectPath or workspacePath. Example: build_run_macos({ projectPath: '/path/to/MyProject.xcodeproj', scheme: 'MyScheme' })
-- `get_macos_app_path` - Gets the app bundle path for a macOS application using either a project or workspace. Provide exactly one of projectPath or workspacePath. Example: get_macos_app_path({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme' })
+- `get_mac_app_path` - Gets the app bundle path for a macOS application using either a project or workspace. Provide exactly one of projectPath or workspacePath. Example: get_mac_app_path({ projectPath: '/path/to/project.xcodeproj', scheme: 'MyScheme' })
 - `launch_mac_app` - Launches a macOS application. Note: In some environments, this tool may be prefixed as mcp0_launch_macos_app.
 - `stop_mac_app` - Stops a running macOS application. Can stop by app name or process ID.
 - `test_macos` - Runs tests for a macOS project or workspace using xcodebuild test and parses xcresult output. Provide exactly one of projectPath or workspacePath.
@@ -84,9 +82,9 @@ XcodeBuildMCP provides 61 tools organized into 12 workflow groups for comprehens
 ### Simulator Management (`simulator-management`)
 **Purpose**: Tools for managing simulators from booting, opening simulators, listing simulators, stopping simulators and setting simulator environment options like location, network, statusbar and appearance. (4 tools)
 
-- `reset_simulator_location` - Resets the simulator's location to default.
+- `reset_sim_location` - Resets the simulator's location to default.
 - `set_sim_appearance` - Sets the appearance mode (dark/light) of an iOS simulator.
-- `set_simulator_location` - Sets a custom GPS location for the simulator.
+- `set_sim_location` - Sets a custom GPS location for the simulator.
 - `sim_statusbar` - Sets the data network indicator in the iOS simulator status bar. Use "clear" to reset all overrides, or specify a network type (hide, wifi, 3g, 4g, lte, lte-a, lte+, 5g, 5g+, 5g-uwb, 5g-uc).
 
 ### Swift Package Manager (`swift-package`)
@@ -123,10 +121,10 @@ XcodeBuildMCP provides 61 tools organized into 12 workflow groups for comprehens
 
 ## Summary Statistics
 
-- **Total Tools**: 61 canonical tools + 22 re-exports = 83 total
+- **Total Tools**: 59 canonical tools + 22 re-exports = 81 total
 - **Workflow Groups**: 12
 - **Analysis Method**: Static AST parsing with TypeScript compiler API
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2025-08-13*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2025-08-15*

eslint.config.js

@@ -6,7 +6,7 @@ export default [
   eslint.configs.recommended,
   ...tseslint.configs.recommended,
   {
-    ignores: ['node_modules/**', 'build/**', 'dist/**', 'coverage/**', 'src/core/generated-plugins.ts', 'src/core/generated-resources.ts'],
+    ignores: ['node_modules/**', 'build/**', 'dist/**', 'coverage/**', 'src/**/generated-*.ts'],
   },
   {
     // TypeScript files in src/ directory (covered by tsconfig.json)

src/core/plugin-registry.ts

@@ -1,4 +1,4 @@
-import type { PluginMeta, WorkflowGroup, WorkflowMeta } from './plugin-types.js';
+import type { PluginMeta, WorkflowGroup, WorkflowMeta } from '../server/plugin-types.js';
 import { WORKFLOW_LOADERS, WorkflowName, WORKFLOW_METADATA } from './generated-plugins.js';
 
 export async function loadPlugins(): Promise<Map<string, PluginMeta>> {

src/index.ts

@@ -38,7 +38,7 @@ import {
   registerDiscoveryTools,
   registerAllToolsStatic,
   registerSelectedWorkflows,
-} from './utils/tool-registry.js';
+} from './server/tool-registry.js';
 
 /**
  * Main function to start the server
@@ -62,7 +62,7 @@ async function main(): Promise<void> {
     }
 
     // Create the server
-    const server = createServer();
+    const server = await createServer();
 
     // Make server available globally for dynamic tools
     (globalThis as { mcpServer?: McpServer }).mcpServer = server;

src/mcp/tools/discovery/discover_tools.ts

@@ -7,7 +7,7 @@ import {
   enableWorkflows,
   getAvailableWorkflows,
   generateWorkflowDescriptions,
-} from '../../../core/dynamic-tools.js';
+} from '../../../server/dynamic-tools.js';
 import { createTypedTool } from '../../../utils/typed-tool-factory.js';
 import { getDefaultCommandExecutor } from '../../../utils/command.js';
 import { McpServer } from '@camsoft/mcp-sdk/server/mcp.js';

src/mcp/tools/doctor/__tests__/doctor.test.ts

@@ -37,7 +37,7 @@ function createDeps(overrides?: Partial<DoctorDependencies>): DoctorDependencies
           USER: 'testuser',
           TMPDIR: '/tmp',
           NODE_ENV: 'test',
-          SENTRY_DISABLED: 'false',
+          XCODEBUILDMCP_SENTRY_DISABLED: 'false',
         };
         return x;
       },
@@ -260,7 +260,7 @@ describe('doctor tool', () => {
               USER: 'testuser',
               TMPDIR: '/tmp',
               NODE_ENV: 'test',
-              SENTRY_DISABLED: 'true',
+              XCODEBUILDMCP_SENTRY_DISABLED: 'true',
             };
             return x;
           },

src/mcp/tools/doctor/doctor.ts

@@ -219,7 +219,7 @@ export async function runDoctor(
     `- Incremental Build Support: ${doctorInfo.features.xcodemake.available && doctorInfo.features.xcodemake.enabled ? '\u2705 Available & Enabled' : doctorInfo.features.xcodemake.available ? '\u2705 Available but Disabled' : '\u274c Not available'}`,
 
     `\n## Sentry`,
-    `- Sentry enabled: ${doctorInfo.environmentVariables.SENTRY_DISABLED !== 'true' ? '✅ Yes' : '❌ No'}`,
+    `- Sentry enabled: ${doctorInfo.environmentVariables.XCODEBUILDMCP_SENTRY_DISABLED !== 'true' ? '✅ Yes' : '❌ No'}`,
 
     `\n## Troubleshooting Tips`,
     `- If UI automation tools are not available, install axe: \`brew tap cameroncooke/axe && brew install axe\``,

src/mcp/tools/doctor/lib/doctor.deps.ts

@@ -1,15 +1,19 @@
 import * as os from 'os';
 import {
   CommandExecutor,
-  loadWorkflowGroups,
-  loadPlugins,
   areAxeToolsAvailable,
   isXcodemakeEnabled,
   isXcodemakeAvailable,
   doesMakefileExist,
-  getEnabledWorkflows,
 } from '../../../../utils/index.js';
-import { getTrackedToolNames } from '../../../../utils/tool-registry.js';
+import {
+  getXcodeInfo,
+  getEnvironmentVariables,
+  checkBinaryAvailability,
+} from '../../../../utils/system-info.js';
+import { loadWorkflowGroups, loadPlugins } from '../../../../core/plugin-registry.js';
+import { getEnabledWorkflows } from '../../../../server/dynamic-tools.js';
+import { getTrackedToolNames } from '../../../../server/tool-registry.js';
 
 export interface BinaryChecker {
   checkBinaryAvailability(binary: string): Promise<{ available: boolean; version?: string }>;
@@ -99,56 +103,32 @@ export function createDoctorDependencies(executor: CommandExecutor): DoctorDepen
       if (binary === 'axe' && areAxeToolsAvailable()) {
         return { available: true, version: 'Bundled' };
       }
-      try {
-        const which = await executor(['which', binary], 'Check Binary Availability');
-        if (!which.success) {
-          return { available: false };
-        }
-      } catch {
-        return { available: false };
-      }
-
-      let version: string | undefined;
-      const versionCommands: Record<string, string> = {
-        axe: 'axe --version',
-        mise: 'mise --version',
-      };
-
-      if (binary in versionCommands) {
-        try {
-          const res = await executor(versionCommands[binary]!.split(' '), 'Get Binary Version');
-          if (res.success && res.output) {
-            version = res.output.trim();
-          }
-        } catch {
-          // ignore
-        }
-      }
 
-      return { available: true, version: version ?? 'Available (version info not available)' };
+      // Use shared system info utility for consistency
+      return checkBinaryAvailability(binary);
     },
   };
 
   const xcode: XcodeInfoProvider = {
     async getXcodeInfo() {
       try {
-        const xcodebuild = await executor(['xcodebuild', '-version'], 'Get Xcode Version');
-        if (!xcodebuild.success) throw new Error('xcodebuild command failed');
-        const version = xcodebuild.output.trim().split('\n').slice(0, 2).join(' - ');
-
-        const pathRes = await executor(['xcode-select', '-p'], 'Get Xcode Path');
-        if (!pathRes.success) throw new Error('xcode-select command failed');
-        const path = pathRes.output.trim();
-
-        const selected = await executor(['xcrun', '--find', 'xcodebuild'], 'Find Xcodebuild');
-        if (!selected.success) throw new Error('xcrun --find command failed');
-        const selectedXcode = selected.output.trim();
+        // Use shared system info utility for basic info
+        const basicInfo = getXcodeInfo();
+        if (basicInfo.error) {
+          return { error: basicInfo.error };
+        }
 
+        // Get additional xcrun version info using executor
         const xcrun = await executor(['xcrun', '--version'], 'Get Xcrun Version');
         if (!xcrun.success) throw new Error('xcrun --version command failed');
         const xcrunVersion = xcrun.output.trim();
 
-        return { version, path, selectedXcode, xcrunVersion };
+        return {
+          version: basicInfo.version,
+          path: basicInfo.path,
+          selectedXcode: basicInfo.selectedXcode,
+          xcrunVersion,
+        };
       } catch (error) {
         return { error: error instanceof Error ? error.message : String(error) };
       }
@@ -157,29 +137,16 @@ export function createDoctorDependencies(executor: CommandExecutor): DoctorDepen
 
   const env: EnvironmentInfoProvider = {
     getEnvironmentVariables() {
-      const relevantVars = [
-        'INCREMENTAL_BUILDS_ENABLED',
-        'PATH',
-        'DEVELOPER_DIR',
-        'HOME',
-        'USER',
-        'TMPDIR',
-        'NODE_ENV',
-        'SENTRY_DISABLED',
-      ];
-
-      const envVars: Record<string, string | undefined> = {};
-      for (const varName of relevantVars) {
-        envVars[varName] = process.env[varName];
-      }
+      // Use shared system info utility for consistency
+      const envVars = getEnvironmentVariables();
 
-      Object.keys(process.env).forEach((key) => {
-        if (key.startsWith('XCODEBUILDMCP_')) {
-          envVars[key] = process.env[key];
-        }
+      // Convert to match interface (string | undefined)
+      const result: Record<string, string | undefined> = {};
+      Object.entries(envVars).forEach(([key, value]) => {
+        result[key] = value || undefined;
       });
 
-      return envVars;
+      return result;
     },
 
     getSystemInfo() {
@@ -218,7 +185,9 @@ export function createDoctorDependencies(executor: CommandExecutor): DoctorDepen
         let totalPlugins = 0;
 
         for (const [dirName, wf] of workflows.entries()) {
-          const toolNames = wf.tools.map((t) => t.name).filter(Boolean) as string[];
+          const toolNames = wf.tools
+            .map((t: { name?: string }) => t.name)
+            .filter(Boolean) as string[];
           totalPlugins += toolNames.length;
           pluginsByDirectory[dirName] = toolNames;
         }

src/mcp/tools/simulator/test_sim.ts

@@ -7,7 +7,8 @@
  */
 
 import { z } from 'zod';
-import { handleTestLogic, log } from '../../../utils/index.js';
+import { handleTestLogic } from '../../../test-utils/test-execution.js';
+import { log } from '../../../utils/index.js';
 import { XcodePlatform } from '../../../utils/index.js';
 import { ToolResponse } from '../../../types/common.js';
 import { CommandExecutor, getDefaultCommandExecutor } from '../../../utils/command.js';