Skip to content

quick-start.md

Latest commit

 

History

History
220 lines (158 loc) · 5.28 KB

quick-start.md

File metadata and controls

220 lines (158 loc) · 5.28 KB
Raw

← Back to Documentation Index

MCP Server Quick Start

Install and configure @dawmatt/api-grade-mcp so your AI tool can grade API specifications directly.

Prerequisites

  • Node.js 20 or later — nodejs.org
  • An MCP-compatible AI tool (Claude Code, Claude Desktop, GitHub Copilot VS Code Agent mode, Cursor, Windsurf, or any MCP host)
  • An OpenAPI or AsyncAPI specification file to grade

Installation

No global install is required. The server runs on demand via npx:

npx -y @dawmatt/api-grade-mcp

Or install globally if you prefer a local binary:

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

Run via Docker

If your environment restricts direct node/npx execution but allows approved container images, run the server as a Docker container instead. Tool behaviour is identical to the npx/node invocation.

docker pull dawmatt/api-grade-mcp
docker run -i --rm -v "$PWD:/workspace" -w /workspace dawmatt/api-grade-mcp

The -v "$PWD:/workspace" bind mount is required — spec and ruleset file paths must resolve inside the container, so mount the directory containing the files you want to grade. The -i flag keeps stdin open for the stdio transport (no -t needed; this is not an interactive terminal session).

Configure Your AI Tool

Claude Code

Register the server from the terminal:

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

Or add it to .claude/settings.json manually:

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

The tools are available immediately in your Claude Code session.

Via Docker:

{
  "mcpServers": {
    "api-grade": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "${PWD}:/workspace", "-w", "/workspace", "dawmatt/api-grade-mcp"]
    }
  }
}

Claude Desktop

  1. Open the configuration file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the server entry:

{
  "mcpServers": {
    "api-grade": {
      "command": "npx",
      "args": ["-y", "@dawmatt/api-grade-mcp"]
    }
  }
}
  1. Restart Claude Desktop. The six api-grade tools will appear in the tools panel.

Via Docker:

{
  "mcpServers": {
    "api-grade": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/path/to/your/workspace:/workspace", "-w", "/workspace", "dawmatt/api-grade-mcp"]
    }
  }
}

GitHub Copilot (VS Code Agent mode)

Requires VS Code 1.99 or later with the GitHub Copilot extension.

  1. Create .vscode/mcp.json in your project root:
{
  "servers": {
    "api-grade": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@dawmatt/api-grade-mcp"]
    }
  }
}

  1. Open the Copilot Chat panel and switch to Agent mode.

  2. The api-grade tools are now available to Copilot in agent mode.

Via Docker:

{
  "servers": {
    "api-grade": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "${workspaceFolder}:/workspace", "-w", "/workspace", "dawmatt/api-grade-mcp"]
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

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

Reload Cursor after saving.

Available Tools

Tool What it does
grade-api Quick grade: letter grade, numeric score, and summary
grade-api-detailed Full grade with all violations, diagnostics, and recommendations
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

Try It

Once configured, ask your AI tool naturally:

Grade an API:

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

Get detailed diagnostics:

Show me all the violations in /workspace/my-api/openapi.yaml with recommendations

Assert a minimum grade:

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

AI-assisted fix:

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

Verifying the Setup

To confirm the server starts correctly:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | npx -y @dawmatt/api-grade-mcp

You should see a JSON response listing all the tools above.

Further Reading