drews-xcode-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is Drew's Xcode MCP Server (PyPI package drews-xcode-mcp, module drews_xcode_mcp) - a Model Context Protocol (MCP) server that enables AI assistants to interact with Xcode projects. It provides tools for building, running, and managing Xcode projects/workspaces programmatically through AppleScript.

The package was originally published as xcode-mcp-server. That PyPI name now hosts a compatibility shim (see shim/) that depends on drews-xcode-mcp with an exact version pin and forwards the old xcode-mcp-server command to it. deploy.sh and deploy-beta.sh publish both packages in lockstep; the shim's version and pin are rewritten automatically at deploy time. The settings directory is ~/.drews-xcode-mcp; on first run, a pre-rename ~/.xcode-mcp-server directory is adopted via rename (see ConfigManager._migrate_legacy_config_dir). The cache directory deliberately keeps the old name (~/Library/Caches/xcode-mcp-server) — it holds only transient logs/screenshots, and log paths already handed out in prior tool results should stay valid. When launched through the legacy name, the shim sets XCODE_MCP_LEGACY_PACKAGE_NAME, and the server adds migration guidance to its instructions, the version tool, and a migrate_to_drews_xcode_mcp MCP prompt.

Development Commands

Local Development

# Quick start with dev script (sets up venv and runs MCP Inspector)
./dev.sh

# Manual setup: Test the server locally with MCP Inspector
export XCODEMCP_ALLOWED_FOLDERS=/Users/username/Projects
mcp dev drews_xcode_mcp/__main__.py

# Run the server directly
python -m drews_xcode_mcp

Testing in-progress changes through the real MCP path

Two MCP servers are registered against this repo:

• drews-xcode-mcp — the deployed build (unpinned uvx drews-xcode-mcp, registered at user scope). It runs the published PyPI release, NOT your working tree. Editing source here does nothing to it until you ./deploy.sh and the server respawns. Unpinned uvx re-resolves "latest" on spawn using uv's HTTP-cached view of the PyPI index (max-age 600s), so a respawn within ~10 minutes of a deploy can still launch the previous version.
• xcode-mcp-local-dev-server — runs your live local source via run_local_for_claude.sh (cd into the repo, then python -m drews_xcode_mcp). Use this to test uncommitted changes without deploying. (Note: the canonical repo path ~/cursor/drews-xcode-mcp and ~/Documents/ncc_source/cursor/drews-xcode-mcp are the same directory via symlink.)