@ebowwa/claude-code-mcp 1.0.0 → 1.0.2

package/DOCUMENTATION.md

@@ -1,747 +0,0 @@
-# @mcp/claude-code
-
-MCP server for managing Claude Code CLI sessions with Doppler integration.
-
-This MCP server **complements** `@mcp/claude-code-history` by providing session management capabilities while the history server handles conversation data access.
-
-## Features
-
-- **Start Sessions**: Launch new Claude Code sessions with project context
-- **Resume Sessions**: Resume existing sessions by UUID with Doppler support
-- **List Sessions**: Discover active and recent sessions
-- **Kill Sessions**: Terminate running sessions
-- **Message Pass-through**: Send messages to active sessions
-- **Context Sync**: Synchronize context between sessions
-- **Doppler Integration**: Seamless secret management for API keys and environment
-- **Stream Output**: Real-time output streaming from sessions
-- **Wait for Completion**: Block until session completes with optional timeout
-
-## Relationship to Other MCPs
-
-| MCP Server | Purpose | How They Work Together |
-|------------|---------|------------------------|
-| `@mcp/claude-code` | **Session Management** - Start, resume, kill sessions | Manages the lifecycle of Claude Code CLI processes |
-| `@mcp/claude-code-history` | **History Access** - Read past conversations | Reads conversation data from completed/active sessions |
-| `@mcp/claude-code-config` | **Configuration** - Manage Claude Code settings | Manages CLAUDE.md, keybindings, MCP server configs |
-
-**Typical Workflow:**
-1. Use `@mcp/claude-code` to start/resume a session
-2. Use `@mcp/claude-code-history` to search past context
-3. Use `@mcp/claude-code-config` to update settings if needed
-
-## Installation
-
-```bash
-cd /Users/ebowwa/Desktop/codespaces/packages/mcp/claude-code
-bun install
-bun run build
-```
-
-## Doppler Setup
-
-The Doppler workaround is essential for session resumption. Claude Code's `--resume` flag requires the `ANTHROPIC_API_KEY` to be set, which we manage through Doppler.
-
-### 1. Install Doppler CLI
-
-```bash
-# macOS
-brew install dopplerlabs/tap/doppler
-
-# Linux
-curl -sSL https://dl.doppler.com/install.sh | sh
-```
-
-### 2. Configure Doppler Project
-
-```bash
-# Login to Doppler
-doppler login
-
-# Create a new project
-doppler projects create claude-code-mcp
-
-# Setup your config
-doppler setup
-```
-
-### 3. Set Required Secrets
-
-```bash
-# Set your Anthropic API key
-doppler secrets set ANTHROPIC_API_KEY sk-ant-xxx
-
-# Optional: Set multiple keys for rotation (rolling keys)
-doppler secrets set ANTHROPIC_API_KEYS '["sk-ant-key1","sk-ant-key2"]'
-
-# Optional: Set Claude directory path
-doppler secrets set CLAUDE_DIR /Users/yourname/.claude
-```
-
-### 4. Verify Configuration
-
-```bash
-# List all secrets
-doppler secrets list
-
-# Run a test command with secrets loaded
-doppler run -- env | grep ANTHROPIC
-```
-
-## Usage
-
-### Add to Claude Code MCP Configuration
-
-Add to your `~/.claude.json` or project `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "claude-code": {
-      "command": "doppler",
-      "args": [
-        "run",
-        "--config",
-        "dev",
-        "--",
-        "bun",
-        "/Users/ebowwa/Desktop/codespaces/packages/mcp/claude-code/src/index.ts"
-      ],
-      "env": {
-        "DOPPLER_PROJECT": "claude-code-mcp",
-        "DOPPLER_CONFIG": "dev"
-      }
-    }
-  }
-}
-```
-
-**Key Pattern:** The `doppler run --` wrapper ensures `ANTHROPIC_API_KEY` is available when using `--resume` flag.
-
-## Available Tools
-
-### Session Management
-
-#### 1. `start_session`
-
-Start a new Claude Code session.
-
-```json
-{
-  "name": "start_session",
-  "arguments": {
-    "projectPath": "/path/to/project",
-    "message": "Initial message to send",
-    "options": {
-      "timeout": 300000,
-      "stream": false
-    }
-  }
-}
-```
-
-**Parameters:**
-- `projectPath` (required): Absolute path to project directory
-- `message` (optional): Initial message to send to the session
-- `options` (optional):
-  - `timeout`: Session timeout in milliseconds (default: 300000)
-  - `stream`: Enable output streaming (default: false)
-
-**Example:**
-```typescript
-const result = await client.callTool({
-  name: 'start_session',
-  arguments: {
-    projectPath: '/Users/ebowwa/Desktop/codespaces',
-    message: 'Review the PR for the rolling-keys package',
-    options: {
-      timeout: 600000,
-      stream: true
-    }
-  }
-});
-```
-
-#### 2. `resume_session`
-
-Resume an existing Claude Code session by UUID.
-
-**CRITICAL:** Requires Doppler to inject `ANTHROPIC_API_KEY` for the `--resume` flag to work.
-
-```json
-{
-  "name": "resume_session",
-  "arguments": {
-    "sessionId": "uuid-here",
-    "message": "Message to send on resume",
-    "options": {
-      "useDoppler": true,
-      "timeout": 300000
-    }
-  }
-}
-```
-
-**Parameters:**
-- `sessionId` (required): UUID of the session to resume
-- `message` (optional): Message to send after resuming
-- `options` (optional):
-  - `useDoppler`: Use Doppler wrapper (default: true)
-  - `timeout`: Session timeout in milliseconds (default: 300000)
-  - `stream`: Enable output streaming (default: false)
-
-**The Doppler Workaround:**
-When `useDoppler` is true, the session is resumed using:
-```bash
-doppler run --command "claude --resume UUID -- 'message'"
-```
-
-This ensures `ANTHROPIC_API_KEY` is available for the resumed session.
-
-**Example:**
-```typescript
-const result = await client.callTool({
-  name: 'resume_session',
-  arguments: {
-    sessionId: 'abc-123-def-456',
-    message: 'Continue with the next task',
-    options: {
-      useDoppler: true,
-      timeout: 600000
-    }
-  }
-});
-```
-
-#### 3. `list_sessions`
-
-List all Claude Code sessions (active and recent).
-
-```json
-{
-  "name": "list_sessions",
-  "arguments": {
-    "status": "all",
-    "limit": 20
-  }
-}
-```
-
-**Parameters:**
-- `status` (optional): Filter by status - "active", "completed", "all" (default: "all")
-- `limit` (optional): Maximum number of sessions to return (default: 20)
-- `projectPath` (optional): Filter sessions by project path
-
-**Example:**
-```typescript
-const result = await client.callTool({
-  name: 'list_sessions',
-  arguments: {
-    status: 'active',
-    projectPath: '/Users/ebowwa/Desktop/codespaces'
-  }
-});
-```
-
-#### 4. `kill_session`
-
-Terminate a running session.
-
-```json
-{
-  "name": "kill_session",
-  "arguments": {
-    "sessionId": "uuid-here",
-    "force": false
-  }
-}
-```
-
-**Parameters:**
-- `sessionId` (required): UUID of the session to kill
-- `force` (optional): Force kill without graceful shutdown (default: false)
-
-**Example:**
-```typescript
-const result = await client.callTool({
-  name: 'kill_session',
-  arguments: {
-    sessionId: 'abc-123-def-456',
-    force: true
-  }
-});
-```
-
-### Message & Context Management
-
-#### 5. `send_message`
-
-Send a message to an active session.
-
-```json
-{
-  "name": "send_message",
-  "arguments": {
-    "sessionId": "uuid-here",
-    "message": "Your message here",
-    "waitForResponse": true
-  }
-}
-```
-
-**Parameters:**
-- `sessionId` (required): UUID of the target session
-- `message` (required): Message content to send
-- `waitForResponse` (optional): Wait for response before returning (default: true)
-
-**Example:**
-```typescript
-const result = await client.callTool({
-  name: 'send_message',
-  arguments: {
-    sessionId: 'abc-123-def-456',
-    message: 'What is the current status of the rolling-key tests?',
-    waitForResponse: true
-  }
-});
-```
-
-#### 6. `sync_context`
-
-Synchronize context between sessions or update context for a session.
-
-```json
-{
-  "name": "sync_context",
-  "arguments": {
-    "sourceSessionId": "source-uuid",
-    "targetSessionId": "target-uuid",
-    "contextType": "all"
-  }
-}
-```
-
-**Parameters:**
-- `sourceSessionId` (optional): Source session UUID (if syncing between sessions)
-- `targetSessionId` (optional): Target session UUID
-- `contextType` (optional): Type of context to sync - "all", "history", "files", "state" (default: "all")
-- `contextData` (optional): Direct context data to apply (JSON object)
-
-**Example:**
-```typescript
-// Sync context between sessions
-const result = await client.callTool({
-  name: 'sync_context',
-  arguments: {
-    sourceSessionId: 'abc-123-def-456',
-    targetSessionId: 'xyz-789-uvw-012',
-    contextType: 'history'
-  }
-});
-
-// Update context directly
-const result2 = await client.callTool({
-  name: 'sync_context',
-  arguments: {
-    targetSessionId: 'xyz-789-uvw-012',
-    contextData: {
-      files: ['/path/to/file1.ts', '/path/to/file2.ts'],
-      lastMessage: 'Here is the context you need'
-    }
-  }
-});
-```
-
-### Advanced Features
-
-#### 7. `stream_output`
-
-Enable real-time output streaming from a session.
-
-```json
-{
-  "name": "stream_output",
-  "arguments": {
-    "sessionId": "uuid-here",
-    "lines": 100
-  }
-}
-```
-
-**Parameters:**
-- `sessionId` (required): UUID of the session
-- `lines` (optional): Number of recent lines to stream (default: 100, 0 for all)
-- "follow" (optional): Continue streaming new output (default: false)
-
-**Example:**
-```typescript
-const result = await client.callTool({
-  name: 'stream_output',
-  arguments: {
-    sessionId: 'abc-123-def-456',
-    lines: 50,
-    follow: true
-  }
-});
-```
-
-#### 8. `wait_for_completion`
-
-Wait for a session to complete with optional timeout.
-
-```json
-{
-  "name": "wait_for_completion",
-  "arguments": {
-    "sessionId": "uuid-here",
-    "timeout": 300000,
-    "pollInterval": 1000
-  }
-}
-```
-
-**Parameters:**
-- `sessionId` (required): UUID of the session to wait for
-- `timeout` (optional): Maximum time to wait in milliseconds (default: 300000)
-- `pollInterval` (optional): Polling interval in milliseconds (default: 1000)
-
-**Example:**
-```typescript
-const result = await client.callTool({
-  name: 'wait_for_completion',
-  arguments: {
-    sessionId: 'abc-123-def-456',
-    timeout: 600000,
-    pollInterval: 2000
-  }
-});
-```
-
-## Session Management Patterns
-
-### Pattern 1: Sequential Task Execution
-
-Start a session, wait for completion, then process results:
-
-```typescript
-// 1. Start session
-const { sessionId } = await client.callTool({
-  name: 'start_session',
-  arguments: {
-    projectPath: '/path/to/project',
-    message: 'Fix the authentication bug'
-  }
-});
-
-// 2. Wait for completion
-await client.callTool({
-  name: 'wait_for_completion',
-  arguments: { sessionId, timeout: 600000 }
-});
-
-// 3. Stream output to see results
-const output = await client.callTool({
-  name: 'stream_output',
-  arguments: { sessionId, lines: 0 }
-});
-```
-
-### Pattern 2: Long-Running Background Task
-
-Start a session, let it run in background, check status later:
-
-```typescript
-// 1. Start session
-const { sessionId } = await client.callTool({
-  name: 'start_session',
-  arguments: {
-    projectPath: '/path/to/project',
-    message: 'Run full test suite and generate coverage report',
-    options: { timeout: 3600000 } // 1 hour
-  }
-});
-
-// 2. Store sessionId for later...
-// 3. Check status later
-const sessions = await client.callTool({
-  name: 'list_sessions',
-  arguments: { status: 'active' }
-});
-
-// 4. Resume if needed
-await client.callTool({
-  name: 'resume_session',
-  arguments: {
-    sessionId,
-    message: 'What is the current progress?',
-    options: { useDoppler: true }
-  }
-});
-```
-
-### Pattern 3: Multi-Session Collaboration
-
-Run multiple sessions in parallel, sync context between them:
-
-```typescript
-// 1. Start backend session
-const backend = await client.callTool({
-  name: 'start_session',
-  arguments: {
-    projectPath: '/path/to/backend',
-    message: 'Implement the user authentication endpoint'
-  }
-});
-
-// 2. Start frontend session
-const frontend = await client.callTool({
-  name: 'start_session',
-  arguments: {
-    projectPath: '/path/to/frontend',
-    message: 'Create the login form component'
-  }
-});
-
-// 3. Sync context from backend to frontend
-await client.callTool({
-  name: 'sync_context',
-  arguments: {
-    sourceSessionId: backend.sessionId,
-    targetSessionId: frontend.sessionId,
-    contextType: 'history'
-  }
-});
-
-// 4. Send API contract info to frontend
-await client.callTool({
-  name: 'send_message',
-  arguments: {
-    sessionId: frontend.sessionId,
-    message: 'The backend API endpoint is: POST /api/auth/login with { email, password }'
-  }
-});
-```
-
-### Pattern 4: Iterative Development with Resume
-
-Use resume to continue work on previous sessions:
-
-```typescript
-// 1. List recent sessions
-const sessions = await client.callTool({
-  name: 'list_sessions',
-  arguments: { status: 'completed', limit: 10 }
-});
-
-// 2. Find the session you want to continue
-const targetSession = sessions.find(s => s.summary.includes('auth fix'));
-
-// 3. Resume with new context
-await client.callTool({
-  name: 'resume_session',
-  arguments: {
-    sessionId: targetSession.id,
-    message: 'I need to add error handling for the auth endpoint',
-    options: { useDoppler: true } // CRITICAL: Enables Doppler workaround
-  }
-});
-```
-
-## Troubleshooting
-
-### "Session not found"
-
-- Verify the session UUID is correct
-- Check if the session has been cleaned up (sessions are purged after 24 hours by default)
-- Use `list_sessions` to find valid session IDs
-
-### "Resume failed: API key not found"
-
-This means the Doppler workaround is not working:
-
-```bash
-# Verify Doppler is configured
-doppler secrets list
-
-# Check ANTHROPIC_API_KEY is set
-doppler run -- env | grep ANTHROPIC
-
-# Ensure useDoppler: true in resume_session options
-```
-
-### "Session timeout"
-
-Increase the timeout value:
-
-```typescript
-const result = await client.callTool({
-  name: 'start_session',
-  arguments: {
-    projectPath: '/path/to/project',
-    message: 'Long running task',
-    options: { timeout: 3600000 } // 1 hour
-  }
-});
-```
-
-### "Context sync failed"
-
-- Verify both sessions exist and are accessible
-- Check contextType is valid ("all", "history", "files", "state")
-- Ensure source session has the requested context data
-
-### Doppler authentication issues
-
-```bash
-# Verify Doppler is authenticated
-doppler me
-
-# Check available projects
-doppler projects
-
-# Verify secrets are set
-doppler secrets list
-
-# Test Doppler run
-doppler run -- echo "Doppler works: $ANTHROPIC_API_KEY"
-```
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `CLAUDE_DIR` | Path to Claude Code directory | `~/.claude` |
-| `DOPPLER_PROJECT` | Doppler project name | - |
-| `DOPPLER_CONFIG` | Doppler config name | `dev` |
-| `DOPPLER_TOKEN` | Doppler auth token | - |
-| `ANTHROPIC_API_KEY` | Anthropic API key | (from Doppler) |
-| `SESSION_TIMEOUT` | Default session timeout (ms) | `300000` |
-| `SESSION_CLEANUP_AGE` | Age to clean up sessions (ms) | `86400000` (24h) |
-
-## Development
-
-```bash
-# Install dependencies
-bun install
-
-# Run in development mode
-bun run dev
-
-# Run tests
-bun run test
-
-# Run specific test suites
-bun run test:cli-wrapper
-bun run test:integration
-
-# Watch mode for tests
-bun run test:watch
-
-# Build
-bun run build
-
-# Start built server
-bun run start
-```
-
-## Testing
-
-Comprehensive test suite with unit and integration tests:
-
-### Test Structure
-
-- **cli-wrapper.test.ts** - Unit tests for CLI wrapper and Doppler integration
-- **integration.test.ts** - Integration tests with mock Claude binary
-- **test-config.ts** - Shared test utilities and mock helpers
-
-### Running Tests
-
-```bash
-# Run all tests
-bun test
-
-# Run with watch mode
-bun run test:watch
-
-# Run specific test file
-bun test src/cli-wrapper.test.ts
-
-# Run specific test
-bun test src/cli-wrapper.test.ts -t "should spawn Claude Code without Doppler"
-```
-
-### Key Test Cases
-
-**CLI Wrapper Tests:**
-- Process spawning with/without Doppler
-- Doppler workaround for `--resume` flag
-- Graceful and forceful process termination
-- Rolling API keys integration
-- Message escaping (quotes, newlines, special chars)
-- Malformed UUID handling
-- Missing Doppler configuration
-
-**Integration Tests:**
-- Full tool call lifecycle
-- Session state management
-- Context synchronization
-- Output streaming
-- Wait for completion with timeout
-
-See [TESTING.md](./TESTING.md) for detailed testing documentation.
-
-## Integration Examples
-
-### With claude-code-history
-
-```typescript
-// 1. Start a session
-const { sessionId } = await client.callTool({
-  name: 'start_session',
-  arguments: { projectPath: '/path/to/project' }
-});
-
-// 2. Wait for completion
-await client.callTool({
-  name: 'wait_for_completion',
-  arguments: { sessionId }
-});
-
-// 3. Use claude-code-history to search the conversation
-const history = await historyClient.callTool({
-  name: 'get_conversation_history',
-  arguments: { sessionId }
-});
-```
-
-### With claude-code-config
-
-```typescript
-// 1. Update CLAUDE.md before starting session
-await configClient.callTool({
-  name: 'write_global_claude_md',
-  arguments: {
-    content: '# Special Instructions\n\nFocus on performance optimization.'
-  }
-});
-
-// 2. Start session with new context
-const { sessionId } = await client.callTool({
-  name: 'start_session',
-  arguments: { projectPath: '/path/to/project' }
-});
-```
-
-## Dependencies
-
-This package requires the following workspace dependencies:
-
-- `@modelcontextprotocol/sdk` - MCP SDK for server implementation
-- `zod` - Runtime type validation
-
-## License
-
-MIT
-
-## Author
-
-ebowwa