# Claude Code Connector MCP

An MCP server that bridges Claude Desktop, Claude Code CLI, and Claude Code for VS Code, enabling seamless developer workflows across all three interfaces.

## Overview

This MCP server allows developers to:
- Plan and research in Claude Desktop
- Push specs and documents directly to project directories
- Invoke Claude Code CLI from Desktop conversations
- Share state and context across all Claude interfaces

## Project Status

**Current Phase**: Planning  
**Target Developer**: antigravity  
**Priority**: P0

## Documentation

- **[PRODUCT_SPEC.md](./PRODUCT_SPEC.md)** - Complete product specification with all features, tools, resources, prompts, and slash commands
- **[ROADMAP.md](./ROADMAP.md)** - Implementation phases and timeline
- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** - Technical architecture (to be created)

## Quick Start (Post-Implementation)

### Installation
```bash
npm install -g @ciq/claude-code-connector-mcp
```

### Configuration
Add to your Claude Desktop config:
```json
{
  "mcpServers": {
    "claude-code": {
      "command": "claude-code-connector",
      "args": ["--projects-config", "~/.claude/projects.json"]
    }
  }
}
```

### Usage
```
/projects                          # List registered projects
/project myapp                     # Set active project
/save docs/spec.md                 # Save to project
/implement create auth middleware  # Invoke Claude Code
/checkpoint completed auth         # Create checkpoint
```

## Development Phases

### Phase 1: MVP (Core File Operations)
- Project registration and management
- File read/write to project directories
- Basic slash commands: /projects, /project, /save
- **Estimated**: 1 week

### Phase 2: Claude Code Integration
- CLI invocation with task delegation
- Streaming status updates
- /implement command
- **Estimated**: 1 week

### Phase 3: State Management
- Checkpoint system
- Session state persistence
- Cross-interface context sharing
- **Estimated**: 1 week

### Phase 4: Advanced Features
- Git integration
- MCP resources and prompts
- Performance optimization
- **Estimated**: 1 week

## Key Features

### MCP Tools (7 total)
1. `register_project` - Register codebase directory
2. `list_projects` - Show all registered projects
3. `write_to_project` - Write file to project
4. `read_from_project` - Read file from project
5. `invoke_claude_code` - Execute Claude Code CLI task
6. `create_checkpoint` - Save conversation state
7. `get_project_status` - Get project overview

### MCP Resources (3 total)
- `claude-code://{projectId}/files` - Project file tree
- `claude-code://{projectId}/session` - Session state
- `claude-code://{projectId}/docs` - Project documentation

### MCP Prompts (4 total)
- `plan-and-implement` - Full workflow guide
- `save-to-project` - Quick save artifacts
- `continue-in-cli` - Handoff to CLI
- `project-status` - Project overview

### Slash Commands (6 total)
- `/projects` - List projects
- `/project {id}` - Set active project
- `/save {path}` - Quick save
- `/implement {task}` - Invoke Claude Code
- `/checkpoint {summary}` - Create checkpoint
- `/status` - Project status

## Architecture

### Components
- **MCP Server**: Node.js/TypeScript server implementing MCP protocol
- **Project Manager**: Handles project registration and file operations
- **CLI Invoker**: Spawns and manages Claude Code processes
- **State Manager**: Handles session state and checkpoints
- **Resource Provider**: Exposes project data as MCP resources

### Data Storage
- `~/.claude/projects.json` - Project registry
- `{project}/.claude/session_state.json` - Per-project session state

## Success Metrics

### MVP Success
- Developer can register project from Desktop
- Developer can write specs to project directory
- Developer can read project files
- Basic commands work reliably

### Full Feature Success
- Developer can invoke Claude Code from Desktop
- State persists across interfaces
- Streaming updates work
- <500ms response time for typical operations

## Contributing

This is a CIQ internal project. Development by antigravity.

### Development Setup
```bash
git clone [repository]
cd claude-code-connector-mcp
npm install
npm run build
npm link  # For local testing
```

### Testing
```bash
npm test              # Run unit tests
npm run test:integration  # Run integration tests
npm run test:e2e     # Run end-to-end tests
```

## License

Proprietary - CIQ Inc.

## Support

For issues or questions, contact Brian (Product Manager) or antigravity (Developer).

## Roadmap

See [ROADMAP.md](./ROADMAP.md) for detailed implementation plan.

## Open Questions

1. Does Claude Code CLI support --task and --context flags?
2. What's the best streaming protocol (SSE, websockets, polling)?
3. Should MCP handle git operations directly?
4. How should VS Code extension consume state files?

**Status**: Awaiting technical discovery from antigravity.