A Spectral ruleset that checks MCP (Model Context Protocol) tool definitions against best practices.
It lints documents shaped like an MCP tools/list result:
{
"tools": [
{
"name": "create_api",
"title": "Create API",
"description": "Creates a new API from an embedded OpenAPI definition.",
"inputSchema": { "type": "object", "properties": { "...": {} } },
"outputSchema": { "type": "object", "properties": { "...": {} } }
}
]
}- Node.js 18 or later
- Spectral CLI 6.x
npm install -g @stoplight/spectral-cliLint a file:
spectral lint -r mcp-ruleset.yaml path/to/mcp-tools.jsonTry the bundled examples:
spectral lint -r mcp-ruleset.yaml examples/valid.json # no problems
spectral lint -r mcp-ruleset.yaml examples/invalid.json # triggers every ruleBy default Spectral lists everything but only exits non-zero on errors. Useful flags:
| Flag | Effect |
|---|---|
-F warn |
Also fail on warnings |
-D |
Only show results at or above the fail severity |
-f json / -f junit / -f sarif |
Machine-readable output for CI |
Reference it from a .spectral.yaml in your project:
extends:
- https://raw.githubusercontent.com/apiaddicts/mcps-style-guide/main/mcp-ruleset.yamlOr point at a local copy (extends: ./path/to/mcp-ruleset.yaml). The functions/ directory has to stay next to the ruleset.
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm install -g @stoplight/spectral-cli
- run: spectral lint -r mcp-ruleset.yaml mcp-tools.json -F warnSee docs/rules.md for the full reference: why each rule exists, passing and failing examples, and the Spectral output it produces.
Each rule has a code (MCR001...) and its Spectral id is mcp:<code>. Every message starts with the code.
| Code | Rule id | Severity | What it checks |
|---|---|---|---|
| MCR001 | mcp:MCR001 |
error | Every tool has a name that follows the configured naming-convention: snake_case (default), camelCase, kebab-case or UpperCamelCase |
| MCR002 | mcp:MCR002 |
warn | title is a non-null, non-empty string |
| MCR003 | mcp:MCR003 |
error | description is present and not empty |
| MCR004 | mcp:MCR004 |
error | A tool object has no duplicate keys (e.g. two _meta) |
| MCR005 | mcp:MCR005 |
error | inputSchema exists and its type is object |
| MCR006 | mcp:MCR006 |
info | Every property in inputSchema.properties has a description |
| MCR007 | mcp:MCR007 |
error | Any openapi field inside the input properties starts with 3. |
| MCR008 | mcp:MCR008 |
error | In embedded OpenAPI schemas, every required name exists in properties |
| MCR009 | mcp:MCR009 |
warn | outputSchema is present and not null |
MCR001 · mcp:MCR001
The convention is the rule's naming-convention option: with camelCase, createApi passes and create_api fails. See docs/resources/MCR001.md.
MCR002 · mcp:MCR002
{ "title": null } // ✗
{ "title": "Create API" } // ✓MCR003 · mcp:MCR003
{ "description": "" } // ✗
{ "description": "Creates a new API from ..." } // ✓MCR004 · mcp:MCR004
{ "_meta": { "version": 1 }, "_meta": { "version": 2 } } // ✗
{ "_meta": { "version": 2 } } // ✓MCR005 · mcp:MCR005
{ "inputSchema": { "type": "string" } } // ✗
{ "inputSchema": { "type": "object", "properties": {} } } // ✓MCR006 · mcp:MCR006
"properties": { "name": { "type": "string" } } // ✗
"properties": { "name": { "type": "string", "description": "API name." } } // ✓MCR007 · mcp:MCR007
"default": { "openapi": "2.0" } // ✗
"default": { "openapi": "3.0.3" } // ✓An input property that is itself named openapi (a schema object, not a version string) doesn't trigger this rule.
MCR008 · mcp:MCR008
"schemas": {
"Pet": {
"required": ["id", "name"],
"properties": { "id": { "type": "integer" } } // ✗ "name" missing
}
}MCR009 · mcp:MCR009
{ "outputSchema": null } // ✗
{ "outputSchema": { "type": "object" } } // ✓-
Spectral reports duplicate keys on its own as a
parsererror.mcp:MCR004adds a named error for duplicates at the top level of a tool object. When a file has duplicates you will see both. -
To turn off or change the severity of a rule, override it in your own
.spectral.yaml:extends: [./mcp-ruleset.yaml] rules: mcp:MCR006: off mcp:MCR009: error
mcp-ruleset.yaml Spectral ruleset
functions/
mcp-tool-naming-convention.js MCR001: tool names vs the configured naming convention
mcp-no-duplicate-keys.js MCR004: duplicate keys, read from parser diagnostics
mcp-required-matches-properties.js MCR008: `required` names vs `properties`
docs/
rules.md reference of every rule
resources/MCRNNN.md full reference of a rule (MCR001)
examples/
valid.json passes every rule
invalid.json breaks every rule
test/
<revision>/<category>/mcrNNN-*.test.js unit tests per MCP revision (20241105, 20250326, 20250618, 20251125, 20260728)
<revision>/<category>/MCRNNN/ their fixtures
helpers/ ruleset loader and shared fixtures
- Add or change the rule in
mcp-ruleset.yamlwith itsmcp:MCRNNNid and anMCRNNN:message prefix (custom logic goes infunctions/, in a file namedmcp-<name>.js). - Update
examples/valid.jsonandexamples/invalid.jsonso the rule has a passing and a failing case. - Add or update its tests in
test/<revision>/<category>/and run them withnpm test(npm installfirst). - Run both examples and check the output.
- Document the rule in
docs/resources/MCRNNN.mdand add it to the tables in this README anddocs/rules.md.
{ "name": "createApi" } // ✗ with the default snake_case { "name": "Create_API" } // ✗ { "name": "create_api" } // ✓