@flexsurfer/reflex-devtools-mcp

v0.1.12

Published

3 months ago

MCP server for Reflex DevTools - enables AI assistants to inspect traces and dispatch events

0High
0Medium
0Low

flexsurfer

mcp devtools debugging ai reflex model-context-protocol

🤖 Reflex DevTools MCP Server

AI-powered debugging for Reflex applications via the Model Context Protocol

This package provides a Model Context Protocol (MCP) server that connects to Reflex DevTools via HTTP API. It enables AI assistants like Claude and Cursor to inspect application traces, query state, and dispatch events for testing and debugging.

Note: Trace storage is handled by the DevTools server (requires --mcp flag). This MCP server acts as a stateless API client.

✨ What is This?

The Reflex DevTools MCP Server acts as a bridge between AI assistants and your running Reflex application. It queries the DevTools server's REST API to provide AI assistants with debugging capabilities:

┌─────────────────┐    WebSocket    ┌─────────────────────────┐    HTTP    ┌─────────────────┐
│   Your App      │◀───────────────▶│   DevTools Server       │◀──────────▶│   MCP Server    │
│  + Reflex SDK   │                 │   + Trace Storage       │            │                 │
└─────────────────┘                 │   + REST API            │            └─────────────────┘
                                    └─────────────────────────┘                    │
                                                                                   │ MCP (stdio)
                                                                                   ▼
                                                                           ┌─────────────────┐
                                                                           │  AI Assistant   │
                                                                           │  (Claude/Cursor)│
                                                                           └─────────────────┘

AI assistants can:

📊 Inspect execution traces - View events, effects, subscriptions, and renders with timing data
🔍 Query application state - Examine the current app database
🚀 Dispatch events - Trigger handlers to test functionality
📚 List handlers - See all registered event handlers, effects, and subscriptions
⚡ Monitor subscriptions - View active reactive queries

🚀 Quick Start

Prerequisites

Install Reflex DevTools in your app (if not already done):
```
npm install --save-dev @flexsurfer/reflex-devtools
```

Enable DevTools in your app (main.tsx or App.tsx):

import { enableTracing } from '@flexsurfer/reflex';
import { enableDevtools } from '@flexsurfer/reflex-devtools';

enableTracing();
enableDevtools();

Start the DevTools server with MCP support:
```
npx reflex-devtools --mcp
```
Important: The --mcp flag enables trace storage and REST API. Without it, MCP will return "MCP not enabled" errors.
Start your Reflex application

Install MCP Server

npm install -g @flexsurfer/reflex-devtools-mcp
# or
pnpm add -g @flexsurfer/reflex-devtools-mcp

Configure with Claude Desktop

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "reflex-devtools": {
      "command": "npx",
      "args": ["reflex-devtools-mcp"],
      "env": {}
    }
  }
}

For custom DevTools server host/port:

{
  "mcpServers": {
    "reflex-devtools": {
      "command": "npx",
      "args": ["reflex-devtools-mcp", "--port", "3000", "--host", "192.168.1.10"],
      "env": {}
    }
  }
}

Restart Claude Desktop, and the tools will be available!

Configure with Cursor IDE

Cursor IDE also supports MCP servers. Add to your Cursor settings:

Open Cursor Settings: Cmd/Ctrl + Shift + P → "Preferences: Open User Settings (JSON)"
Add MCP configuration to your settings.json:

{
  "mcp.servers": {
    "reflex-devtools": {
      "command": "npx",
      "args": ["reflex-devtools-mcp"],
      "env": {}
    }
  }
}

Use with Cursor Composer/Chat: Ask the AI to inspect your app:
- "Show me recent traces from my Reflex app"
- "What's causing the performance issue?"
- "Dispatch a test event to my app"

Custom Configuration for Cursor:

{
  "mcp.servers": {
    "reflex-devtools": {
      "command": "reflex-devtools-mcp",
      "args": ["--port", "4000", "--host", "localhost"],
      "env": {},
      "description": "Reflex DevTools for debugging"
    }
  }
}

🛠️ Available MCP Tools