MCP Tools Reference

All tools accept and return JSON. Every debug session tool requires session_id (returned by debug_launch). Browser tools use session_id returned by chrome_start.

Debug Tools

debug_launch

Launch a debug target process. Sets initial breakpoints and returns a session handle. The viewport shows source, locals, and call stack at each stop. Automatically detects test/web frameworks (pytest, django, flask, jest, mocha, gotest) to configure the debugger appropriately.

Parameter	Type	Required	Description
command	string	No	Command to execute, e.g. 'python app.py' or 'pytest tests/'. Required unless launch_config is provided. Test and web frameworks are auto-detected and configured for debugging.
language	string	No	Supported: python (.py), node/javascript/typescript/js/ts (.js .mjs .cjs .ts .mts .cts .tsx), go (.go), rust (.rs), java (.java), cpp (.c .cpp .cc .cxx .h .hpp), ruby (.rb), csharp (.cs), swift (.swift), kotlin (.kt). Omit to auto-detect from the file extension in the command.
framework	string	No	Override framework auto-detection. Known frameworks: pytest, django, flask, jest, mocha, gotest. Use 'none' to disable auto-detection.
breakpoints	object[]	No	Initial breakpoints to set before execution begins. Note: breakpoints on non-executable lines (comments, blank lines, decorators) may be adjusted by the debugger to the nearest executable line.
cwd	string	No	Working directory for the debug target
env	object	No	Additional environment variables for the debug target
viewport_config	object	No	Override default viewport rendering parameters
stop_on_entry	boolean	No	Pause on the first executable line. Default: false
launch_config	object	No	Use a VS Code launch.json configuration instead of a command string

debug_stop

Terminate a debug session and kill the target process. This terminates (kills) the process — it does not detach. If the session was created with debug_attach, the attached process is also killed. Cleans up all session resources.

Parameter	Type	Required	Description
session_id	string	Yes	The session to terminate

debug_status

Get the current status of a debug session. Returns viewport if stopped. Includes token stats, action count, and adapter capabilities.

Parameter	Type	Required	Description
session_id	string	Yes	The session to query

debug_continue

Resume execution until the next breakpoint or program end. Returns the viewport at the next stop point.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
timeout_ms	number	No	Max wait time for next stop in ms. Default: 30000
thread_id	number	No	Thread ID to continue. Default: the thread that last stopped. Use debug_threads to list available threads.

debug_step

Step execution: 'over' steps over function calls, 'into' steps into them, 'out' steps out to the caller. Returns the viewport after stepping.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
direction	"over" | "into" | "out"	Yes	Step granularity: 'over' skips function calls, 'into' enters them, 'out' runs to parent frame
count	number	No	Number of steps to take. Default: 1. Useful for stepping through loops without setting breakpoints.
thread_id	number	No	Thread ID to step. Default: the thread that last stopped. Use debug_threads to list available threads.

debug_run_to

Run execution to a specific file and line number, then pause. If the target line is never reached, a timeout error is returned (controlled by timeout_ms). Unlike setting a breakpoint, this is a one-time temporary stop.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
file	string	Yes	Target file path
line	number	Yes	Target line number
timeout_ms	number	No	Max wait time in ms. Default: 30000

debug_set_breakpoints

Set breakpoints in a source file. REPLACES all existing breakpoints in that file. Supports conditions ('discount < 0'), hit counts ('>=100'), and logpoints ('discount={discount}'). Logpoints log a message when hit instead of breaking. Not all debuggers support logpoints — if unsupported, the breakpoint will be set as a regular breakpoint. Note: breakpoints on non-executable lines may be adjusted by the debugger.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
file	string	Yes	Source file path
breakpoints	object[]	Yes	Breakpoint definitions. REPLACES all existing breakpoints in this file. To add a breakpoint without removing existing ones, include them all.

debug_set_exception_breakpoints

Configure exception breakpoint filters. Controls which exceptions pause execution. Python filters: 'raised' (all exceptions), 'uncaught' (unhandled only), 'userUnhandled'. Node.js filters: 'all' (all exceptions), 'uncaught' (unhandled only). Go/Delve: 'panic' (runtime panics). Use debug_status after launch to see exact available filters for the current adapter.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
filters	string[]	Yes	Exception filter IDs. Python: 'raised' (all exceptions), 'uncaught' (unhandled only), 'userUnhandled'. Node.js: 'all' (all exceptions), 'uncaught' (unhandled only). Go/Delve: 'panic' (runtime panics). Use debug_status to see available filters for the current adapter.

debug_list_breakpoints

List all breakpoints currently set in the debug session.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session

debug_evaluate

Evaluate an expression in the current debug context. Can access variables, call functions, and inspect nested objects.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
expression	string	Yes	Expression to evaluate in the debugee's context. E.g., 'cart.items[0].dict', 'len(results)', 'discount < 0'. Can call methods and access nested attributes.
frame_index	number	No	Stack frame context: 0 = current frame (default), 1 = caller, 2 = caller's caller, etc.
max_depth	number	No	Object expansion depth for the result. Default: 2

debug_variables

Get variables from a specific scope and stack frame.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
scope	"local" | "global" | "closure" | "all"	No	Variable scope to retrieve. Default: 'local'. Note: 'closure' is Node.js only — not available in Python or Go.
frame_index	number	No	Stack frame context (0 = current). Default: 0
filter	string	No	Regex filter on variable names. E.g., '^user' to show only user-prefixed vars
max_depth	number	No	Object expansion depth. Default: 1

debug_stack_trace

Get the current call stack showing the execution path to the current point.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
max_frames	number	No	Maximum frames to return. Default: 20
include_source	boolean	No	Include source context around each frame. Default: false

debug_source

Read source code from a file with line numbers. Use this instead of a plain file read when you need line numbers that match the debugger's view, or to read source-mapped or virtual files that don't exist at a literal path on disk.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
file	string	Yes	Source file path
start_line	number	No	Start of range. Default: 1
end_line	number	No	End of range. Default: start_line + 40

debug_watch

Manage watch expressions. Watched expressions are automatically evaluated and shown in every viewport snapshot.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
action	"add" | "remove"	No	Whether to add or remove expressions. Default: 'add'
expressions	string[]	Yes	Expressions to add or remove from the watch list. E.g., ['len(cart.items)', 'user.tier', 'total > 0']

debug_action_log

Get the investigation log for the current session. Shows actions taken, key observations (unexpected values, variable changes), and cumulative viewport token consumption. Older entries are automatically compressed into summaries. Use this to reconstruct your reasoning chain without re-reading old viewports.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
format	"summary" | "detailed"	No	Level of detail. 'summary' compresses older entries. 'detailed' includes timestamps and full observations. Default: 'summary'

debug_output

Get captured stdout/stderr output from the debug target.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session
stream	"stdout" | "stderr" | "both"	No	Which output stream. Default: 'both'
since_action	number	No	Only show output captured since action N. Default: 0 (all)

debug_attach

Attach to an already-running process for debugging. Use when the target is a long-running service (web server, daemon) or when you need to debug a process you didn't launch. The process must already be listening for a debugger: python needs 'python -m debugpy --listen 5678 app.py', node/typescript needs '--inspect' flag (node --inspect app.js), go attaches by PID via Delve.

Parameter	Type	Required	Description
language	string	Yes	Language of the target process. Required for attach (no command to infer from). Supported: python (.py), node/javascript/typescript/js/ts (.js .mjs .cjs .ts .mts .cts .tsx), go (.go), rust (.rs), java (.java), cpp (.c .cpp .cc .cxx .h .hpp), ruby (.rb), csharp (.cs), swift (.swift), kotlin (.kt). Omit to auto-detect from the file extension in the command.
pid	number	No	Process ID to attach to (Go/Delve).
port	number	No	Debug server port. Python debugpy default: 5678. Node.js inspector default: 9229.
host	string	No	Debug server host. Default: '127.0.0.1'
cwd	string	No	Working directory for source file resolution
breakpoints	object[]	No	Breakpoints to set after attaching
viewport_config	object	No	Override default viewport rendering parameters

debug_threads

List all threads in the debug session. Useful for multi-threaded programs (Go goroutines, Python threads). Shows thread IDs and names. Use thread_id on step/continue/evaluate to operate on a specific thread.

Parameter	Type	Required	Description
session_id	string	Yes	The active debug session

Browser & Session Tools

chrome_start

Launch Chrome and start recording browser events (network, console, user input). By default, launches a new isolated Chrome instance — no conflict with an existing Chrome window. Use profile='krometrail' (or any name) to get a fully isolated Chrome that won't collide with your regular browser. Returns a session info summary once Chrome is ready. Use chrome_status to check recording state, chrome_mark to place markers, chrome_stop to end the session. After stopping, use session_list and session_overview to investigate what was recorded. Use attach=true only if Chrome was already launched with --remote-debugging-port=9222.

Parameter	Type	Required	Description
url	string	No	URL to open when launching Chrome
port	number	No	Chrome remote debugging port. Default: 9222
profile	string	No	Chrome profile name — creates an isolated user-data-dir under ~/.krometrail/chrome-profiles/<name>. Each profile has its own cookies, storage, and login state. Use this to avoid conflicts with an already-running Chrome. Example: 'krometrail'
attach	boolean	No	Attach to an already-running Chrome instance (don't launch). Requires Chrome to have been started with --remote-debugging-port=9222. If Chrome is running normally without that flag, use profile instead to launch an isolated instance.
all_tabs	boolean	No	Record all browser tabs. Default: first/active tab only
tab_filter	string	No	Glob pattern — record only tabs whose URL matches, e.g. '/app/'
screenshot_interval_ms	number	No	Periodic screenshot interval in ms. 0 or omit to disable. Example: 5000 for a screenshot every 5s
framework_state	boolean | "react" | "vue" | "solid" | "svelte"[]	No	Enable framework state observation. true = auto-detect all supported frameworks. ["react"] = only React. ["react", "vue"] = both. Default: false (disabled).

chrome_status

Show the current Chrome recording status — whether Chrome is active, how many events and markers have been captured, and which tabs are being recorded.

No parameters.

chrome_mark

Place a named marker in the Chrome recording buffer at the current moment. Markers let you annotate significant events (e.g. 'submitted form', 'saw error') so you can quickly find them later with session_overview or session_search using around_marker.

Parameter	Type	Required	Description
label	string	No	Label for the marker, e.g. 'form submitted' or 'error appeared'. Descriptive labels help you find this marker later with around_marker.

chrome_stop

Stop the active Chrome recording session and flush all buffered events to the database. After stopping, use session_list to find the recorded session and session_overview to investigate it.

Parameter	Type	Required	Description
close_chrome	boolean	No	Also close the Chrome browser. Default: false

session_list

List recorded browser sessions. Use this to find sessions to investigate. Filter by time, URL, or whether the session has markers/errors.

Parameter	Type	Required	Description
after	string	No	ISO timestamp — only sessions after this time
before	string	No	ISO timestamp — only sessions before this time
url_contains	string	No	Filter by URL pattern
has_markers	boolean	No	Only sessions with user-placed markers
has_errors	boolean	No	Only sessions with captured errors (4xx/5xx, exceptions, console errors)
limit	number	No	Max results. Default: 10

session_overview

Get a structured overview of a recorded browser session — navigation timeline, markers, errors, and network summary. Use this to understand what happened before diving into details. Focus on a specific marker with around_marker.

Parameter	Type	Required	Description
session_id	string	Yes	Session ID from session_list
include	"timeline" | "markers" | "errors" | "network_summary" | "framework"[]	No	What to include. Default: all
around_marker	string	No	Center overview on this marker ID
time_range	object	No	Focus on a specific time window
token_budget	number	No	Max tokens for the response. Default: 3000

session_search

Search recorded browser session events. Supports natural language search (uses FTS5) and structured filters (event type, status code, time range, framework, component, pattern). Use natural language for exploratory search, structured filters for precise queries.

Parameter	Type	Required	Description
session_id	string	Yes	Session ID
query	string	No	Natural language search query, e.g. 'validation error' or 'phone format'
event_types	"navigation" | "network_request" | "network_response" | "console" | "page_error" | "user_input" | "websocket" | "performance" | "marker" | "framework_detect" | "framework_state" | "framework_error"[]	No	Filter by event type
status_codes	number[]	No	Filter network responses by HTTP status code, e.g. [400, 422, 500]
time_range	object	No	Filter by time window
around_marker	string	No	Center search around this marker ID (±120s before, +30s after)
url_pattern	string	No	Glob pattern to filter by URL in summary, e.g. '/api/patients'
console_levels	string[]	No	Filter console events by level, e.g. ['error', 'warn']
contains_text	string	No	Case-insensitive substring match on event summary
limit	number	No	Max results. Default: 10
token_budget	number	No	Max tokens for the response. Default: 2000
framework	"react" | "vue" | "solid" | "svelte"	No	Filter by framework. Automatically narrows to framework event types.
component	string	No	Filter by component name (substring match), e.g. 'UserProfile'
pattern	string	No	Filter by bug pattern name, e.g. 'stale_closure', 'infinite_rerender'

session_inspect

Deep-dive into a specific event or moment in a recorded browser session. Returns full event detail, network request/response bodies, surrounding events, and nearest screenshot. This is the primary evidence-gathering tool. If multiple of event_id, marker_id, and timestamp are provided, precedence is: event_id > marker_id > timestamp.

Parameter	Type	Required	Description
session_id	string	Yes	Session ID
event_id	string	No	Specific event ID (from session_search results)
marker_id	string	No	Jump to a marker
timestamp	string	No	ISO timestamp — inspect the moment closest to this time
include	"surrounding_events" | "network_body" | "screenshot" | "form_state" | "console_context"[]	No	What to include alongside the event detail. Default: all
context_window	number	No	Seconds of surrounding events to include. Default: 5
token_budget	number	No	Max tokens for the response. Default: 3000

session_diff

Compare two moments in a recorded browser session. Shows what changed between two timestamps or events: URL, form state, storage, new console messages, and network activity. Useful for understanding what happened between page load and an error.

Parameter	Type	Required	Description
session_id	string	Yes	Session ID
from	string	Yes	First moment — timestamp (ISO or HH:MM:SS) or event ID
to	string	Yes	Second moment — timestamp (ISO or HH:MM:SS) or event ID
include	"form_state" | "storage" | "url" | "console_new" | "network_new" | "framework_state"[]	No	What to diff. Default: form_state, storage, url, console_new, network_new (framework_state must be explicitly requested)
token_budget	number	No	Max tokens. Default: 2000

session_replay_context

Generate a reproduction context from a recorded browser session. Outputs reproduction steps, test scaffolds (Playwright or Cypress), or a summary. Use this to create actionable artifacts from investigation findings.

Parameter	Type	Required	Description
session_id	string	Yes	Session ID
around_marker	string	No	Focus on events around this marker
time_range	object	No	Focus on a specific time window
format	"summary" | "reproduction_steps" | "test_scaffold"	Yes	Output format: 'summary' for overview, 'reproduction_steps' for step-by-step, 'test_scaffold' for automated test code
test_framework	"playwright" | "cypress"	No	Test framework for scaffold generation. Default: playwright