Getting started¶
Lint a saved snapshot¶
Pass a saved tools/list result or an mcp-lint snapshot with --file:
npx https://superintelligenceco.github.io/pkg/mcp-lint.tgz --file tools.json
The last lines of the report show the score, the grade, and whether the run passed, for example:
Score 50/100 Grade F (6 errors, 10 warnings, 3 info)
Failed: score is below the minimum of 70.
The exit code is 1 because the score is below the default minimum of 70.
Lint a running server¶
Put a stdio server's command after --:
mcp-lint -- npx -y @modelcontextprotocol/server-everything
For a remote server, pass --url. mcp-lint tries Streamable HTTP first and falls back to
HTTP+SSE:
mcp-lint --url https://mcp.example.com/mcp -H "Authorization: Bearer $MCP_TOKEN"
Gate a pull request¶
Save a snapshot once, commit it, and lint it in CI without starting the server:
mcp-lint --save mcp-snapshot.json -- node dist/server.js
mcp-lint --file mcp-snapshot.json --min-score 85 --sarif mcp-lint.sarif
In GitHub Actions, install the CLI, lint the server, and upload the SARIF report to code scanning:
- run: npm install -g https://superintelligenceco.github.io/pkg/mcp-lint.tgz
- run: mcp-lint --min-score 80 --sarif mcp-lint.sarif -- node dist/server.js
- if: always()
uses: github/codeql-action/upload-sarif@v4
with:
sarif_file: mcp-lint.sarif
category: mcp-lint
Configure rules¶
Put a .mcp-lint.json in the working directory:
{
"minScore": 80,
"rules": { "naming/inconsistent-style": "off" },
"ignoreTools": ["debug_dump"]
}
Unknown keys and unknown rule IDs are errors, so a typo cannot silently disable a rule.
Use the library¶
Add the package to your project with npm install https://superintelligenceco.github.io/pkg/mcp-lint.tgz, then:
import { lint, readSnapshotFile } from "@superintelligenceco/mcp-lint";
const { snapshot } = readSnapshotFile("tools.json");
const result = lint(snapshot);
console.log(result.score, result.grade, result.findings.length);