feat: add tool discovery mode with automatic client capability fallback

.vscode/launch.json

@@ -4,8 +4,9 @@
     {
       "type": "node",
       "request": "attach",
-      "name": "Attach to MCP Server Dev",
+      "name": "Wait for MCP Server to Start",
       "port": 9999,
+      "address": "localhost",
       "restart": true,
       "skipFiles": [
         "<node_internals>/**"
@@ -15,6 +16,36 @@
         "${workspaceFolder}/build/**/*.js"
       ],
       "cwd": "${workspaceFolder}",
+      "sourceMapPathOverrides": {
+        "/*": "${workspaceFolder}/src/*"
+      },
+      "timeout": 60000,
+      "localRoot": "${workspaceFolder}",
+      "remoteRoot": "${workspaceFolder}"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Launch MCP Server Dev",
+      "program": "${workspaceFolder}/build/index.js",
+      "cwd": "${workspaceFolder}",
+      "runtimeArgs": [
+        "--inspect=9999"
+      ],
+      "env": {
+        "XCODEBUILDMCP_DEBUG": "true",
+        "XCODEBUILDMCP_DYNAMIC_TOOLS": "true",
+        "INCREMENTAL_BUILDS_ENABLED": "false",
+        "XCODEBUILDMCP_IOS_TEMPLATE_PATH": "/Volumes/Developer/XcodeBuildMCP-iOS-Template",
+        "XCODEBUILDMCP_MACOS_TEMPLATE_PATH": "/Volumes/Developer/XcodeBuildMCP-macOS-Template"
+      },
+      "sourceMaps": true,
+      "outFiles": [
+        "${workspaceFolder}/build/**/*.js"
+      ],
+      "skipFiles": [
+        "<node_internals>/**"
+      ],
       "sourceMapPathOverrides": {
         "/*": "${workspaceFolder}/src/*"
       }

README.md

@@ -311,11 +311,11 @@ https://github.com/user-attachments/assets/e3c08d75-8be6-4857-b4d0-9350b26ef086
 
 Contributions are welcome! Here's how you can help improve XcodeBuildMCP.
 
-See our [CONTRIBUTING](docs/CONTRIBUTING.md) document for detailed contribution guidelines, including:
-- Development setup instructions
-- Mandatory testing principles
-- Code quality standards
-- Pre-commit checklist
+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
 
 ## Licence
 

docs/CODE_QUALITY.md

@@ -0,0 +1,303 @@
+# XcodeBuildMCP Code Quality Guide
+
+This guide consolidates all code quality, linting, and architectural compliance information for the XcodeBuildMCP project.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [ESLint Configuration](#eslint-configuration)
+3. [Architectural Rules](#architectural-rules)
+4. [Development Scripts](#development-scripts)
+5. [Code Pattern Violations](#code-pattern-violations)
+6. [Type Safety Migration](#type-safety-migration)
+7. [Best Practices](#best-practices)
+
+## Overview
+
+XcodeBuildMCP enforces code quality through multiple layers:
+
+1. **ESLint**: Handles general code quality, TypeScript rules, and stylistic consistency
+2. **TypeScript**: Enforces type safety with strict mode
+3. **Pattern Checker**: Enforces XcodeBuildMCP-specific architectural rules
+4. **Migration Scripts**: Track progress on type safety improvements
+
+## ESLint Configuration
+
+### Current Configuration
+
+The project uses a comprehensive ESLint setup that covers:
+
+- TypeScript type safety rules
+- Code style consistency
+- Import ordering
+- Unused variable detection
+- Testing best practices
+
+### ESLint Rules
+
+For detailed ESLint rules and rationale, see [ESLINT_RULES.md](./ESLINT_RULES.md).
+
+### Running ESLint
+
+```bash
+# Check for linting issues
+npm run lint
+
+# Auto-fix linting issues
+npm run lint:fix
+```
+
+## Architectural Rules
+
+XcodeBuildMCP enforces several architectural patterns that cannot be expressed through ESLint:
+
+### 1. Dependency Injection Pattern
+
+**Rule**: All tools must use dependency injection for external interactions.
+
+✅ **Allowed**:
+- `createMockExecutor()` for command execution mocking
+- `createMockFileSystemExecutor()` for file system mocking
+- Logic functions accepting `executor?: CommandExecutor` parameter
+
+❌ **Forbidden**:
+- Direct use of `vi.mock()`, `vi.fn()`, or any Vitest mocking
+- Direct calls to `execSync`, `spawn`, or `exec` in production code
+- Testing handler functions directly
+
+### 2. Handler Signature Compliance
+
+**Rule**: MCP handlers must have exact signatures as required by the SDK.
+
+✅ **Tool Handler Signature**:
+```typescript
+async handler(args: Record<string, unknown>): Promise<ToolResponse>
+```
+
+✅ **Resource Handler Signature**:
+```typescript
+async handler(uri: URL): Promise<{ contents: Array<{ text: string }> }>
+```
+
+❌ **Forbidden**:
+- Multiple parameters in handlers
+- Optional parameters
+- Dependency injection parameters in handlers
+
+### 3. Testing Architecture
+
+**Rule**: Tests must only call logic functions, never handlers directly.
+
+✅ **Correct Pattern**:
+```typescript
+const result = await myToolLogic(params, mockExecutor);
+```
+
+❌ **Forbidden Pattern**:
+```typescript
+const result = await myTool.handler(params);
+```
+
+### 4. Server Type Safety
+
+**Rule**: MCP server instances must use proper SDK types, not generic casts.
+
+✅ **Correct Pattern**:
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+const server = (globalThis as { mcpServer?: McpServer }).mcpServer;
+server.server.createMessage({...});
+```
+
+❌ **Forbidden Pattern**:
+```typescript
+const server = (globalThis as { mcpServer?: Record<string, unknown> }).mcpServer;
+const serverInstance = (server.server ?? server) as Record<string, unknown> & {...};
+```
+
+## Development Scripts
+
+### Core Scripts
+
+```bash
+# Build the project
+npm run build
+
+# Run type checking
+npm run typecheck
+
+# Run tests
+npm run test
+
+# Check code patterns (architectural compliance)
+node scripts/check-code-patterns.js
+
+# Check type safety migration progress
+npm run check-migration
+```
+
+### Pattern Checker Usage
+
+The pattern checker enforces XcodeBuildMCP-specific architectural rules:
+
+```bash
+# Check all patterns
+node scripts/check-code-patterns.js
+
+# Check specific pattern type
+node scripts/check-code-patterns.js --pattern=vitest
+node scripts/check-code-patterns.js --pattern=execsync
+node scripts/check-code-patterns.js --pattern=handler
+node scripts/check-code-patterns.js --pattern=handler-testing
+node scripts/check-code-patterns.js --pattern=server-typing
+
+# Get help
+node scripts/check-code-patterns.js --help
+```
+
+### Tool Summary Scripts
+
+```bash
+# Show tool and resource summary
+npm run tools
+
+# List all tools
+npm run tools:list
+
+# List both tools and resources
+npm run tools:all
+```
+
+## Code Pattern Violations
+
+The pattern checker identifies the following violations:
+
+### 1. Vitest Mocking Violations
+
+**What**: Any use of Vitest mocking functions
+**Why**: Breaks dependency injection architecture
+**Fix**: Use `createMockExecutor()` instead
+
+### 2. ExecSync Violations
+
+**What**: Direct use of Node.js child_process functions in production code
+**Why**: Bypasses CommandExecutor dependency injection
+**Fix**: Accept `CommandExecutor` parameter and use it
+
+### 3. Handler Signature Violations
+
+**What**: Handlers with incorrect parameter signatures
+**Why**: MCP SDK requires exact signatures
+**Fix**: Move dependencies inside handler body
+
+### 4. Handler Testing Violations
+
+**What**: Tests calling `.handler()` directly
+**Why**: Violates dependency injection principle
+**Fix**: Test logic functions instead
+
+### 5. Improper Server Typing Violations
+
+**What**: Casting MCP server instances to `Record<string, unknown>` or using custom interfaces instead of SDK types
+**Why**: Breaks type safety and prevents proper API usage
+**Fix**: Import `McpServer` from SDK and use proper typing instead of generic casts
+
+## Type Safety Migration
+
+The project is migrating to improved type safety using the `createTypedTool` factory:
+
+### Check Migration Status
+
+```bash
+# Show summary
+npm run check-migration
+
+# Show detailed analysis
+npm run check-migration:verbose
+
+# Show only unmigrated tools
+npm run check-migration:unfixed
+```
+
+### Migration Benefits
+
+1. **Compile-time type safety** for tool parameters
+2. **Automatic Zod schema validation**
+3. **Better IDE support** and autocomplete
+4. **Consistent error handling**
+
+## Best Practices
+
+### 1. Before Committing
+
+Always run these checks before committing:
+
+```bash
+npm run build          # Ensure code compiles
+npm run typecheck      # Check TypeScript types
+npm run lint           # Check linting rules
+npm run test           # Run tests
+node scripts/check-code-patterns.js  # Check architectural compliance
+```
+
+### 2. Adding New Tools
+
+1. Use dependency injection pattern
+2. Follow handler signature requirements
+3. Create comprehensive tests (test logic, not handlers)
+4. Use `createTypedTool` factory for type safety
+5. Document parameter schemas clearly
+
+### 3. Writing Tests
+
+1. Import the logic function, not the default export
+2. Use `createMockExecutor()` for mocking
+3. Test three dimensions: validation, command generation, output processing
+4. Never test handlers directly
+
+### 4. Code Organization
+
+1. Keep tools in appropriate workflow directories
+2. Share common tools via `-shared` directories
+3. Re-export shared tools, don't duplicate
+4. Follow naming conventions for tools
+
+## Automated Enforcement
+
+The project uses multiple layers of automated enforcement:
+
+1. **Pre-commit**: ESLint and TypeScript checks (if configured)
+2. **CI Pipeline**: All checks run on every PR
+3. **PR Blocking**: Checks must pass before merge
+4. **Code Review**: Automated and manual review processes
+
+## Troubleshooting
+
+### ESLint False Positives
+
+If ESLint reports false positives in test files, check that:
+1. Test files are properly configured in `.eslintrc.json`
+2. Test-specific rules are applied correctly
+3. File patterns match your test file locations
+
+### Pattern Checker Issues
+
+If the pattern checker reports unexpected violations:
+1. Check if it's a legitimate architectural violation
+2. Verify the file is in the correct directory
+3. Ensure you're using the latest pattern definitions
+
+### Type Safety Migration
+
+If migration tooling reports incorrect status:
+1. Ensure the tool exports follow standard patterns
+2. Check that schema definitions are properly typed
+3. Verify the handler uses the schema correctly
+
+## Future Improvements
+
+1. **Automated Fixes**: Add auto-fix capability to pattern checker
+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