dap-mcp

dap-mcp is an implementation of the Model Context Protocol (MCP) tailored for managing Debug Adapter Protocol (DAP) sessions. MCP provides a standardized framework to optimize and extend the context window of large language models, and in this project, it is used to enhance and streamline debugging workflows.

Features

• Debug Adapter Protocol Integration: Interact with debuggers using a standardized protocol.
• MCP Framework: Leverage MCP to optimize context and enhance debugging workflows.
• Rich Debugging Tools: Set, list, and remove breakpoints; control execution (continue, step in/out/next); evaluate expressions; change stack frames; and view source code.
• Flexible Configuration: Customize debugger settings, source directories, and other parameters via a JSON configuration file.

Installation

Prerequisites

• Python 3.10 or higher
• uv (optional, for running the server)

Installing and Running the Server

Install dap-mcp and its dependencies:

pip install dap-mcp
python -m dap_mcp --config config.json

# Or, if you have uv installed
uvx dap-mcp@latest --config config.json

Configuration

The project uses a JSON configuration file (e.g., .config.json) to specify debugger settings and source directories. An example configuration:

{
  "type": "debugpy",
  "debuggerPath": "/path/to/python/with/debugpy",
  "debuggerArgs": [
    "-m",
    "debugpy.adapter"
  ],
  // source directories for resolving file paths
  // if you always use absolute paths, you can omit this
  "sourceDirs": [
    "/path/to/source/code"
  ],
  // debugger-specific settings start here
  // configurations for debugpy can be found at
  // https://github.com/microsoft/debugpy/wiki/Debug-configuration-settings
  
  // you can use "program" instead of "module" to specify the program to debug
  "module": "pytest",
  // the python executable to use to run the debuggee
  "python": ["/path/to/python"],
  "cwd": "/path/to/working/directory"
}

This configuration informs the debugger about:

• The path to the debugger executable and its arguments.
• The source directories for resolving file paths during breakpoint operations.
• Other settings (such as module, working directory, and interpreter path) necessary for launching the debuggee.

Available Debugger Types

Type	Example Path	Example Args
debugpy	/usr/bin/python3	["-m", "debugpy.adapter"]
lldb	/usr/bin/lldb-dap	[]

Available Tools

The project exposes several tools that can be invoked via the MCP framework:

• launch: Launch the debuggee program.
• set_breakpoint: Set a breakpoint at a specified file and line (with an optional condition).
• remove_breakpoint: Remove a breakpoint from a specified file and line.
• list_all_breakpoints: List all breakpoints currently set in the debugger.
• continue_execution: Continue program execution after hitting a breakpoint.
• step_in: Step into a function call.
• step_out: Step out of the current function.
• next: Step over to the next line of code.
• evaluate: Evaluate an expression in the current debugging context.
• change_frame: Switch to a different stack frame.
• view_file_around_line: View source code around a specified line (using the last provided file if none is specified).
• terminate: Terminate the debugging session.

These tools provide XML-rendered output for integration with MCP clients.

Extending with Other DAP Servers

To support additional DAP servers, you can simply add a new DAP-specific configuration class in the dap_mcp/config.py file. All DAP configurations extend from the base DAPConfig class. Each new subclass should:

• Define a unique type value (using a Literal) to act as a discriminator.
• Include any additional fields or settings specific to that debugger.

For example, to add support for a hypothetical DAP server called "mydap", you might add:

class MyDAP(DAPConfig):
    type: Literal["mydap"]
    # Add any additional settings for MyDAP here
    customSetting: Optional[str] = Field(
        None, description="A custom setting for MyDAP."
    )

After creating your new configuration class, update the union type used for debugger-specific configurations by including your new class. For example:

DebuggerSpecificConfig = Annotated[Union[DebugPy, MyDAP], Field(..., discriminator="type")]

Now, when you supply a configuration JSON with "type": "mydap", it will be parsed and validated using your new MyDAP class, and your DAP server extension will be fully integrated.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Write tests and ensure all checks pass.
4. Submit a pull request.

Please follow the coding guidelines and include appropriate tests with your changes.

License

This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.