CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.21.0] - 2026-05-30

Changed

• Minimum Node.js raised to 22. All packages now declare engines.node >=22.0.0, and the Docker image builds on node:22-slim. Node 18 and 20 are no longer supported (Node 20 reached end-of-life April 2026).

Dependencies

• Bumped which 6 → 7 (requires Node 22+). The API is unchanged, and which is bundled into the @debugmcp/mcp-debugger npx CLI, so end-user installs are unaffected. (supersedes #76)

[0.20.0] - 2026-03-29

Added

• redefine_classes MCP tool — hot-swap changed Java classes into a running JVM without restarting the debug session (21 MCP tools total) (PR #26, contributed by @Finomosec)
• E2E tests for redefine_classes and Java ClassPrepareEvent/BreakpointEvent race condition
• redefine_classes documentation in docs/java/README.md

Fixed

• Attach-mode stopOnEntry — restore default to preserve paused state; pass stopOnEntry through to attach and default to false in create_debug_session
• Java event loop race — prevent ClassPrepareEvent from resuming stopped threads (PR #27, contributed by @Finomosec)
• Java attach suspend — suspend VM on attach when stopOnEntry is true
• Remove dead ProcessAdapter class and unrecognized --no-wait arg from debugpy E2E test

Changed

• Comprehensive osoji sweeps — dead code removal, stale docs rewrite, test robustness improvements
• Replace istanbul ignore comments with real unit tests
• Fix comprehensive test matrix failures; add dotnet/java language coverage

[0.19.0] - 2026-03-22

Added

• .NET/C# debug adapter — full debugging via netcoredbg with launch/attach modes, conditional breakpoints, exception breakpoints, TCP-to-stdio bridge, and Portable PDB support (PR #24, contributed by @bob7123)
• list_threads MCP tool — list all threads in the debugged process (20 MCP tools total)
• pause_execution enhanced — optional threadId parameter to pause a specific thread
• Java pause command — pause_execution support for Java adapter
• Java per-breakpoint suspend policy — control thread suspension behavior per breakpoint (PR #25, contributed by @Finomosec)
• Batteries-included CLI bundle — Rust, Java, and .NET adapters now bundled in @debugmcp/mcp-debugger
• Pause test programs for Go, .NET, Java
• Regression tests for Go and .NET pause fixes
• Adapter registry, server coverage, and Go policy unit tests
• Bridge fallback and bundle asset verification tests
• Disconnect/detach safety tests

Fixed

• Go and .NET pause workflow failures
• Latent bugs in adapter loader, mock DAP parser, Java adapter, and Docker entrypoint
• Fail fast with clear error when Docker daemon is not running
• netcoredbg bridge path resolution for spaces in paths and NPX bundle variants
• dapLaunchArgs.program preservation for compiled languages
• Comprehensive osoji audit remediations (runtime bugs, dead code, stale docs)
• 0% coverage files addressed after Vitest 4 upgrade

Changed

• Adapter loading, error handling, logging, and language-specific documentation updated
• Test robustness improvements and dead code removal

[0.18.1] - 2026-03-11

Added

• Java FQCN (Fully Qualified Class Name) support as breakpoint file parameter — pass class names like com.example.MyClass instead of file paths

Fixed

• Multi-breakpoint aggregation and sourcePath-based breakpoint cleanup
• Moved isJavaFqcn into adapter policy layer following Open/Closed principle

[0.18.0] - 2026-03-05

Added

• Go debugging support – full Delve DAP adapter with debug, test, exec, replay, and core modes, goroutine-aware stack traces, and automatic dlv detection (contributed by @swinyx)
• Java debugging support – JDI bridge (JdiDapServer.java) with launch and attach modes, variable inspection, and deferred breakpoints via ClassPrepareRequest (contributed by @roofpig95008)
• Java attach mode – connect to running JVMs via JDWP agent for debugging servers and complex applications
• Java expression evaluation – full expression evaluator supporting field access, method calls, array indexing, arithmetic, string concatenation, casting, instanceof, ternary, and unary operators
• Java conditional breakpoints – conditions evaluated server-side via the expression evaluator
• Java documentation – docs/java/README.md user guide covering prerequisites, JDI bridge architecture, and troubleshooting
• CI Go + Java toolchains – workflow now installs Go 1.21, Delve, and JDK 21 for cross-platform E2E testing
• Dev proxy – lightweight MCP proxy for hot-reloading mcp-debugger during development without restarting Claude Code
• Dev proxy STDIO backend transport mode – STDIO transport option for the dev proxy

Changed

• Java backend – replaced KDA (kotlin-debug-adapter) and stdio-tcp-bridge with a single JDI bridge (JdiDapServer.java) using com.sun.jdi.* directly; zero external dependencies, compiles on first use
• Java minimum JDK – recommended JDK 21+ to match --release 21 bridge compilation target; the adapter warns (but does not error) when Java is below 21, and the runtime adapter warns when Java is below version 11
• Removed dead sendConfigDoneWithAttach/sendConfigDoneWithLaunch code paths

Fixed

• Java inner class breakpoints – fixed JDWP ClassPrepareRequest filter patterns (*ClassName$* silently fails; changed to ClassName$*)
• Java instanceof with interfaces – isSubtypeOf now handles InterfaceType subjects and recursive interface-extends-interface chains
• Java thread ID overflow – changed from int to long thread IDs throughout the DAP bridge
• Java frame ID collisions – replaced arithmetic encoding (threadId * 100000 + frameIndex) with lookup-table approach
• Java breakpoint IDs – added unique, monotonically increasing breakpoint IDs per DAP spec
• Java thread safety – used ConcurrentHashMap and AtomicInteger for shared state; added synchronized blocks for frame cache access
• Java boolean operators – && and || parsing now consumes tokens correctly; note that the RHS is still evaluated for JDI side effects before deciding the result value
• Java thread discovery – discover JVM threads via DAP threads request instead of hardcoding threadId=1
• Java variable access – document and enforce javac -g requirement for LocalVariableTable (JDI needs it for local variable inspection)
• Block EventSource phantom reconnection in SSE transport
• Coerce stringified tool arguments from SSE transport
• Docker Java support, crash safety, and continue-execution state race
• Auto-detach safety for attach sessions
• Prevent orphan child processes from holding ports after SSE crash
• Prevent SSE backend from crashing immediately after startup
• Two-phase initialized event handling for Delve on Windows
• Replace printf-generated Docker entry.sh with version-controlled script
• Downgrade missing debugpy to warning for virtualenv support
• Prevent Docker path double-prefixing with idempotent resolution
• Bundled Go adapter and mock-adapter-process for npx distribution
• Resolved workspace:* dependency resolution during pnpm pack
• Fixed cross-test pollution from process.env.PATH in Go/Python unit tests
• Added Go adapter to Dockerfile and fixed Windows volume mount paths

Removed

• Java jdb adapter – jdb text-parsing approach proved too fragile; replaced by JDI bridge

[0.17.0] - 2025-11-22

Added

• Rust adapter (Alpha) – integrates CodeLLDB to support Cargo projects, async runtimes, and cross-platform execution with smart rebuild detection

Improved

• Stepping UX – every step_* response now embeds current source context so agents see the active file/line instead of generic “success” acknowledgements

Packaging

• CodeLLDB footprint – CLI bundle ships the Linux x64 CodeLLDB runtime by default (other platforms can point CODELLDB_PATH to an installed binary or re-run the vendor script) to stay within npm size limits

[0.16.0] - 2025-11-09

Added

• JavaScript adapter (Alpha) – full debugging loop backed by bundled js-debug, TypeScript detector, and adapter policy orchestration
• Adapter documentation – updated docs/javascript/* guides covering architecture, source maps, and usage
• Proxy session analytics – dry-run/handshake instrumentation persisted in logs for CI triage

Changed

• Build system – migrated CLI bundling from esbuild to tsup (noExternal: [/./]) for deterministic workspace packaging
  • Produces self-contained @debugmcp/mcp-debugger bundles and trims install size
  • Simplifies npx execution by embedding adapter assets
• Proxy bundling – emitted dedicated proxy-bundle.cjs process with automatic runtime detection of bundled vs dev mode
• Adapter wiring – session manager now loads adapters via registry/policies, enabling future language additions

Fixed

• Resolved missing dependency errors when running via npx (fs-extra, etc.)
• Ensured proxy bootstrap locates js-debug artifacts in bundled distributions
• Hardened Windows dry-run handling to avoid silent exits

Improved

• npx distribution – zero-runtime dependencies; CLI bundle (~3 MB) includes all workspace packages, proxy bundle ships with required modules
• Build performance – faster incremental builds with tsup and shared cache
• Deployment simplicity – single command npx @debugmcp/mcp-debugger stdio “just works”; Docker image consumes same artifact layout
• Documentation footprint – refreshed build pipeline notes (docs/development/build-pipeline.md) and architecture overview

[0.15.7] - 2025-09-27

Added

• Monorepo architecture - Complete refactor to workspace-based monorepo structure, setting the foundation for multi-language adapter support
  • Extracted Python adapter into @debugmcp/adapter-python package
  • Extracted Mock adapter into @debugmcp/adapter-mock package
  • Created shared types and interfaces in @debugmcp/shared package
  • Dynamic adapter loading system for extensibility
• Pre-push lint validation - ESLint now runs before push to prevent CI failures
• Typed error system - Replaced brittle string matching in tests with proper typed errors
• Validation script - Test in clean environment before release
• npx distribution package - Direct execution support via npx @debugmcp/mcp-debugger
• pnpm workspace support - Migrated from npm to pnpm for better monorepo management

Fixed

• Removed unused SessionNotFoundError import that was blocking CI
• Docker container file operations now use relative paths
• Docker E2E test converted to use stdio transport for reliability
• Deprecated warnings resolved before release
• Build artifacts removed from git and prevented in CI tests
• Proxy bootstrap JavaScript file restored to fix CI failures
• TypeScript module resolution issues in CI/CD pipeline
• Workspace package type declarations and build order

Changed

• Architecture: Modularized codebase into workspace packages for better maintainability and future language support
• Docker E2E tests now enabled locally by default
• Improved error handling with typed error classes for better reliability
• Enhanced pre-push hooks to match CI validation requirements
• Build system now uses TypeScript composite projects for proper inter-package dependencies

[0.14.1] - 2025-01-16

Fixed

• Resolved ESLint violations that were blocking CI/CD pipeline
• Fixed linting issues in proxy modules and test files

[0.14.0] - 2025-01-15

Added

• evaluate_expression tool - Execute expressions in the current debug context to inspect and modify program state dynamically
• Proxy-ready handshake mechanism - Ensures reliable proxy initialization and prevents race conditions
• Orphan process detection - Automatically terminates proxy processes that become orphaned

Fixed

• Memory leak in DAP client buffer management - Improved from O(n²) to O(n) complexity
• Race condition in MinimalDapClient causing unhandled error events during connection phase
• Race condition in proxy initialization causing unhandled promise rejections
• Proxy processes becoming orphaned after test suite execution on Linux

Changed

• Proxy initialization timeout reduced from 30s to 10s to prevent resource consumption
• Improved error handling in ProxyProcessAdapter with proper promise lifecycle management

[0.13.0] - 2025-01-15

Added

• Initial implementation of evaluate_expression tool for dynamic debugging capabilities

[0.12.0] - 2025-07-28

Added

• Path validation to prevent crashes from non-existent files - immediate feedback instead of cryptic "[WinError 267]" errors
• Line context in set_breakpoint responses - enables AI agents to make intelligent breakpoint placement decisions
• get_source_context tool implementation - previously unimplemented tool now provides source code exploration capabilities
• Efficient line reading with LRU caching - optimized file access for repeated operations on the same files

Fixed

• Cryptic "[WinError 267] The directory name is invalid" crashes when debugging with non-existent files
• Silent acceptance of invalid breakpoints - now provides immediate validation feedback
• Missing implementation of get_source_context tool

Changed

• set_breakpoint now returns immediate feedback for missing files with clear error messages
• Improved error messages throughout - all file-related errors now include resolved paths and helpful context
• set_breakpoint responses now include optional context field with line content and surrounding code

[0.11.2] - 2025-01-14

Fixed

• PyPI package deployment workflow - fixed invalid classifier format that was preventing successful uploads
• npm package deployment - added missing provenance configuration for trusted publishing

Changed

• Updated Python package classifiers to use standard PyPI format
• Enhanced CI/CD workflows for more reliable multi-platform releases

[0.11.1] - 2025-01-13

Fixed

• Release workflow to use correct secret name for PyPI deployment
• Documentation references to old package names

[0.11.0] - 2025-01-13

Breaking Changes

• Package renamed from debug-mcp-server to @debugmcp/mcp-debugger on npm
• Python launcher renamed to debug-mcp-server-launcher on PyPI
• Docker image moved to debugmcp/mcp-debugger on Docker Hub

Added

• Official organization structure under debugmcp namespace
• Multi-platform Docker builds (amd64, arm64)
• Comprehensive deployment documentation

Fixed

• CI/CD workflows for seamless releases across all platforms

[0.10.0] - 2025-06-24

Added

• Dynamic Tool Documentation: Tool descriptions now adapt to runtime environment (host vs container), helping LLMs understand path requirements without trial and error
• Structured JSON Logging: All debugging operations emit structured JSON logs for visualization and monitoring
  • Tool invocations with sanitized parameters
  • Debug state changes (paused/running/stopped)
  • Breakpoint lifecycle events
  • Variable inspections with truncated values
• Comprehensive Smoke Tests: Added SSE and container transport smoke tests to complement existing stdio tests
  • Tests for all transport mechanisms (stdio, SSE, containerized)
  • Cross-platform volume mounting verification
  • Smart Docker image caching for faster tests
• Path Translation System: Improved dependency injection for container/host path flexibility
• Test Utilities: Enhanced test helpers for smoke tests including Docker utilities

Changed

• Docker Image Optimization: Reduced image size by 64% (670MB → 240MB), improving deployment size and container startup time
  • Switched to Alpine Linux base image
  • Implemented esbuild bundling for JavaScript dependencies
  • Optimized multi-stage build process
• Container Proxy Bundling: Fixed proxy dependency issues in Alpine environments
• Parameter Validation: Improved validation with proper MCP error responses
• Error Messages: Enhanced error messages with clearer context for debugging

Fixed

• Container proxy dependency resolution in Alpine Linux environments
• Test mocking issues in dynamic tool documentation
• Path handling edge cases in container mode
• Various test stability improvements

[0.9.0] - 2025-01-09

Breaking Changes

• SessionManager constructor changed to use dependency injection (backward compatibility maintained but deprecated)
• Removed ActiveDebugRun type in favor of ProxyManager architecture

Added

• Vitest Migration: Complete migration from Jest to Vitest for native ESM support (10-20x faster test execution)
• Dependency Injection: Comprehensive dependency injection system with factories for all major components
• Error Handling: Centralized error messages module with user-friendly timeout explanations
• Proxy Architecture: Three-layer proxy architecture (core/worker/entry) for better separation of concerns
• Functional Core: Pure functional DAP handling logic with no side effects
• Documentation:
  • Comprehensive developer documentation in docs/development/
  • Architecture diagrams and patterns guide in docs/architecture/ and docs/patterns/
  • LLM collaboration journey documentation
• Test Utilities: Extensive test helper functions and mock factories

Changed

• Test Coverage: Increased from <20% to >90% with 657 passing tests (up from 355)
• SessionManager: Reduced complexity by 40% through ProxyManager delegation
• Code Organization: Improved separation of concerns with clear module boundaries
• Event Management: Proper lifecycle management with cleanup on session close

Fixed

• Memory leak in event handlers (proper cleanup in closeSession)
• Race condition in dry run (replaced hardcoded timeout with event-based coordination)
• Unhandled promise rejections in tests
• Enhanced timeout error messages for better debugging

Removed

• Jest test runner and all Jest-related dependencies
• Obsolete test files and configurations
• python-utils.ts from core (refactored and consolidated into packages/adapter-python/src/utils/python-utils.ts)
• Various deprecated provider and protocol files

[0.1.0] - 2025-05-27

Added

• Initial public release of debug-mcp-server.
• Core functionality for Python debugging using the Debug Adapter Protocol (DAP) via debugpy.
• MCP server implementation with tools for:
  • Creating and managing debug sessions (create_debug_session, list_debug_sessions, close_debug_session).
  • Debug actions: set_breakpoint, start_debugging, step_over, step_into, step_out, continue_execution.
  • State inspection: get_stack_trace, get_scopes, get_variables.
• Support for both STDIN/STDOUT and HTTP transport for MCP communication.
• Basic CLI to start the server with transport and logging options.
• Python "launcher" package (debug-mcp-server-launcher) for PyPI, to aid users in running the server and ensuring debugpy is available.
• Dockerfile for building and running the server in a containerized environment, including OCI labels.
• GitHub Actions CI setup for:
  • Building and testing on Ubuntu and Windows.
  • Linting with ESLint.
  • Publishing Docker image to Docker Hub on version tags.
  • Publishing Python launcher package to PyPI on version tags.
• Project structure including:
  • LICENSE (MIT).
  • CONTRIBUTING.md (basic template).
  • GitHub issue and pull request templates.
  • README.md with quick start, features, and usage instructions.
  • docs/ directory with initial documentation (quickstart.md).
  • examples/ directory with:
    • python_simple_swap/: A buggy Python script and a demo script showing how to debug it using MCP tools.
    • agent_demo.py: A minimal example of an LLM agent loop interacting with the server.
• Unit and integration tests for core functionality. (E2E tests for HTTP transport are currently skipped due to environment complexities).
• pyproject.toml for the Python launcher and package.json for the Node.js server.

Changed

• Build output directory standardized to dist/.

Known Issues

• E2E tests for HTTP transport (tests/e2e/debugpy-connection.test.ts) are temporarily skipped due to challenges with JavaScript environment setup (fetch/ReadableStream polyfills in Jest/JSDOM). These will be revisited.
• Placeholder URLs and names (e.g., for repository, Docker Hub user, author) in package.json, pyproject.toml, Dockerfile, README.md, and example scripts need to be updated with actual project details.