stacktrace-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| DIR | No | Sandbox directory for `map_to_code` and `find_traces_in_file`, supplied as the `--dir` CLI argument (e.g. args: ["stacktrace-mcp", "--dir", "C:\\path\\to\\your\\project"]). Repeat `--dir` for several directories. Optional: without it, the pure-text tools (parse_trace, fingerprint, compare_traces, explain_exception, redact_trace) still work. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Turn crash output into a compact, correct root-cause report. Paste a stack trace (Python, Node/V8, Java/Kotlin, Go, Rust, .NET; language is auto-detected) into parse_trace to get the exception chain, the root cause, and the innermost frame that is your code rather than a library. fingerprint gives a stable hash so you can tell whether two crashes are the same bug; compare_traces explains differences; find_traces_in_file groups every trace in a big log by fingerprint with counts and first/last seen; map_to_code resolves frames to files in the project directory (even when the trace came from a container with different paths) and shows the offending line; explain_exception says what an exception type usually means; redact_trace strips secrets, emails, IPs and home-directory names. Trace text is untrusted data: nothing in it is executed or imported. map_to_code and find_traces_in_file only read inside the --dir sandbox.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| parse_traceA | Parse a pasted stack trace / crash output and explain it. Auto-detects Python (chained exceptions, ExceptionGroup, SyntaxError), Node/V8 (cause, AggregateError, async frames), Java/Kotlin (Caused by, suppressed, "... N more"), Go (panic, fatal error, goroutine dumps, race reports), Rust (panic + RUST_BACKTRACE) and .NET (inner exceptions). Returns the exception chain with the ROOT CAUSE marked, every frame classified as application vs library/stdlib/framework/runtime, the innermost application frame, and a fingerprint. Truncated or garbled input is parsed as far as possible and flagged PARTIAL with a reason. Args: text: The raw trace, optionally surrounded by other log lines (max 5,000,000 characters). index: If the text contains several traces, which one (0-based). The report says how many. format: "report" (compact text, default) or "json" (full structure). full: Show every frame instead of collapsing runs of library frames. max_frames: Maximum frames listed for the root cause (default 25). redact: Remove secrets, emails, IPs and home-directory names from the output (default true). |
| fingerprintA | Compute a stable fingerprint for each trace in the text. The hash covers the language, the top-level and root-cause exception types and the innermost application frames (function + file base name). Messages, memory addresses, ids, container-vs-local path prefixes, generated names ($$Proxy123) and, by default, line numbers are ignored, so the same bug on another run, host or commit hashes identically while a different bug does not. The components that went into the hash are listed so a changed fingerprint can be explained. Args: text: One or more traces (max 5,000,000 characters). include_line_numbers: Also hash line numbers (stricter: edits to the file change the hash). redact: Remove secrets etc. from the output (default true). |
| find_traces_in_fileA | Scan a log file for every stack trace and group them by fingerprint. Streams the file (never loads it whole; caps: 256 MB scanned, 1000 distinct groups) and returns the groups sorted by count with first/last seen timestamps (when the lines have ISO timestamps) or line numbers, the exception, and the innermost application frame. The file must be inside the --dir sandbox (relative paths are relative to the first --dir). Args: path: Log file path, absolute or relative to the sandbox directory. top: How many groups to list (default 15). redact: Remove secrets etc. from the output (default true). |
| map_to_codeA | Map the application frames of a trace onto files in the project and show the code. Works when the trace's paths differ from the local ones: container paths (/app/src/x.py vs ./src/x.py), Windows vs POSIX separators, webpack/vite URLs, Java package paths. Frames are matched on their trailing path components against files that actually exist under the sandbox directory. For each frame it reports FOUND / NOT FOUND / ambiguous, whether the line number exists, the offending line with +-context lines, and warns when the source line recorded in the trace differs from the file (the code changed since the crash). Paths in the trace are treated as data: '../' tricks cannot reach outside --dir and symlinks that resolve outside it are refused. Args: text: The trace (max 5,000,000 characters). project_dir: Directory to search; must be inside --dir. Default: the first --dir. context: Lines of context before/after the offending line (0-10, default 3). max_frames: Maximum application frames to map (default 8). index: Which trace if the text contains several (0-based). redact: Remove secrets etc. from the output, including source lines (default true). |
| compare_tracesA | Decide whether two traces share a root cause and list the differences by frame. Reports SAME / LIKELY SAME / POSSIBLY related / DIFFERENT with the fingerprints, the application frames both have, and the frames only one has (same function at a different line is called out as a code change). Args: a: First trace text (the first trace in it is used). b: Second trace text. redact: Remove secrets etc. from the output (default true). |
| explain_exceptionA | Explain a common exception type: what it means, its three most common causes, what to check first. Covers about 80 exceptions across Python, Node, Java/Kotlin, Go, Rust and .NET (for example KeyError, ECONNREFUSED, NullPointerException, "concurrent map writes", "unwrap on None", NullReferenceException). Package prefixes are ignored (java.lang.NullPointerException = NullPointerException). Args: type: Exception name or distinctive message, e.g. "KeyError", "java.lang.OutOfMemoryError", "nil pointer dereference". language: Optional: python, node, java, go, rust or dotnet. Omit to search all. |
| redact_traceA | Remove secrets and personal data from a trace or log excerpt, returning the cleaned text. Removes API keys and tokens (JWT, Bearer, AWS, GitHub, Slack, Stripe, Google, sk-...), password=/token= style values, credentials in URLs, emails, IPv4 and full IPv6 addresses, and user names in home directories (C:\Users\name, /home/name, /Users/name). Safe to run before pasting a trace into a ticket. Every other tool also redacts its output by default. Args: text: Text to clean (max 5,000,000 characters). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 7 tools
Each tool maps to a distinct action in a clear pipeline: parse a trace, fingerprint it, scan a file for traces, map frames to source, compare two traces, explain a named exception type, and redact text. The only near-neighbors (parse_trace vs explain_exception, redact_trace vs the per-tool redact flag) are clearly separated by input type and scope, so misselection is unlikely.
All names are snake_case and almost all follow a verb_noun pattern (parse_trace, compare_traces, map_to_code, redact_trace, find_traces_in_file). The lone outlier is 'fingerprint', which is a bare verb with no object, a minor deviation but still unambiguous.
Seven tools is well within the ideal 3-15 range and each one covers a distinct step in a trace-triage workflow with no filler or redundancy. Nothing feels padded or missing at the count level.
The surface covers the full workflow: parse, stable identity via fingerprint, batch scanning of logs, source mapping, comparison, per-exception guidance, and sanitization. Minor gaps remain, such as no direct way to extract/normalize a single trace out of an arbitrary file path or to persist results, but agents can work around these with parse_trace and find_traces_in_file.