debug_mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Debug MCP is an open-source MCP (Model Context Protocol) server for debugging distributed systems (starting with AWS: Lambda, Step Functions, ECS) directly from Claude Code or any MCP client. The project aims to eliminate context switching between console interfaces by bringing debugging capabilities into AI coding assistants.

Current Status: Direct Tool Registration - Tools are exposed directly to MCP clients (no gateway). Only tools for configured services are registered, allowing selective tool exposure based on provided credentials.

Development Commands

Environment Setup

# Install dependencies
uv sync

# Install with dev dependencies
uv sync --dev

# Run the MCP server locally
uv run debug-mcp

# Run in development mode from project root
uv run python -m debug_mcp

Testing

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=src/debug_mcp

# Run specific test file
uv run pytest tests/test_cloudwatch_logs.py

Code Quality

Pre-commit handles linting and formatting automatically. Setup:

uv sync --dev
uv run pre-commit install

Manual Testing

# Test AWS client factory in Python REPL
uv run python
>>> from debug_mcp.aws.client_factory import AWSClientFactory
>>> from debug_mcp.tools.cloudwatch_logs import CloudWatchLogsTools
>>> factory = AWSClientFactory()
>>> tools = CloudWatchLogsTools(factory)
>>> tools.describe_log_groups(prefix="/aws/lambda/")

Architecture

Project Structure

The project uses direct tool registration with conditional loading based on credentials:

src/debug_mcp/
├── server.py              # Main MCP server, conditional tool registration
├── __main__.py            # Entry point, CLI argument parsing
└── tools/
    ├── cloudwatch_logs.py         # CloudWatch implementation (boto3)
    ├── cloudwatch_registry.py     # CloudWatch tool registration
    ├── stepfunctions.py           # Step Functions implementation (boto3)
    ├── stepfunctions_registry.py  # Step Functions tool registration
    ├── langsmith.py               # LangSmith implementation (SDK)
    ├── langsmith_registry.py      # LangSmith tool registration
    ├── jira.py                    # Jira implementation (SDK)
    └── jira_registry.py           # Jira tool registration