Claude Code Connector MCP

# Product Spec: Claude Code Connector MCP ## Overview An MCP server enabling seamless workflow between Claude Desktop, Claude Code CLI, and Claude Code for VS Code. Provides file system integration, Claude Code invocation, and cross-interface state management for developer workflows. **Target Developer**: antigravity **Priority**: P0 - Core developer workflow enabler --- ## MCP Server Architecture ### Server Name `claude-code-connector` ### Installation ```bash npm install -g @ciq/claude-code-connector-mcp # or pip install claude-code-connector-mcp ``` ### Configuration Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "claude-code": { "command": "claude-code-connector", "args": ["--projects-config", "~/.claude/projects.json"], "env": { "CLAUDE_CODE_PATH": "/usr/local/bin/claude-code" } } } } ``` --- ## Data Models ### Project Configuration File: `~/.claude/projects.json` ```json { "projects": [ { "id": "myapp", "name": "My Application", "rootPath": "/Users/brian/dev/myapp", "defaultBranch": "main", "specPaths": ["docs/", "specs/", "requirements/"], "claudeStatePath": ".claude/", "active": true, "created": "2025-01-15T10:00:00Z", "lastAccessed": "2025-01-20T14:30:00Z" } ] } ``` ### Session State File: `{project}/.claude/session_state.json` ```json { "sessionId": "sess_abc123", "desktopConversationId": "conv_xyz789", "checkpoints": [ { "timestamp": "2025-01-20T14:30:00Z", "source": "desktop", "summary": "Created authentication spec", "artifacts": ["docs/auth_spec.md"], "nextActions": ["Implement JWT middleware"] } ], "claudeCodeTasks": [ { "taskId": "task_001", "status": "completed", "command": "scaffold REST API from spec", "startTime": "2025-01-20T14:35:00Z", "endTime": "2025-01-20T14:38:00Z", "filesModified": ["src/api/auth.ts", "tests/auth.test.ts"] } ] } ``` --- ## MCP Tools ### 1. register_project **Purpose**: Register a codebase directory for Claude Desktop access ```typescript { name: "register_project", description: "Register a project directory for Claude Code Connector access", inputSchema: { type: "object", properties: { name: { type: "string", description: "Human-readable project name" }, rootPath: { type: "string", description: "Absolute path to project root" }, id: { type: "string", description: "Optional unique ID (auto-generated if not provided)", pattern: "^[a-z0-9-]+$" }, specPaths: { type: "array", items: { type: "string" }, description: "Relative paths for spec/doc storage (default: ['docs/', 'specs/'])" } }, required: ["name", "rootPath"] } } ``` **Output**: ```json { "success": true, "projectId": "myapp", "message": "Project 'My Application' registered at /Users/brian/dev/myapp" } ``` **Error Cases**: - Path doesn't exist → Return error with suggestion to create directory - Path not accessible → Return permission error - Duplicate ID → Suggest unique ID or confirm overwrite --- ### 2. list_projects **Purpose**: Show all registered projects ```typescript { name: "list_projects", description: "List all registered projects with status", inputSchema: { type: "object", properties: { includeInactive: { type: "boolean", default: false } } } } ``` **Output**: ```json { "projects": [ { "id": "myapp", "name": "My Application", "rootPath": "/Users/brian/dev/myapp", "active": true, "lastAccessed": "2 hours ago", "hasClaudeState": true } ] } ``` --- ### 3. write_to_project **Purpose**: Write file from Desktop conversation to project directory ```typescript { name: "write_to_project", description: "Write content to a file in registered project directory", inputSchema: { type: "object", properties: { projectId: { type: "string", description: "ID of registered project" }, filePath: { type: "string", description: "Relative path within project (e.g., 'docs/spec.md')" }, content: { type: "string", description: "File content to write" }, createDirs: { type: "boolean", default: true, description: "Create parent directories if they don't exist" }, overwrite: { type: "boolean", default: false, description: "Overwrite if file exists (prompts user if false)" } }, required: ["projectId", "filePath", "content"] } } ``` **Behavior**: - If file exists and overwrite=false → Ask user for confirmation - Create parent directories automatically if createDirs=true - Update session state with artifact reference - Return full absolute path in response **Output**: ```json { "success": true, "fullPath": "/Users/brian/dev/myapp/docs/auth_spec.md", "action": "created", "bytes": 4532 } ``` --- ### 4. read_from_project **Purpose**: Read file from project into Desktop context ```typescript { name: "read_from_project", description: "Read file content from registered project", inputSchema: { type: "object", properties: { projectId: { type: "string" }, filePath: { type: "string", description: "Relative path within project" }, startLine: { type: "number", description: "Optional: Read from line N (1-indexed)" }, endLine: { type: "number", description: "Optional: Read to line N (1-indexed)" } }, required: ["projectId", "filePath"] } } ``` --- ### 5. invoke_claude_code **Purpose**: Execute Claude Code CLI with specific task ```typescript { name: "invoke_claude_code", description: "Invoke local Claude Code CLI to perform coding task", inputSchema: { type: "object", properties: { projectId: { type: "string", description: "ID of registered project" }, task: { type: "string", description: "Natural language task description for Claude Code" }, contextFiles: { type: "array", items: { type: "string" }, description: "Relative paths to files Claude Code should read for context" }, maxTime: { type: "number", default: 300, description: "Max execution time in seconds" }, streaming: { type: "boolean", default: true, description: "Stream status updates back to Desktop" } }, required: ["projectId", "task"] } } ``` **Implementation Details**: - Spawn Claude Code process: `claude-code --project={rootPath} --task="{task}" --context={contextFiles}` - If streaming=true, return progress updates as tool continues executing - Save task to session state `.claude/session_state.json` - Return summary of files created/modified **Output** (streaming): ```json { "status": "running", "taskId": "task_001", "updates": [ { "time": "14:35:02", "message": "Reading context files..." }, { "time": "14:35:05", "message": "Analyzing requirements..." }, { "time": "14:35:12", "message": "Creating src/api/auth.ts..." } ] } ``` **Output** (completed): ```json { "status": "completed", "taskId": "task_001", "duration": 180, "filesModified": ["src/api/auth.ts", "tests/auth.test.ts"], "filesCreated": ["src/middleware/jwt.ts"], "summary": "Implemented JWT authentication middleware with tests", "exitCode": 0 } ``` **Error Cases**: - Claude Code not installed → Return error with install instructions - Project path doesn't exist → Return error - Timeout exceeded → Kill process, return partial results + timeout status --- ### 6. create_checkpoint **Purpose**: Save conversation state for cross-interface pickup ```typescript { name: "create_checkpoint", description: "Save current conversation state to project for CLI/VS Code pickup", inputSchema: { type: "object", properties: { projectId: { type: "string" }, summary: { type: "string", description: "Brief description of current state" }, nextActions: { type: "array", items: { type: "string" }, description: "Suggested next steps for CLI/VS Code" }, artifacts: { type: "array", items: { type: "string" }, description: "Files created/modified in this session" } }, required: ["projectId", "summary"] } } ``` **Behavior**: - Append checkpoint to `.claude/session_state.json` - Include timestamp and Desktop conversation ID - Return confirmation with path to state file --- ### 7. get_project_status **Purpose**: Get current project state and Claude Code task history ```typescript { name: "get_project_status", description: "Get project overview including recent tasks and file changes", inputSchema: { type: "object", properties: { projectId: { type: "string" }, includeGitStatus: { type: "boolean", default: false, description: "Include git branch and uncommitted changes" } }, required: ["projectId"] } } ``` **Output**: ```json { "projectId": "myapp", "rootPath": "/Users/brian/dev/myapp", "checkpoints": 3, "lastCheckpoint": "2 hours ago: Created authentication spec", "claudeCodeTasks": [ { "taskId": "task_001", "status": "completed", "summary": "Scaffolded REST API", "completedAt": "1 hour ago" } ], "recentFiles": ["docs/auth_spec.md", "src/api/auth.ts"], "gitStatus": { "branch": "feature/auth", "uncommitted": 5 } } ``` --- ## MCP Resources ### Project Files Resource **URI Template**: `claude-code://{projectId}/files` **Purpose**: Expose project file structure as browsable resource **Implementation**: ```typescript { uri: "claude-code://myapp/files", mimeType: "application/json", text: JSON.stringify({ project: "myapp", rootPath: "/Users/brian/dev/myapp", tree: [ { path: "docs/", type: "directory" }, { path: "docs/auth_spec.md", type: "file", size: 4532, modified: "2 hours ago" }, { path: "src/", type: "directory" }, { path: "src/api/", type: "directory" }, { path: "src/api/auth.ts", type: "file", size: 2156, modified: "1 hour ago" } ] }) } ``` **Usage**: Claude can reference this to understand project structure without reading entire filesystem --- ### Session State Resource **URI Template**: `claude-code://{projectId}/session` **Purpose**: Expose current session state for context awareness **Implementation**: ```typescript { uri: "claude-code://myapp/session", mimeType: "application/json", text: JSON.stringify({ sessionId: "sess_abc123", checkpoints: [...], claudeCodeTasks: [...], artifacts: [...] }) } ``` **Usage**: Claude can check session state to understand what work has been done --- ### Project Docs Resource **URI Template**: `claude-code://{projectId}/docs` **Purpose**: Quick access to all spec/doc files in project **Implementation**: ```typescript { uri: "claude-code://myapp/docs", mimeType: "text/markdown", text: "# Project Documentation\n\n## auth_spec.md\n[content]..." } ``` --- ## MCP Prompts ### 1. "Plan and Implement Feature" **Prompt ID**: `plan-and-implement` **Purpose**: Guide user through full Desktop → CLI workflow **Content**: ```markdown I'll help you plan and implement a new feature across Claude interfaces. **Step 1: Planning (Desktop)** Let's start by creating a detailed spec. I'll ask you: - What feature are you building? - What are the key requirements? - Any technical constraints? **Step 2: Spec Creation** I'll write a comprehensive spec and save it to your project using write_to_project. **Step 3: Implementation (Claude Code CLI)** I'll invoke Claude Code to implement based on the spec using invoke_claude_code. **Step 4: Review** I'll bring back the results and we can review together. **Step 5: Checkpoint** I'll create a checkpoint so you can pick up in VS Code if needed. Ready to start? Which project should we work on? ``` --- ### 2. "Save Work to Project" **Prompt ID**: `save-to-project` **Purpose**: Quick save current conversation artifacts **Content**: ```markdown I'll save our work to your project. Current artifacts in this conversation: - [List any specs, docs, or code created] Which project should I save to? (Use /projects to see registered projects) I'll save to the appropriate directory (docs/, specs/, or custom path). ``` --- ### 3. "Continue in CLI" **Prompt ID**: `continue-in-cli` **Purpose**: Handoff current work to Claude Code **Content**: ```markdown I'll hand off our current work to Claude Code CLI for implementation. Summary of what we've done: - [Summarize conversation] What should Claude Code implement? I'll: 1. Create a checkpoint with our current state 2. Invoke Claude Code with your task 3. Stream progress updates back here 4. Return results for review Ready to proceed? ``` --- ### 4. "Project Status" **Prompt ID**: `project-status` **Purpose**: Quick project overview **Content**: ```markdown I'll give you a complete overview of your project's current state: - Recent checkpoints - Claude Code task history - Modified files - Git status (if available) Which project would you like to check? ``` --- ## Slash Commands ### /projects **Purpose**: Quick list of registered projects **Behavior**: 1. Call `list_projects` tool 2. Display formatted table of projects 3. Show last accessed time and Claude state availability **Output Format**: ``` 📁 Registered Projects: myapp /Users/brian/dev/myapp Active 2 hours ago backend-api /Users/brian/dev/backend Active 5 days ago frontend /Users/brian/dev/frontend Inactive 30 days ago Use register_project to add new projects. ``` --- ### /project {projectId} **Purpose**: Set active project context for conversation **Behavior**: 1. Call `get_project_status` for specified project 2. Set project as active in conversation context 3. Load session state resource 4. Display project info + recent activity **Output Format**: ``` ✅ Active project: My Application 📂 /Users/brian/dev/myapp Recent activity: • 2 hours ago: Created authentication spec • 1 hour ago: Claude Code scaffolded REST API 3 checkpoints available | 5 files modified | Git: feature/auth branch What would you like to work on? ``` --- ### /save {filePath} **Purpose**: Quick save to active project **Behavior**: 1. Require active project context (set via /project) 2. Extract most recent artifact from conversation 3. Call `write_to_project` with specified path 4. Confirm save with full path **Example**: ``` User: /save docs/feature_spec.md Claude: ✅ Saved to /Users/brian/dev/myapp/docs/feature_spec.md (4.5 KB) ``` --- ### /implement {task} **Purpose**: Quick invoke Claude Code with task **Behavior**: 1. Require active project context 2. Call `invoke_claude_code` with task description 3. Stream progress updates 4. Display results when complete **Example**: ``` User: /implement create JWT middleware based on auth spec Claude: 🚀 Starting Claude Code task... ⏳ Reading context files... (14:35:02) ⏳ Analyzing requirements... (14:35:05) ✍️ Creating src/middleware/jwt.ts... (14:35:12) ✅ Task completed in 3m 2s Files modified: • src/middleware/jwt.ts (created) • tests/middleware/jwt.test.ts (created) • src/api/auth.ts (modified) Ready to review the changes? ``` --- ### /checkpoint {summary} **Purpose**: Quick checkpoint creation **Behavior**: 1. Require active project context 2. Gather recent artifacts from conversation 3. Call `create_checkpoint` with summary 4. Confirm checkpoint saved **Example**: ``` User: /checkpoint completed auth spec and middleware implementation Claude: ✅ Checkpoint saved to /Users/brian/dev/myapp/.claude/session_state.json You can now pick up this work in: • Claude Code CLI: cd /Users/brian/dev/myapp && claude-code • VS Code: The Claude Code extension will load this state automatically ``` --- ### /status **Purpose**: Show status of active project **Behavior**: 1. Require active project context 2. Call `get_project_status` with git info 3. Display formatted status **Example**: ``` User: /status Claude: 📊 Project Status: myapp Checkpoints: 3 (last: 2 hours ago) Claude Code Tasks: 2 completed, 0 running Recent Files: docs/auth_spec.md, src/api/auth.ts Git: feature/auth (5 uncommitted changes) Last checkpoint: "Created authentication spec" Next suggested actions: • Implement JWT middleware • Add integration tests ``` --- ## Error Handling ### User-Facing Errors **Project not found**: ``` ❌ Project 'myapp' not registered. Available projects: • backend-api • frontend Register this project: /register_project myapp /path/to/myapp ``` **File already exists**: ``` ⚠️ File 'docs/spec.md' already exists in myapp. Options: 1. Overwrite (will replace existing content) 2. Cancel and choose different path 3. Append to existing file What would you like to do? ``` **Claude Code not installed**: ``` ❌ Claude Code CLI not found at /usr/local/bin/claude-code Install Claude Code: • brew install claude-code (macOS) • npm install -g @anthropic-ai/claude-code Or configure custom path in MCP settings. ``` **Task timeout**: ``` ⚠️ Claude Code task exceeded 5m timeout. Partial results: • Created src/api/auth.ts • In progress: tests/auth.test.ts Options: 1. View partial results 2. Retry with longer timeout 3. Continue manually in CLI ``` --- ## Implementation Notes for Developer ### Priority Order 1. **Phase 1** (MVP): Tools 1-4 (register, list, write, read) + /projects, /project, /save commands 2. **Phase 2**: invoke_claude_code tool + /implement command + streaming support 3. **Phase 3**: Checkpoint system (tools 6-7) + remaining prompts + resources 4. **Phase 4**: Git integration in get_project_status ### Technical Considerations **Claude Code CLI Integration**: - Spawn process using Node.js `child_process.spawn` - Capture stdout/stderr for streaming - Parse output for structured data (file changes, errors) - Handle graceful termination on timeout **File System Security**: - Only access paths within registered projects - Validate all paths to prevent directory traversal (../) - Use path.resolve() to normalize paths - Check write permissions before file operations **State Management**: - Use atomic writes for session_state.json (write to temp, then rename) - Lock file while writing to prevent corruption - Keep in-memory cache of active projects for performance - Lazy-load resources (don't read all files on startup) **Performance**: - Index large projects (>10k files) in background - Cache file tree for resources (refresh on demand) - Stream large file reads (don't load entire file into memory) - Debounce rapid tool calls (e.g., multiple quick saves) **Testing Requirements**: - Unit tests for all tools - Integration test: Desktop → write → CLI invoke → checkpoint flow - Error handling tests for all failure modes - Performance test with 100k file project --- ## Success Criteria **MVP (Phase 1)**: - Developer can register project from Desktop - Developer can write spec from Desktop conversation to project docs/ - Developer can read project files into Desktop context - /projects and /save commands work reliably **Full Feature (Phase 2-3)**: - Developer can invoke Claude Code from Desktop and get results - Session state preserves context across interfaces - Streaming updates work without blocking **Quality Bar**: - All tools respond in <500ms for typical projects - Zero data loss (atomic writes, error recovery) - Clear error messages for all failure modes - Works with projects up to 100k files --- ## Open Questions for antigravity 1. **Claude Code CLI API**: Does Claude Code support --task and --context flags, or do we need to work with stdin? 2. **Streaming protocol**: Should we use SSE, websockets, or polling for status updates? 3. **Git integration**: Should MCP handle git operations or just read status? 4. **VS Code extension**: Do we need explicit handoff API, or can VS Code just read .claude/ state files? **Recommended**: Start with Phase 1 MVP, get user feedback, then expand to CLI invocation.