Curupira - Servidor MCP de Debug para React
pleme-io/curupira
Debug de React e state management via Chrome DevTools Protocol para assistentes IA
Ver no GitHubServidor MCP que oferece ao Claude acesso direto ao Chrome DevTools Protocol, permitindo inspeção de componentes React, debugging de state management (Apollo, Zustand, XState, Redux, TanStack Query) e análise de runtime de aplicações frontend. Integra-se com DevTools via WebSocket, HTTP/SSE ou stdio para diferentes cenários de deployment.
Instalação
npx convez-ai pleme-io/curupira1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Inspecionar e debugar componentes React em tempo real com acesso ao Chrome DevTools
- Analisar estado de aplicações complexas com múltiplas bibliotecas de state management
- Rastrear problemas de execução através da integração com Runtime, Debugger e Network do CDP
- Assistir debugging de aplicações React Router, Framer Motion, React Hook Form durante desenvolvimento
Veredito

Ferramenta especializada e bem-arquitetada para trazer capacidades avançadas de debugging de frontend para dentro do Claude. Ideal para desenvolvedores React que buscam assistência IA profunda em problemas complexos de estado e runtime, com suporte robusto a múltiplas bibliotecas e transports de conexão.
README
A tradução para o português deste README ainda está na fila.
Curupira - MCP Frontend Debugging Tool
Overview
Curupira is a Model Context Protocol (MCP) debugging tool that provides AI assistants with direct access to browser DevTools, React state, and runtime debugging capabilities. It bridges the gap between AI assistants and complex frontend applications through Chrome DevTools Protocol.
Key Features
- 🔍 Chrome DevTools Protocol Integration: Full access to CDP domains (Runtime, Debugger, Network, DOM, etc.)
- ⚛️ React Application Debugging: Component inspection, props/state analysis, hooks debugging
- 🎯 State Management: Apollo GraphQL, Zustand stores, XState machines, TanStack Query
- 🛠️ Framework Support: React Router, Framer Motion, React Hook Form, Vite, Panda CSS
- 🚀 Multiple Transports: WebSocket, HTTP/SSE, and stdio for different deployment scenarios
- 📦 Dependency Injection: Clean architecture with comprehensive DI container
- 🤖 AI-Optimized: Built specifically for AI assistant interaction via MCP
📚 Documentation
- API Documentation - Complete API reference for all resources, tools, and prompts
- CLI Reference - Command-line interface documentation
- Development Guide - Development setup and architecture
- Usage Examples - Common debugging scenarios and integration examples
- Troubleshooting Guide - Solutions for common issues
- Architecture - System architecture and design
Quick Start
Using Docker with Browserless
# Start Browserless Chrome service
docker run -d -p 3000:3000 --name browserless browserless/chrome
# Start Curupira MCP server
docker run -p 8080:8080 -e CHROME_SERVICE_URL=http://host.docker.internal:3000 drzln/curupira:latest
Using npm
# Install globally
npm install -g curupira
# Start with default configuration
curupira start
# Or specify a custom config
curupira start --config ./config/production.yaml
From Source
# Clone the repository
git clone https://github.com/pleme-io/nexus.git
cd nexus/pkgs/services/typescript/curupira
# Install dependencies
npm install
# Build the project
npm run build
# Start the MCP server
npm run start
# Or run in development mode with hot reload
npm run dev
Claude Code Integration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"curupira": {
"command": "node",
"args": ["/path/to/curupira/mcp-server/dist/main.js"],
"env": {
"CHROME_SERVICE_URL": "http://localhost:3000",
"LOGGING_LEVEL": "info"
}
}
}
}
Architecture
Curupira follows a clean architecture with dependency injection:
graph TD
A[Chrome Browser] -->|CDP WebSocket| B[Browserless Service]
B -->|CDP Protocol| C[Chrome Service Layer]
C -->|Events| D[Tool/Resource Providers]
D -->|MCP Protocol| E[MCP Server]
E -->|stdio/HTTP/WS| F[Claude/AI Assistant]
G[DI Container] -.->|Injects| C
G -.->|Injects| D
G -.->|Injects| E
Architectural Layers
- Foundation Layer - Branded types, interfaces, error definitions
- Core Services - Chrome service, buffer services, validators
- MCP Layer - Tool/resource providers, protocol handlers
- Application Layer - Server bootstrap, DI container, transport management
Key Components
- Chrome Service: Manages CDP connections with event-driven architecture
- Tool Registry: Dynamic tool registration with factory pattern
- Resource Registry: Provides browser state as MCP resources
- DI Container: Manages dependencies and service lifecycle
Installation
Prerequisites
- Node.js 20+ LTS
- npm 10+
- Chrome/Chromium browser
- Docker (optional)
Chrome Extension Setup
- Clone the repository
- Build the extension:
npm run build:extension - Open Chrome and navigate to
chrome://extensions/ - Enable "Developer mode"
- Click "Load unpacked" and select
chrome-extension/dist
Server Setup
# Using npm scripts
npm run dev:server
# Using Docker
docker-compose up -d
# Using Kubernetes
kubectl apply -f k8s/
Usage Examples
Debug Lazy-Loaded Icons
// AI Assistant can request:
await mcp.runTool('inspect', {
component: 'Icon',
props: { name: 'pigeon', lazy: true }
})
Analyze GraphQL Errors
// AI Assistant can request:
await mcp.runTool('analyzeGraphQL', {
operation: 'GetProducts',
error: "cannot query field 'products' on type 'Product'"
})
Time Travel Debugging
// AI Assistant can request:
const recording = await mcp.runTool('timeTravel', {
store: 'cart',
duration: 30000
})
MCP Resources & Tools
Available Resources
console- Browser console logs and errorsnetwork- HTTP requests and responsesdom- DOM tree and element inspectionreact- React component tree and statestate- Application state management
Available Tools
inspect- Inspect components and elementsevaluate- Execute code in page contextdebug- Set breakpoints and step through codeprofile- Performance profilingtimeTravel- Record and replay state changes
Configuration
Create a .env file based on .env.example:
# Server Configuration
CURUPIRA_PORT=8080
CURUPIRA_HOST=localhost
CURUPIRA_LOG_LEVEL=debug
# WebSocket Configuration
CURUPIRA_WS_URL=ws://localhost:8080/mcp
# Authentication (optional)
CURUPIRA_AUTH_ENABLED=false
CURUPIRA_JWT_SECRET=your-secret-here
Docker Support
Build Image
docker build -t curupira:latest .
Run Container
docker run -p 8080:8080 \
-e CURUPIRA_LOG_LEVEL=info \
curupira:latest
Docker Compose
docker-compose up -d
Development
Project Structure
curupira/
├── chrome-extension/ # Browser extension
├── mcp-server/ # MCP protocol server
├── shared/ # Shared utilities
├── docs/ # Documentation
├── k8s/ # Kubernetes configs
└── scripts/ # Build scripts
NPM Scripts
# Development
npm run dev # Start all services
npm run dev:server # Start MCP server only
npm run dev:extension # Build extension (watch)
# Building
npm run build # Build all packages
npm run build:docker # Build Docker image
# Testing
npm run test # Run all tests
npm run test:watch # Run tests (watch)
npm run test:coverage # Generate coverage
# Code Quality
npm run lint # Lint and fix
npm run format # Format code
npm run type-check # Check types
Testing
# Unit tests
npm run test:unit
# Integration tests
npm run test:integration
# E2E tests
npm run test:e2e
Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Security
For security issues, please email security@pleme.io instead of using the issue tracker.
Publishing
For Maintainers
To release a new version:
# Bump version (patch, minor, or major)
./scripts/version.sh patch
# Push changes and tag
git push origin main
git push origin v1.0.1
# Publish to npm and Docker Hub
./scripts/publish.sh
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Built on the Model Context Protocol specification
- Inspired by Chrome DevTools and React DevTools
- Named after the Curupira from Brazilian folklore