# Debug MCP
MCP server for debugging distributed systems (AWS CloudWatch Logs, Step Functions, LangSmith, Jira) directly from Claude Code or any MCP client.
**Status**: ✅ Complete - Single gateway tool exposing 17 debugging tools
**Context Reduction**: ~95% token savings (13K → ~500 tokens)
**Repository**: https://github.com/Coykto/debug_mcp
## Quick Start
### Installation
**Option 1: Using Claude Code CLI (Recommended)**
AWS only:
```bash
claude mcp add --scope user --transport stdio debug-mcp \
-- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
--aws-region us-west-2 \
--aws-profile your-aws-profile-name
```
AWS + Jira:
```bash
claude mcp add --scope user --transport stdio debug-mcp \
-- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
--aws-region us-west-2 \
--aws-profile your-aws-profile-name \
--jira-host yourcompany.atlassian.net \
--jira-email your.email@company.com \
--jira-project PROJ \
--jira-token your-api-token
```
**Option 2: Manual configuration in `.mcp.json`**
AWS only:
```json
{
"mcpServers": {
"debug-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"--from", "git+https://github.com/Coykto/debug_mcp",
"debug-mcp",
"--aws-region", "us-west-2",
"--aws-profile", "your-aws-profile-name"
]
}
}
}
```
AWS + Jira:
```json
{
"mcpServers": {
"debug-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"--from", "git+https://github.com/Coykto/debug_mcp",
"debug-mcp",
"--aws-region", "us-west-2",
"--aws-profile", "your-aws-profile-name",
"--jira-host", "yourcompany.atlassian.net",
"--jira-email", "your.email@company.com",
"--jira-project", "PROJ",
"--jira-token", "your-api-token"
]
}
}
}
```
**Note**: Configuration is passed as CLI arguments to work around a [known bug in Claude Code](https://github.com/anthropics/claude-code/issues/1254) where environment variables aren't reliably passed to MCP servers.
**Prerequisites:**
- Python 3.11+
- `uvx` installed ([installation guide](https://docs.astral.sh/uv/))
- AWS credentials configured (`aws configure`)
- For Jira: API token from [Atlassian](https://id.atlassian.com/manage-profile/security/api-tokens) (see [Jira Configuration](#jira-configuration))
## How to Use
Debug MCP exposes a **single gateway tool** called `debug()` that provides discovery and execution of 17 debugging tools:
### Discovery Pattern
Ask Claude to discover available tools:
```
"What debugging tools are available?"
→ Claude calls: debug(tool="list")
"What CloudWatch tools are available?"
→ Claude calls: debug(tool="list:cloudwatch")
"List all Step Functions tools"
→ Claude calls: debug(tool="list:stepfunctions")
```
### Execution Pattern
Ask Claude natural language questions and it will use the appropriate tool:
**CloudWatch Logs:**
- "List all Lambda log groups"
- "Search for ERROR in /aws/lambda/my-function from the last hour"
- "Analyze /aws/lambda/my-function logs for patterns"
- "Run a CloudWatch Insights query on my Lambda logs"
**Step Functions Debugging:**
- "List all my Step Functions state machines"
- "Show me the workflow definition and Lambda functions for state machine X"
- "Show me failed executions for state machine X from the last 3 days"
- "Get execution details including the workflow definition"
- "Find executions where the Match state output contains 'company' and show me the Lambda ARNs"
**LangSmith Tracing:**
- "List my LangSmith projects in prod environment"
- "Show me errored runs from the last hour in production"
- "Get details for LangSmith run abc-123 in dev"
- "Search for conversations containing a specific error message"
**Jira Tickets:**
- "Search for bugs in To Do status"
- "Find tickets assigned to me"
- "Get details for ticket PROJ-123"
- "Show me all in-progress stories about authentication"
Claude automatically translates your questions into the appropriate `debug()` call with the right tool name and arguments.
## How It Works
This MCP server uses a **Tool Discovery Gateway** pattern:
1. **Single Tool Interface**: Exposes one `debug()` tool to Claude instead of 17 individual tools
2. **~95% Token Reduction**: Reduces context from ~13K tokens to ~500 tokens (tool list only)
3. **Category-based Discovery**: Tools organized by category (cloudwatch, stepfunctions, langsmith, jira)
4. **Direct Implementation**: Uses boto3 and SDKs directly (no AWS MCP proxies)
### Gateway Architecture
```
debug(tool="list") → List categories
debug(tool="list:cloudwatch") → List CloudWatch tools
debug(tool="describe_log_groups", ...) → Execute tool
```
All 17 debugging tools remain available - they're just accessed through the gateway instead of being exposed individually.
## Available Tools (via Gateway)
### CloudWatch Logs (4 tools)
- `describe_log_groups` - List CloudWatch log groups
- `analyze_log_group` - Analyze logs for anomalies and patterns
- `execute_log_insights_query` - Run CloudWatch Insights queries
- `get_logs_insight_query_results` - Get query results
### Step Functions (5 tools)
**Debugging:**
- `list_state_machines` - List all state machines (get ARNs)
- `get_state_machine_definition` - Get ASL definition with extracted Lambda ARNs and resources
- `list_step_function_executions` - List executions with filtering
- `get_step_function_execution_details` - Get full execution details with state inputs/outputs
- `search_step_function_executions` - Advanced search with state/input/output pattern matching
**Definition & Resources:**
The `get_state_machine_definition` tool extracts:
- Full Amazon States Language (ASL) workflow definition
- Lambda function ARNs used in the workflow
- Other resources (SNS topics, SQS queues, DynamoDB tables, nested state machines)
- IAM role, logging, and tracing configuration
You can also include the definition with execution details using `include_definition=True` in:
- `get_step_function_execution_details` - See the workflow definition alongside execution data
- `search_step_function_executions` - See definitions with filtered execution results
### LangSmith (6 tools)
**Tracing & Debugging:**
- `list_langsmith_projects` - List available LangSmith projects
- `list_langsmith_runs` - List runs/traces with filtering (type, errors, time range)
- `get_langsmith_run_details` - Get full run details with inputs/outputs and child runs (stores in memory)
- `search_langsmith_runs` - Search for conversations containing specific text
- `search_run_content` - Semantic search within a stored run's content
- `get_run_field` - Get a specific field from a stored run
**Multi-Environment Support:**
Each LangSmith tool requires an `environment` parameter:
- `prod` - Uses `PRODUCTION/env/vars` from AWS Secrets Manager
- `dev` - Uses `DEV/env/vars` from AWS Secrets Manager
- `local` - Loads from `.env` file using python-dotenv
**Credentials in Secrets Manager:**
Your AWS Secrets Manager secret should contain:
- `LANGCHAIN_API_KEY` - Your LangSmith API key
- `LANGCHAIN_PROJECT` - Default project name (optional)
**Local Development (.env file):**
```env
LANGCHAIN_API_KEY=ls_your_api_key_here
LANGCHAIN_PROJECT=your-project-name
```
> **Note**: LangSmith integration currently requires AWS Secrets Manager for `prod`/`dev` environments (this is how our team stores credentials). If you'd like to use LangSmith with direct CLI token arguments (similar to Jira), PRs are welcome!
### Jira (2 tools)
- `search_jira_tickets` - Search tickets with filters (type, status, assignee) and text search
- `get_jira_ticket` - Get full ticket details including linked issues, attachments, subtasks, and Epic children
**Returned fields for `get_jira_ticket`:**
- Basic: key, summary, description, status, issue_type, priority, assignee, reporter, labels, created, updated
- Relationships: linked_issues, parent (for subtasks), subtasks, epic_children (for Epics)
- Attachments: list of filenames
## Configuration
### AWS Authentication
Pass AWS credentials as CLI arguments (recommended to work around [Claude Code env var bug](https://github.com/anthropics/claude-code/issues/1254)):
```bash
# Using Claude Code CLI
claude mcp add --scope user --transport stdio debug-mcp \
-- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
--aws-region us-west-2 \
--aws-profile your-profile-name
```
Or in `.mcp.json`:
```json
"args": [
"--from", "git+https://github.com/Coykto/debug_mcp",
"debug-mcp",
"--aws-region", "us-west-2",
"--aws-profile", "your-profile-name"
]
```
**Alternative**: Set environment variables before launching Claude Code:
```bash
export AWS_REGION=us-west-2
export AWS_PROFILE=your-profile-name
# Then launch Claude Code
```
### Jira Configuration
Jira integration allows you to search tickets and get full ticket details directly from Claude Code.
#### Step 1: Create a Jira API Token
1. Go to [Atlassian API Token Management](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Give it a descriptive label (e.g., "Debug MCP")
4. Copy the generated token (you won't see it again)
#### Step 2: Gather Your Jira Details
You'll need:
- **Host**: Your Jira Cloud hostname (e.g., `yourcompany.atlassian.net`)
- **Email**: The email address associated with your Atlassian account
- **Project**: The project key for your default project (e.g., `PROJ`, `DEV`, `CORE`)
- **Token**: The API token from Step 1
#### Step 3: Configure Debug MCP
**Option A: Claude Code CLI (Recommended)**
```bash
claude mcp add --scope user --transport stdio debug-mcp \
-- uvx --from git+https://github.com/Coykto/debug_mcp debug-mcp \
--aws-region us-west-2 \
--aws-profile your-profile-name \
--jira-host yourcompany.atlassian.net \
--jira-email your.email@company.com \
--jira-project PROJ \
--jira-token your-api-token
```
**Option B: Manual `.mcp.json` Configuration**
```json
{
"mcpServers": {
"debug-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"--from", "git+https://github.com/Coykto/debug_mcp",
"debug-mcp",
"--aws-region", "us-west-2",
"--aws-profile", "your-profile-name",
"--jira-host", "yourcompany.atlassian.net",
"--jira-email", "your.email@company.com",
"--jira-project", "PROJ",
"--jira-token", "your-api-token"
]
}
}
}
```
**Option C: Use Environment Variable for Token**
If you prefer not to store the token in your config, set `JIRA_API_TOKEN` as an environment variable before launching Claude Code:
```bash
export JIRA_API_TOKEN=your-api-token
```
Then omit `--jira-token` from the CLI args (other Jira args are still required).
#### Configuration Reference
| Source | Name | Required | Description |
|--------|------|----------|-------------|
| CLI arg | `--jira-host` | Yes | Jira Cloud hostname (e.g., `company.atlassian.net`) |
| CLI arg | `--jira-email` | Yes | Atlassian account email |
| CLI arg | `--jira-project` | Yes | Default Jira project key (e.g., `PROJ`) |
| CLI arg | `--jira-token` | Yes* | Jira API token |
| Env var | `JIRA_API_TOKEN` | Yes* | Alternative to `--jira-token` CLI arg |
*Either `--jira-token` or `JIRA_API_TOKEN` is required.
#### Jira Troubleshooting
**"Jira credentials not configured" error:**
- Verify all required args are provided: `--jira-host`, `--jira-email`, `--jira-project`, and token
- Check that your API token is valid at [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
**"401 Unauthorized" error:**
- Your API token may have expired - create a new one
- Verify the email matches your Atlassian account exactly
**"Project not found" error:**
- Check the project key (not name) - it's the prefix in ticket IDs (e.g., `PROJ` in `PROJ-123`)
- Ensure your account has access to the project
## Troubleshooting
### Server won't start
- Check AWS credentials: `aws sts get-caller-identity --profile YOUR_PROFILE`
- Verify uvx is installed: `uvx --version`
- Check Claude Code MCP logs in settings
### Wrong AWS region/account
- Update `--aws-region` and `--aws-profile` CLI arguments
- Make sure the profile exists in `~/.aws/credentials`
- Verify the region is correct: `aws configure get region --profile YOUR_PROFILE`
### Environment variables not working
Due to a [known bug in Claude Code](https://github.com/anthropics/claude-code/issues/1254), environment variables in the MCP `env` block aren't reliably passed to servers. **Use CLI arguments instead** (see installation examples above).
## Development
### Local Development
```bash
# Install dependencies
uv sync
# Run the server locally
uv run debug-mcp --aws-region us-west-2 --aws-profile your-profile
# Test
uv run pytest
```
### Architecture
The server uses a **Tool Discovery Gateway** pattern with direct boto3/SDK implementations:
**Gateway Layer** (`src/debug_mcp/server.py`):
- Single `debug()` tool exposed to Claude
- Handles discovery (`tool="list"`, `tool="list:cloudwatch"`)
- Routes execution to registered tools
- Validates arguments with Pydantic models
**Registry System** (`src/debug_mcp/registry.py`):
- Central registry for all tools with schemas
- Category-based organization
- `@debug_tool()` decorator for registration
- Validation and execution routing
**Tool Implementations**:
- **CloudWatch** (`cloudwatch_logs.py` + `cloudwatch_registry.py`): boto3 CloudWatch Logs client
- **Step Functions** (`stepfunctions.py` + `stepfunctions_registry.py`): boto3 Step Functions client
- **LangSmith** (`langsmith.py` + `langsmith_registry.py`): LangSmith SDK with multi-environment support
- **Jira** (`jira.py` + `jira_registry.py`): Jira SDK with lazy client initialization
Each `*_registry.py` file registers tools using the `@debug_tool()` decorator with schemas and handlers.
## Team Sharing
Share with your team:
1. They update `--aws-profile` with their own profile name
2. Optionally adjust `--aws-region` if different
3. All 17 debugging tools are available through the single `debug()` gateway - no tool filtering needed
## Contributing
Contributions are welcome! Some areas where PRs would be appreciated:
- **LangSmith CLI token support**: Currently LangSmith credentials are loaded from AWS Secrets Manager (for `prod`/`dev`) or `.env` files (for `local`). Adding `--langsmith-api-key` CLI argument support (similar to Jira) would make setup easier for teams not using Secrets Manager.
- **Additional debugging tools**: New tools for other AWS services (ECS, Lambda logs, X-Ray traces)
- **Bug fixes and improvements**: Error handling, documentation, tests
To contribute:
1. Fork the repository
2. Create a feature branch
3. Make your changes (see [Adding New Tools](CLAUDE.md#adding-new-tools) in CLAUDE.md)
4. Submit a PR
## License
MIT License - See LICENSE file
