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 } |