@ebowwa/claude-code-mcp 1.0.0 → 1.0.2

package/ARCHITECTURE.md

@@ -1,1802 +0,0 @@
-# Claude Code MCP Server Architecture
-
-**Version:** 1.0.0
-**Date:** 2026-02-05
-**Status:** Design Document
-
----
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Design Philosophy](#design-philosophy)
-3. [Architecture Diagram](#architecture-diagram)
-4. [Core Components](#core-components)
-5. [Tool Schemas](#tool-schemas)
-6. [Session State Management](#session-state-management)
-7. [Doppler Integration](#doppler-integration)
-8. [Message Pass-Through Protocol](#message-pass-through-protocol)
-9. [Inter-Agent Communication](#inter-agent-communication)
-10. [Type System](#type-system)
-11. [Integration Patterns](#integration-patterns)
-12. [Security Considerations](#security-considerations)
-13. [Error Handling](#error-handling)
-14. [Performance Considerations](#performance-considerations)
-15. [Testing Strategy](#testing-strategy)
-16. [Future Enhancements](#future-enhancements)
-
----
-
-## Overview
-
-The Claude Code MCP Server provides programmatic control over Claude Code sessions via the Model Context Protocol (MCP). It complements the existing `claude-code-history` MCP by adding session lifecycle management capabilities.
-
-### Key Capabilities
-
-- **Session Management**: Start, resume, list, and kill Claude Code sessions
-- **Message Pass-Through**: Send messages to active sessions and receive responses
-- **Context Synchronization**: Sync project context and working directory state
-- **Doppler Integration**: Automatic secrets injection via `doppler run`
-- **Multi-Agent Coordination**: Built-in support for teammate messaging via `@ebowwa/teammates`
-- **Persistent State**: Session metadata tracking for recovery and monitoring
-
-### Relationship to Other MCPs
-
-```
-claude-code-history (READ-ONLY)
-├── List conversations
-├── Get conversation history
-└── Search conversations
-
-claude-code (READ-WRITE) ← This MCP
-├── Start new sessions
-├── Resume existing sessions
-├── Kill sessions
-├── Send messages to sessions
-└── Sync context
-
-Complementary: Together provide full lifecycle management
-```
-
----
-
-## Design Philosophy
-
-### Core Principles
-
-1. **Composability**: Every component is modular and reusable
-2. **Type Safety**: Full TypeScript coverage with Zod validation
-3. **Idempotency**: Operations are safe to retry
-4. **Observability**: All actions are logged and traceable
-5. **Graceful Degradation**: Failures don't crash sessions
-6. **Doppler-First**: Secrets management via environment variables
-
-### Architectural Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| **stdio Transport** | Local execution, no network overhead |
-| **JSON-RPC 2.0** | Standard MCP protocol (2024-11-05) |
-| **Zod Schemas** | Runtime validation + TypeScript inference |
-| **Doppler Wrapping** | Secure secrets injection without .env files |
-| **Teammates Integration** | Native multi-agent coordination |
-| **File-Based State** | Simple persistence, no database required |
-
----
-
-## Architecture Diagram
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                         Claude Code MCP                         │
-│                     (stdio:// transport)                        │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-                ┌────────────┴────────────┐
-                │                         │
-        ┌───────▼────────┐       ┌────────▼────────┐
-        │  Tool Router   │       │ State Manager   │
-        └───────┬────────┘       └────────┬────────┘
-                │                         │
-        ┌───────┴─────────────────────────┴────────┐
-        │                                          │
-┌───────▼────────┐  ┌────────────┐  ┌────────────▼──────┐
-│ start_session  │  │ resume_    │  │ sync_context      │
-│ kill_session   │  │ session    │  │ send_message      │
-│ list_sessions  │  │ wait_for_  │  │ stream_output     │
-└───────┬────────┘  │ completion │  └──────────┬───────┘
-        │           └────────────┘             │
-        │                                       │
-┌───────▼───────────────────────────────────────▼────────┐
-│            Claude Code CLI Wrapper                      │
-│  (doppler run --command "claude-code ...")              │
-└──────────────────────┬──────────────────────────────────┘
-                       │
-         ┌─────────────┼─────────────┐
-         │             │             │
-    ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
-    │ Doppler │  │ Tmux    │  │ Team    │
-    │ Secrets │  │ Session │  │ Mates   │
-    └─────────┘  └─────────┘  └─────────┘
-```
-
----
-
-## Core Components
-
-### 1. MCP Server (stdio)
-
-```typescript
-// src/server.ts
-interface MCPServer {
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  handleRequest(request: JSONRPCMessage): Promise<JSONRPCResponse>;
-}
-```
-
-**Responsibilities:**
-- JSON-RPC 2.0 message handling
-- Tool routing and dispatch
-- Error handling and logging
-- Protocol negotiation (2024-11-05)
-
-### 2. Tool Router
-
-```typescript
-// src/tools/router.ts
-interface ToolRouter {
-  routes: Map<string, ToolHandler>;
-  register(name: string, handler: ToolHandler): void;
-  dispatch(name: string, args: unknown): Promise<ToolResult>;
-}
-```
-
-**Responsibilities:**
-- Tool registration and discovery
-- Input validation via Zod schemas
-- Handler execution
-- Response formatting
-
-### 3. Claude Code Wrapper
-
-```typescript
-// src/wrapper/claude-code.ts
-interface ClaudeCodeWrapper {
-  startSession(options: StartSessionOptions): Promise<ClaudeSession>;
-  resumeSession(sessionId: string): Promise<ClaudeSession>;
-  killSession(sessionId: string): Promise<void>;
-  sendMessage(sessionId: string, message: string): Promise<void>;
-  streamOutput(sessionId: string): AsyncIterable<string>;
-}
-```
-
-**Responsibilities:**
-- Spawn Claude Code processes
-- Wrap with `doppler run`
-- Manage process lifecycle
-- Handle stdio streams
-
-### 4. State Manager
-
-```typescript
-// src/state/manager.ts
-interface StateManager {
-  sessions: Map<string, SessionState>;
-  create(sessionId: string, state: SessionState): void;
-  get(sessionId: string): SessionState | undefined;
-  update(sessionId: string, updates: Partial<SessionState>): void;
-  delete(sessionId: string): void;
-  list(): SessionState[];
-  persist(): Promise<void>;
-}
-```
-
-**Responsibilities:**
-- Session metadata tracking
-- State persistence to disk
-- Concurrent access safety
-- Cleanup of stale sessions
-
-### 5. Doppler Integration
-
-```typescript
-// src/integrations/doppler.ts
-interface DopplerIntegration {
-  wrapCommand(command: string): string;
-  injectSecrets(): Promise<void>;
-  getSecret(key: string): string | undefined;
-}
-```
-
-**Responsibilities:**
-- Generate `doppler run` wrappers
-- Load secrets from Doppler config
-- Handle `--resume` flag workaround
-- Validate secret availability
-
-### 6. Teammates Messenger
-
-```typescript
-// src/integrations/teammates.ts
-interface TeammatesMessenger {
-  sendToTeammate(teammateName: string, message: string): Promise<void>;
-  broadcast(message: string): Promise<void>;
-  requestShutdown(teammateName: string): Promise<void>;
-  notifyIdle(reason: string): Promise<void>;
-}
-```
-
-**Responsibilities:**
-- Inter-agent communication
-- Teammate discovery via config
-- Message serialization
-- Response handling
-
----
-
-## Tool Schemas
-
-### Tool: start_session
-
-Start a new Claude Code session with optional context.
-
-```typescript
-import { z } from "zod";
-
-export const StartSessionSchema = z.object({
-  // Session identifier (auto-generated if not provided)
-  session_id: z.string().optional().describe(
-    "Unique session identifier. Auto-generated UUID if not provided."
-  ),
-
-  // Working directory for the session
-  cwd: z.string().optional().describe(
-    "Working directory for Claude Code session. Defaults to current directory."
-  ),
-
-  // Doppler project configuration
-  doppler_project: z.string().optional().describe(
-    "Doppler project name for secrets injection."
-  ),
-
-  doppler_config: z.string().optional().describe(
-    "Doppler configuration name (dev, prod, etc.). Defaults to 'dev'."
-  ),
-
-  // Initial prompt to send
-  prompt: z.string().optional().describe(
-    "Initial prompt/message to send to the session."
-  ),
-
-  // Teammate integration
-  team_name: z.string().optional().describe(
-    "Team name for teammates integration. Session will join this team."
-  ),
-
-  teammate_name: z.string().optional().describe(
-    "Name for this session as a teammate. Auto-generated if not provided."
-  ),
-
-  // Session options
-  model: z.string().optional().describe(
-    "Claude model to use (e.g., 'claude-sonnet-4-5-20250929')."
-  ),
-
-  max_turns: z.number().optional().describe(
-    "Maximum number of conversation turns. Optional for unlimited."
-  ),
-
-  // Output options
-  stream_output: z.boolean().default(false).describe(
-    "Whether to stream session output to stdout."
-  ),
-
-  log_file: z.string().optional().describe(
-    "Path to file for session logging. Optional."
-  ),
-});
-
-export type StartSessionInput = z.infer<typeof StartSessionSchema>;
-
-// Response schema
-export const StartSessionResponseSchema = z.object({
-  session_id: z.string().describe("Unique session identifier"),
-  status: z.enum(["starting", "ready", "error"]).describe("Session status"),
-  pid: z.number().optional().describe("Process ID if running"),
-  tmux_pane: z.string().optional().describe("Tmux pane ID if using tmux"),
-  started_at: z.string().datetime().describe("ISO 8601 timestamp"),
-});
-
-export type StartSessionResponse = z.infer<typeof StartSessionResponseSchema>;
-```
-
----
-
-### Tool: resume_session
-
-Resume an existing Claude Code session.
-
-```typescript
-export const ResumeSessionSchema = z.object({
-  session_id: z.string().describe(
-    "Session ID to resume. Must be an existing but inactive session."
-  ),
-
-  cwd: z.string().optional().describe(
-    "Override working directory. Defaults to original session directory."
-  ),
-
-  doppler_project: z.string().optional().describe(
-    "Override Doppler project. Defaults to original project."
-  ),
-
-  doppler_config: z.string().optional().describe(
-    "Override Doppler config. Defaults to original config."
-  ),
-
-  message: z.string().optional().describe(
-    "Message to send upon resuming."
-  ),
-});
-
-export type ResumeSessionInput = z.infer<typeof ResumeSessionSchema>;
-
-export const ResumeSessionResponseSchema = z.object({
-  session_id: z.string(),
-  status: z.enum(["resuming", "ready", "not_found", "error"]),
-  resumed_at: z.string().datetime(),
-  previous_state: z.object({
-    created_at: z.string().datetime(),
-    last_active: z.string().datetime().optional(),
-  }).optional(),
-});
-
-export type ResumeSessionResponse = z.infer<typeof ResumeSessionResponseSchema>;
-```
-
-**Resume Flag Workaround:**
-
-Due to Claude Code CLI limitations, resume is implemented via:
-```bash
-doppler run --command "claude-code --resume <session-id>"
-```
-
----
-
-### Tool: kill_session
-
-Terminate a running Claude Code session.
-
-```typescript
-export const KillSessionSchema = z.object({
-  session_id: z.string().describe(
-    "Session ID to terminate."
-  ),
-
-  force: z.boolean().default(false).describe(
-    "Force kill if graceful shutdown fails. Uses SIGKILL instead of SIGTERM."
-  ),
-
-  save_state: z.boolean().default(true).describe(
-    "Whether to save session state before killing. Preserves conversation history."
-  ),
-});
-
-export type KillSessionInput = z.infer<typeof KillSessionSchema>;
-
-export const KillSessionResponseSchema = z.object({
-  session_id: z.string(),
-  status: z.enum(["killed", "not_found", "already_dead", "error"]),
-  killed_at: z.string().datetime(),
-  exit_code: z.number().optional(),
-  state_saved: z.boolean(),
-});
-
-export type KillSessionResponse = z.infer<typeof KillSessionResponseSchema>;
-```
-
----
-
-### Tool: list_sessions
-
-List all Claude Code sessions with optional filtering.
-
-```typescript
-export const ListSessionsSchema = z.object({
-  status_filter: z.enum(["all", "active", "inactive", "error"]).default("all").describe(
-    "Filter sessions by status."
-  ),
-
-  team_filter: z.string().optional().describe(
-    "Filter sessions by team name."
-  ),
-
-  limit: z.number().optional().describe(
-    "Maximum number of sessions to return. Optional for unlimited."
-  ),
-
-  include_metadata: z.boolean().default(false).describe(
-    "Include full session metadata. Increases response size."
-  ),
-});
-
-export type ListSessionsInput = z.infer<typeof ListSessionsSchema>;
-
-export const ListSessionsResponseSchema = z.object({
-  sessions: z.array(z.object({
-    session_id: z.string(),
-    status: z.enum(["active", "inactive", "error", "zombie"]),
-    pid: z.number().optional(),
-    cwd: z.string().optional(),
-    created_at: z.string().datetime(),
-    last_active: z.string().datetime().optional(),
-    team_name: z.string().optional(),
-    teammate_name: z.string().optional(),
-    model: z.string().optional(),
-  })),
-  total_count: z.number(),
-  filtered_count: z.number(),
-});
-
-export type ListSessionsResponse = z.infer<typeof ListSessionsResponseSchema>;
-```
-
----
-
-### Tool: send_message
-
-Send a message to an active Claude Code session.
-
-```typescript
-export const SendMessageSchema = z.object({
-  session_id: z.string().describe(
-    "Target session ID. Must be active."
-  ),
-
-  message: z.string().describe(
-    "Message content to send to the session."
-  ),
-
-  wait_for_response: z.boolean().default(true).describe(
-    "Whether to wait for Claude's response before returning."
-  ),
-
-  timeout_ms: z.number().default(30000).describe(
-    "Maximum time to wait for response in milliseconds."
-  ),
-
-  include_context: z.boolean().default(false).describe(
-    "Include current file/context in message."
-  ),
-});
-
-export type SendMessageInput = z.infer<typeof SendMessageSchema>;
-
-export const SendMessageResponseSchema = z.object({
-  session_id: z.string(),
-  message_sent: z.boolean(),
-  response: z.string().optional().describe("Claude's response if wait_for_response=true"),
-  error: z.string().optional(),
-  sent_at: z.string().datetime(),
-  responded_at: z.string().datetime().optional(),
-});
-
-export type SendMessageResponse = z.infer<typeof SendMessageResponseSchema>;
-```
-
----
-
-### Tool: sync_context
-
-Synchronize project context between sessions.
-
-```typescript
-export const SyncContextSchema = z.object({
-  session_id: z.string().describe(
-    "Target session ID."
-  ),
-
-  context_type: z.enum(["files", "env", "git", "all"]).default("all").describe(
-    "Type of context to sync."
-  ),
-
-  paths: z.array(z.string()).optional().describe(
-    "Specific file/directory paths to sync. Optional for all."
-  ),
-
-  force: z.boolean().default(false).describe(
-    "Force sync even if context appears unchanged."
-  ),
-});
-
-export type SyncContextInput = z.infer<typeof SyncContextSchema>;
-
-export const SyncContextResponseSchema = z.object({
-  session_id: z.string(),
-  synced_at: z.string().datetime(),
-  context_type: z.string(),
-  files_synced: z.number().optional(),
-  env_vars_synced: z.number().optional(),
-  git_status_synced: z.boolean().optional(),
-  warnings: z.array(z.string()).optional(),
-});
-
-export type SyncContextResponse = z.infer<typeof SyncContextResponseSchema>;
-```
-
----
-
-### Tool: wait_for_completion
-
-Wait for a session to complete its current task.
-
-```typescript
-export const WaitForCompletionSchema = z.object({
-  session_id: z.string().describe(
-    "Session ID to wait for."
-  ),
-
-  timeout_ms: z.number().default(300000).describe(
-    "Maximum wait time in milliseconds. Default: 5 minutes."
-  ),
-
-  poll_interval_ms: z.number().default(1000).describe(
-    "Polling interval in milliseconds. Default: 1 second."
-  ),
-
-  check_idle: z.boolean().default(true).describe(
-    "Wait for session to become idle (not just responsive)."
-  ),
-});
-
-export type WaitForCompletionInput = z.infer<typeof WaitForCompletionSchema>;
-
-export const WaitForCompletionResponseSchema = z.object({
-  session_id: z.string(),
-  completed: z.boolean(),
-  timed_out: z.boolean(),
-  waited_ms: z.number(),
-  final_state: z.enum(["idle", "active", "error", "dead"]),
-  completed_at: z.string().datetime().optional(),
-});
-
-export type WaitForCompletionResponse = z.infer<typeof WaitForCompletionResponseSchema>;
-```
-
----
-
-### Tool: stream_output
-
-Stream real-time output from a session.
-
-```typescript
-export const StreamOutputSchema = z.object({
-  session_id: z.string().describe(
-    "Session ID to stream from."
-  ),
-
-  lines: z.number().optional().describe(
-    "Number of lines to stream. Optional for continuous stream."
-  ),
-
-  follow: z.boolean().default(false).describe(
-    "Continue streaming new output as it arrives."
-  ),
-});
-
-export type StreamOutputInput = z.infer<typeof StreamOutputSchema>;
-
-// Note: This tool uses Server-Sent Events (SSE) for streaming
-// The response is a continuous stream of text chunks
-```
-
----
-
-## Session State Management
-
-### Session State Schema
-
-```typescript
-// src/state/schema.ts
-import { z } from "zod";
-
-export const SessionStateSchema = z.object({
-  // Identity
-  session_id: z.string().describe("UUID v4 identifier"),
-
-  // Lifecycle
-  status: z.enum([
-    "starting",   // Process spawning
-    "ready",      // Accepting messages
-    "busy",       // Processing task
-    "idle",       // Waiting for work
-    "error",      // Error state
-    "dead",       // Process terminated
-    "zombie",     // Orphaned process
-  ]).describe("Current session status"),
-
-  // Process info
-  pid: z.number().optional().describe("Process ID"),
-  tmux_pane_id: z.string().optional().describe("Tmux pane ID"),
-
-  // Timing
-  created_at: z.string().datetime().describe("Session creation time"),
-  started_at: z.string().datetime().optional().describe("Ready time"),
-  last_active: z.string().datetime().optional().describe("Last activity"),
-  killed_at: z.string().datetime().optional().describe("Termination time"),
-
-  // Configuration
-  cwd: z.string().describe("Working directory"),
-  command: z.string().describe("Full command used to start"),
-  args: z.array(z.string()).describe("Command arguments"),
-
-  // Doppler
-  doppler_project: z.string().optional(),
-  doppler_config: z.string().optional(),
-
-  // Teammates
-  team_name: z.string().optional().describe("Team membership"),
-  teammate_name: z.string().optional().describe("Teammate identifier"),
-
-  // Model
-  model: z.string().optional().describe("Claude model"),
-  max_turns: z.number().optional().describe("Turn limit"),
-
-  // State
-  turn_count: z.number().default(0).describe("Messages exchanged"),
-  last_message: z.string().optional().describe("Last message sent"),
-  last_response: z.string().optional().describe("Last Claude response"),
-
-  // Logging
-  log_file: z.string().optional().describe("Session log path"),
-  error_log: z.array(z.string()).describe("Error history"),
-
-  // Metrics
-  messages_sent: z.number().default(0),
-  responses_received: z.number().default(0),
-  total_chars_sent: z.number().default(0),
-  total_chars_received: z.number().default(0),
-});
-
-export type SessionState = z.infer<typeof SessionStateSchema>;
-```
-
-### State Persistence
-
-```typescript
-// src/state/persistence.ts
-interface StatePersistence {
-  savePath: string; // ~/.claude/sessions/state.json
-
-  load(): Promise<Map<string, SessionState>>;
-  save(sessions: Map<string, SessionState>): Promise<void>;
-
-  // Atomic write to prevent corruption
-  atomicWrite(sessions: Map<string, SessionState>): Promise<void>;
-
-  // Backup before writes
-  backup(): Promise<void>;
-}
-```
-
-**Storage Format:**
-
-```json
-{
-  "version": "1.0.0",
-  "updated_at": "2026-02-05T12:00:00Z",
-  "sessions": {
-    "uuid-1": { /* SessionState */ },
-    "uuid-2": { /* SessionState */ }
-  }
-}
-```
-
-### State Transitions
-
-```
-     start_session()
-          │
-          ▼
-    [starting]
-          │
-   process ready
-          │
-          ▼
-     [ready] ◄─────────────┐
-          │                │
-   send_message()          │
-          │                │
-          ▼                │
-     [busy] ───complete──▶ [idle]
-          │                │
-       error              timeout
-          │                │
-          ▼                │
-     [error]               │
-          │                │
-     recover/cleanup       │
-          │                │
-          └────────────────▴──────▶ [dead]
-```
-
----
-
-## Doppler Integration
-
-### Doppler Command Wrapper
-
-```typescript
-// src/integrations/doppler.ts
-export class DopplerWrapper {
-  /**
-   * Wrap a Claude Code command with Doppler secrets injection
-   */
-  wrapCommand(command: string, options: {
-    project?: string;
-    config?: string;
-  }): string {
-    const { project, config = "dev" } = options;
-
-    if (!project) {
-      return command; // No wrapping if no project
-    }
-
-    // Use doppler run for automatic secrets injection
-    return `doppler run --command "${command}"`;
-  }
-
-  /**
-   * Generate Claude Code start command with Doppler
-   */
-  generateStartCommand(options: StartSessionInput): string {
-    const baseCommand = this.buildClaudeCodeCommand(options);
-    return this.wrapCommand(baseCommand, options);
-  }
-
-  /**
-   * Generate Claude Code resume command with Doppler
-   *
-   * WORKAROUND: Claude Code CLI doesn't natively support --resume flag
-   * We use doppler run --command to inject environment variables
-   */
-  generateResumeCommand(sessionId: string, options: ResumeSessionInput): string {
-    const resumeCmd = `claude-code --resume ${sessionId}`;
-    return this.wrapCommand(resumeCmd, options);
-  }
-
-  /**
-   * Build base Claude Code command
-   */
-  private buildClaudeCodeCommand(options: StartSessionInput): string {
-    const parts = ["claude-code"];
-
-    if (options.model) {
-      parts.push("--model", options.model);
-    }
-
-    if (options.max_turns) {
-      parts.push("--max-turns", String(options.max_turns));
-    }
-
-    if (options.cwd) {
-      parts.push("--cwd", options.cwd);
-    }
-
-    return parts.join(" ");
-  }
-}
-```
-
-### Environment Variables
-
-Doppler automatically injects these environment variables:
-
-```bash
-# From Doppler config
-ANTHROPIC_API_KEY=sk-ant-...
-OPENAI_API_KEY=sk-...
-GITHUB_TOKEN=ghp_...
-
-# Session-specific (set by MCP server)
-CLAUDE_SESSION_ID=<uuid>
-CLAUDE_TEAM_NAME=<team>
-CLAUDE_TEAMMATE_NAME=<name>
-```
-
-### Configuration
-
-```typescript
-// .doppler/doppler.yaml (example)
-project: claude-code-mcp
-config:
-  dev:
-    ANTHROPIC_API_KEY: sk-ant-...
-  prod:
-    ANTHROPIC_API_KEY: sk-ant-...
-```
-
----
-
-## Message Pass-Through Protocol
-
-### Protocol Design
-
-Messages flow through the MCP server to Claude Code sessions via stdio:
-
-```
-MCP Client → MCP Server → Claude Code Process → Claude
-    ↑                                                      ↓
-    └──────────────────────── response ───────────────────┘
-```
-
-### Message Format
-
-```typescript
-// src/messaging/protocol.ts
-interface PassThroughMessage {
-  version: "1.0";
-  session_id: string;
-  timestamp: string;
-
-  // Request
-  request: {
-    type: "message" | "context_sync" | "status_check";
-    payload: unknown;
-  };
-
-  // Response (async)
-  response?: {
-    type: "success" | "error" | "partial";
-    payload: unknown;
-  };
-}
-```
-
-### Send Message Flow
-
-```typescript
-// src/tools/send-message.ts
-async function sendMessage(input: SendMessageInput): Promise<SendMessageResponse> {
-  const session = stateManager.get(input.session_id);
-  if (!session) {
-    throw new Error(`Session ${input.session_id} not found`);
-  }
-
-  if (session.status !== "ready" && session.status !== "idle") {
-    throw new Error(`Session ${input.session_id} is not ready`);
-  }
-
-  // Write to process stdin
-  const process = processManager.get(input.session_id);
-  process.stdin.write(input.message + "\n");
-
-  // Update state
-  stateManager.update(input.session_id, {
-    last_message: input.message,
-    last_active: new Date().toISOString(),
-    status: "busy",
-    messages_sent: session.messages_sent + 1,
-    total_chars_sent: session.total_chars_sent + input.message.length,
-  });
-
-  // Wait for response if requested
-  if (input.wait_for_response) {
-    const response = await waitForResponse(session.pid, input.timeout_ms);
-
-    stateManager.update(input.session_id, {
-      last_response: response,
-      status: "idle",
-      responses_received: session.responses_received + 1,
-    });
-
-    return {
-      session_id: input.session_id,
-      message_sent: true,
-      response,
-      sent_at: new Date().toISOString(),
-      responded_at: new Date().toISOString(),
-    };
-  }
-
-  return {
-    session_id: input.session_id,
-    message_sent: true,
-    sent_at: new Date().toISOString(),
-  };
-}
-```
-
-### Response Parsing
-
-Claude Code outputs are captured from stdout:
-
-```typescript
-// src/messaging/response-parser.ts
-async function* readResponse(process: ChildProcess): AsyncIterable<string> {
-  const decoder = new TextDecoder();
-
-  for await (const chunk of process.stdout) {
-    const text = decoder.decode(chunk);
-
-    // Parse Claude Code output format
-    // (depends on actual CLI output format)
-    if (text.startsWith("claude: ")) {
-      yield text.slice(8);
-    }
-  }
-}
-```
-
----
-
-## Inter-Agent Communication
-
-### Teammates Integration
-
-The MCP server integrates with `@ebowwa/teammates` for multi-agent coordination:
-
-```typescript
-// src/integrations/teammates.ts
-import { Team, Teammate, sendMessage } from "@ebowwa/teammates";
-
-export class TeammatesIntegration {
-  /**
-   * Start a session as a teammate
-   */
-  async startAsTeammate(sessionId: string, options: StartSessionInput): Promise<void> {
-    if (!options.team_name) {
-      return; // No team integration
-    }
-
-    const teammate = await Teammate.create(options.team_name, {
-      teamName: options.team_name,
-      name: options.teammate_name || `session-${sessionId.slice(0, 8)}`,
-      subagentType: "general-purpose",
-      prompt: `Claude Code session ${sessionId}`,
-      backendType: "tmux",
-      mode: "delegate",
-    });
-
-    // Store teammate reference in session state
-    stateManager.update(sessionId, {
-      team_name: options.team_name,
-      teammate_name: teammate.name,
-    });
-  }
-
-  /**
-   * Send message to teammate
-   */
-  async sendToTeammate(sessionId: string, message: string): Promise<void> {
-    const session = stateManager.get(sessionId);
-    if (!session?.teammate_name) {
-      throw new Error(`Session ${sessionId} is not a teammate`);
-    }
-
-    await sendMessage({
-      type: "message",
-      recipient: session.teammate_name,
-      content: message,
-      summary: message.slice(0, 50),
-    });
-  }
-
-  /**
-   * Broadcast to team
-   */
-  async broadcastToTeam(sessionId: string, message: string): Promise<void> {
-    const session = stateManager.get(sessionId);
-    if (!session?.team_name) {
-      throw new Error(`Session ${sessionId} has no team`);
-    }
-
-    const team = await Team.load(session.team_name);
-    await team.broadcast(message);
-  }
-
-  /**
-   * Notify idle status
-   */
-  async notifyIdle(sessionId: string, reason: string): Promise<void> {
-    const session = stateManager.get(sessionId);
-    if (!session?.teammate_name) {
-      return;
-    }
-
-    await sendIdleNotification(session.teammate_name, reason);
-  }
-}
-```
-
-### Coordination Patterns
-
-**Pattern 1: Delegation**
-```
-User → MCP Server → Session A
-                    ↓
-              Session B (teammate)
-```
-
-**Pattern 2: Broadcast**
-```
-MCP Server → broadcast("Update available")
-             ↓
-    ┌────────┼────────┐
-    ▼        ▼        ▼
-Session A  Session B  Session C
-```
-
-**Pattern 3: Request/Response**
-```
-Session A → requestShutdown(Session B)
-Session B ──────────────────► approve: true
-Session A ──────────────────► terminate B
-```
-
----
-
-## Type System
-
-### Core Types
-
-```typescript
-// src/types/index.ts
-import { z } from "zod";
-
-// ============================================================================
-// SESSION TYPES
-// ============================================================================
-
-export type SessionStatus =
-  | "starting"
-  | "ready"
-  | "busy"
-  | "idle"
-  | "error"
-  | "dead"
-  | "zombie";
-
-export interface SessionMetadata {
-  session_id: string;
-  status: SessionStatus;
-  pid?: number;
-  tmux_pane_id?: string;
-  cwd: string;
-  created_at: string;
-  started_at?: string;
-  last_active?: string;
-}
-
-// ============================================================================
-// MESSAGE TYPES
-// ============================================================================
-
-export interface MessageRequest {
-  session_id: string;
-  content: string;
-  wait_for_response?: boolean;
-  timeout_ms?: number;
-}
-
-export interface MessageResponse {
-  session_id: string;
-  success: boolean;
-  response?: string;
-  error?: string;
-}
-
-// ============================================================================
-// CONTEXT TYPES
-// ============================================================================
-
-export type ContextType = "files" | "env" | "git" | "all";
-
-export interface ContextSyncRequest {
-  session_id: string;
-  context_type: ContextType;
-  paths?: string[];
-  force?: boolean;
-}
-
-// ============================================================================
-// PROCESS TYPES
-// ============================================================================
-
-export interface ProcessInfo {
-  pid: number;
-  ppid: number;
-  command: string;
-  args: string[];
-  cwd: string;
-  status: "running" | "stopped" | "zombie";
-}
-
-// ============================================================================
-// MCP TYPES
-// ============================================================================
-
-export interface MCPToolCall {
-  name: string;
-  arguments: Record<string, unknown>;
-}
-
-export interface MCPToolResponse {
-  content: Array<{
-    type: "text" | "image" | "resource";
-    text?: string;
-    data?: string;
-    uri?: string;
-  }>;
-  isError?: boolean;
-}
-
-// ============================================================================
-// ERROR TYPES
-// ============================================================================
-
-export class SessionNotFoundError extends Error {
-  constructor(public sessionId: string) {
-    super(`Session ${sessionId} not found`);
-    this.name = "SessionNotFoundError";
-  }
-}
-
-export class SessionNotReadyError extends Error {
-  constructor(
-    public sessionId: string,
-    public status: SessionStatus
-  ) {
-    super(`Session ${sessionId} is not ready (status: ${status})`);
-    this.name = "SessionNotReadyError";
-  }
-}
-
-export class DopplerError extends Error {
-  constructor(message: string, public project?: string) {
-    super(`Doppler error: ${message}`);
-    this.name = "DopplerError";
-  }
-}
-
-// ============================================================================
-// ZOD SCHEMAS (re-exported)
-// ============================================================================
-
-export * from "./schemas/session.js";
-export * from "./schemas/tools.js";
-export * from "./schemas/messages.js";
-```
-
----
-
-## Integration Patterns
-
-### Pattern 1: Complement claude-code-history MCP
-
-```typescript
-// Use both MCPs together
-import { ClaudeCodeMCP } from "@claude-code/mcp";
-import { ClaudeCodeHistoryMCP } from "@claude-code-history/mcp";
-
-// 1. List historical conversations
-const history = await historyMCP.listConversations();
-
-// 2. Resume specific conversation
-const session = await claudeCodeMCP.resumeSession(history[0].id);
-
-// 3. Send message
-await claudeCodeMCP.sendMessage(session.session_id, "Continue from here");
-```
-
-### Pattern 2: Coordinate with terminal MCP
-
-```typescript
-// Use terminal MCP for tmux + claude-code MCP for sessions
-import { TerminalMCP } from "@terminal/mcp";
-import { ClaudeCodeMCP } from "@claude-code/mcp";
-
-// 1. Create tmux session
-const tmux = await terminalMCP.createSession("host", "tmux");
-
-// 2. Start Claude Code in tmux
-const session = await claudeCodeMCP.startSession({
-  cwd: "/project",
-  team_name: "dev-team",
-});
-
-// 3. Split pane for monitoring
-await terminalMCP.splitPane(tmux.session_id, "htop");
-```
-
-### Pattern 3: Multi-Agent Orchestration
-
-```typescript
-import { Team } from "@ebowwa/teammates";
-import { ClaudeCodeMCP } from "@claude-code/mcp";
-
-// 1. Create team
-const team = await Team.create({
-  name: "code-review",
-  description: "Automated code review team",
-});
-
-// 2. Start multiple sessions
-const reviewer1 = await claudeCodeMCP.startSession({
-  team_name: "code-review",
-  teammate_name: "reviewer-1",
-  prompt: "Review for security issues",
-});
-
-const reviewer2 = await claudeCodeMCP.startSession({
-  team_name: "code-review",
-  teammate_name: "reviewer-2",
-  prompt: "Review for performance",
-});
-
-// 3. Send work to team
-await claudeCodeMCP.sendMessage(reviewer1.session_id, "Review auth.ts");
-await claudeCodeMCP.sendMessage(reviewer2.session_id, "Review api.ts");
-```
-
----
-
-## Security Considerations
-
-### 1. Secrets Management
-
-- **Never log secrets**: Doppler secrets are never written to logs
-- **Ephemeral injection**: Secrets only exist in process environment
-- **No .env files**: Avoids accidental commits
-
-### 2. Process Isolation
-
-```typescript
-// Spawn with restricted permissions
-const spawnOptions = {
-  env: { ...process.env, ...dopplerSecrets },
-  cwd: session.cwd,
-  uid: process.getuid(), // Run as current user
-  gid: process.getgid(),
-  detached: false, // No detached processes
-};
-```
-
-### 3. Input Validation
-
-- All tool inputs validated via Zod schemas
-- Path sanitization to prevent directory traversal
-- Command injection prevention via shell escaping
-
-### 4. Resource Limits
-
-```typescript
-// Limit concurrent sessions
-const MAX_CONCURRENT_SESSIONS = 10;
-
-// Limit session lifetime
-const MAX_SESSION_DURATION = 24 * 60 * 60 * 1000; // 24 hours
-
-// Limit message size
-const MAX_MESSAGE_SIZE = 100_000; // 100k characters
-```
-
-### 5. Audit Logging
-
-```typescript
-// Audit log for all operations
-interface AuditLog {
-  timestamp: string;
-  operation: string;
-  session_id?: string;
-  user?: string;
-  success: boolean;
-  error?: string;
-}
-
-// Write to audit log
-await auditLogger.write({
-  timestamp: new Date().toISOString(),
-  operation: "start_session",
-  session_id: sessionId,
-  user: process.env.USER,
-  success: true,
-});
-```
-
----
-
-## Error Handling
-
-### Error Categories
-
-```typescript
-// src/errors/index.ts
-export enum ErrorCategory {
-  SESSION_NOT_FOUND = "SESSION_NOT_FOUND",
-  SESSION_NOT_READY = "SESSION_NOT_READY",
-  DOPPLER_ERROR = "DOPPLER_ERROR",
-  PROCESS_ERROR = "PROCESS_ERROR",
-  VALIDATION_ERROR = "VALIDATION_ERROR",
-  TIMEOUT_ERROR = "TIMEOUT_ERROR",
-  PERMISSION_ERROR = "PERMISSION_ERROR",
-}
-
-export class MCPError extends Error {
-  constructor(
-    public category: ErrorCategory,
-    message: string,
-    public details?: unknown
-  ) {
-    super(message);
-    this.name = "MCPError";
-  }
-
-  toJSON() {
-    return {
-      name: this.name,
-      category: this.category,
-      message: this.message,
-      details: this.details,
-    };
-  }
-}
-```
-
-### Error Response Format
-
-```typescript
-// MCP tool error response
-interface ErrorResponse {
-  error: {
-    code: string; // ErrorCategory
-    message: string;
-    details?: unknown;
-    retryable: boolean;
-    suggestion?: string;
-  };
-}
-
-// Example
-{
-  error: {
-    code: "SESSION_NOT_FOUND",
-    message: "Session abc123 not found",
-    retryable: false,
-    suggestion: "Check session ID with list_sessions tool",
-  }
-}
-```
-
-### Retry Strategy
-
-```typescript
-// src/utils/retry.ts
-export async function retry<T>(
-  fn: () => Promise<T>,
-  options: {
-    maxAttempts: number;
-    baseDelay: number;
-    maxDelay: number;
-    retryableErrors: ErrorCategory[];
-  }
-): Promise<T> {
-  let lastError: Error;
-
-  for (let attempt = 0; attempt < options.maxAttempts; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error;
-
-      if (!isRetryable(error, options.retryableErrors)) {
-        throw error;
-      }
-
-      const delay = Math.min(
-        options.baseDelay * Math.pow(2, attempt),
-        options.maxDelay
-      );
-
-      await sleep(delay);
-    }
-  }
-
-  throw lastError;
-}
-```
-
----
-
-## Performance Considerations
-
-### 1. State Management
-
-- **In-memory cache**: Fast lookups for active sessions
-- **Lazy persistence**: Write to disk on state changes, not every tick
-- **Batch updates**: Aggregate multiple updates before persisting
-
-### 2. Process Pool
-
-```typescript
-// Reuse processes when possible
-class ProcessPool {
-  private pool: Map<string, ChildProcess> = new Map();
-
-  acquire(sessionId: string): ChildProcess {
-    return this.pool.get(sessionId) || this.spawn(sessionId);
-  }
-
-  release(sessionId: string): void {
-    // Keep process alive for reuse
-  }
-}
-```
-
-### 3. Streaming
-
-```typescript
-// Stream large outputs instead of buffering
-async function* streamOutput(sessionId: string): AsyncIterable<string> {
-  const process = getProcess(sessionId);
-
-  for await (const chunk of process.stdout) {
-    yield chunk.toString();
-  }
-}
-```
-
-### 4. Connection Pooling
-
-```typescript
-// Pool connections to Doppler API
-class DopplerConnectionPool {
-  private connections: Array<DopplerClient> = [];
-
-  acquire(): DopplerClient {
-    return this.connections.pop() || this.create();
-  }
-
-  release(client: DopplerClient): void {
-    this.connections.push(client);
-  }
-}
-```
-
----
-
-## Testing Strategy
-
-### Unit Tests
-
-```typescript
-// src/tools/__tests__/start-session.test.ts
-import { describe, it, expect, vi } from "vitest";
-import { startSession } from "../start-session.js";
-import { z } from "zod";
-
-describe("start_session tool", () => {
-  it("should validate input schema", () => {
-    const input = {
-      cwd: "/project",
-      doppler_project: "my-project",
-    };
-
-    expect(() => StartSessionSchema.parse(input)).not.toThrow();
-  });
-
-  it("should generate unique session ID if not provided", async () => {
-    const result = await startSession({ cwd: "/project" });
-
-    expect(result.session_id).toMatch(
-      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
-    );
-  });
-
-  it("should wrap command with doppler run", async () => {
-    const spy = vi.spyOn(DopplerWrapper, "wrapCommand");
-
-    await startSession({
-      cwd: "/project",
-      doppler_project: "my-project",
-    });
-
-    expect(spy).toHaveBeenCalledWith(
-      expect.stringContaining("claude-code"),
-      { project: "my-project", config: "dev" }
-    );
-  });
-});
-```
-
-### Integration Tests
-
-```typescript
-// tests/integration/session-lifecycle.test.ts
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { ClaudeCodeMCP } from "@claude-code/mcp";
-
-describe("Session lifecycle", () => {
-  const mcp = new ClaudeCodeMCP();
-  let sessionId: string;
-
-  it("should start a new session", async () => {
-    const result = await mcp.callTool("start_session", {
-      cwd: "/tmp/test-project",
-    });
-
-    expect(result.status).toBe("ready");
-    sessionId = result.session_id;
-  });
-
-  it("should list the session", async () => {
-    const result = await mcp.callTool("list_sessions", {
-      status_filter: "active",
-    });
-
-    expect(result.sessions).toContainEqual(
-      expect.objectContaining({ session_id: sessionId })
-    );
-  });
-
-  it("should send a message", async () => {
-    const result = await mcp.callTool("send_message", {
-      session_id: sessionId,
-      message: "Hello, Claude!",
-      wait_for_response: true,
-    });
-
-    expect(result.message_sent).toBe(true);
-    expect(result.response).toBeDefined();
-  });
-
-  it("should kill the session", async () => {
-    const result = await mcp.callTool("kill_session", {
-      session_id: sessionId,
-    });
-
-    expect(result.status).toBe("killed");
-  });
-});
-```
-
-### Load Tests
-
-```typescript
-// tests/load/concurrent-sessions.test.ts
-import { describe, it, expect } from "vitest";
-import { ClaudeCodeMCP } from "@claude-code/mcp";
-
-describe("Concurrent sessions", () => {
-  it("should handle 10 concurrent sessions", async () => {
-    const mcp = new ClaudeCodeMCP();
-    const sessionIds: string[] = [];
-
-    // Start 10 sessions concurrently
-    const promises = Array.from({ length: 10 }, (_, i) =>
-      mcp.callTool("start_session", {
-        cwd: `/tmp/test-project-${i}`,
-      })
-    );
-
-    const results = await Promise.all(promises);
-
-    results.forEach((result) => {
-      expect(result.status).toBe("ready");
-      sessionIds.push(result.session_id);
-    });
-
-    // Cleanup
-    await Promise.all(
-      sessionIds.map((id) =>
-        mcp.callTool("kill_session", { session_id: id })
-      )
-    );
-  });
-});
-```
-
----
-
-## Future Enhancements
-
-### Phase 2 Features
-
-1. **Session Templates**
-   ```typescript
-   const template = await mcp.createTemplate("code-review", {
-     prompt: "Review for security and performance",
-     model: "claude-sonnet-4-5",
-     max_turns: 50,
-   });
-
-   const session = await mcp.startFromTemplate("code-review", {
-     cwd: "/project",
-   });
-   ```
-
-2. **Session Cloning**
-   ```typescript
-   const clone = await mcp.cloneSession(originalSessionId, {
-     cwd: "/new-location",
-   });
-   ```
-
-3. **Batch Operations**
-   ```typescript
-   await mcp.batchOperation({
-     operation: "send_message",
-     session_ids: [id1, id2, id3],
-     message: "Update available",
-   });
-   ```
-
-4. **Session Metrics**
-   ```typescript
-   const metrics = await mcp.getSessionMetrics(sessionId);
-   // {
-   //   avg_response_time: 1.2,
-   //   total_tokens: 50000,
-   //   error_rate: 0.01,
-   // }
-   ```
-
-5. **Webhooks**
-   ```typescript
-   await mcp.registerWebhook({
-     events: ["session.ready", "session.error"],
-     url: "https://hook.example.com/events",
-   });
-   ```
-
-### Phase 3: AI Coordination
-
-1. **Auto-scaling Teams**
-   - Automatically spawn teammates based on workload
-   - Load balancing across sessions
-
-2. **Task Orchestration**
-   - DAG-based task dependencies
-   - Parallel execution with coordination
-
-3. **Context Sharing**
-   - Shared memory between sessions
-   - Distributed state management
-
----
-
-## Appendix
-
-### A. Configuration Files
-
-**package.json**
-```json
-{
-  "name": "@claude-code/mcp",
-  "version": "1.0.0",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "claude-code-mcp": "./dist/cli.js"
-  },
-  "dependencies": {
-    "@ebowwa/teammates": "workspace:*",
-    "zod": "^3.22.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
-    "vitest": "^1.0.0"
-  }
-}
-```
-
-**tsconfig.json**
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "outDir": "./dist",
-    "rootDir": "./src"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}
-```
-
-### B. Environment Variables
-
-```bash
-# Doppler Configuration
-DOPPLER_PROJECT=claude-code-mcp
-DOPPLER_CONFIG=dev
-
-# MCP Server Configuration
-MCP_PORT=8914
-MCP_LOG_LEVEL=info
-
-# Session Limits
-MAX_CONCURRENT_SESSIONS=10
-MAX_SESSION_DURATION=86400000
-
-# State Persistence
-STATE_DIR=~/.claude/sessions
-BACKUP_ENABLED=true
-```
-
-### C. MCP Server Manifest
-
-```json
-{
-  "name": "claude-code-mcp",
-  "version": "1.0.0",
-  "description": "Claude Code session management via MCP",
-  "protocolVersion": "2024-11-05",
-  "capabilities": {
-    "tools": {}
-  },
-  "tools": [
-    {
-      "name": "start_session",
-      "description": "Start a new Claude Code session"
-    },
-    {
-      "name": "resume_session",
-      "description": "Resume an existing Claude Code session"
-    },
-    {
-      "name": "kill_session",
-      "description": "Terminate a Claude Code session"
-    },
-    {
-      "name": "list_sessions",
-      "description": "List all Claude Code sessions"
-    },
-    {
-      "name": "send_message",
-      "description": "Send a message to a Claude Code session"
-    },
-    {
-      "name": "sync_context",
-      "description": "Sync context to a Claude Code session"
-    },
-    {
-      "name": "wait_for_completion",
-      "description": "Wait for session to complete current task"
-    },
-    {
-      "name": "stream_output",
-      "description": "Stream real-time output from a session"
-    }
-  ]
-}
-```
-
----
-
-## Sources
-
-This architecture document references the following resources:
-
-- [Model Context Protocol Architecture Documentation](https://modelcontextprotocol.info/docs/concepts/architecture/)
-- [MCP TypeScript SDK (mcp-auth)](https://github.com/mcp-auth/mcp-typescript-sdk)
-- [@mcpbay/easy-mcp-server](https://jsr.io/@mcpbay/easy-mcp-server)
-- [MCP Server Development Guide](https://github.com/cyanheads/model-context-protocol-resources/blob/main/guides/mcp-server-development-guide.md)
-- [详解MCP 传输机制](https://blog.csdn.net/sinat_37574187/article/details/147185240)
-- [@enth/mcp-sdk](https://www.npmjs.com/package/%40enth/mcp-sdk)
-- [Chinese MCP Architecture Guide](https://mcpcn.com/docs/concepts/architecture/)
-- [MCP Server and Client with SSE](https://levelup.gitconnected.com/mcp-server-and-client-with-sse-the-new-streamable-http-d860850d9d9d)
-- [Tencent Cloud MCP TypeScript SDK](https://cloud.tencent.com/developer/mcp/server/11591)
-- [The Model Context Protocol — Complete Tutorial](https://medium.com/@nimritakoul01/the-model-context-protocol-mcp-a-complete-tutorial-a3abe8a7f4ef)
-
----
-
-**Document Status:** Ready for Implementation
-**Next Steps:** Create package.json, implement tool handlers, write tests