mcp-tools-lint
Lint MCP tool schemas and annotations before clients reject them.
What it is
Lint MCP tool schemas and annotations before clients reject them. Point it at a running MCP server (stdio, Streamable HTTP or the older HTTP+SSE transport) or at a saved tools/list result, and it checks every tool against what Claude Code and other strict clients accept: JSON Schema 2020-12 only, no boolean schemas, required names that exist, and annotations that are present, camelCase and not self-contradictory. It prints text, JSON or SARIF, writes an RFC 6902 patch for the fixable findings, and ships as a GitHub Action.
Built alongside dev-mcp-servers.
Who it is for: authors of MCP servers who want CI to catch the schema and annotation mistakes that make Claude Code and other strict clients reject their tools, and people choosing a third-party server who want to know before installing it.
Quick start
git clone https://github.com/basitalisandhu/mcp-tools-lint && cd mcp-tools-lint
npm install && npm run build
node dist/cli.js -- node tests/fixtures/servers/draft07.mjs # or: node dist/cli.js tools.json, or an https:// URL
The last line lints a bundled fixture server built with the TypeScript SDK's defaults. A real run (first tool shown):
node tests/fixtures/servers/draft07.mjs: 2 tools
read_file
error dialect-2020-12 inputSchema declares dialect "http://json-schema.org/draft-07/schema#"; the default validator in Claude Code supports JSON Schema 2020-12 only [fixable]
at /tools/0/inputSchema/$schema
...
5 errors, 0 warnings, 0 infos (5 fixable with --fix)
The npm package and container image are on GitHub Packages; see Install. Project site: https://basitalisandhu.github.io/mcp-tools-lint/. Related: mcp-egress records which hosts the same server contacts at run time.
Install
npx @basitalisandhu/mcp-tools-lint --help # run without installing
npm install -g @basitalisandhu/mcp-tools-lint@0.3.0 # global CLI, installs the mcp-tools-lint command
npm install -D @basitalisandhu/mcp-tools-lint@0.3.0 # as a dev dependency of a server project
From the README; see the full README for every option.
Links
Releases
Posts about it
- Do MCP servers say which tools are safe?
I read the tool registrations of 304 public MCP servers. Six in ten mark none of their tools as read-only or destructive, and only one delete-or-send tool in five says it is destructive.
More in MCP tooling
- dev-mcp-servers: Ten small MCP servers for everyday development and security checks.
- mcp-server-template: Secure MCP server template in TypeScript and Python, safe by default.
- mcp-auth-doctor: Diagnose OAuth discovery problems on remote MCP servers.
- mcp-egress: Record every host an MCP server contacts, per tool, and fail CI on new ones.
- claude-mcp-allow: Least-privilege Claude Code permission rules for MCP tools, generated from their annotations.
- agentdojo-mcp: Run the AgentDojo benchmark's user and injection tasks against a real MCP server's tools.
- garak-mcp-probes: Run garak against your own MCP servers, with detectors for denied tool calls, leaked canaries and runaway step counts.
- mcp-rc-check: MCP specification migration checker for the 2026-07-28 revision: flags removed, changed and deprecated constructs and writes a patch for mechanical fixes.
Topics: ai-agents, claude-code, cli, developer-tools, github-actions, hacktoberfest, json-patch, json-schema, lint, linter, mcp, mcp-server, mcp-tools, model-context-protocol, npm, sarif, tool-annotations, typescript