# API Debugger MCP 🚀

A production-oriented Model Context Protocol (MCP) server for inspecting, testing, validating, comparing, and debugging HTTP APIs with FastMCP.

## Why this project?

API failures often require jumping between API clients, OpenAPI documentation, logs, test suites, and bug trackers. API Debugger MCP gives an MCP-compatible AI agent a structured toolkit for performing those investigations.

## Features

- 12 MCP tools for API debugging and QA
- Safe secret redaction for common credential fields and headers
- Configurable timeout and response-size limits
- Private/local network blocking by default
- JSON-schema-style response contract validation
- Regression comparison between response bodies
- Multi-endpoint health checks
- Automated API test scenario generation
- Structured bug-report generation
- End-to-end incident investigation workflow
- MCP resource and reusable prompt
- Docker support
- Pytest + coverage
- Ruff linting
- GitHub Actions CI across Python 3.10–3.12

## MCP tools

1. `inspect_endpoint`
2. `send_request`
3. `validate_response`
4. `compare_responses`
5. `analyze_error`
6. `detect_api_issue`
7. `generate_api_tests`
8. `generate_bug_report`
9. `check_contract`
10. `api_health_check`
11. `redact_sensitive_data`
12. `investigate_incident`

## Project structure

```text
api-debugger-mcp/
├── .github/workflows/ci.yml
├── docs/
├── src/api_debugger_mcp/
│   ├── analysis.py
│   ├── client.py
│   ├── config.py
│   ├── models.py
│   ├── security.py
│   ├── server.py
│   └── tools.py
├── tests/
├── .dockerignore
├── .env.example
├── .gitignore
├── Dockerfile
├── LICENSE
├── Makefile
├── docker-compose.yml
└── pyproject.toml
```

## Quick start

### 1. Create a virtual environment

```bash
python -m venv .venv
```

Windows:

```powershell
.venv\Scripts\activate
```

macOS/Linux:

```bash
source .venv/bin/activate
```

### 2. Install

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

### 3. Configure

Copy `.env.example` to `.env` and set only the values required for your environment.

Never commit real API keys or bearer tokens.

### 4. Run locally

For an HTTP MCP server:

```bash
api-debugger-mcp
```

The default MCP endpoint is:

```text
http://localhost:8000/mcp
```

For local stdio mode:

```text
MCP_TRANSPORT=stdio
```

then run:

```bash
api-debugger-mcp
```

## Docker

```bash
docker compose up --build
```

The server is exposed on port `8000`.

## Testing

```bash
pytest
```

Lint:

```bash
ruff check .
```

Format:

```bash
ruff format .
```

## Example MCP workflow

An MCP-compatible agent can combine the tools like this:

```text
investigate_incident
    ↓
inspect_endpoint
    ↓
send_request
    ↓
detect_api_issue
    ↓
analyze_error
    ↓
check_contract
    ↓
generate_bug_report
```

For regression testing:

```text
send_request (baseline)
        ↓
send_request (current)
        ↓
compare_responses
        ↓
validate_response
```

## Security notes

This server is designed to avoid accidental credential leakage and unsafe network access by default.

- Common auth/cookie/API-key headers are redacted from returned results.
- Common secret fields are redacted recursively.
- Requests to local/private IP targets are disabled by default.
- Do not commit `.env` with real credentials.
- In production, place the MCP server behind your organization's authentication and network controls.
- Add an explicit allowlist before enabling private-network requests in sensitive environments.

## Production roadmap

- OpenAPI 3.x import and endpoint discovery
- OAuth/API-key secret providers
- Persistent regression baselines
- Sentry/observability integration
- Jira/GitHub issue creation
- Request correlation IDs
- Rate limiting
- Audit logging
- RBAC/authentication
- Async parallel health checks
- MCP task/background execution for long-running investigations

## License

MIT