Home / MCP tooling

mcp-tools-lint

Lint MCP tool schemas and annotations before clients reject them.

TypeScript · MIT · latest v0.3.0

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.

Releases

Posts about it

More in MCP tooling

All tools

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