mcp-lint

01 — Proof

The tool failed.
The agent stopped.

A schema can be valid and still hand the agent a terminal command, a silent payload, or “wait and retry.” mcp-lint marks that on the page before a user does.

  1. Schema valid

    The JSON parses. The types match. Eight clients can read the tool.

  2. Tool fails

    Credential, permission, rate limit, timeout, or an empty payload.

  3. Agent stops

    The error says “run npm login” or “wait.” Nothing in the tool list can do that.

02 — Bench

What the red mark means

  1. 03

    Name the tool

    A credential error has to say login, not “run npm login.” A rate limit has to name the call to repeat.

  2. 04

    Stay inside the protocol

    Terminal, config file, browser page. An agent limited to MCP tools cannot do those, and it will try anyway.

  3. 05

    Mark the destructive ones

    check now warns when a delete, send, payment, or deploy tool has no destructiveHint, and errors when a read-only hint is a lie.

The name has to survive the client.

OpenAI rejects anything outside letters, digits, underscore, and hyphen, and it caps the name at 64 characters. Gemini also refuses a name that starts with a digit.

One CLI. The whole check.

check
Lint a tools file, a live server, or the stdio servers already configured on this machine. Exit 1 on errors.
npx mcp-lint check tools.json
compat
Show which tools survive Claude, Cursor, Gemini, VS Code, Windsurf, Cline, OpenAI, and Continue.
npx mcp-lint compat tools.json
fix
Apply the safe auto-fixes. Dry-run first if the file is already in git.
npx mcp-lint fix tools.json --dry-run
explain
Print one rule, why it exists, and whether it can be fixed.
npx mcp-lint explain openai/no-additional-properties
preflight
Score a proposed tool call before it runs. Allow, deny, approval, or rewrite.
npx mcp-lint preflight action.json --policy preflight.yml
recover
Score a recorded failure. The bench on this page uses that same function.
npx mcp-lint recover errors.json
snapshot
Save a live tool list. Commit it, then let diff fail the build when a later list gets worse.
npx mcp-lint snapshot -o tools.json --server stdio -- node server.js
diff
Fail CI when a new schema introduces errors the old one did not have.
npx mcp-lint diff before.json after.json
init
Write a starter config for all eight clients.
npx mcp-lint init

Eight clients, one schema.

A tool that is fine for one picker can be illegal for another. check runs the shared rules and the client rules together.

Run it on the schema you already have

In GitHub Actions, robert19001-cmyk/mcp-lint@v0.7.0 runs the same checks. Pass recover when you have a failure file. The package is MIT and stays free.