curupira: Instructions file for Claude Code

Curupira MCP Debug Server

Context: Apply general Nexus Design Principles and TypeScript Standards to Curupira's Chrome DevTools Protocol + MCP bridge architecture.

🎯 Curupira-Specific Implementation

Curupira is an MCP debugging server that bridges Chrome DevTools Protocol with Model Context Protocol for React application debugging.

Architecture Overview

Chrome Browser ↔ CDP WebSocket ↔ Curupira Server ↔ MCP Protocol ↔ Claude

Curupira-Specific Hierarchy (Following Nexus Standards)

Level 0: Foundation        → Branded types, interfaces, configuration, errors
Level 1: Core Services     → Chrome service, repositories, buffer services  
Level 2: API Layer         → MCP handlers, resource/tool providers, transport
Level 3: Application       → Server bootstrap, dependency injection container

🔧 Chrome DevTools Protocol Integration

CDP Connection Management

// Branded types are defined in shared/src/types/branded.ts
import type { SessionId } from '@curupira/shared';

// Chrome service follows dependency injection pattern
export class ChromeService extends EventEmitter implements IChromeService {
  constructor(
    private readonly config: ChromeConfig,
    private readonly logger: ILogger,
    private readonly consoleBufferService?: IConsoleBufferService,
    networkBufferService?: INetworkBufferService
  ) {
    super();
  }

  async connect(options: ConnectionOptions): Promise<IChromeClient> {
    const client = new ChromeClient(this.logger, this.browserlessDetector, options);
    await client.connect();
    this.client = client;
    
    // Emit events for dynamic tool registration
    this.emit('connected', { client, options });
    
    return client;
  }
}

React Application Detection

// React detection implemented in integrations/react/detector.ts
export class ReactDetector {
  constructor(private logger: ILogger) {}
  
  async detect(client: IChromeClient, sessionId?: string): Promise<ReactInfo | null> {
    try {
      // Simplified detection using Runtime.evaluate
      const result = await client.send('Runtime.evaluate', {
        expression: 'typeof window.__REACT_DEVTOOLS_GLOBAL_HOOK__ !== "undefined"',
        returnByValue: true
      }, sessionId);
      
      if (result.result?.value === true) {
        return this.extractReactInfo(client, sessionId);
      }
      
      return null;
    } catch (error) {
      this.logger.debug({ error }, 'React detection failed');
      return null;
    }
  }
}