### Development Setup and Build

Source: https://github.com/debugmcp/mcp-debugger/blob/main/README.md

Installs dependencies, builds the project, and runs tests. Debug adapters are automatically downloaded during installation.

```bash
# Development setup
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Install dependencies and vendor debug adapters
pnpm install
# All debug adapters (JavaScript js-debug, Rust CodeLLDB) are automatically downloaded

# Build the project
pnpm build

# Run tests
pnpm test

# Check adapter vendoring status
pnpm vendor:status

# Force re-vendor all adapters (if needed)
pnpm vendor:force
```

--------------------------------

### Create and Start Debug Session Example

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/api-reference.md

Demonstrates the workflow for creating a debug session, setting breakpoints, starting the debugging process, and listening for events. This example covers the essential steps for initiating a debugging session.

```typescript
// 1. Create session
const sessionInfo = await sessionManager.createSession({
  language: 'python',
  name: 'My Debug Session'
});

// 2. Set breakpoints (one call per breakpoint)
await sessionManager.setBreakpoint(sessionInfo.sessionId, 'app.py', 10);
await sessionManager.setBreakpoint(sessionInfo.sessionId, 'app.py', 20);

// 3. Start debugging
await sessionManager.startDebugging({
  sessionId: sessionInfo.sessionId,
  script: 'app.py',
  launchConfig: { stopOnEntry: true }
});

// 4. Listen for events via the ProxyManager for the session
// Note: SessionManager is not an EventEmitter. Subscribe to events through
// the ProxyManager associated with the session, or poll session state.
const session = sessionManager.getSession(sessionInfo.sessionId);
session?.proxyManager?.on('stopped', (threadId, reason) => {
  console.log('Paused at:', reason);
});

// 5. Continue execution
await sessionManager.continue(sessionInfo.sessionId);
```

--------------------------------

### Verify Installation with Tests

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Run the project's test suite to ensure the setup is correct. Some environment-specific tests may be expected to fail.

```bash
npm test
```

--------------------------------

### Example Loader Error: Adapter Not Installed

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/dynamic-loading-architecture.md

This error message indicates that the required adapter package for a specific language is not installed in the current runtime. Follow the suggested command to install it.

```text
Failed to load adapter for 'python' from package '@debugmcp/adapter-python'. Adapter not installed. Install with: npm install @debugmcp/adapter-python
```

--------------------------------

### Install Dependencies

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/getting-started.md

Install project dependencies and build the project.

```bash
pnpm install
npm run build
```

--------------------------------

### Husky Setup in package.json

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/git-hooks-guide.md

Configures Husky to run the `prepare` script, which is responsible for installing and setting up Git hooks when the project is cloned or dependencies are installed.

```json
"scripts": {
    "prepare": "husky install"
  }
```

--------------------------------

### Launch mode commands

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/ruby/README.md

Example commands for creating a debug session, setting breakpoints, and starting the debugging process in launch mode. These commands are sent from the MCP client to mcp-debugger.

```text
create_debug_session  { "language": "ruby", "name": "My Session" }
set_breakpoint        { "sessionId": "...", "file": "/abs/path/app.rb", "line": 15 }
start_debugging       { "sessionId": "...", "scriptPath": "/abs/path/app.rb" }
```

--------------------------------

### Install nvm and Node.js

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Install Node Version Manager (nvm) and then use it to install and switch to Node.js version 22. This is useful for managing multiple Node.js versions.

```bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node 22
nvm install 22
nvm use 22
```

--------------------------------

### Start the Server

Source: https://github.com/debugmcp/mcp-debugger/blob/main/CLAUDE.md

Starts the main server after building the project. Can be run directly or via Node.

```bash
npm start
```

```bash
node dist/index.js
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/debugmcp/mcp-debugger/blob/main/CONTRIBUTING.md

Install all necessary project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Production Container Configuration Example

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/patterns/dependency-injection.md

An example demonstrating how to create and configure dependencies for a production environment.

```APIDOC
## Real-World Usage: Production Container Configuration

**Location**: `src/container/dependencies.ts`

This function `createProductionDependencies` illustrates how to instantiate and wire up the core dependencies for a production setup.

### Function: `createProductionDependencies`

#### Parameters
- `config` (ContainerConfig) - Optional - Configuration object for the container.

#### Returns
- `Dependencies` - An object containing all configured dependencies.

#### Dependency Instantiation Example:
```typescript
import { FileSystemImpl, ProcessManagerImpl, NetworkManagerImpl, ... } from '../implementations/index.js';
import { createLogger } from '../utils/logger.js';

export function createProductionDependencies(config: ContainerConfig = {}): Dependencies {
  const logger = createLogger('debug-mcp', { level: config.logLevel, ... });
  const environment = new ProcessEnvironment();
  const fileSystem = new FileSystemImpl();
  const processManager = new ProcessManagerImpl();
  const networkManager = new NetworkManagerImpl();

  // Process launchers
  const processLauncher = new ProcessLauncherImpl(processManager);
  const proxyProcessLauncher = new ProxyProcessLauncherImpl(processManager);
  const debugTargetLauncher = new DebugTargetLauncherImpl(processLauncher, networkManager);

  // Factories
  const proxyManagerFactory = new ProxyManagerFactory(proxyProcessLauncher, fileSystem, logger);
  const sessionStoreFactory = new SessionStoreFactory();

  // Adapter registry
  const adapterRegistry = new AdapterRegistry({
    validateOnRegister: false,
    allowOverride: false,
    enableDynamicLoading: true
  });

  return {
    fileSystem, processManager, networkManager, logger, environment,
    processLauncher, proxyProcessLauncher, debugTargetLauncher,
    proxyManagerFactory, sessionStoreFactory, adapterRegistry
  };
}
```
```

--------------------------------

### MCP Settings Configuration Examples

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/windows-launcher-guide.md

Examples of how to configure the 'command' setting in MCP for different launcher scripts, including paths with spaces.

```json
"command": "C:\\path\\to\\mcp-debugger\\simple-run.cmd"
```

```json
"command": "C:\\Program Files\\mcp-debugger\\run-debug-server.cmd"
```

```json
"command": "node \"C:\\workspace\\mcp-debugger\\direct-launch.js\""
```

--------------------------------

### Build Async Example Project

Source: https://github.com/debugmcp/mcp-debugger/blob/main/examples/rust/README.md

Commands to build the async_example Rust project. Debugging follows similar steps to the hello_world example.

```bash
# Build the project
cd examples/rust/async_example
cargo build

# Debug similar to hello_world
```

--------------------------------

### Example Adapter Implementation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/adapter-api-reference.md

A minimal example demonstrating how to implement the `IDebugAdapter` interface, including state management, DAP operations, connection handling, and error reporting.

```APIDOC
## Example Adapter Implementation

### Description
This example shows a basic implementation of the `IDebugAdapter` interface, covering essential methods for a debug adapter.

### Class Definition
```typescript
import { EventEmitter } from 'events';
import type { IDebugAdapter, AdapterState, DebugFeature, AdapterCapabilities } from '@debugmcp/shared';

export class ExampleAdapter extends EventEmitter implements IDebugAdapter {
  readonly language = 'example' as any;
  readonly name = 'Example Debug Adapter';
  private state: AdapterState = AdapterState.UNINITIALIZED;

  async initialize() { this.state = AdapterState.READY; this.emit('initialized'); }
  async dispose() { this.state = AdapterState.UNINITIALIZED; this.emit('disposed'); }
  getState() { return this.state; }
  isReady() { return this.state === AdapterState.READY || this.state === AdapterState.DEBUGGING; }
  getCurrentThreadId() { return null; }

  async validateEnvironment() { return { valid: true, errors: [], warnings: [] }; }
  getRequiredDependencies() { return []; }

  async resolveExecutablePath(preferred?: string) { return preferred ?? 'example'; }
  getDefaultExecutableName() { return 'example'; }
  getExecutableSearchPaths() { return []; }

  buildAdapterCommand(config) { return { command: 'example', args: ['--port', String(config.adapterPort)], env: process.env as any }; }
  getAdapterModuleName() { return 'example.adapter'; }
  getAdapterInstallCommand() { return 'npm install -g example-adapter'; }

  async transformLaunchConfig(cfg) { return cfg; }
  getDefaultLaunchConfig() { return { stopOnEntry: true }; }

  async sendDapRequest(command, args) { throw new Error('not implemented'); }
  handleDapEvent(_e) { /* map events to state; emit as needed */ }
  handleDapResponse(_r) { /* optional */ }

  async connect(_h, _p) { this.state = AdapterState.CONNECTED; this.emit('connected'); }
  async disconnect() { this.state = AdapterState.DISCONNECTED; this.emit('disconnected'); }
  isConnected() { return this.state === AdapterState.CONNECTED || this.state === AdapterState.DEBUGGING; }

  getInstallationInstructions() { return 'Install example-adapter per your OS instructions.'; }
  getMissingExecutableError() { return 'Example executable not found'; }
  translateErrorMessage(err: Error) { return err.message; }

  supportsFeature(_f: DebugFeature) { return false; }
  getFeatureRequirements(_f: DebugFeature) { return []; }
}
```
```

--------------------------------

### Install Adapter Package

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/dynamic-loading-architecture.md

Install the necessary adapter package for your language to resolve MODULE_NOT_FOUND errors. Ensure you rebuild or redeploy after installation.

```bash
npm install @debugmcp/adapter-<language>
```

--------------------------------

### Install and Verify debugpy

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Ensure pip is up-to-date, then install the debugpy Python package. Finally, verify the installation by printing the debugpy version.

```bash
# Ensure pip is up to date
python -m pip install --upgrade pip

# Install debugpy
python -m pip install debugpy

# Verify installation
python -c "import debugpy; print(debugpy.__version__)"
```

--------------------------------

### Example: Quick WIP Commit

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/commit-workflow.md

This example shows how to perform a quick work-in-progress commit, where only the personal information check is executed.

```bash
# Make changes
git add .
npm run commit:fast -- -m "WIP: debugging connection"
# Only personal info check runs
```

--------------------------------

### Install mcp-debugger using NPX

Source: https://github.com/debugmcp/mcp-debugger/blob/main/CLAUDE.md

Use this method for trying out mcp-debugger without a full installation.

```bash
# Best for: Trying out mcp-debugger
/home/ubuntu/.claude/local/claude mcp add-json mcp-debugger \
  '{"type":"stdio","command":"npx","args":["@debugmcp/mcp-debugger","stdio"]}'
```

--------------------------------

### Build and Debug Goroutines Example

Source: https://github.com/debugmcp/mcp-debugger/blob/main/examples/go/README.md

Build the 'goroutines' Go program with debug symbols. Debugging follows a similar process to the 'hello_world' example.

```bash
# Build the project
cd examples/go/goroutines
go build -gcflags="all=-N -l" -o goroutines main.go

# Debug similar to hello_world
```

--------------------------------

### Example: Regular Development Commit

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/commit-workflow.md

This example demonstrates a standard commit process during regular development, ensuring all checks are performed.

```bash
# Make changes
git add .
git commit -m "fix: resolve connection issue"
# All checks run
```

--------------------------------

### Verify Git Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Confirm that Git is installed on your system.

```bash
git --version
```

--------------------------------

### Claude Code CLI Installation Script

Source: https://github.com/debugmcp/mcp-debugger/blob/main/README.md

Clone the repository and run the installation script for Claude Code users. Ensure the Claude CLI is installed and available on your PATH before execution.

```bash
# Clone the repository
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Run the installation script
./scripts/install-claude-mcp.sh

# Verify the connection (use 'claude mcp list' if claude is on your PATH)
claude mcp list
```

--------------------------------

### Install mcp-debugger from Source

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/quickstart.md

Clone the repository, install dependencies, and build the project from source. This is useful for development or when the npm package is not yet available.

```bash
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger
pnpm install
npm run build
```

--------------------------------

### Local Node.js Installation and Execution

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/system-overview.md

Install dependencies and build the project locally, then run the debugger using Node.js. Suitable for development environments.

```bash
pnpm install && npm run build
node dist/index.js stdio                # stdio mode
node dist/index.js http -p 3001         # Streamable HTTP mode (recommended)
node dist/index.js sse -p 3001          # SSE mode (deprecated)
```

--------------------------------

### Install Act CLI

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/ACT_LOCAL_CI_TESTING.md

Installs the Act CLI using a script. Ensure you have curl and sudo privileges.

```bash
# Check installed version
act --version

# Example installation (see Act docs for latest methods)
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
sudo mv ./bin/act /usr/local/bin/
```

--------------------------------

### Start Debugging a Simple Binary

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/rust-debugging.md

Use this JSON configuration to start a debugging session for a standalone binary. Ensure `sessionId` is unique and `scriptPath` points to the compiled executable.

```json
{
  "tool": "start_debugging",
  "arguments": {
    "sessionId": "your-session-id",
    "scriptPath": "target/debug/my_program"
  }
}
```

--------------------------------

### Check Docker Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/tests/e2e/README.md

Verify that Docker is installed and running on your system. These commands are useful for troubleshooting container test failures.

```bash
docker --version
```

```bash
docker ps
```

--------------------------------

### Install Rust Toolchain

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/rust-debugging.md

Installs the Rust toolchain using rustup. This is a prerequisite for Rust development and debugging.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Install Stable GNU Toolchain

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/rust-debugging-windows.md

Installs the pre-built stable GNU toolchain for Rust on Windows for convenience.

```bash
rustup toolchain install stable-gnu
```

--------------------------------

### Verify .NET SDK Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/dotnet/README.md

Check if the .NET SDK version is 6.0 or higher. Ensure the SDK is installed before proceeding.

```bash
dotnet --version    # Should show 6.0+ or 8.0+
```

--------------------------------

### Start debugging with Bundler

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/ruby/README.md

Configuration to start debugging a Ruby script using Bundler. Pass `useBundler: true` in the adapterLaunchConfig to ensure the script is run via `bundle exec`.

```json
start_debugging {
  "sessionId": "...",
  "scriptPath": "/abs/path/bin/rspec",
  "adapterLaunchConfig": { "useBundler": true }
}
```

--------------------------------

### Build and Debug Hello World Example

Source: https://github.com/debugmcp/mcp-debugger/blob/main/examples/go/README.md

Build the 'hello_world' Go program with debug symbols and initiate a debugging session using MCP Debugger.

```bash
# Build the project with debug symbols
cd examples/go/hello_world
go build -gcflags="all=-N -l" -o hello_world main.go

# Create a debug session
mcp-debugger create_debug_session --language go

# Set a breakpoint
mcp-debugger set_breakpoint --file main.go --line 15

# Start debugging
mcp-debugger start_debugging --script ./hello_world
```

--------------------------------

### Capture New Screenshots Guide

Source: https://github.com/debugmcp/mcp-debugger/blob/main/assets/screenshots/README.md

Follow these steps to capture new screenshots for the mcp-debugger. This involves starting the system, connecting a client, executing commands, and capturing/optimizing images.

```bash
python examples/visualizer/demo_runner.py
```

```bash
python examples/visualizer/optimize_screenshots.py
```

--------------------------------

### Start Debugging Parameters

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/api-reference.md

Specifies the parameters for starting a debugging session, including session ID, script path, and optional launch configurations, executable path, arguments, environment variables, and current working directory.

```typescript
{
  sessionId: string;
  script: string;
  launchConfig?: Partial<LaunchConfig>;
  executablePath?: string;
  args?: string[];
  env?: Record<string, string>;
  cwd?: string;
}
```

--------------------------------

### Start Debugging TypeScript File

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/javascript/README.md

This JSON payload is used to initiate a debugging session for a TypeScript file. Ensure that a TypeScript runner like `tsx` or `ts-node` is installed and detectable by the factory.

```json
{
  "tool": "start_debugging",
  "params": {
    "sessionId": "session-id",
    "scriptPath": "app.ts",
    "args": []
  }
}
```

--------------------------------

### Docker BuildKit Plain Progress Example

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/vitest-llm-optimization.md

Use `--progress=plain` to get static, linear output from Docker BuildKit. This is automatically added by the script if no `--progress` flag is supplied.

```powershell
docker build -t myimage .
# Automatically becomes:
docker build --progress=plain -t myimage .
```

--------------------------------

### Build All Adapters

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/javascript-adapter.md

Execute this command to build all available adapters, including mock, Python, and JavaScript. This is useful for contributors who need all components.

```bash
pnpm -w run build:adapters:all
```

--------------------------------

### Example Loader Error: Factory Class Not Found

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/dynamic-loading-architecture.md

This error message indicates that the adapter package is installed, but the expected factory class (e.g., `PythonAdapterFactory`) was not found as a named export. Ensure the factory class is correctly exported.

```text
Failed to load adapter for 'python' from package '@debugmcp/adapter-python'. Error: Factory class PythonAdapterFactory not found in @debugmcp/adapter-python.
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/ACT_LOCAL_CI_TESTING.md

Install project dependencies using npm ci for a clean and reproducible installation.

```bash
npm ci
```

--------------------------------

### Install Python debugpy

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Install the Python debugpy package, which is required for Python debugging. Use pip or pip3 depending on your Python installation.

```bash
pip install debugpy
```

```bash
pip3 install debugpy
```

--------------------------------

### Launch Configuration Example

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/migration-guide.md

Launch configurations remain largely the same and are processed through language adapters. Ensure your configuration includes necessary properties like stopOnEntry, justMyCode, env, and cwd.

```typescript
{
  stopOnEntry: true,
  justMyCode: false,
  env: { "MY_VAR": "value" },
  cwd: "/path/to/project"
}
```

--------------------------------

### Install mcp-debugger CLI

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/migration-guide.md

Use npm to install the mcp-debugger CLI package. This command installs the core debugger and its bundled adapter packages as optional dependencies.

```bash
npm install @debugmcp/mcp-debugger
```

--------------------------------

### Verify pnpm Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Check if pnpm is installed and accessible.

```bash
pnpm --version
```

--------------------------------

### Clone and Navigate Repository

Source: https://github.com/debugmcp/mcp-debugger/blob/main/CONTRIBUTING.md

Clone your forked repository and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/mcp-debugger.git
cd mcp-debugger
```

--------------------------------

### Install debugpy using Python module syntax

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/troubleshooting.md

An alternative method to install debugpy using the 'python -m pip' command, which can sometimes resolve installation issues.

```bash
python -m pip install debugpy
```

--------------------------------

### Normal Development Commit Example

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/git-hooks-guide.md

Demonstrates the typical development flow using fast pre-commit checks for personal information. Tests are deferred until the push stage.

```bash
# Make changes
git add .
git commit -m "WIP: refactoring session manager"  # ✅ Fast commit, only personal info check

# Continue working...
git add .
git commit -m "WIP: add type safety improvements"  # ✅ Another fast commit

# Ready to share
git push origin feature-branch  # 🧪 Tests run here, push only if tests pass
```

--------------------------------

### Build and Debug Hello World Project

Source: https://github.com/debugmcp/mcp-debugger/blob/main/examples/rust/README.md

Commands to build the hello_world Rust project, create a debug session, set a breakpoint, and start debugging.

```bash
# Build the project
cd examples/rust/hello_world
cargo build

# Create a debug session
mcp-debugger create_debug_session --language rust

# Set a breakpoint
mcp-debugger set_breakpoint --file src/main.rs --line 10

# Start debugging
mcp-debugger start_debugging --script target/debug/hello_world
```

--------------------------------

### Install Delve for Go Debugging

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Install the Delve debugger for Go development.

```bash
go install github.com/go-delve/delve/cmd/dlv@latest
```

--------------------------------

### Create Adapter Package Directory

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/adapter-development-guide.md

Use mkdir -p to create the necessary directory structure for a new adapter package.

```bash
mkdir -p packages/adapter-<language>/src
```

--------------------------------

### Verify Node.js Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Check if Node.js is installed and meets the version requirement.

```bash
node --version
```

--------------------------------

### Install mcp-debugger from Source

Source: https://github.com/debugmcp/mcp-debugger/blob/main/CLAUDE.md

Suitable for one-off use directly from a local clone of the repository.

```bash
# Best for: One-off use from a local clone
pnpm install && npm run build
/home/ubuntu/.claude/local/claude mcp add-json mcp-debugger \
  '{"type":"stdio","command":"node","args":["/home/ubuntu/mcp-debugger/dist/index.js","stdio"]}'
```

--------------------------------

### Create Mock Adapter with Configuration

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/mock-adapter-design.md

Example of creating a `MockAdapterFactory` with custom configuration and then creating an adapter instance. Error scenarios are set on the adapter instance at runtime.

```typescript
const factory = new MockAdapterFactory({
  connectionDelay: 100,
  supportedFeatures: [
    DebugFeature.CONDITIONAL_BREAKPOINTS,
    DebugFeature.FUNCTION_BREAKPOINTS
  ]
});

const adapter = factory.createAdapter(dependencies);
// Error scenarios are set on the adapter instance at runtime:
adapter.setErrorScenario(MockErrorScenario.CONNECTION_TIMEOUT);
```

--------------------------------

### Verify debugpy Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/CLAUDE.md

Checks if the debugpy Python package is installed and reports its version.

```bash
python3 -m debugpy --version
```

--------------------------------

### Install CodeLLDB for Rust Adapter

Source: https://github.com/debugmcp/mcp-debugger/blob/main/examples/rust/README.md

Commands to build the Rust adapter and automatically download CodeLLDB. This is a prerequisite for debugging Rust projects.

```bash
cd packages/adapter-rust
npm run build:adapter
```

--------------------------------

### Check Act Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/ACT_LOCAL_CI_TESTING.md

Verify that the Act CLI is installed and accessible by checking its version.

```bash
act --version
```

--------------------------------

### Vitest Setup File for Test Environment

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/testing-architecture.md

Initializes the test environment by setting up global listeners, environment variables, and utility functions before each test file runs.

```typescript
import { afterAll, afterEach, beforeAll, vi } from "vitest";
import { portManager } from "./test-utils/helpers/port-manager";

// Install listeners for unhandled rejections and uncaught exceptions
process.on("unhandledRejection", (reason) => {
  console.error("Unhandled Rejection:", reason);
});
process.on("uncaughtException", (error) => {
  console.error("Uncaught Exception:", error);
});

// Ensure console output is visible for unit tests
delete process.env.CONSOLE_OUTPUT_SILENCED;

// Compute __dirname for ESM context with Windows path normalization
const __dirname = new URL(".", import.meta.url).pathname.replace(/\\/g, "/");

// Make portManager globally available
globalThis.testPortManager = portManager;

// Reset port manager allocations before all tests
beforeAll(() => {
  globalThis.testPortManager.reset();
});

// Reset mocks and restore spies after each test
afterEach(() => {
  vi.resetAllMocks();
  vi.restoreAllMocks();
});

// Reset port manager after all tests
afterAll(() => {
  globalThis.testPortManager.reset();
});

```

--------------------------------

### Check pip Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/troubleshooting.md

Verify that pip is installed and accessible in your system's PATH.

```bash
pip --version
```

--------------------------------

### Install mcp-debugger via npm

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/releases/RELEASE_NOTES_v0.12.0.md

Command to install the mcp-debugger globally using npm.

```bash
npm install -g @debugmcp/mcp-debugger@0.12.0
```

--------------------------------

### Run Go Adapter Tests

Source: https://github.com/debugmcp/mcp-debugger/blob/main/examples/go/README.md

Execute tests for the Go adapter from the project root or run only integration tests.

```bash
# From the project root
pnpm test tests/adapters/go

# Run only integration tests
pnpm test tests/adapters/go/integration
```

--------------------------------

### Check Python and Debugpy Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/getting-started.md

Verify that Python is installed and that the debugpy library is available.

```bash
python --version
pip list | grep debugpy
```

--------------------------------

### Install pnpm Globally

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Install pnpm, a required package manager for the project, using npm.

```bash
npm install -g pnpm
```

--------------------------------

### Build Project Packages

Source: https://github.com/debugmcp/mcp-debugger/blob/main/CLAUDE.md

Builds all packages and the main project. Use `npm run <script>` which delegates to pnpm.

```bash
npm run build
```

```bash
npm run build:shared
```

```bash
npm run build:adapters
```

```bash
npm run build:adapters:all
```

```bash
npm run build:packages
```

--------------------------------

### Build the Project

Source: https://github.com/debugmcp/mcp-debugger/blob/main/CONTRIBUTING.md

Build the entire project using the npm build script.

```bash
npm run build
```

--------------------------------

### Install mcp-debugger server launcher via pip

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/releases/RELEASE_NOTES_v0.12.0.md

Command to install the debug-mcp-server-launcher using pip.

```bash
pip install debug-mcp-server-launcher==0.12.0
```

--------------------------------

### Unit Test Example

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

An example of a unit test written in TypeScript using a describe-it structure.

```typescript
// Unit test example
describe('MyComponent', () => {
  it('should handle specific case', () => {
    // Arrange
    const component = new MyComponent(mockDependencies);
    
    // Act
    const result = component.doSomething();
    
    // Assert
    expect(result).toBe(expectedValue);
  });
});
```

--------------------------------

### Install Monorepo Dependencies

Source: https://github.com/debugmcp/mcp-debugger/blob/main/AGENTS.md

Use this command to set up all necessary dependencies for the monorepo. Always respect the generated pnpm-lock.yaml file.

```bash
pnpm install
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Examples of commit messages following the conventional commit format.

```text
feat(session): add timeout configuration
fix(proxy): handle connection errors properly
docs(api): update endpoint documentation
test(integration): add Python 3.11 tests
```

--------------------------------

### Go Program Example for Debugging

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/go/README.md

A simple Go program to demonstrate debugging. Ensure it's built with debug flags for effective debugging.

```go
package main

import "fmt"

func main() {
    x := 10
    y := 20
    sum := add(x, y)
    fmt.Printf("Sum: %d\n", sum)
}

func add(a, b int) int {
    return a + b
}
```

--------------------------------

### Track Start Calls on MockProxyManager

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/testing-architecture.md

Records all invocations to the `start` method on `MockProxyManager` for structural assertions.

```typescript
MockProxyManager.startCalls[]
```

--------------------------------

### Adapter Host Configuration Example

Source: https://github.com/debugmcp/mcp-debugger/blob/main/packages/adapter-javascript/docs/LESSONS_LEARNED.md

Illustrates the preferred 'localhost' for adapter spawn commands and '127.0.0.1' for session-manager operations. This setting is crucial for establishing debugging connections.

```typescript
// For adapter spawn commands (buildAdapterCommand), prefer 'localhost'
// For session-manager adapterHost and child-session attach, '127.0.0.1' is used
adapterHost: '127.0.0.1'  // Used in session-manager-operations.ts
```

--------------------------------

### Run Unit Tests

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/architecture/javascript-adapter.md

Execute this command to run all unit tests. This includes verifying language discovery and ensuring the adapter loader correctly identifies installed adapters.

```bash
pnpm run test:unit
```

--------------------------------

### Verify Python Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/setup-guide.md

Check if Python is installed and meets the version requirement for testing Python debugging.

```bash
python --version
```

--------------------------------

### Check Act Installation with NPM

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/ACT_LOCAL_CI_TESTING.md

Verifies if the Act CLI is installed and accessible via NPM scripts.

```bash
# Check Act is installed
npm run act:check
```

--------------------------------

### Build from Source

Source: https://github.com/debugmcp/mcp-debugger/blob/main/packages/adapter-javascript/docs/README.md

Builds the js-debug adapter from source, which is slower but may be necessary if prebuilt artifacts are unavailable. Requires git and a package manager.

```bash
JS_DEBUG_BUILD_FROM_SOURCE=true pnpm -w -F @debugmcp/adapter-javascript run build:adapter
```

--------------------------------

### Kubernetes Remote Attach Build, Setup, and Port Forward

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/ruby/README.md

Builds a Docker image, creates a Kind cluster, loads the image, applies a Kubernetes manifest, and forwards the debugger port.

```bash
docker build -t ruby-remote-attach:demo examples/ruby/remote-attach
kind create cluster --name ruby-debug-demo
kind load docker-image ruby-remote-attach:demo --name ruby-debug-demo
kubectl apply -f examples/ruby/remote-attach/pod.yaml
kubectl port-forward pod/ruby-remote-attach 12399:12345
```

--------------------------------

### Install mcp-debugger via npm

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/quickstart.md

Install the mcp-debugger globally using npm. This is the recommended method when the package is published.

```bash
npm install -g @debugmcp/mcp-debugger
```

--------------------------------

### Mocking Dependencies with Vitest

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/testing-guide.md

Illustrates how to mock external dependencies using helper functions, typically defined in test utilities. Shows how to create mock instances and verify their method calls.

```typescript
// Using test utilities
import { createMockLogger, createMockFileSystem } from '../../test-utils/helpers/test-dependencies.js';

const mockLogger = createMockLogger();
const mockFileSystem = createMockFileSystem();

// Verify mock calls
expect(mockLogger.info).toHaveBeenCalledWith(
  '[Component] Operation completed',
  { sessionId: 'test-123' }
);
```

--------------------------------

### Run Development Server

Source: https://github.com/debugmcp/mcp-debugger/blob/main/AGENTS.md

Launches the TypeScript entry point using ts-node for rapid development feedback. Useful for quick iteration during development.

```bash
pnpm dev
```

--------------------------------

### Verify Java Installation

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/java/README.md

Check if Java Development Kit (JDK) and Java Compiler (javac) are installed and accessible.

```bash
java -version    # Should show JDK 21+
javac -version   # Should show matching version
```

--------------------------------

### File Logging for Server Startup Diagnostics

Source: https://github.com/debugmcp/mcp-debugger/blob/main/docs/development/debugging-guide.md

Use `fs.appendFileSync` to write diagnostic information to a file during server startup, as `console` methods are silenced.

```typescript
// In src/index.ts — use the logger, not console (console is silenced)
import fs from 'fs';
// Write diagnostics to a file since console output is suppressed
fs.appendFileSync('/tmp/mcp-debug-startup.log',
  `[DEBUG] Starting server with args: ${process.argv.join(' ')}\n`);

// Transport startup is managed in src/cli/stdio-command.ts or src/cli/sse-command.ts,
// not in DebugMcpServer.start() (which only logs startup/build info).
// To debug transport binding, add logger calls to the CLI command handlers.
```