MCP Control - Debugger para Agentes IA em JetBrains
brannow/idea-mcp-control
Controle total do debugger PhpStorm via MCP para agentes IA
Ver no GitHubPlugin MCP server para IDEs JetBrains (PhpStorm) que expõe o debugger completo para agentes IA via protocol Model Context. Oferece 13 ferramentas para controle de breakpoints, sessões de debug, navegação e inspeção de variáveis em tempo real.
Instalação
npx convez-ai brannow/idea-mcp-control1 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
- Agentes IA debugando código PHP automaticamente
- Inspeção remota de variáveis e stack frames durante execução
- Automação de breakpoints e sessões de debug programaticamente
Veredito

Solução técnica madura e bem-estruturada que fecha uma lacuna real: dar aos agentes IA acesso nativo ao debugger JetBrains. Implementação séria com 13 tools robustos, suporte multi-cliente MCP e configuração simples. Recomendado para times que já usam Claude Code/Cursor e PhpStorm.
README
A tradução para o português deste README ainda está na fila.
Setup
- Install the plugin (Settings > Plugins > Install Plugin from Disk)
- Open the MCP Control tool window (bottom panel)
- Click Install .mcp.json to auto-configure your MCP client
- Click Start Server
Works with Claude Code, Cursor, Claude Desktop, and any other MCP client.
Configuration
Settings > Tools > MCP Control
| Setting | Default | What it does |
|---|---|---|
| Port | 6969 | Localhost port for the MCP server |
| Auto-start | off | Start the server when the project opens |
If the port is already in use (e.g., another PhpStorm instance), you get a notification with options to change the port or retry.
Installation
From GitHub Release: Download the latest .zip from Releases, then in PhpStorm go to Settings > Plugins > Gear icon > Install Plugin from Disk and select the zip.
From source: Run ./gradlew buildPlugin, the zip is in build/distributions/.
Tools
13 tools across 4 categories. All debug tools operate on the active session (the one focused in the IDE's debug panel).
Breakpoints (work without a debug session)
| Tool | What it does |
|---|---|
breakpoint_list | List all breakpoints (line + exception) with conditions, status, annotations |
breakpoint_add | Add a line or method breakpoint (a method/function definition line becomes a real method breakpoint) with optional condition, log expression, suspend control |
breakpoint_add_exception | Break on a PHP exception class. Short names are resolved via project index. |
breakpoint_update | Modify any breakpoint by ID (enable/disable, change condition, etc.) |
breakpoint_remove | Remove by ID, file:line, exception class FQCN, file path, or all |
Session management
| Tool | What it does |
|---|---|
session_list | List active debug sessions with position and status |
session_stop | Stop the active session or all sessions |
Navigation (requires paused session)
| Tool | What it does |
|---|---|
debug_step | Step over / into / out / continue. Returns a snapshot after pausing. |
debug_run_to_line | Run to a specific file:line. Returns a snapshot. |
Inspection (requires paused session)
| Tool | What it does |
|---|---|
debug_snapshot | Get current state without changing anything; frame_index inspects any stack frame's scope |
debug_variable_detail | Expand variables to any depth with circular reference detection; offset/limit page through large collections |
debug_evaluate | Evaluate PHP expressions in debug context, including side effects; offset/limit page through large results |
debug_console | Read stdout/stderr from the debug console (works with Docker/remote processes) |
How it works
You start debug sessions in PhpStorm as usual. The agent connects via MCP and interacts with those sessions: setting breakpoints, stepping through code, inspecting state. You both see the same debug session.
Human: starts debug session, hits breakpoint
Agent: debug_snapshot → sees source, variables, stack
Agent: debug_step(action: "over") → next line, new snapshot
Agent: debug_variable_detail(path: "$request.headers") → expands nested object
Agent: debug_evaluate(expression: "count($items)") → evaluates in current scope
The Debug Snapshot
Most tools return a snapshot. It mirrors what a human sees when paused at a breakpoint: session info, source context, variables, and call stack in one response.
#12345 "index.php" at src/WorldClass.php:22 (active)
\Brannow\Sandbox\WorldClass::fooBar() — src/WorldClass.php:22
20 $engine = new TypedPatternEngine();
21 $result = $engine->match('PAGE55');
→22 return $bar;
$this = {Brannow\Sandbox\WorldClass}
$foo = {string} "foo"
$bar = {string} "foo-bar"
→#0 WorldClass->fooBar() at src/WorldClass.php:22
#1 WorldClass->foo() at src/WorldClass.php:11
#2 {main}() at src/index.php:8
Snapshots are customizable. Pass include: ["source", "variables"] to skip the stack trace. Useful when stepping through 10 lines and you don't need the full stack every time.
Design decisions
Natural language, not JSON. Tools respond with readable text, not structured data. The agent reasons about it directly, no parsing needed.
Self-contained responses. Every error includes enough context to self-correct. Not found? Here are all breakpoints in the project. Ambiguous? Here are the options with IDs. The agent never needs a follow-up call just to orient itself.
Input matches output. If a tool outputs src/index.php:15, another tool accepts src/index.php:15 as input. No reformatting between calls.
Tools, not wrappers. Each tool is designed like an application for the agent, not a thin API wrapper. The agent doesn't need to know how XDebugSession or XBreakpointManager work internally.
Build from source
./gradlew build # compile + test
./gradlew runIde # launch sandboxed IDE with plugin
./gradlew buildPlugin # build distributable zip
Requires JDK 21.