# Honeybadger MCP Server

A Model Context Protocol (MCP) server implementation for interacting with the Honeybadger API. This server allows AI agents to fetch and analyze error data from your Honeybadger projects.

## Overview

This MCP server provides a bridge between AI agents and the Honeybadger error monitoring service. It follows the best practices laid out by Anthropic for building MCP servers, allowing seamless integration with any MCP-compatible client.

## Features

The server provides two essential tools for interacting with Honeybadger:

1. **`list_faults`**: List and filter faults from your Honeybadger project

   - Search by text query
   - Filter by creation or occurrence timestamps
   - Sort by frequency or recency
   - Paginate results

2. **`get_fault_details`**: Get detailed information about specific faults
   - Filter notices by creation time
   - Paginate through notices
   - Results ordered by creation time descending

## Prerequisites

- Python 3.10+
- Honeybadger API key and Project ID
- Docker if running the MCP server as a container (recommended)

## Installation

### Using uv

1. Install uv if you don't have it:

   ```bash
   pip install uv
   ```

2. Clone this repository:

   ```bash
   git clone https://github.com/bobtista/honeybadger-mcp.git
   cd honeybadger-mcp
   ```

3. Install dependencies:

   ```bash
   uv pip install -e .
   ```

4. Install development dependencies (optional):

   ```bash
   uv pip install -e ".[dev]"
   ```

5. Create your environment file:

   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

### Using Docker (Recommended)

1. Build the Docker image:

   ```bash
   docker build -t honeybadger/mcp --build-arg PORT=8050 .
   ```

2. Create a `.env` file and configure your environment variables

## Configuration

You can configure the server using either environment variables or command-line arguments:

| Option     | Env Variable           | CLI Argument | Default   | Description                                |
| ---------- | ---------------------- | ------------ | --------- | ------------------------------------------ |
| API Key    | HONEYBADGER_API_KEY    | --api-key    | Required  | Your Honeybadger API key                   |
| Project ID | HONEYBADGER_PROJECT_ID | --project-id | Required  | Your Honeybadger project ID                |
| Transport  | TRANSPORT              | --transport  | sse       | Transport protocol (sse or stdio)          |
| Host       | HOST                   | --host       | 127.0.0.1 | Host to bind to when using SSE transport   |
| Port       | PORT                   | --port       | 8050      | Port to listen on when using SSE transport |
| Log Level  | LOG_LEVEL              | --log-level  | INFO      | Logging level (INFO, DEBUG, etc.)          |

## Running the Server

### Running with uv (Development)

#### SSE Transport (Default)

```bash
# Using environment variables:
HONEYBADGER_API_KEY=your-key HONEYBADGER_PROJECT_ID=your-project uv run src/honeybadger_mcp_server/server.py

# Using CLI arguments:
uv run src/honeybadger_mcp_server/server.py --api-key your-key --project-id your-project
```

#### Using Stdio

```bash
uv run src/honeybadger_mcp_server/server.py --transport stdio --api-key your-key --project-id your-project
```

### Running Installed Package

#### SSE Transport (Default)

```bash
# Using environment variables:
HONEYBADGER_API_KEY=your-key HONEYBADGER_PROJECT_ID=your-project honeybadger-mcp-server

# Using CLI arguments:
honeybadger-mcp-server --api-key your-key --project-id your-project
```

#### Using Stdio

```bash
honeybadger-mcp-server --transport stdio --api-key your-key --project-id your-project
```

### Using Docker

#### Run with SSE

```bash
docker run --env-file .env -p 8050:8050 honeybadger/mcp
```

#### Using Stdio

With stdio, the MCP client itself can spin up the MCP server container, so nothing to run at this point.

## Integration with MCP Clients

### SSE Configuration

Once you have the server running with SSE transport, you can connect to it using this configuration:

```json
{
  "mcpServers": {
    "honeybadger": {
      "transport": "sse",
      "url": "http://localhost:8050/sse"
    }
  }
}
```

### Claude Desktop Configuration

#### Using SSE Transport (Recommended)

First, start the server:

```bash
honeybadger-mcp-server --api-key your-key --project-id your-project
```

Then add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "honeybadger": {
      "transport": "sse",
      "url": "http://localhost:8050/sse"
    }
  }
}
```

#### Using Stdio Transport

Add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "honeybadger": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/honeybadger-mcp",
        "src/honeybadger_mcp_server/server.py",
        "--transport",
        "stdio",
        "--api-key",
        "YOUR-API-KEY",
        "--project-id",
        "YOUR-PROJECT-ID"
      ]
    }
  }
}
```

### Docker Configuration

```json
{
  "mcpServers": {
    "honeybadger": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "honeybadger/mcp",
        "--transport",
        "stdio",
        "--api-key",
        "YOUR-API-KEY",
        "--project-id",
        "YOUR-PROJECT-ID"
      ]
    }
  }
}
```

## Tool Usage Examples

### List Faults

```python
result = await client.call_tool("list_faults", {
    "q": "RuntimeError",           # Optional search term
    "created_after": 1710806400,  # Unix timestamp (2024-03-19T00:00:00Z)
    "occurred_after": 1710806400, # Filter by occurrence time
    "limit": 10,                  # Max 25 results
    "order": "recent"             # 'recent' or 'frequent'
})
```

### Get Fault Details

```python
result = await client.call_tool("get_fault_details", {
    "fault_id": "abc123",
    "created_after": 1710806400,  # Unix timestamp
    "created_before": 1710892800, # Optional end time
    "limit": 5                    # Number of notices (max 25)
})
```

## Development

### Running Tests

```bash
# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest
```

### Code Quality

```bash
# Run type checker
pyright

# Run linter
ruff check .
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.