debug-server-local

Headless, file-path-based debug runtime.

Given an absolute file_path (or inline content), a language, and a set of process env vars, debug-server-local runs the code under a debugger and exposes every introspection/control primitive over HTTP, MCP, and a programmatic API.

What it knows about

• Languages (to pick the V8 Inspector for node-family, DAP for python/others).
• A user-supplied env_vars map and path_prepend array used to configure each spawned child process.

What it does NOT know about

• Workspaces, persistent file storage, tar uploads.
• Engine installation or version registries.
• Any dashboard UI.

For those concerns, see the debug-server-remote project, which embeds debug-server-local as a library and wraps it with a workspace + runtime engine layer.

Run

npm install
npm start            # standalone HTTP server on :4200
npm run mcp          # MCP stdio server
npm test

Programmatic API

const { create_router, create_app, SessionManager } = require( '@mchiver/debug-server-local' );

• create_router( options ) returns an Express Router so a host app can mount it.
• create_app( options ) returns a full Express app + WebSocket server for standalone use.
• SessionManager is exported directly for callers that need to do their own translation before delegating into the debug runtime.

API Reference

Session Lifecycle

Description	HTTP Endpoint	MCP Tool	Programmatic API
Create a new debug session	POST /api/sessions	create_session	SessionManager.create( options )
List all active sessions	GET /api/sessions	list_sessions	SessionManager.list()
Get a single session	GET /api/sessions/:id	get_session	SessionManager.get( id )
Kill a session	DELETE /api/sessions/:id	kill_session	SessionManager.destroy( id )
Restart a session	POST /api/sessions/:id/restart	restart_session	SessionManager.restart( id )
Read stdout/stderr lines	GET /api/sessions/:id/output	read_output	DebugSession.read_output( offset, limit )
Write to stdin	POST /api/sessions/:id/input	send_input	DebugSession.send_input( data )
Update session settings	POST /api/sessions/:id/settings	update_settings	DebugSession.break_on_first_line = ...

Debug Control

Description	HTTP Endpoint	MCP Tool	Programmatic API
Resume execution	POST /api/sessions/:id/debug/resume	debug_resume	DebugSession.debug_resume()
Step over current line	POST /api/sessions/:id/debug/step_over	debug_step_over	DebugSession.debug_step_over()
Step into function call	POST /api/sessions/:id/debug/step_into	debug_step_into	DebugSession.debug_step_into()
Step out of function	POST /api/sessions/:id/debug/step_out	debug_step_out	DebugSession.debug_step_out()
Get call stack	GET /api/sessions/:id/debug/stack	get_call_stack	DebugSession.get_call_stack()
Get source code and breakpoints	GET /api/sessions/:id/source	get_source	DebugSession.get_source()
Get protocol traffic logs	GET /api/sessions/:id/logs	get_logs	DebugSession.get_logs( offset, limit )
Get variables in scope	GET /api/sessions/:id/debug/variables	get_variables	DebugSession.get_variables( frame_index, scope_type )
Evaluate expression	POST /api/sessions/:id/debug/evaluate	evaluate	DebugSession.evaluate( expression, frame_index )
Set a breakpoint	POST /api/sessions/:id/debug/breakpoint	set_breakpoint	DebugSession.set_breakpoint( url, line_number, column_number )
Remove a breakpoint	DELETE /api/sessions/:id/debug/breakpoint/:breakpoint_id	remove_breakpoint	DebugSession.remove_breakpoint( breakpoint_id )
Configure exception pause	POST /api/sessions/:id/debug/exception-pause	set_exception_pause	DebugSession.set_exception_pause( state )

LLM Primitives

Description	HTTP Endpoint	MCP Tool	Programmatic API
Stateless run-and-report	POST /api/triage	run_and_report	SessionManager.triage( options )
Set a non-pausing logpoint	POST /api/sessions/:id/debug/logpoint	set_logpoint	DebugSession.set_logpoint( url, line_number, expression )
Get logpoint traces	GET /api/sessions/:id/traces	get_traces	DebugSession.get_traces( offset, limit )
Clear logpoint traces	DELETE /api/sessions/:id/traces	clear_traces	DebugSession.clear_traces()
Snapshot variables as checkpoint	POST /api/sessions/:id/debug/checkpoint	take_checkpoint	DebugSession.take_checkpoint( name, frame_index, scope_type )
List checkpoints	GET /api/sessions/:id/debug/checkpoints	list_checkpoints	DebugSession.list_checkpoints()
Diff two checkpoints	GET /api/sessions/:id/debug/checkpoint_diff	compare_checkpoints	DebugSession.compare_checkpoints( before, after )

WebSocket Events

Events are broadcast to all connected WebSocket clients.

Event Name	When Sent	Description
session_list	On client connect	Snapshot of all active sessions.
session_created	After a session is created	Includes the new session info.
session_updated	On any state change (excl. pause/resume)	Includes the updated session info.
session_exited	After a session is destroyed	{ session_id }
debugger_paused	When execution hits a pause	{ session_id, callFrames, reason }
debugger_resumed	When execution resumes	{ session_id }
output_update	When new stdout/stderr is captured	{ session_id, lines }