Skip to content

About

Lint MCP tool schemas and annotations before clients reject them: flags non-2020-12 $schema dialects, boolean schemas, bad required lists and missing or contradictory annotations in tools/list, over stdio, Streamable HTTP, legacy SSE or a JSON file. Text, JSON and SARIF output, RFC 6902 --fix patch, GitHub Action.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

mcp-tools-lint

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.

CI License: MIT Node 20+

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.

Why now

The MCP specification defines inputSchema and outputSchema as JSON Schema 2020-12, and the 2026-07-28 revision of the spec widened them to allow any 2020-12 keyword. Claude Code enforces that dialect: its default validator compiles 2020-12 only, so a tool whose schema carries "$schema": "http://json-schema.org/draft-07/schema#" is listed without complaint and then fails on every call with JSON Schema declares an unsupported dialect.

That $schema line is what the TypeScript SDK's McpServer writes by default. The SDK converts zod schemas with toJsonSchemaCompat and no target, which falls back to draft-7 (verified against @modelcontextprotocol/sdk 1.32.0 on 2026-10-03, for zod v3 and zod v4 schemas, on both inputSchema and outputSchema). The reference filesystem server was unusable from Claude Code for this reason (anthropics/claude-code#88882, opened 2026-08-22 and open as of 2026-10-03), and the same bug was then filed against one downstream server after another in the following weeks, for example whoop-mcp#251 (which quotes the client error and was fixed by dropping the dialect declaration), vikunja-mcp#3 and IBM/ibmi-mcp-server#165. This linter catches that in CI, before a user does.

Annotations are the second half. The MCP blog's post on tool annotations says coverage is uneven and many servers ship without them; clients that gate on readOnlyHint then prompt on every call, and a tool that says readOnlyHint: true while being called delete_record teaches users to click through prompts. A separate class of bug comes from servers that emit read_only_hint in snake_case, as the Python SDK 2.x does: clients read readOnlyHint, so every such tool is treated as write-capable (hermes-agent#123485).

What it catches

Rule Severity What it means --fix
schema-compiles error Input or output schema cannot compile as JSON Schema 2020-12, including dangling local $refs and invalid keyword values. External references are ignored without fetching; format validation is not performed. no
dialect-2020-12 error A $schema anywhere in inputSchema or outputSchema is not https://json-schema.org/draft/2020-12/schema (a trailing # is accepted). removes the $schema key
no-boolean-schema error true or false sits where a schema object is expected: a properties entry, items, an allOf/anyOf/oneOf entry, $defs, not, if/then/else, the root. Booleans under additionalProperties, additionalItems, unevaluatedProperties and unevaluatedItems are allowed. no: replace true with {} and false with {"not": {}}
required-names-property error A required entry names a key that properties does not define on the same object schema. Schemas that compose others (allOf, $ref and so on) are skipped. no: add the property or drop the entry
unsupported-keyword warning $id with a fragment, definitions instead of $defs, or a boolean required (draft-03 style). no: use $anchor, $defs, an array required
missing-annotations warning The tool has no annotations object. no: add the four hints truthfully
readonly-verb-contradiction error readOnlyHint is true but the name or title starts with create, add, insert, update, set, put, patch, delete, remove, drop, send, post, publish, write, execute, run, deploy, move or rename followed by _ or -. no: set readOnlyHint: false
destructive-without-hint warning The name starts with delete, remove or drop and destructiveHint is not declared. no: declare destructiveHint
snake-case-annotation-keys error annotations contains read_only_hint, destructive_hint, idempotent_hint or open_world_hint. renames to camelCase (or removes the duplicate when the camelCase key already exists)
description-missing info The tool has no description. no

mcp-tools-lint --rules prints the same list. Use repeatable --ignore-rule <id> flags to suppress known findings and their fixes; unknown IDs exit 2. SARIF keeps suppressed rule descriptors, disabled, so their indices remain stable. Rules are pure functions (tool) => Finding[] in src/rules.ts; the verb lists are deliberately short to keep false positives down.

Adopt incrementally with a baseline

node dist/cli.js tools.json --baseline-write baseline.json
node dist/cli.js tools.json --baseline baseline.json --fail-on error

--baseline-write saves the current findings in the JSON report shape. --baseline then drops every finding already in that report before the summary and exit code are computed, so CI fails only on new findings while the backlog is worked down, and --fix/--write patches touch only what is new. Matching uses tool name, tool-relative path and rule ID, so reordering tools, changing the target path or a later release rewording a message does not recreate findings. Additional identical occurrences remain new. Summaries count suppressed and resolved findings; JSON and SARIF findings carry baselineState. A missing or malformed baseline exits 2 before contacting a server. Regenerate the baseline deliberately as debt is fixed; it is not a rule-wide allowlist.

Install

Requires Node.js 20 or newer. Runtime dependencies are @modelcontextprotocol/sdk, its peer zod, and ajv for local JSON Schema compilation.

Every release is published by publish-github-packages.yml in two places on GitHub Packages: the npm package @basitalisandhu/mcp-tools-lint and the container image ghcr.io/basitalisandhu/mcp-tools-lint. The package is not on npmjs.com yet; when it is, it will use the same scoped name.

npm from GitHub Packages

Point the @basitalisandhu scope at GitHub Packages in ~/.npmrc (or the project's .npmrc):

@basitalisandhu:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

GitHub's npm registry asks for a token even to install public packages. That is a GitHub limitation, not a setting of this repository: use a personal access token (classic) with the read:packages scope, exported as GITHUB_TOKEN. Then:

npx @basitalisandhu/mcp-tools-lint --help              # run without installing
npm install -g @basitalisandhu/[email protected]    # global CLI, installs the mcp-tools-lint command
npm install -D @basitalisandhu/[email protected]    # as a dev dependency of a server project

Container image

The image is built for linux/amd64 and linux/arm64, runs as the non-root node user, and is tagged with the version and latest; pin the version. The working directory is /work, so mount the files to lint there:

docker run --rm -v "$PWD:/work:ro" ghcr.io/basitalisandhu/mcp-tools-lint:0.3.2 tools.json
docker run --rm ghcr.io/basitalisandhu/mcp-tools-lint:0.3.2 https://mcp.example.com/mcp -H "Authorization: Bearer $TOKEN"

A stdio target runs inside the container, so it only works for a server command the image can start (Node.js is available; mount the server's files). To write a SARIF file or a patch, mount /work read-write.

The image is signed with cosign (keyless) and carries a build provenance attestation; an SPDX SBOM is attached to the GitHub release. To check it before running it:

cosign verify ghcr.io/basitalisandhu/mcp-tools-lint:0.3.2 \
  --certificate-identity-regexp '^https://github.com/basitalisandhu/mcp-tools-lint/\.github/workflows/publish-github-packages\.yml@refs/tags/v' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
gh attestation verify oci://ghcr.io/basitalisandhu/mcp-tools-lint:0.3.2 --owner basitalisandhu

To build the image from a checkout: docker build -t mcp-tools-lint .

From a clone

git clone https://github.com/basitalisandhu/mcp-tools-lint && cd mcp-tools-lint
npm install && npm run build
node dist/cli.js --help            # or `npm link`, which puts `mcp-tools-lint` on your PATH

Usage

Three kinds of target:

# 1. A stdio server: everything after "--" is the command. -e adds to its environment.
npx @basitalisandhu/mcp-tools-lint -- node dist/index.js
npx @basitalisandhu/mcp-tools-lint -e GITHUB_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github

# 2. A Streamable HTTP server. -H adds request headers.
npx @basitalisandhu/mcp-tools-lint https://mcp.example.com/mcp -H "Authorization: Bearer $TOKEN"
#    A server that still speaks the 2024-11-05 HTTP+SSE transport (it answers 405 or
#    hangs on Streamable HTTP): point at its event-stream URL and add --transport sse.
npx @basitalisandhu/mcp-tools-lint https://mcp.example.com/sse --transport sse -H "Authorization: Bearer $TOKEN"

# 3. A JSON file holding a tools/list result ({"tools": [...]}, a bare array,
#    or a whole JSON-RPC response with result.tools).
npx @basitalisandhu/mcp-tools-lint tools.json

Options go before the target; everything after -- belongs to the server command. The tool calls initialize and tools/list (following nextCursor) with a 20 second timeout (--timeout <seconds>), and never calls a tool. It reads the raw tools/list payload rather than the SDK's parsed version, because the SDK's own parser would reject a boolean property schema and silently drop snake_case annotation keys, which are exactly the things to report.

Options: --format text|json|sarif, --transport streamable-http|sse (HTTP targets only; -H headers go on the event stream and on every message POST), --out <file>, --fix, --patch-out <file>, --write, --fail-on error|warning|info|none (default error), --ignore-rule <id> (repeatable), --sarif-location <uri>, --rules, --version.

Use --ignore-rule dialect-2020-12 to suppress one known rule without changing the failure threshold for other rules. Repeat the flag to suppress more rules. Ignored findings and their patch operations are omitted; SARIF retains the rule descriptor with defaultConfiguration.enabled: false. Unknown IDs are usage errors (exit 2); --rules lists valid IDs.

Example output

Against a server built with the TypeScript SDK's defaults (tests/fixtures/tools/draft07.json):

$ npx @basitalisandhu/mcp-tools-lint -- node tests/fixtures/servers/draft07.mjs
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
    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/properties/options/$schema
    error    dialect-2020-12  outputSchema 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/outputSchema/$schema

  write_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/1/inputSchema/$schema
    error    dialect-2020-12  outputSchema declares dialect "http://json-schema.org/draft-07/schema#"; the default validator in Claude Code supports JSON Schema 2020-12 only  [fixable]
                              at /tools/1/outputSchema/$schema

5 errors, 0 warnings, 0 infos (5 fixable with --fix)

Against a server with schema and annotation mistakes (tests/fixtures/tools/boolean.json):

$ npx @basitalisandhu/mcp-tools-lint tests/fixtures/tools/boolean.json
tests/fixtures/tools/boolean.json: 3 tools

  search_docs
    error    no-boolean-schema        boolean schema true where an object schema is expected (under properties); clients that compile tool schemas reject it
                                      at /tools/0/inputSchema/properties/filters
    error    no-boolean-schema        boolean schema true where an object schema is expected (under items); clients that compile tool schemas reject it
                                      at /tools/0/inputSchema/properties/tags/items
    error    required-names-property  required lists "limit" but properties has no "limit"
                                      at /tools/0/inputSchema/required/1
    warning  unsupported-keyword      definitions is a draft-07 keyword; 2020-12 uses $defs
                                      at /tools/0/inputSchema/definitions

  update_doc
    error    readonly-verb-contradiction  readOnlyHint is true but "update_doc" starts with a write verb
                                          at /tools/1/annotations/readOnlyHint
    warning  unsupported-keyword          $id "https://example.com/schemas/update-doc#body" contains a fragment; 2020-12 forbids fragments in $id (use $anchor)
                                          at /tools/1/inputSchema/$id
    warning  unsupported-keyword          required: true is draft-03 syntax; 2020-12 expects an array of property names on the parent object
                                          at /tools/1/inputSchema/properties/id/required

  delete_doc
    warning  missing-annotations       no annotations; clients that gate on readOnlyHint will treat this tool as write-capable
                                       at /tools/2/annotations
    warning  destructive-without-hint  "delete_doc" looks destructive but declares no destructiveHint
                                       at /tools/2/annotations
    info     description-missing       no description
                                       at /tools/2/description

4 errors, 5 warnings, 1 info

A clean server prints the tool count and No problems found. and exits 0.

--fix and --write

--fix writes <target>.patch.json (or --patch-out <file>), an RFC 6902 JSON Patch against the tools/list document that removes every offending $schema and renames snake_case annotation keys. Paths are JSON Pointers into {"tools": [...]} (or into the array, or into result.tools, matching the shape of a file target). For a server built with the Python SDK 2.x conventions (tests/fixtures/tools/snake.json):

$ npx @basitalisandhu/mcp-tools-lint tests/fixtures/tools/snake.json --fix
...
6 errors, 0 warnings, 0 infos (6 fixable with --fix)
wrote 6 patch operations to tests/fixtures/tools/snake.json.patch.json
[
  {
    "op": "move",
    "from": "/tools/0/annotations/read_only_hint",
    "path": "/tools/0/annotations/readOnlyHint"
  },
  {
    "op": "move",
    "from": "/tools/0/annotations/destructive_hint",
    "path": "/tools/0/annotations/destructiveHint"
  },
  ...
  {
    "op": "remove",
    "path": "/tools/1/annotations/read_only_hint"
  }
]

--write applies the patch to a JSON file target in place (it rewrites the file with two-space indentation); a second run then reports nothing. For a live server the patch tells you what to change in the server's source: delete the $schema keys from the schemas you register, or, with the TypeScript SDK, strip them before returning from your tools/list handler. The patch files for all four fixture servers are committed under tests/fixtures/expected/ and tested byte for byte.

JSON output

npx @basitalisandhu/mcp-tools-lint tools.json --format json
{
  "version": 1,
  "target": "tests/fixtures/tools/snake.json",
  "tools": 2,
  "summary": { "errors": 6, "warnings": 0, "infos": 0 },
  "findings": [
    {
      "ruleId": "snake-case-annotation-keys",
      "severity": "error",
      "path": "/annotations/read_only_hint",
      "message": "annotations uses read_only_hint; clients read readOnlyHint and ignore this key",
      "fix": [{ "op": "move", "from": "/annotations/read_only_hint", "path": "/annotations/readOnlyHint" }],
      "tool": "get_sleep",
      "toolIndex": 0,
      "pointer": "/tools/0/annotations/read_only_hint"
    }
  ],
  "patch": [ ... ]
}

path is relative to the tool; pointer is relative to the document and is what the patch uses.

SARIF and GitHub code scanning

npx @basitalisandhu/mcp-tools-lint --format sarif --out mcp-tools-lint.sarif --sarif-location src/index.ts -- node dist/index.js

The output is SARIF 2.1.0 with one reportingDescriptor per rule id, error, warning and note levels, a stable partialFingerprints entry per finding, and the RFC 6902 operation attached as a fix description where one exists. Each result carries a physical location (the file target, the first existing file among a stdio command's arguments, or whatever --sarif-location names) so GitHub code scanning shows it as an alert, plus a logical location with the tool name and the JSON Pointer.

GitHub Action

name: mcp-tools-lint
on: [push, pull_request]
permissions:
  contents: read
  security-events: write
jobs:
  lint-tools:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci && npm run build
      - uses: basitalisandhu/mcp-tools-lint/[email protected]   # pin a release tag
        with:
          command: node dist/index.js        # or target: tools.json / https://host/mcp
          sarif-location: src/index.ts
          fail-on: error                     # error | warning | info | none
          env: |
            API_TOKEN=${{ secrets.API_TOKEN }}

Inputs: target, command, env, headers, sarif-file, sarif-location, fail-on, upload (set false to skip the code scanning upload), patch-file, timeout, node-version, version (version of @basitalisandhu/mcp-tools-lint to install from GitHub Packages; empty builds the action's own checkout), token (used for that install; defaults to the workflow token, which must be able to read packages). Outputs: sarif-file, exit-code, errors, warnings. The job summary gets the text report. See action/action.yml.

Exit codes

Code Meaning
0 No finding at or above --fail-on (default: no errors).
1 At least one finding at or above --fail-on.
2 The target could not be read or reached (file missing or not JSON, server failed to start, connection or timeout), or the arguments were invalid. The server's stderr is included in the message.

As a library

import { lintTools, locateTools, applyPatch, checkTool } from '@basitalisandhu/mcp-tools-lint';

const doc = locateTools(JSON.parse(text));       // {"tools": [...]}, an array, or a JSON-RPC response
const result = lintTools(doc, 'tools.json');     // { findings, patch, summary, tools }
const fixed = applyPatch(doc.document, result.patch);
const findings = checkTool(tool);                // one tool, no I/O

Troubleshooting

Real messages and what to do about them.

npm error 401 Unauthorized ... authentication token not provided when installing. GitHub Packages asks for a token with read:packages even for public packages; see npm from GitHub Packages, or build from a clone with no token.

cannot list tools from my-server: spawn my-server ENOENT. The command after -- is not on PATH. Use the full path, node path/to/server.js, or npx -y <package>.

cannot list tools from https://host/mcp: fetch failed. Nothing answered at that URL: check the host, port and path. A server that answers 405, or hangs, may still speak the 2024-11-05 HTTP+SSE transport; point at its event-stream URL with --transport sse.

MCP error -32001: Request timed out. The server started but did not answer initialize or tools/list within --timeout seconds (default 20). A server that writes logs to stdout instead of stderr breaks the stdio protocol and causes this too.

tools.json is UTF-16 text; save it as UTF-8 or is not UTF-8 text. PowerShell's > writes UTF-16; use Out-File -Encoding utf8. A UTF-8 byte order mark is fine. Before 0.3.1 such a file failed with a confusing JSON error (UTF-16) or was linted with replacement characters in the tool names (Latin-1).

tools.json is nested more than 256 levels deep; refusing to lint it. No real tool schema nests that deep. Before 0.3.1 this crashed with RangeError: Maximum call stack size exceeded.

server returned a nextCursor on 1000 tools/list pages in a row. The server never ends its listing. It should leave nextCursor out of the last page. Before 0.3.1 the linter kept following the cursors.

Frequently asked questions

Why does Claude Code reject my MCP server's tools with "unsupported dialect" when the Inspector shows them fine? Claude Code compiles a tool's outputSchema with a JSON Schema 2020-12 validator, and the error is raised at call time, not at tools/list, so the Inspector's listing and even a successful tools/list prove nothing. The usual cause is a "$schema": "http://json-schema.org/draft-07/schema#" key that the TypeScript SDK adds when it converts zod schemas, and the fix is to delete it: the MCP specification already fixes the dialect at 2020-12, so the key carries no information. mcp-tools-lint -- <your server command> finds every such key, including nested ones, and --fix writes the patch.

Which JSON Schema keywords can I use in an MCP tool's inputSchema? Since the 2026-07-28 revision of the specification, any JSON Schema 2020-12 keyword, with the root required to be type: object. What to avoid is the older dialect's spelling: definitions (use $defs), a fragment in $id (use $anchor), a boolean required on a property (use the array form on the parent), and true or false where a schema object belongs, except under additionalProperties and the unevaluated* keywords, where booleans are the normal way to close a schema. The unsupported-keyword and no-boolean-schema rules cover those cases.

Do tool annotations matter if clients treat them as untrusted hints? Yes, in both directions. Clients that gate on readOnlyHint (write-approval modes, plan modes, auto-allow rules) prompt for every tool that lacks it, so a server without annotations trains its users to approve everything. A server whose delete_ tool says readOnlyHint: true is worse, because a client that trusts the server will let it run unprompted. And a server that emits read_only_hint in snake_case gets neither benefit: clients read the camelCase key and treat every tool as write-capable. The three annotation rules flag all of this; they do not decide whether your server should be trusted.

Can I run this in CI against a server that needs credentials or a running backend? Yes. For a stdio server pass -e KEY=VALUE for each variable (the SDK's default environment is kept and your entries are added), for a Streamable HTTP server pass -H "Authorization: Bearer ...". The tool only calls initialize and tools/list, so a server that can start and enumerate its tools is enough; nothing is invoked. If the server needs OAuth with a browser round trip, save a tools/list response once with any client and lint the JSON file instead. Exit code 2 is reserved for "could not run", so a job can tell a broken server from a failing lint.

Related tools

As of 2026-10-03: mcp-lint (npm) ships cross-client schema rules but no dialect or annotation rule; mcp-conform (PyPI) checks for boolean schemas and predates the dialect change; mcp-surface (npm) compiles schemas and snapshots the tool surface; the official conformance suite checks wire messages rather than tool contracts. None of them writes a fix.

Design notes

  • Rules are pure functions over one tool and produce findings with a JSON Pointer; the engine prefixes /tools/<i> and collects the patch. No rule has side effects, so the same input always gives the same report, which is what makes byte-for-byte patch tests possible.
  • The CLI reads the raw tools/list payload through client.request with a permissive schema instead of client.listTools(), so that it sees what the server sent rather than what the SDK's parser accepts.
  • The validator rules of any client are undocumented and can change. This repository tracks them as a versioned rule set: a rule's meaning changes only with a minor version bump and a changelog entry.
  • The write-verb and destructive-verb lists are intentionally short and anchored at the start of the name, followed by _ or -, so deleted_items_report is not flagged.

Contributing

Issues and pull requests are welcome. Adding a rule is one function in src/rules.ts plus a unit test and, where the rule has a fix, a fixture; see CONTRIBUTING.md and docs/good-first-issues.md. Run npm test before opening a pull request. Security problems: see SECURITY.md.

Sibling projects

More tools by the same author: https://github.com/basitalisandhu

  • dev-mcp-servers: ten small MCP servers for everyday development and security checks, one npm package each.

Licence

MIT, see LICENSE. Copyright 2026 Muhammad Basit Ali.

About

Lint MCP tool schemas and annotations before clients reject them: flags non-2020-12 $schema dialects, boolean schemas, bad required lists and missing or contradictory annotations in tools/list, over stdio, Streamable HTTP, legacy SSE or a JSON file. Text, JSON and SARIF output, RFC 6902 --fix patch, GitHub Action.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages