# MCP Xcode Server

An MCP (Model Context Protocol) server that provides tools for interacting with Xcode projects programmatically.

## Installation

Clone this repository:

```bash
git clone https://github.com/chacebot/mcp-xcode-server.git
cd mcp-xcode-server
npm install
```

Or install from a local directory:

```bash
cd /path/to/mcp-xcode-server
npm install
```

## Features

This server provides the following tools for Xcode project management:

- **xcode_read_project** - Read and parse Xcode project files
- **xcode_list_schemes** - List all build schemes in a project
- **xcode_list_targets** - List all targets in a project
- **xcode_add_test_target** - Add a test target to a project
- **xcode_configure_test_target** - Configure a test target for a project
- **xcode_add_file_to_target** - Add files to project targets
- **xcode_remove_file_from_target** - Remove files from project targets
- **xcode_list_files_in_target** - List all files in a target
- **xcode_build** - Build Xcode projects
- **xcode_test** - Run tests in Xcode projects
- **xcode_get_build_settings** - Get build settings
- **xcode_get_build_errors** - Get and parse build errors
- **xcode_clean** - Clean build artifacts
- **xcode_validate_project** - Validate project structure and check for issues

## Quick Start

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Configure your MCP client** (Claude Desktop, Cursor, etc.):
   ```json
   {
     "mcpServers": {
       "xcode": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-xcode-server/src/index.js"],
         "env": {}
       }
     }
   }
   ```

3. **Restart your MCP client** to load the server

4. **Start using Xcode tools** through your AI assistant!

See [QUICKSTART.md](./QUICKSTART.md) for a 5-minute setup guide, or [SETUP.md](./SETUP.md) for detailed instructions.

## Usage

### As an MCP Server

Configure this server in your MCP client configuration. For example, in Claude Desktop or Cursor:

```json
{
  "mcpServers": {
    "xcode": {
      "command": "node",
      "args": ["/path/to/mcp-xcode-server/src/index.js"],
      "env": {}
    }
  }
}
```

### Standalone Testing

You can test the server directly:

```bash
npm start
```

The server communicates via stdio using the MCP protocol.

## Requirements

- Node.js 18+
- Xcode command-line tools installed
- Access to Xcode projects

## Tools Reference

### xcode_read_project

Read and parse an Xcode project file to extract its structure.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file

**Example:**
```json
{
  "name": "xcode_read_project",
  "arguments": {
    "projectPath": "/path/to/Project.xcodeproj"
  }
}
```

### xcode_list_schemes

List all build schemes available in the project.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file

### xcode_list_targets

List all targets in the project.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file

### xcode_add_test_target

Add a new test target to the project. Note: This currently provides instructions rather than directly modifying the pbxproj file, as that requires careful parsing and manipulation.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `targetName` (optional): Name for the test target (defaults to ProjectNameTests)

### xcode_add_file_to_target

Add a file to a specific target in the project.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `filePath` (required): Relative path to the file from project root
- `targetName` (required): Name of the target

### xcode_build

Build the Xcode project using xcodebuild.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Build scheme name
- `configuration` (optional): Debug or Release (default: Debug)

### xcode_test

Run tests in the Xcode project.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Test scheme name

### xcode_get_build_settings

Get build settings for the project or a specific scheme.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Scheme name
- `configuration` (optional): Debug or Release (default: Debug)

### xcode_clean

Clean build artifacts from the project.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Build scheme name

### xcode_remove_file_from_target

Remove a file from an Xcode project target.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `filePath` (required): Relative path to the file from project root
- `targetName` (required): Name of the target

### xcode_get_build_errors

Get build errors from the last build attempt. Parses xcodebuild output to extract error messages.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `scheme` (optional): Build scheme name

### xcode_list_files_in_target

List all files in a specific target.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file
- `targetName` (required): Name of the target

### xcode_validate_project

Validate Xcode project structure and check for common issues like missing targets, schemes, or configuration problems.

**Parameters:**
- `projectPath` (required): Path to the .xcodeproj file

## Limitations

- The pbxproj parser is simplified and may not handle all edge cases
- Adding targets/files requires careful manipulation of the pbxproj format
- Some operations may require Xcode to be installed and properly configured

## Future Improvements

- Full pbxproj parser using a proper library (e.g., `xcode` npm package)
- Better error handling and validation
- Support for Xcode workspaces (.xcworkspace)
- Support for Swift Package Manager integration
- Support for modifying build settings
- Support for managing code signing

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin feature/my-feature`
5. Submit a pull request

## License

MIT - see [LICENSE](./LICENSE) file for details