Provides containerization support for the debugging tool with Docker images and compose configurations for easy deployment and scaling
Enables environment-based configuration management for server settings, WebSocket connections, and authentication parameters
Supports version control workflows for development with branching, commits, and collaborative features
Integrates with GitHub for repository hosting, issue tracking, and collaborative development workflows
Provides debugging capabilities for GraphQL operations, including error analysis and query inspection
Offers Kubernetes deployment configurations for orchestrating the debugging server in containerized environments
Uses Mermaid diagrams to visualize the architecture and data flow between components
Built on Node.js runtime for server-side execution and package management
Distributed via npm package registry for easy installation and dependency management
Provides comprehensive React debugging capabilities including component state inspection, props monitoring, and render tracking through React DevTools integration
Displays project status badges for license, version, and build information
Implements type-safe development with TypeScript for robust code quality and developer experience
Enables debugging and inspection of XState state machines for complex application state management
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
Using npm
From Source
Claude Code Integration
Add to your claude_desktop_config.json
:
Architecture
Curupira follows a clean architecture with dependency injection:
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
Usage Examples
Debug Lazy-Loaded Icons
Analyze GraphQL Errors
Time Travel Debugging
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
:
Docker Support
Build Image
Run Container
Docker Compose
Development
Project Structure
NPM Scripts
Testing
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:
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
Links
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables AI assistants to debug frontend applications by providing direct access to browser DevTools, React state, DOM inspection, and runtime debugging capabilities. Bridges the gap between AI and complex web applications for autonomous debugging and issue resolution.