mcp-dap: Instructions file for Codex

AGENTS.md - Coding Agent Instructions

This file contains instructions for AI coding agents working on the mcp-dap codebase.

Project Overview

MCP-DAP is a bridge that enables code agents to debug processes using the Debug Adapter Protocol (DAP). It exposes DAP capabilities through an MCP (Model Context Protocol) server.

Build & Development Commands

Setup

uv venv && source .venv/bin/activate && uv sync

Testing

uv run pytest                                    # Run all tests
uv run pytest tests/test_server.py               # Run a single test file
uv run pytest tests/test_server.py::test_serve   # Run a single test function
uv run pytest -k "test_serve"                    # Run tests matching pattern
uv run pytest --cov=src/mcp_dap                  # Run with coverage
uv run pytest -m "not slow"                      # Exclude slow tests

Linting & Formatting

uv run ruff check .              # Check linting
uv run ruff check --fix .        # Auto-fix linting
uv run ruff format .             # Apply formatting
uv run mypy src                  # Type checking

Dependency Management

uv add <package>                 # Add a dependency
uv add --dev <package>           # Add a dev dependency
uv lock                          # Update lock file
uv sync                          # Sync dependencies from lock file

Code Style Guidelines

Imports

• Use from __future__ import annotations at the top of every module
• One import per line (enforced by ruff isort)
• Order: stdlib → third-party → first-party (mcp_dap)
• Use TYPE_CHECKING block for type-only imports

from __future__ import annotations

import asyncio
from typing import TYPE_CHECKING

from pydantic import BaseModel

from mcp_dap.types import DebugSession

if TYPE_CHECKING:
    from mcp_dap.protocol import DAPClient

Formatting

• Line length: 100 characters max
• Indent: 4 spaces (no tabs)
• Quote style: double quotes
• Use pathlib.Path instead of os.path