@dawmatt/api-grade-mcp

MCP (Model Context Protocol) server that exposes api-grade capabilities as seven AI tools — grade OpenAPI and AsyncAPI specifications directly from Claude Code, GitHub Copilot, or any MCP-compatible AI host.

Installation

npm install -g @dawmatt/api-grade-mcp

Or use without installing (recommended):

npx -y @dawmatt/api-grade-mcp

Quick Start

Claude Code

claude mcp add api-grade -- npx -y @dawmatt/api-grade-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "api-grade": {
      "command": "npx",
      "args": ["-y", "@dawmatt/api-grade-mcp"]
    }
  }
}

GitHub Copilot (VS Code Agent mode)

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "api-grade": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@dawmatt/api-grade-mcp"]
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | grade-api | Letter grade, score, and summary — token-efficient overview | | grade-api-detailed | Full grade with all violations and diagnostics | | assert-api-grade | Pass/fail assertion for a minimum grade threshold | | grade-api-remediation-safety | Classified list of diagnostics filtered by remediation safety level (safe, humanreview, or unsafe), each with a risk/confidence indicator, for AI-assisted correction | | analyse-ruleset-safety | Per-rule risk, confidence, and remediation-safety analysis for a ruleset, independent of grading any spec | | set-ruleset-config | Set the default Spectral ruleset at session, workspace, or global scope | | get-ruleset-config | Get the active Spectral ruleset and which scope is effective |

Usage Examples

Once configured, ask your AI tool naturally:

Grade the API at /workspace/my-api/openapi.yaml

Check whether /workspace/my-api/openapi.yaml meets a minimum grade of B

Apply safe remediations to /workspace/my-api/openapi.yaml

Set the workspace default ruleset to https://github.example.com/org/standards/raw/main/ruleset.yaml

Default Ruleset Configuration

All grading tools support an optional rulesetPath per-request. To avoid supplying it every time, configure a default:

• Session — in-memory, cleared on restart
• Workspace — saved to .api-grade/config.json in the project root
• Global — saved to ~/.api-grade/config.json

Precedence: per-request → session → workspace → global → built-in.

Supported auth: GitHub PAT (GITHUB_TOKEN env var).

Supported Spec Formats

• OpenAPI 2.x (Swagger)
• OpenAPI 3.x
• AsyncAPI 2.x
• AsyncAPI 3.x

Requirements

• Node.js ≥ 20.0.0

Related Packages

| Package | Purpose | |---------|---------| | @dawmatt/api-grade | CLI tool — grade specs from the terminal | | @dawmatt/api-grade-core | Grading engine — embed in your own tools | | @dawmatt/backstage-plugin-api-grade | Backstage frontend card plugin | | @dawmatt/backstage-plugin-api-grade-backend | Backstage backend grading plugin |

Documentation

• Quick Start — install and configure in minutes
• Configuration Reference — default rulesets, auth, and scope precedence
• Troubleshooting — common issues and solutions
• Full Documentation

License

MIT