212 lines
12 KiB
PHP
212 lines
12 KiB
PHP
<?php
|
|
|
|
// `bin/jumphp debug`: the IDE's debugger (ide/src/Debug) as an MCP server on stdin / stdout, for Claude Code in a
|
|
// terminal: `claude mcp add jumphp-debug -- bin/jumphp debug`. It listens for Xdebug on JUMPHP_DEBUG_PORT (9003);
|
|
// Claude runs the program itself with JUMPHP_XDEBUG=<port> (bin/jumphp test / shot / php ...), then debug_wait.
|
|
// Runs in the desktop image (bin/jumphp starts it), the project mounted as /workspace. docs/ide.md "Debugging".
|
|
|
|
declare(strict_types=1);
|
|
|
|
spl_autoload_register(static function (string $class): void {
|
|
if (str_starts_with($class, 'JumPHP\\Ide\\')) {
|
|
$file = __DIR__ . '/../ide/src/' . str_replace('\\', '/', substr($class, 11)) . '.php';
|
|
if (is_file($file)) {
|
|
require $file;
|
|
}
|
|
}
|
|
});
|
|
|
|
use JumPHP\Ide\Async\Deferred;
|
|
use JumPHP\Ide\Debug\Debugger;
|
|
|
|
$root = getenv('JUMPHP_DEBUG_ROOT') ?: '/workspace';
|
|
$port = (int)(getenv('JUMPHP_DEBUG_PORT') ?: 9003);
|
|
/** @var list<array{0: string, 1: array}> */
|
|
$events = [];
|
|
$debugger = new Debugger($root, function (string $event, array $payload) use (&$events): void {
|
|
$events[] = [$event, $payload];
|
|
});
|
|
$listening = $debugger->listen(getenv('JUMPHP_DEBUG_HOST') ?: '127.0.0.1', $port);
|
|
fwrite(STDERR, "[jumphp debug] waiting for Xdebug on port $listening: run JUMPHP_XDEBUG=$listening bin/jumphp ...\n");
|
|
|
|
$tick = static function () use ($debugger): void {
|
|
$debugger->tick();
|
|
};
|
|
/** Runs the debugger until $done() or $seconds pass. */
|
|
$until = static function (callable $done, float $seconds) use ($tick): bool {
|
|
$end = microtime(true) + $seconds;
|
|
while (microtime(true) < $end) {
|
|
$tick();
|
|
if ($done()) {
|
|
return true;
|
|
}
|
|
usleep(10000);
|
|
}
|
|
return false;
|
|
};
|
|
$settle = static function (Deferred $d, float $seconds = 30.0) use ($until): mixed {
|
|
if (!$until(fn () => $d->isDone(), $seconds)) {
|
|
throw new RuntimeException('Xdebug did not answer in time');
|
|
}
|
|
return $d->result();
|
|
};
|
|
$paused = static function () use ($debugger): ?array {
|
|
foreach ($debugger->status()['sessions'] as $s) {
|
|
if ($s['paused'] !== null) {
|
|
return $s['paused'];
|
|
}
|
|
}
|
|
return null;
|
|
};
|
|
$state = static function (int $frame = 0) use ($debugger, $paused, $settle): array {
|
|
$p = $paused();
|
|
if ($p === null) {
|
|
$running = count($debugger->status()['sessions']);
|
|
return ['status' => $running ? 'running (not stopped: debug_wait)' : 'no program connected yet: run it with JUMPHP_XDEBUG=' . $debugger->status()['port'] . ', then debug_wait'];
|
|
}
|
|
$vars = $settle($debugger->variables($p['session'], $frame));
|
|
return ['status' => 'paused', 'path' => $p['path'], 'line' => $p['line'], 'frame' => $frame,
|
|
'exception' => $p['exception'] ?? null,
|
|
'stack' => array_map(fn ($f) => "#{$f['level']} {$f['where']} " . ($f['path'] ? "{$f['path']}:{$f['line']}" : "(outside the project) line {$f['line']}"), $p['stack']),
|
|
'variables' => array_map(fn ($v) => ['name' => $v['name'], 'type' => $v['type'], 'value' => $v['value']] + ($v['children'] ? ['expandable' => true] : []), array_slice($vars, 0, 80))];
|
|
};
|
|
/** Waits for the program to stop or end after a resume. */
|
|
$afterResume = static function (Deferred $d, float $timeout) use ($until, $state): array {
|
|
$until(fn () => $d->isDone(), $timeout);
|
|
if (!$d->isDone()) {
|
|
return ['status' => "still running after {$timeout} s (no breakpoint reached yet): debug_wait"];
|
|
}
|
|
$r = $d->result();
|
|
return ($r['status'] ?? '') === 'break' ? $state() : ['status' => 'the program ended'];
|
|
};
|
|
$session = static function () use ($paused): int {
|
|
return $paused()['session'] ?? throw new RuntimeException('the program is not stopped: run it with JUMPHP_XDEBUG, then debug_wait');
|
|
};
|
|
|
|
$line = ['type' => 'integer', 'minimum' => 1];
|
|
$tools = [
|
|
'debug_breakpoints' => ['Sets the breakpoints of a file (all of them: lines not given are removed); a line can have a condition (a PHP expression: it stops only when true). Without a path: lists them. clear_all removes every breakpoint first. Paths relative to the project.',
|
|
['path' => ['type' => 'string'], 'lines' => ['type' => 'array', 'items' => ['anyOf' => [$line, ['type' => 'object', 'properties' => ['line' => $line, 'condition' => ['type' => 'string']], 'required' => ['line']]]]], 'clear_all' => ['type' => 'boolean']], []],
|
|
'debug_exceptions' => ['Exceptions that stop the program where they are thrown, caught or not ("*": every exception; class names: Error, TypeError, App\\GameOver; []: none). Without classes: lists them.',
|
|
['classes' => ['type' => 'array', 'items' => ['type' => 'string']]], []],
|
|
'debug_wait' => ['Waits until the program run with JUMPHP_XDEBUG=<port> (bin/jumphp test pong, shot pong, php games/x/tool.php... started by you, in the background) stops at a breakpoint or an exception (then: where, the stack, the variables), or `timeout` seconds pass (default 120).',
|
|
['timeout' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 600]], []],
|
|
'debug_state' => ['Where the program is stopped: file, line, exception, the stack, the variables of a frame (0: where it stopped; 1: its caller...).',
|
|
['frame' => ['type' => 'integer', 'minimum' => 0]], []],
|
|
'debug_step' => ['Moves the stopped program: step_over, step_into, step_out, run (to the next breakpoint), stop (ends it). Waits until it stops again or ends.',
|
|
['action' => ['type' => 'string', 'enum' => ['step_over', 'step_into', 'step_out', 'run', 'stop']], 'timeout' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 600]], ['action']],
|
|
'debug_run_to' => ['Runs the stopped program to a line and waits until it stops there, at a breakpoint met first, or ends.',
|
|
['path' => ['type' => 'string'], 'line' => $line, 'timeout' => ['type' => 'integer', 'minimum' => 1, 'maximum' => 600]], ['path', 'line']],
|
|
'debug_eval' => ['Evaluates a PHP expression where the program is stopped ($this->score * 2, count($enemies)...): its value and children.',
|
|
['expression' => ['type' => 'string']], ['expression']],
|
|
'debug_variables' => ['The variables of a frame, or the children of one of them (name: its full name, e.g. $this->player, $list[3]).',
|
|
['name' => ['type' => 'string'], 'frame' => ['type' => 'integer', 'minimum' => 0]], []],
|
|
'debug_set_value' => ['Gives a variable of the stopped program a new value: a PHP expression evaluated there (9, "Ada", [1, 2], null).',
|
|
['name' => ['type' => 'string'], 'value' => ['type' => 'string'], 'frame' => ['type' => 'integer', 'minimum' => 0]], ['name', 'value']],
|
|
];
|
|
|
|
$call = static function (string $name, array $a) use ($debugger, $settle, $until, $state, $afterResume, $session, $paused): mixed {
|
|
$timeout = (float)($a['timeout'] ?? 60);
|
|
switch ($name) {
|
|
case 'debug_breakpoints':
|
|
if (!empty($a['clear_all'])) {
|
|
$debugger->clearBreakpoints();
|
|
}
|
|
if (isset($a['path'])) {
|
|
$debugger->setBreakpoints((string)$a['path'], array_map(fn ($l) => is_array($l) ? $l : ['line' => (int)$l], (array)($a['lines'] ?? [])));
|
|
}
|
|
return ['breakpoints' => $debugger->breakpointList()];
|
|
case 'debug_exceptions':
|
|
return ['exceptions' => isset($a['classes']) ? $debugger->setExceptionBreakpoints(array_map('strval', (array)$a['classes'])) : $debugger->status()['exceptions']];
|
|
case 'debug_wait':
|
|
$until(fn () => $paused() !== null, (float)($a['timeout'] ?? 120));
|
|
return $state();
|
|
case 'debug_state':
|
|
return $state((int)($a['frame'] ?? 0));
|
|
case 'debug_step':
|
|
$how = (string)$a['action'];
|
|
if ($how === 'stop') {
|
|
$debugger->resume($session(), 'stop');
|
|
return ['status' => 'stopped'];
|
|
}
|
|
return $afterResume($debugger->resume($session(), $how), $timeout);
|
|
case 'debug_run_to':
|
|
return $afterResume($debugger->runTo($session(), (string)$a['path'], (int)$a['line']), $timeout);
|
|
case 'debug_eval':
|
|
$r = $settle($debugger->evaluate($session(), (string)$a['expression']));
|
|
return ['type' => $r['type'], 'value' => $r['value'], 'items' => array_map(fn ($v) => ['name' => $v['name'], 'type' => $v['type'], 'value' => $v['value']], array_slice($r['items'] ?? [], 0, 80))];
|
|
case 'debug_variables':
|
|
if (empty($a['name'])) {
|
|
return $state((int)($a['frame'] ?? 0))['variables'] ?? [];
|
|
}
|
|
$r = $settle($debugger->children($session(), (string)$a['name'], (int)($a['frame'] ?? 0)));
|
|
return $r === null ? null : ['name' => $r['fullname'] ?: $a['name'], 'type' => $r['type'], 'value' => $r['value'],
|
|
'items' => array_map(fn ($v) => ['name' => $v['name'], 'fullname' => $v['fullname'], 'type' => $v['type'], 'value' => $v['value']], array_slice($r['items'] ?? [], 0, 200))];
|
|
case 'debug_set_value':
|
|
$r = $settle($debugger->setValue($session(), (string)$a['name'], (string)$a['value'], (int)($a['frame'] ?? 0)));
|
|
return $r === null ? null : ['name' => $r['fullname'] ?: $a['name'], 'type' => $r['type'], 'value' => $r['value']];
|
|
}
|
|
throw new RuntimeException("unknown tool $name");
|
|
};
|
|
|
|
$instructions = "Step debugging of the project's PHP (Xdebug), port $listening. Set breakpoints (debug_breakpoints, paths relative to "
|
|
. "the project) or exceptions to stop at (debug_exceptions), then start the program yourself, in the background, with "
|
|
. "JUMPHP_XDEBUG=$listening (e.g. `JUMPHP_XDEBUG=$listening bin/jumphp test pong`), then debug_wait. Read (debug_state, "
|
|
. "debug_variables, debug_eval), move (debug_step, debug_run_to), try a value (debug_set_value); end with debug_step run or stop.";
|
|
|
|
$send = static function (array $message): void {
|
|
fwrite(STDOUT, json_encode($message, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE) . "\n");
|
|
fflush(STDOUT);
|
|
};
|
|
|
|
stream_set_blocking(STDIN, false);
|
|
$buffer = '';
|
|
while (true) {
|
|
$read = [STDIN];
|
|
$write = $except = null;
|
|
if (@stream_select($read, $write, $except, 0, 20000) > 0) {
|
|
$chunk = fread(STDIN, 65536);
|
|
if ($chunk === '' && feof(STDIN)) {
|
|
break; // Claude Code closed it
|
|
}
|
|
$buffer .= (string)$chunk;
|
|
}
|
|
$tick();
|
|
while (($nl = strpos($buffer, "\n")) !== false) {
|
|
$raw = trim(substr($buffer, 0, $nl));
|
|
$buffer = substr($buffer, $nl + 1);
|
|
if ($raw === '') {
|
|
continue;
|
|
}
|
|
$m = json_decode($raw, true);
|
|
if (!is_array($m) || !isset($m['method'])) {
|
|
continue;
|
|
}
|
|
$id = $m['id'] ?? null;
|
|
if ($id === null) {
|
|
continue; // a notification
|
|
}
|
|
try {
|
|
$result = match ($m['method']) {
|
|
'initialize' => ['protocolVersion' => (string)($m['params']['protocolVersion'] ?? '2025-06-18'), 'capabilities' => ['tools' => new stdClass()],
|
|
'serverInfo' => ['name' => 'jumphp-debug', 'version' => '1.0'], 'instructions' => $instructions],
|
|
'ping' => new stdClass(),
|
|
'tools/list' => ['tools' => array_map(fn ($name, $t) => ['name' => $name, 'description' => $t[0],
|
|
'inputSchema' => ['type' => 'object', 'properties' => $t[1] ?: new stdClass(), 'required' => $t[2]]], array_keys($tools), $tools)],
|
|
'tools/call' => (function () use ($m, $call): array {
|
|
try {
|
|
$out = $call((string)$m['params']['name'], (array)($m['params']['arguments'] ?? []));
|
|
return ['content' => [['type' => 'text', 'text' => json_encode($out, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE)]]];
|
|
} catch (Throwable $e) {
|
|
return ['content' => [['type' => 'text', 'text' => $e->getMessage()]], 'isError' => true];
|
|
}
|
|
})(),
|
|
default => throw new RuntimeException("unknown method {$m['method']}"),
|
|
};
|
|
$send(['jsonrpc' => '2.0', 'id' => $id, 'result' => $result]);
|
|
} catch (Throwable $e) {
|
|
$send(['jsonrpc' => '2.0', 'id' => $id, 'error' => ['code' => -32601, 'message' => $e->getMessage()]]);
|
|
}
|
|
}
|
|
}
|
|
$debugger->close();
|