Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
346 lines (263 loc) · 9.72 KB

CONTRIBUTING.md

File metadata and controls

346 lines (263 loc) · 9.72 KB
Raw

Contributing to mcp-debugger

Thank you for your interest in contributing to mcp-debugger! We welcome contributions from the community and are grateful for your support.

📋 Table of Contents

📜 Code of Conduct

This project adheres to a Code of Conduct that all contributors are expected to follow. Please be respectful and professional in all interactions.

🚀 Getting Started

Prerequisites

  • Node.js 18+ (20.x recommended)
  • pnpm (required — workspace:* protocol needs pnpm, not npm)
  • Python 3.7+ (for debugging Python code)
  • Go 1.18+ and Delve (for debugging Go code, optional)
  • Rust toolchain (for debugging Rust code, optional — CodeLLDB auto-downloads during install)
  • JDK 21+ (for debugging Java code, optional — JDI bridge compiles on first use; compile target code with javac -g for variable inspection)
  • Docker (optional, for containerized development)
  • Git

Initial Setup

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/mcp-debugger.git
cd mcp-debugger
  3. Add upstream remote: 
    git remote add upstream https://github.com/debugmcp/mcp-debugger.git
  4. Install dependencies: 
    pnpm install
  5. Build the project: 
    npm run build

💻 Development Workflow

  1. Sync with upstream:

    git fetch upstream
git checkout main
git merge upstream/main

  2. Create a feature branch:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  3. Make your changes following our code style guidelines

  4. Build and test:

    npm run build
npm test
npm run lint

  5. Commit your changes using conventional commits (see below)

  6. Push to your fork:

    git push origin feature/your-feature-name

  7. Create a Pull Request from your fork to our main branch

🔒 Privacy Guidelines

IMPORTANT: Never commit personal information to the repository. This includes:

  • Personal file paths (e.g., C:\path\to\ or /path/to/)
  • Personal email addresses (project emails like debug@sycamore.llc are okay)
  • Cloud storage paths with personal folders
  • Any other personally identifiable information

Pre-commit Hook

We have a pre-commit hook that automatically checks for personal information patterns. If detected, your commit will be blocked with instructions on how to fix it.

How to Handle Paths

When documenting or writing examples, always use generic paths like:

  • /path/to/project
  • C:\path\to\project
  • ~/workspace/project

Testing the Privacy Check

You can manually run the privacy check:

# Check staged files (what pre-commit does)
npm run check:personal-paths

# Check all files in the repository
npm run check:all-personal-paths

🎨 Code Style

We use ESLint and Prettier to maintain consistent code style.

Setup

# Run ESLint
npm run lint

# Fix auto-fixable issues
npm run lint:fix

# Format code with Prettier (if configured)
npm run format

Guidelines

  • Use TypeScript for all new code
  • Follow the existing code structure and patterns
  • Write self-documenting code with clear variable names
  • Add JSDoc comments for public APIs
  • Keep functions small and focused
  • Use dependency injection patterns (see existing code)

Editor Configuration

We recommend configuring your editor to:

  • Format on save using Prettier
  • Show ESLint warnings/errors inline
  • Use the project's TypeScript version

Example VS Code settings:

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

Testing

The project includes a comprehensive test suite. Please ensure all tests pass before submitting a pull request. If you're adding a new feature, please include tests for it.

Running Tests

The project uses Vitest as its test runner:

# Run all tests
npm test

# Run specific test suites
npm run test:unit         # Unit tests only
npm run test:integration  # Integration tests only
npm run test:e2e         # End-to-end tests only

# Run tests with coverage
npm run test:coverage

# Run a specific test file
npx vitest run tests/unit/session/session-manager.test.ts

Test Architecture

Our tests follow a three-tiered approach:

  1. Unit Tests: Test individual components in isolation.
    • Focus: Session management, debugger provider implementations, utility functions.
  2. Integration Tests: Test interactions between components.
    • Focus: Complete debugging workflow tests, DAP message sequencing.
  3. End-to-End (E2E) Tests: Test the full system with actual debugpy servers.
    • Focus: Full debugging scenarios from MCP request to debugpy interaction and back.

Writing Tests

  • Write tests for all new features and bug fixes
  • Aim for >90% code coverage
  • Use descriptive test names that explain what is being tested
  • Follow the AAA pattern: Arrange, Act, Assert
  • Mock external dependencies appropriately

📝 Commit Messages

We follow the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, semicolons, etc.)
  • refactor: Code refactoring without changing functionality
  • perf: Performance improvements
  • test: Adding or modifying tests
  • build: Build system or dependency changes
  • ci: CI/CD configuration changes
  • chore: Other changes that don't modify src or test files

Examples

feat(debugger): add support for conditional breakpoints

Added ability to set breakpoints with conditions that are evaluated
at runtime. This allows for more precise debugging workflows.

Closes #123
fix(session): handle disconnect during stepping

Fixed race condition where disconnect during step operations
could leave the session in an invalid state.

🚦 Pull Request Process

  1. Before submitting:

    • Ensure all tests pass
    • Update documentation if needed
    • Add tests for new functionality
    • Run linting and fix any issues
    • Update CHANGELOG.md if applicable

  2. PR Guidelines:

    • Use the PR template
    • Link related issues
    • Keep PRs focused on a single concern
    • Write clear descriptions
    • Add screenshots/demos for UI changes

  3. Review Process:

    • PRs require at least one review from @debugmcp
    • Address all review comments
    • Keep discussions professional and constructive
    • Be patient - reviews may take a few days

  4. After Approval:

    • Squash commits if requested
    • Ensure CI passes
    • Maintainer will merge using "Squash and merge"

📁 Project Structure

mcp-debugger/
├── packages/               # Monorepo workspace packages
│   ├── shared/            # Shared interfaces, types, and utilities
│   ├── adapter-python/    # Python debug adapter (debugpy)
│   ├── adapter-javascript/# JavaScript/Node.js adapter (js-debug)
│   ├── adapter-rust/      # Rust adapter (CodeLLDB)
│   ├── adapter-go/        # Go adapter (Delve)
│   ├── adapter-java/      # Java adapter (JDI bridge)
│   ├── adapter-mock/      # Mock adapter for testing
│   └── mcp-debugger/      # Self-contained CLI bundle (npx distribution)
├── src/                    # Core server source code
│   ├── adapters/          # Adapter loading and registry
│   ├── cli/               # CLI commands and setup
│   ├── container/         # Dependency injection
│   ├── proxy/             # DAP proxy components
│   ├── session/           # Session management
│   └── utils/             # Utility functions
├── tests/                 # Test files
│   ├── core/             # Core unit and integration tests
│   ├── adapters/         # Adapter-specific tests
│   ├── e2e/              # End-to-end tests
│   └── test-utils/       # Shared test utilities
├── examples/              # Example scripts
├── docs/                  # Documentation
└── .github/               # GitHub templates and workflows

Key Components

  • Session Manager: Manages debugging session lifecycle
  • DAP Proxy: Handles communication with debug adapters via DAP protocol
  • Adapter Registry: Dynamically loads and manages language-specific adapters
  • Adapter Policies: Language-specific behavior via policy pattern
  • MCP Tools: Implements the 19 MCP protocol tools

🏃 Running the Demo

To see mcp-debugger in action:

  1. Build the project:

    npm run build

  2. Run with a demo script:

    # Start the server in STDIO mode
node dist/index.js stdio

# Or start in SSE mode for web clients
node dist/index.js sse -p 3001

  3. Example debugging session:

    • Create a debug session
    • Set a breakpoint at line 10
    • Start debugging swap_vars.py
    • Step through and inspect variables
    • See the bug and fix it!

❓ Questions?

Thank you for contributing to mcp-debugger! 🙏