Xcode MCP Server

🚀 Xcode MCP Server

The Xcode MCP Server is a powerful tool designed to streamline Xcode project operations. It provides a convenient way to manage and execute various Xcode - related tasks, enhancing development efficiency.

🚀 Quick Start

The Xcode MCP Server simplifies the process of managing Xcode projects. Here's how you can get started quickly:

Register a Tool

Create a new tool category in the src/tools/ directory and register the tool within it:

// src/tools/build/index.ts
export const build = new Tool({
  name: 'build',
  description: 'Builds an Xcode project or workspace.',
  parameters: {
    // Define the parameter schema
  },
})

Use the Tool

Invoke the tool by sending an HTTP request:

curl -X POST http://localhost:3000/tools/build \
     -H "Content-Type: application/json" \
     -d '{"parameter": "value"}'

✨ Features

• Customizable Configuration: Allows users to configure allowed directories and log levels according to their needs.
• Safe and Secure: Implements path validation and error - handling mechanisms to ensure the security and stability of operations.
• Extensible: Supports custom tool classification and extended logging functions.

📦 Installation

Please follow the steps below to install the Xcode MCP Server:

1. Clone the Repository

   git clone https://github.com/yourusername/xcode-mcp-server.git
   cd xcode-mcp-server
   

2. Install Dependencies

   npm install
   

3. Start the Server

   npm start
   

By default, the server will run on localhost:3000.

📚 Documentation

Configuration Guide

Configure Allowed Directories

Create a .env file in the project root directory:

ALLOWED_DIRS=/path/to/your/project/directory

Configure Log Level

Edit the src/server.ts file to set the log level:

const logger = Logger({
  level: 'info', // Available values: 'debug', 'info', 'warn', 'error'
})

Security Guide

Path Validation

All file operations are restricted to the allowed directories:

const path = await validatePathAgainstAllowedDirs(filePath);

Error Handling

Errors are caught and logged during tool execution:

try {
  // Execute tool logic
} catch (error) {
  logger.error(error.message);
}

Usage Notes

• Permissions: Ensure that the allowed directories have the correct access permissions.
• Log Management: Clean up old log files in a timely manner to avoid running out of disk space.
• Compatibility Check: Make sure the server is compatible with the Xcode version you are using.

Advanced Topics

Custom Tool Classification

Create a new sub - directory in the src/tools/ directory and register the tool in the corresponding index.ts file:

// src/tools/custom/index.ts
export const customTool = new Tool({
  name: 'custom',
  description: 'Custom Xcode operation.',
  parameters: {
    // Define the parameter schema
  },
})

Extended Logging

Customize the log format and output:

const logger = Logger({
  format: ({ level, message }: { level: string; message: string }) =>
    `${new Date().toISOString()} [${level.toUpperCase()}] ${message}`,
});

Frequently Asked Questions

Q1. How to handle path access errors?

A: Check and ensure that the path you are trying to access is within the allowed directories.

Q2. Why does the build fail?

A: Make sure the Xcode command - line tools are installed and the version is correct.

Q3. Why is the tool not recognized?

A: Verify that the tool name is correct and confirm that it has been registered in the index.ts file.

Contribution Guide

Contributions are welcome! Please follow the steps below to submit a Pull Request:

1. Fork the Repository
2. Create a Feature Branch (git checkout -b feature/amazing - feature)
3. Commit Changes (git commit -m 'Add some amazing feature')
4. Push to the Branch (git push origin feature/amazing - feature)
5. Submit a Pull Request

Development Guide

• Follow the existing code style and organizational structure.
• Use the Zod scheme for parameter validation and add detailed error messages.
• Write test cases for new features.
• Update the documentation to reflect your changes.
• Ensure compatibility with different project types (standard, workspace, SPM).

Adding New Tools

To add a new tool to the server, follow these steps:

1. Determine the Appropriate Category in the src/tools/ directory.
2. Implement the Tool Using the Existing Pattern and perform Zod scheme validation.
3. Register the Tool in the Category's index.ts File.
4. Add Error Handling and Specific Error Messages.
5. Update the Documentation to Record the New Tool.

📄 License

[Insert license information here]

For further assistance, please refer to our FAQ page or contact the support team.