@dawmatt/api-grade-mcp

Grade an API specification and return the full result including all individual violations, per-category breakdowns, and prioritised recommendations. Use this when you need to analyse specific violations or present detailed findings to the user. Supports OpenAPI (2.x, 3.x) and AsyncAPI (2.x, 3.x).

Return the active Spectral ruleset used by this MCP server when no rulesetPath is supplied on a grading request. Supports three scopes: session (in-memory, resets on server restart), workspace (persisted in workspace), and global (persisted to home). Return configuration at every scope, indicate which scope is currently in effect (the effective ruleset), and show the full resolution chain. Use this to diagnose why a particular ruleset is being applied or to confirm a set-ruleset-config call took effect.

Assert that an API specification meets a minimum grade threshold. Returns a structured pass/fail result. Use this in AI-assisted code review workflows or quality gates. Grade ordering: A (best) > B > C > D > F (worst).

Inspect a Spectral ruleset

Grade an API specification file and return quality score, letter grade, and diagnostic summary. Use this for a token-efficient overview without the full violations list. Supports OpenAPI (2.x, 3.x) and AsyncAPI (2.x, 3.x) specifications in YAML or JSON.

Set the default Spectral ruleset used by this MCP server when no rulesetPath is supplied on a grading request. Supports three scopes: session (in-memory, resets on server restart), workspace (persisted to .api-grade/config.json in the workspace root), and global (persisted to ~/.api-grade/config.json). Optionally configure authentication for rulesets hosted in secured locations.

Return a classified, AI-actionable list of diagnostics filtered by remediation safety level: `safe` (non-breaking, safe to auto-apply), `humanreview` (typically additive/clarifying but should be confirmed by a human before applying at scale), or `unsafe` (could change request/response validation, required fields, types, or the parameter surface — requires human or explicitly-confirmed-agent review). Each returned item also carries a confidence indicator (riskLevel/confidenceLevel) explaining how sure the analyser is in its classification. Use this tool (not grade-api-detailed) when the goal is for the AI to safely resolve violations; the AI generates the corrected specification content and the MCP server does not modify files.