Curupira MCP Server API Documentation

Overview

Curupira MCP Server provides a Model Context Protocol (MCP) interface for debugging web applications through Chrome DevTools Protocol (CDP). This document describes all available resources, tools, and prompts.

Resources
Tools
Prompts
Configuration
Error Handling

Resources

Resources provide read-only access to browser and application state. Resources are registered dynamically based on Chrome connection status.

Browser Resources

`browser://status`

Get current browser connection status and capabilities.

Response:

{
  "connected": true,
  "serviceUrl": "chrome://localhost:9222",
  "activeSessions": 1,
  "sessions": [{
    "sessionId": "default",
    "createdAt": "2024-01-15T10:00:00Z",
    "duration": 0
  }],
  "capabilities": {
    "screenshot": true,
    "evaluate": true,
    "navigate": true,
    "profiling": true,
    "debugging": true
  }
}

DOM Resources

`chrome://dom/tree`

Get the current DOM tree structure.

Response:

{
  "rootNode": {
    "nodeId": 1,
    "nodeName": "HTML",
    "nodeType": 1,
    "children": [...]
  }
}

Network Resources

`chrome://network/requests`

Get recent network requests.

Response:

{
  "requests": [{
    "requestId": "123",
    "url": "https://api.example.com/data",
    "method": "GET",
    "status": 200,
    "responseTime": 123
  }]
}

`chrome://network/websockets`

Get active WebSocket connections.

Response:

{
  "connections": [{
    "url": "wss://ws.example.com",
    "state": "open",
    "messages": []
  }]
}

State Resources

`chrome://state/react`

Get React component state information.

`chrome://state/apollo`

Get Apollo GraphQL cache state.

`chrome://state/zustand`

Get Zustand store state.

React Resources

`react://components`

Get React component tree.

Response:

{
  "components": [
    {
      "id": "1",
      "name": "App",
      "type": "function",
      "props": {
        "title": "My App"
      },
      "state": null,
      "hooks": ["useState", "useEffect"],
      "children": ["2", "3"],
      "depth": 0
    }
  ],
  "total": 15,
  "reactVersion": "18.2.0"
}

`react://component/{id}`

Get specific component details.

Parameters:

id: Component ID from the component tree

Response:

{
  "id": "1",
  "name": "UserProfile",
  "type": "function",
  "props": {
    "userId": 123,
    "showAvatar": true
  },
  "hooks": [
    {
      "type": "useState",
      "value": { "loading": false }
    }
  ],
  "fiber": {
    "effectTag": 0,
    "elementType": "function"
  }
}

`react://performance`

Get React performance metrics.

Response:

{
  "slowComponents": [
    {
      "name": "ExpensiveList",
      "renderTime": 125.5,
      "renderCount": 10
    }
  ],
  "totalRenders": 150,
  "averageRenderTime": 15.2
}

State Management Resources

`xstate://machines`

Get all XState machines.

Response:

{
  "machines": [
    {
      "id": "auth",
      "state": "authenticated",
      "context": {
        "user": { "id": 123 }
      }
    }
  ]
}

`zustand://stores`

Get all Zustand stores.

Response:

{
  "stores": [
    {
      "name": "useCartStore",
      "state": {
        "items": [],
        "total": 0
      }
    }
  ]
}

Network Resources

`network://requests`

Get recent network requests (last 500).

Response:

{
  "requests": [
    {
      "id": "req-1",
      "url": "https://api.example.com/users",
      "method": "GET",
      "status": 200,
      "type": "xhr",
      "duration": 125,
      "size": 2048
    }
  ],
  "total": 45,
  "stats": {
    "totalSize": 150000,
    "totalDuration": 5000,
    "failedCount": 2
  }
}

Tools

Tools provide actions to interact with the browser and debug applications. All tools are registered at startup but require Chrome connection to function.

Chrome Connection Tools

`chrome_connect`

Connect to Chrome browser via CDP.

Parameters:

{
  "host": "localhost",
  "port": 3000,
  "timeout": 5000
}

`chrome_disconnect`

Disconnect from Chrome browser.

`chrome_list_targets`

List all available Chrome targets/tabs.

CDP Tools

`cdp_evaluate`

Evaluate JavaScript expression in the browser.

Parameters:

{
  "expression": "document.title",
  "sessionId": "optional-session-id"
}

`cdp_navigate`

Navigate to a URL.

Parameters:

{
  "url": "https://example.com",
  "sessionId": "optional-session-id"
}

`cdp_get_cookies`

Get browser cookies.

Parameters:

{
  "urls": ["https://example.com"],
  "sessionId": "optional-session-id"
}

React Tools

`react_detect_version`

Detect React version and DevTools availability.

`react_get_component_tree`

Get the React component tree structure.

Parameters:

{
  "rootSelector": "#root",
  "maxDepth": 10,
  "includeProps": true
}

`react_inspect_component`

Inspect a specific React component.

Parameters:

{
  "componentSelector": "App > Header",
  "includeProps": true,
  "includeState": true,
  "includeHooks": true
}

`react_analyze_rerenders`

Analyze component re-renders for performance.

Parameters:

{
  "componentSelector": "MyComponent",
  "duration": 5000
}

DOM Tools

`dom_query_selector`

Find DOM elements using CSS selectors.

Parameters:

{
  "selector": ".btn-primary",
  "all": false
}

`dom_click`

Click a DOM element.

Parameters:

{
  "selector": "#submit-btn"
}

Network Tools

`network_get_requests`

Get recent network requests.

`network_get_websockets`

Get active WebSocket connections.

`network_intercept_requests`

Intercept and modify network requests.

Storage Tools

`get_local_storage`

Get localStorage items.

`get_session_storage`

Get sessionStorage items.

`get_cookies`

Get browser cookies.

`set_cookie`

Set a browser cookie.

Console Tools

`console_get_messages`

Get console log messages.

`console_execute`

Execute code in the browser console.

`console_clear`

Clear the console.

Debugger Tools

`debugger_enable`

Enable Chrome debugger.

`debugger_pause`

Pause JavaScript execution.

`debugger_resume`

Resume JavaScript execution.

`debugger_set_breakpoint`

Set a breakpoint.

State Management Tools

`apollo_get_cache`

Get Apollo GraphQL cache state.

`zustand_get_stores`

Get Zustand store states.

`xstate_get_machines`

Get XState machine states.

`tanstack_query_get_cache`

Get TanStack Query cache.

Development Tools

`vite_dev_server_info`

Get Vite dev server information.

`react_router_get_routes`

Get React Router routes.

`react_hook_form_get_forms`

Get React Hook Form states.

UI/Animation Tools

`framer_motion_get_animations`

Get Framer Motion animations.

`panda_css_get_styles`

Get Panda CSS styles and tokens.

Prompts

Prompts provide pre-configured debugging scenarios for common use cases.

`debug-lazy-loading`

Debug lazy-loaded component issues.

Arguments:

componentName (required): Name of the component having issues

`trace-graphql-error`

Trace GraphQL query errors.

Arguments:

operation (required): GraphQL operation name
error (required): Error message

`profile-performance`

Profile component render performance.

Arguments:

component (optional): Component to profile

Configuration

Curupira follows the Nexus configuration pattern: Base YAML → Environment YAML → Environment Variables.

Configuration Files

# config/base.yaml
server:
  name: "curupira-mcp-server"
  version: "1.1.3"
  host: "localhost"
  port: 8080

chrome:
  serviceUrl: "http://localhost:3000"
  connectTimeout: 5000

transports:
  websocket:
    enabled: true
  http:
    enabled: true
  sse:
    enabled: true

Environment Variables

All configuration can be overridden via environment variables:

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# Chrome
CHROME_SERVICE_URL=http://browserless:3000
CHROME_DISCOVERY_ENABLED=true

# Logging
LOGGING_LEVEL=debug

# Storage
STORAGE_MINIO_ENABLED=true

Error Handling

All errors follow a consistent format:

{
  "error": "Chrome not connected",
  "code": "CHROME_DISCONNECTED",
  "details": {
    "suggestion": "Use chrome_connect tool first"
  }
}

Common Error Codes

CHROME_DISCONNECTED: Chrome browser not connected
SESSION_NOT_FOUND: Invalid session ID
TOOL_EXECUTION_FAILED: Tool failed to execute
RESOURCE_NOT_FOUND: Requested resource not found
INVALID_PARAMETERS: Invalid tool parameters

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

Curupira MCP Server API Documentation

Overview

Table of Contents

Resources

Browser Resources

browser://status

DOM Resources

chrome://dom/tree

Network Resources

chrome://network/requests

chrome://network/websockets

State Resources

chrome://state/react

chrome://state/apollo

chrome://state/zustand

React Resources

react://components

react://component/{id}

react://performance

State Management Resources

xstate://machines

zustand://stores

Network Resources

network://requests

Tools

Chrome Connection Tools

chrome_connect

chrome_disconnect

chrome_list_targets

CDP Tools

cdp_evaluate

cdp_navigate

cdp_get_cookies

React Tools

react_detect_version

react_get_component_tree

react_inspect_component

react_analyze_rerenders

DOM Tools

dom_query_selector

dom_click

Network Tools

network_get_requests

network_get_websockets

network_intercept_requests

Storage Tools

get_local_storage

get_session_storage

get_cookies

set_cookie

Console Tools

console_get_messages

console_execute

console_clear

Debugger Tools

debugger_enable

debugger_pause

debugger_resume

debugger_set_breakpoint

State Management Tools

apollo_get_cache

zustand_get_stores

xstate_get_machines

tanstack_query_get_cache

Development Tools

vite_dev_server_info

react_router_get_routes

react_hook_form_get_forms

UI/Animation Tools

framer_motion_get_animations

panda_css_get_styles

Prompts

debug-lazy-loading

trace-graphql-error

`browser://status`

`chrome://dom/tree`

`chrome://network/requests`

`chrome://network/websockets`

`chrome://state/react`

`chrome://state/apollo`

`chrome://state/zustand`

`react://components`

`react://component/{id}`

`react://performance`

`xstate://machines`

`zustand://stores`

`network://requests`

`chrome_connect`

`chrome_disconnect`

`chrome_list_targets`

`cdp_evaluate`

`cdp_navigate`

`cdp_get_cookies`

`react_detect_version`

`react_get_component_tree`

`react_inspect_component`

`react_analyze_rerenders`

`dom_query_selector`

`dom_click`

`network_get_requests`

`network_get_websockets`

`network_intercept_requests`

`get_local_storage`

`get_session_storage`

`get_cookies`

`set_cookie`

`console_get_messages`

`console_execute`

`console_clear`

`debugger_enable`

`debugger_pause`

`debugger_resume`

`debugger_set_breakpoint`

`apollo_get_cache`

`zustand_get_stores`

`xstate_get_machines`

`tanstack_query_get_cache`

`vite_dev_server_info`

`react_router_get_routes`

`react_hook_form_get_forms`

`framer_motion_get_animations`

`panda_css_get_styles`

`debug-lazy-loading`

`trace-graphql-error`

`profile-performance`