Submit
jeremylongshore

Conversational API Debugger

Community jeremylongshore
Updated

Hundreds of Claude Code plugins with embedded AI skills. Learn via interactive Jupyter tutorials.

Conversational API Debugger

Debug REST API failures using OpenAPI specs and HTTP logs

An MCP server that helps developers quickly identify and fix API issues by analyzing OpenAPI specifications, ingesting HTTP logs, explaining failures, and generating reproducible test commands.

What It Does

This plugin transforms API debugging from guesswork into systematic analysis:

  1. Load OpenAPI Specs - Parse API documentation (JSON/YAML)
  2. Ingest HTTP Logs - Import request/response data (HAR, JSON)
  3. Explain Failures - Analyze why API calls failed with root cause analysis
  4. Generate Repros - Create cURL/HTTPie/fetch commands to reproduce issues

Installation

/plugin install conversational-api-debugger@claude-code-plugins-plus

Features

4 Powerful MCP Tools

1. load_openapi

Load and parse OpenAPI 3.x specifications.

{
  "filePath": "/path/to/openapi.yaml",
  "name": "my-api"
}

Returns:

  • API title, version, description
  • Base URL and servers
  • Complete endpoint list
  • Endpoint count and structure
2. ingest_logs

Import HTTP request/response logs for analysis.

{
  "filePath": "/path/to/requests.har",
  "format": "har"
}

Or provide logs directly:

{
  "logs": [
    {
      "timestamp": "2025-10-10T12:00:00Z",
      "method": "POST",
      "url": "https://api.example.com/users",
      "statusCode": 400,
      "requestBody": { "name": "John" },
      "responseBody": { "error": "Missing required field: email" }
    }
  ]
}

Returns:

  • Total requests ingested
  • Success/failure breakdown
  • Status code distribution
  • Method distribution
  • Top errors (first 10)
3. explain_failure

Analyze why an API call failed.

{
  "logIndex": 0,
  "specName": "my-api"
}

Returns:

  • Severity: critical | high | medium | low
  • Possible Causes: List of likely root causes
  • Suggested Fixes: Actionable remediation steps
  • Matching Endpoint: Comparison with OpenAPI spec
  • Details: Request/response for inspection
4. make_repro

Generate cURL command to reproduce API call.

{
  "logIndex": 0,
  "includeHeaders": true,
  "pretty": true
}

Returns:

  • cURL Command: Ready to copy-paste
  • HTTPie Alternative: Shorter syntax
  • JavaScript fetch: For automated tests
  • Metadata: Method, URL, headers count

Quick Start

Scenario 1: Debugging a 400 Bad Request

# 1. Load your OpenAPI spec
Use load_openapi with path to your spec file

# 2. Export HAR from browser DevTools
# Network tab → Right-click → Save as HAR with content

# 3. Ingest the logs
Use ingest_logs with HAR file path

# 4. Analyze the failure
Use explain_failure on the failed request

# 5. Get a working cURL command
Use make_repro to generate test command

Example Output:

 ANALYSIS
Status: 400 Bad Request
Severity: HIGH

 ROOT CAUSE
Missing required field: "email"

OpenAPI spec requires:
- name (string, required)
- email (string, format: email, required)

Your request only included "name".

 SUGGESTED FIXES
1. Add "email" field to request body
2. Ensure email format is valid ([email protected])

 TEST COMMAND
curl -X POST "https://api.example.com/users" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]"
  }'

Scenario 2: Understanding 401 Unauthorized

# 1. Ingest logs showing 401 errors
Use ingest_logs

# 2. Explain the failure
Use explain_failure

# Get specific guidance on:
# - Missing Authorization header
# - Invalid/expired token
# - Wrong authentication scheme
# - Missing scopes/permissions

Slash Command

Use the /debug-api command for a guided debugging workflow:

/debug-api

This activates a systematic 4-step process:

  1. Load API documentation (OpenAPI spec)
  2. Ingest HTTP logs (HAR or JSON)
  3. Analyze failures (explain errors)
  4. Generate test commands (cURL repros)

AI Agent

The api-expert agent specializes in API debugging:

  • Root cause analysis of HTTP errors
  • OpenAPI spec interpretation
  • Severity assessment (critical → low)
  • Actionable fix suggestions
  • Test command generation

Activate by asking questions like:

  • "Why is my API returning 400?"
  • "Help me debug this authentication error"
  • "Analyze these API logs"

Supported Formats

OpenAPI Specs

  • OpenAPI 3.0.x
  • OpenAPI 3.1.x
  • JSON format
  • YAML format
  • ️ Swagger 2.0 (limited support)

HTTP Logs

  • HAR (HTTP Archive) - browser DevTools export
  • JSON array of request/response objects
  • Direct log objects (manual entry)

Status Code Knowledge Base

The plugin has built-in expertise for all common HTTP status codes:

4xx Client Errors

  • 400 Bad Request → Validation/syntax errors
  • 401 Unauthorized → Authentication issues
  • 403 Forbidden → Permission problems
  • 404 Not Found → Endpoint/resource missing
  • 405 Method Not Allowed → Wrong HTTP method
  • 408 Request Timeout → Network/performance
  • 409 Conflict → Resource state conflict
  • 422 Unprocessable Entity → Semantic validation
  • 429 Too Many Requests → Rate limiting

5xx Server Errors

  • 500 Internal Server Error → Server bug (CRITICAL)
  • 502 Bad Gateway → Upstream error (CRITICAL)
  • 503 Service Unavailable → Temporary issue (HIGH)
  • 504 Gateway Timeout → Upstream timeout (HIGH)

How It Works

Under the Hood

  1. OpenAPI Parsing: Uses openapi-types and yaml to parse specs
  2. HAR Processing: Extracts requests/responses from browser exports
  3. Pattern Matching: Matches URLs to OpenAPI endpoints with regex
  4. Failure Analysis: Compares actual vs expected behavior
  5. Command Generation: Creates executable test commands

In-Memory Storage

The plugin maintains:

  • API Specs: Map of loaded OpenAPI documents
  • HTTP Logs: Array of ingested requests/responses
  • Log Indexing: Fast lookup by index for analysis

Data persists during the session but clears on restart (no disk storage).

Examples

Export HAR from Browser

Chrome/Edge:

  1. Open DevTools (F12)
  2. Go to Network tab
  3. Perform API calls
  4. Right-click network log
  5. "Save all as HAR with content"

Firefox:

  1. Open DevTools (F12)
  2. Go to Network tab
  3. Perform API calls
  4. Click gear icon → "Save All As HAR"

Manual Log Entry

// If you have logs in code, convert to this format:
const logs = [
  {
    timestamp: new Date().toISOString(),
    method: 'POST',
    url: 'https://api.example.com/users',
    statusCode: 400,
    requestHeaders: {
      'Content-Type': 'application/json'
    },
    requestBody: {
      name: 'John'
    },
    responseBody: {
      error: 'Missing required field: email'
    }
  }
];

// Then use ingest_logs with logs array directly

️ Architecture

conversational-api-debugger/
├── servers/
│   └── api-debugger.ts        # MCP server (730+ lines)
├── tests/
│   └── api-debugger.test.ts   # Comprehensive tests (36 tests)
├── commands/
│   └── debug-api.md           # /debug-api workflow
├── agents/
│   └── api-expert.md          # API debugging agent
└── .claude-plugin/
    └── plugin.json            # Plugin metadata

Testing

# Run test suite
pnpm test

# Run with coverage
pnpm test:coverage

# Build TypeScript
pnpm build

Test Coverage:

  • OpenAPI spec loading (JSON/YAML)
  • HAR file parsing
  • Log analysis (status codes, methods)
  • Failure analysis (all HTTP status codes)
  • Endpoint matching (path parameters)
  • cURL generation (headers, bodies)
  • Input validation (Zod schemas)
  • Error handling

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE

Related Tools

  • project-health-auditor - Code quality and technical debt analysis
  • domain-memory-agent - Knowledge base with semantic search
  • design-to-code - Figma/screenshot to component generation
  • workflow-orchestrator - DAG-based task automation

Use Cases

  1. Debugging Production Issues - Analyze production API failures quickly
  2. API Integration - Understand third-party API errors
  3. Documentation - Generate examples for API docs
  4. Testing - Create reproducible test cases
  5. Bug Reports - Include working repro commands
  6. Onboarding - Help new developers understand APIs

Best Practices

  1. Always load OpenAPI spec first - Provides context for analysis
  2. Use HAR files when possible - Most complete log format
  3. Include request/response bodies - Critical for validation errors
  4. Generate repro commands - Makes debugging tangible
  5. Test fixes immediately - Use generated cURL to verify
  6. Keep specs up-to-date - Ensure accurate comparisons

Performance

  • OpenAPI Loading: < 100ms for typical specs
  • HAR Parsing: < 500ms for 100 requests
  • Failure Analysis: < 50ms per request
  • cURL Generation: < 10ms per command

Troubleshooting

Q: OpenAPI spec fails to loadA: Ensure it's valid OpenAPI 3.x (check openapi: "3.0.0" field)

Q: HAR file won't parseA: Verify it's exported with "content" option enabled

Q: Can't find matching endpointA: Check URL path matches OpenAPI spec (including base path)

Q: Generated cURL doesn't workA: Verify all required headers are in original request

Features Coming Soon

  • Support for GraphQL APIs
  • Batch failure analysis
  • Custom validation rules
  • Postman collection export
  • Response schema validation
  • Performance profiling

Made with ️ by Intent Solutions

Part of the Claude Code Plugin Marketplace

MCP Server · Populars

MCP Server · New