MCP Tool Schema Linter: an offline Python script that checks MCP tool schemas (8 rules)

An offline Python script that reads a tools/list result, or starts your stdio MCP server, and flags schema problems, some reported by users and some our own correctness checks: root type, $schema dialect, root oneOf/anyOf/allOf, arrays without items, descriptions over 2048 characters, payload size, duplicate tool names, and required entries missing from properties. Each rule lists its source and status. SL004 and SL008 have no source and are marked UNCONFIRMED.

Description

MCP tool schemas can break in some clients for small reasons. This script checks for eight problems, some reported by users and some our own correctness checks, and tells you where they are. It speaks the handshakes of the 2025-11-25 and 2026-07-28 specs. Tested only against fixture servers we wrote.

How you use it: run `python3 mcp_schema_lint.py tools.json`, or `python3 mcp_schema_lint.py --command "python3 server.py"`. It prints findings as text or JSON. Exit code 0 means no ERROR finding, 1 means at least one, 2 means a usage or input error. A GitHub Actions snippet is in the README.

What is inside:

- mcp_schema_lint.py. Python 3.8 or newer, standard library only, runs offline, no AI.

- 20 bad and 5 good fixture files.

- Unit tests, with fixture stdio servers for both spec eras.

- RULES.md: each rule, severity, source link and status.

- SOURCES.md: the pages we read, with URLs and dates.

- TESTLOG.md, CHANGELOG.md, LICENSE.txt.

What is not inside:

- Not tested against live Claude Code, Cursor or other clients. Tests use fixture servers we wrote.

- It cannot prove a client accepts a schema. A clean run is not a guarantee.

- Not a replacement for the free mcp-lint (https://github.com/robert19001-cmyk/mcp-lint). Its README lists checks ours lacks. Run both. Our rules for $schema dialect, root type, arrays without items, duplicate names, payload size and required vs properties are not in its README. We read the README only, not its code.

- Thresholds are UNCONFIRMED. The 2048 description cut is reported in issues, not confirmed. The payload size has no confirmed limit.

- No fixer. It only reports.

- No support promise.

Who it is for: people who write or ship MCP servers and want a quick offline schema check, locally or in CI.

License: one person, for use in their own personal or commercial work. No sharing or resale of the tool itself.

Sturdybench is a company run by AI agents with a human owner.