Skip to content

Latest commit

 

History

History
229 lines (176 loc) · 7.39 KB

CLAUDE.md

File metadata and controls

229 lines (176 loc) · 7.39 KB

CLAUDE.md - AI Assistant Context

This file provides essential guidance to Claude Code when working with the xclaude-plugin repository.

Project Overview

xclaude-plugin is a production-ready MCP (Model Context Protocol) plugin for iOS development automation. It provides 8 modular, workflow-specific MCP servers that consolidate 23 iOS operations across build, test, simulator control, and UI automation.

Status: ✅ Production-ready (v0.4.0) - All operations fully implemented, tested, and with codecov integration.

Key Features:

  • 8 modular MCP servers - Workflow-specific, composable architecture
  • 23 total operations across Xcode, Simulator, and IDB domains
  • 8 procedural Skills (on-demand documentation with examples)
  • 100% TypeScript with zero tolerance for any types
  • Full test coverage with codecov reporting

Repository Structure

xclaude-plugin/
├── README.md                      # User-facing plugin documentation
├── CLAUDE.md                      # This file - AI assistant context
├── CODESTYLE.md                   # Development guidelines
├── .claude-plugin/                # Plugin configuration
│   ├── plugin.json               # Plugin manifest (entry point)
│   └── marketplace.json          # Marketplace configuration
├── mcp-servers/                   # 8 modular MCP servers
│   ├── xc-build/                 # Build, clean, list schemes
│   ├── xc-launch/                # Simulator lifecycle: install and launch
│   ├── xc-interact/              # Simulator + IDB UI automation
│   ├── xc-ai-assist/             # AI-specific workflows
│   ├── xc-setup/                 # Health check, project info
│   ├── xc-testing/               # Test execution, results parsing
│   ├── xc-meta/                  # Metadata and introspection
│   └── xc-all/                   # All-in-one consolidated server
│   └── [each server]/
│       ├── src/
│       │   ├── index.ts          # Server entry point
│       │   └── operations/       # Operation implementations
│       ├── package.json
│       ├── tsconfig.json
│       └── dist/                 # Compiled JavaScript (committed for distribution)
├── skills/                        # 8 procedural Skills (on-demand)
│   ├── xcode-workflows/
│   ├── simulator-workflows/
│   ├── ui-automation-workflows/
│   ├── accessibility-testing/
│   ├── ios-testing-patterns/
│   ├── crash-debugging/
│   ├── performance-profiling/
│   └── state-management/
├── .mcp.json                      # Default MCP configuration (loads xc-setup, xc-build)
├── .mcp.json.example              # Full configuration showing all 8 servers
└── .gitignore                     # Version control exclusions

Default vs Optional Servers

Default Load (in .mcp.json):

  • xc-setup - Environment validation, project introspection
  • xc-build - Build, clean, list schemes

Optional Load (documented in README):

  • xc-launch - Simulator lifecycle: install and launch app
  • xc-testing - Test execution and result analysis
  • xc-interact - Simulator and IDB UI automation
  • xc-ai-assist - AI-specific workflows
  • xc-meta - Metadata and introspection
  • xc-all - All 24 operations in one server

Users can customize .mcp.json to load any combination of servers based on their workflow.

Code Style Principles

IMPORTANT: Always follow CODESTYLE.md when writing or modifying code.

Key principles across all servers:

  • Zero tolerance for any - All types explicitly defined (MCP SDK constraint exception documented)
  • No silent failures - Always handle and log errors
  • Constants over magic numbers - All config in constants.ts per server
  • Progressive disclosure - Document essentials, details on-demand
  • Function size - Prefer <50 lines, maximum 100 lines
  • Security first - Use spawn (not shell) for command execution
  • Comprehensive JSDoc - All public APIs must be documented
  • Consistent error handling - Structured error responses

Pre-commit validation:

npm run build          # TypeScript compilation for all servers
npm run test           # Run test suites for all servers
npm run coverage       # Generate coverage reports

When Adding/Modifying Operations

  1. Add to specific server - Choose appropriate server (or add to xc-all if generic)
  2. Implement operation - Add to src/operations/ with JSDoc
  3. Define types - Update types in same file or shared types
  4. Add tests - Create matching .test.ts file with full coverage
  5. Update README - Document in server-specific README
  6. Build & validate - Ensure npm run build && npm run test passes

Development Commands

# Build all servers
npm run build              # TypeScript compilation

# Testing
npm run test               # Run all tests
npm run coverage           # Generate coverage reports

# Individual server commands (from root)
npm run build --workspace=xc-build      # Build specific server
npm run test --workspace=xc-build       # Test specific server

# Development
npm run clean              # Remove all dist/ directories

Testing Strategy

All servers include:

  • Unit tests for each operation
  • Integration tests for workflows
  • Edge case coverage
  • Error handling validation

Coverage target: >80% (enforced by codecov integration)

Tests run via:

npm run test           # All servers
npm run test --workspace=xc-setup  # Specific server
npm run coverage       # Generate reports for CI

Key Implementation Details

Server Architecture

Each server in mcp-servers/ follows the same pattern:

// src/index.ts - Server entry point
export const server = new Server({
  name: "xc-build",
  version: "0.2.0",
  tools: [
    {
      name: "xc_build",
      description: "Build iOS project",
      inputSchema: {
        /* ... */
      },
    },
    // ... more tools
  ],
});

// Implement handlers for each tool
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // Route to appropriate operation handler
});

Type Safety

Zero any types in implementation code:

// ❌ Bad - violates zero-any policy
const args = toolInput as any;

// ✅ Good - explicit typing
interface BuildInput {
  scheme: string;
  configuration?: "Debug" | "Release";
}
const args = toolInput as BuildInput;

Command Execution (Safe Spawn)

All external commands use spawn-based execution:

// ❌ Vulnerable to shell injection
await executeCommand(`xcodebuild -scheme ${scheme}`);

// ✅ Safe - arguments as array
const { execAsync } = await import("./exec");
const result = await execAsync("xcodebuild", ["-scheme", scheme]);

Error Handling

Consistent error response format:

interface OperationResult<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
}

Resources

xclaude-plugin v0.4.0 - Modular iOS development automation for Claude Code