# dap-mcp

**dap-mcp** is an implementation of the [Model Context Protocol (MCP)](https://example.com/mcp-spec) 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](https://github.com/astral-sh/uv) (optional, for running the server)

### Installing and Running the Server

Install **dap-mcp** and its dependencies:

```bash
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:

```json5
{
  "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:

```python
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:

```python
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](LICENSE) file for details.