Lint an MCP server
plune mcp lint (from CLI 0.34.5) reads the whole tool list of an MCP
server and reports what makes a model choose the wrong tool or call it wrong. A model picks a tool by
its name, its description and its input schema, and nothing else: a tool with no description, two
tools that read alike, or a status field that takes any string are guesses the model has to make on
every request.
It needs no Plune account and no model, and it does not talk to the Plune platform: it starts the
server you name after --, or connects to the --url you give, and reads its tools. How to connect
a stdio or an HTTP server is on Test an MCP server.
The sample server
Section titled “The sample server”A notebook server of three tools, about 50 lines on the official SDK, written with three defects on purpose:
get_notehas no description;- the
statusparameter ofset_statuslists its values in the description instead of anenum; list_notesreturns a list but takes nolimit.
-
Make a folder with these two files:
package.json {"name": "mcp-sample-server","version": "1.0.0","private": true,"type": "module","dependencies": {"@modelcontextprotocol/sdk": "1.32.2"}}server.mjs // mcp-sample-server: a notebook of three tools, with three deliberate defects for plune mcp lint.import { Server } from "@modelcontextprotocol/sdk/server/index.js";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";const notes = [{ id: 1, title: "Release checklist", status: "open" }];const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };const tools = [{name: "list_notes", // defect 3: returns a list, but has no limitdescription: "Return the notes with their id, title and status. Do not use it to read one note; use get_note instead.",inputSchema: { type: "object", properties: {} },annotations: readOnly,},{name: "get_note", // defect 1: no descriptioninputSchema: {type: "object",properties: { id: { type: "integer", description: "The id of the note, as list_notes shows it." } },required: ["id"],},annotations: readOnly,},{name: "set_status",description: "Change the status of one note. Do not use it to edit the title; this server has no tool for that.",inputSchema: {type: "object",properties: {id: { type: "integer", description: "The id of the note to change." },// defect 2: the allowed values are in the description instead of an enumstatus: { type: "string", description: "The new status: one of open, done, archived." },},required: ["id", "status"],},annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },},];const server = new Server({ name: "mcp-sample-server", version: "1.0.0" }, { capabilities: { tools: {} } });server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));server.setRequestHandler(CallToolRequestSchema, async ({ params: { name, arguments: args = {} } }) => {const text = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }] });if (name === "list_notes") return text(notes);const note = notes.find((n) => n.id === args.id);if (!note) return { isError: true, content: [{ type: "text", text: `No note with id ${args.id}.` }] };if (name === "set_status") note.status = args.status;return text(note);});await server.connect(new StdioServerTransport()); -
Install its one dependency:
Terminal window npm install -
Lint it:
$ npx -y @plune-ai/cli@0.39.9 mcp lint -- node server.mjsServer: mcp-sample-server 1.0.0 · stdio · 3 toolswarn get_note desc-missingThe tool has no description.expected: a description; actual: nonefix: Describe what the tool does, when to use it and when not to: the model chooses tools by name and description alone. The specification does not require a description; this is advice on quality.spec: https://modelcontextprotocol.io/specification/2025-11-25/schema#tool-descriptionwarn list_notes list-no-paging"list_notes" returns a list by its name, but cannot be asked for less.expected: one of: limit, cursor, page, offset, pagesize, perpage, per_page, page_size, pagetoken, page_token; actual: parameters: nonefix: Let the caller bound the answer: add a limit and a cursor (or page) parameter.warn set_status.status param-enum-in-textThe parameter description lists a closed set of values, but the schema does not.expected: an enum; actual: a free string described as "The new status: one of open, done, archived."fix: List the allowed values in "enum" rather than in the description, so the client can check them.0 errors, 3 warnings, 0 info, 0 suppressed · failing on: error$ echo $?0
Three findings, one per defect, and exit 0: all three rules are warn, and by default only an
error fails the run. To make advice fail too, lower the bar:
$ npx -y @plune-ai/cli@0.39.9 mcp lint --fail-on warn -- node server.mjsServer: mcp-sample-server 1.0.0 · stdio · 3 tools
warn get_note desc-missing The tool has no description. expected: a description; actual: none fix: Describe what the tool does, when to use it and when not to: the model chooses tools by name and description alone. The specification does not require a description; this is advice on quality. spec: https://modelcontextprotocol.io/specification/2025-11-25/schema#tool-descriptionwarn list_notes list-no-paging "list_notes" returns a list by its name, but cannot be asked for less. expected: one of: limit, cursor, page, offset, pagesize, perpage, per_page, page_size, pagetoken, page_token; actual: parameters: none fix: Let the caller bound the answer: add a limit and a cursor (or page) parameter.warn set_status.status param-enum-in-text The parameter description lists a closed set of values, but the schema does not. expected: an enum; actual: a free string described as "The new status: one of open, done, archived." fix: List the allowed values in "enum" rather than in the description, so the client can check them.
0 errors, 3 warnings, 0 info, 0 suppressed · failing on: warn$ echo $?1The fixed server
Section titled “The fixed server”The same server with each defect fixed: get_note has a description that says when not to use it,
status has an enum, and list_notes takes a limit.
// mcp-sample-server, fixed: the same three tools with the three defects removed.import { Server } from "@modelcontextprotocol/sdk/server/index.js";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
const notes = [{ id: 1, title: "Release checklist", status: "open" }];const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
const tools = [ { name: "list_notes", description: "Return the notes with their id, title and status. Do not use it to read one note; use get_note instead.", inputSchema: { type: "object", properties: { limit: { type: "integer", minimum: 1, maximum: 100, description: "How many notes to return at most (default 20)." } }, required: [], }, annotations: readOnly, }, { name: "get_note", description: "Read a single note when you know its id. Do not use it to browse; use list_notes instead.", inputSchema: { type: "object", properties: { id: { type: "integer", description: "The id of the note, as list_notes shows it." } }, required: ["id"], }, annotations: readOnly, }, { name: "set_status", description: "Change the status of one note. Do not use it to edit the title; this server has no tool for that.", inputSchema: { type: "object", properties: { id: { type: "integer", description: "The id of the note to change." }, status: { type: "string", enum: ["open", "done", "archived"], description: "The new status." }, }, required: ["id", "status"], }, annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, },];
const server = new Server({ name: "mcp-sample-server", version: "1.0.0" }, { capabilities: { tools: {} } });server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));server.setRequestHandler(CallToolRequestSchema, async ({ params: { name, arguments: args = {} } }) => { const text = (value) => ({ content: [{ type: "text", text: JSON.stringify(value) }] }); if (name === "list_notes") return text(notes.slice(0, args.limit ?? 20)); const note = notes.find((n) => n.id === args.id); if (!note) return { isError: true, content: [{ type: "text", text: `No note with id ${args.id}.` }] }; if (name === "set_status") note.status = args.status; return text(note);});await server.connect(new StdioServerTransport());Even at the strictest level, with info findings printed, nothing is left:
$ npx -y @plune-ai/cli@0.39.9 mcp lint --fail-on info --show-info -- node server-fixed.mjsServer: mcp-sample-server 1.0.0 · stdio · 3 tools
0 errors, 0 warnings, 0 info, 0 suppressed · failing on: info$ echo $?0Reading --fail-on
Section titled “Reading --fail-on”--fail-on decides which findings make the run exit 1. The others are still printed and counted.
--fail-on | Exit 1 on | Use it for |
|---|---|---|
error (default) | an error finding | a gate on what breaks the specification |
warn | a warn or error finding | a server whose tool list you keep clean of advice too |
info | any finding | the strictest review |
never | nothing | a report only |
Heuristic rules report warn at most, so the default error never fails a build on advice. A rule
that could not run — over 1000 tools for the two rules that compare every pair, or an input schema
nested deeper than 64 levels — is a finding in the could-not-run state, and the run exits 3 (or
1 when a finding is at the --fail-on level): not measured is not clean. info findings are only
counted unless --show-info prints them.
The rules
Section titled “The rules”Every rule has a stable id, which the exceptions file, the JSON report and the JUnit case name use. A rule is one of three classes:
- deterministic: follows from the specification or the schema; the same tool list always gives the same answer, and the error-level rules are all here;
- heuristic: advice from names, words and similarity; it reports
warnat most and does not fail the default run; - measure: a size estimate against a limit (characters divided by four, no tokenizer).
The table is built from plune mcp lint --list-rules --format json of the CLI version these docs pin;
run that command for the catalog of the version you have. The call- rules check answers and run
only with --call.
| Rule | Class | Level | What it reports | Before → after |
|---|---|---|---|---|
input-schema-not-object | deterministic | error | The input schema is missing or its root is not of type “object”. | "inputSchema": {"type": "string"} → "inputSchema": {"type": "object", "properties": {"query": {"type": "string"}}} |
output-schema-not-object | deterministic | error | The output schema is given, but its root is not of type “object”. | "outputSchema": {"type": "array"} → "outputSchema": {"type": "object", "properties": {"notes": {"type": "array"}}} |
required-unknown-property | deterministic | error | ”required” names a property a closed schema does not define, so no call can satisfy it. | "required": ["query"] in a schema with "additionalProperties": false and no query property → query added to properties, or taken out of required |
name-duplicate | deterministic | error | Two tools share a name, so only one of them can be called. | two tools named search → search_notes and search_tags |
name-invalid | deterministic | warn | The name uses characters or a length outside what the specification recommends. | get notes! → get_notes |
desc-missing | deterministic | warn | The tool has no description to choose it by. | no description → "Read a single note when you know its id. Do not use it to browse; use list_notes instead." |
desc-short | heuristic | info | The description is too short to tell when to choose the tool. | "Gets a note." → what the tool returns and when to choose it, in 40 characters or more |
desc-long | heuristic | warn | The description is long enough to cost every request. | a manual of over 1000 characters → two or three sentences, with each parameter explained in its own description |
desc-no-when-not | heuristic | info | The description does not say when not to use the tool (a warning when a similar tool exists). | "Search the notes by text." → "Search the notes by text. Do not use it to read one note by id; use get_note instead." |
tools-similar | heuristic | warn | Two tools have names or descriptions too alike to tell apart. | get_note and fetch_note, both "Get a note." → one tool, or two descriptions that say how they differ |
param-enum-in-text | heuristic | warn | A string parameter lists its allowed values in the description instead of an enum. | {"type": "string", "description": "One of open, done, archived."} → {"type": "string", "enum": ["open", "done", "archived"]} |
param-type-by-name | heuristic | warn | A parameter named like a number, flag, date or URL is a free string. | "limit": {"type": "string"} → "limit": {"type": "integer"} |
param-desc-missing | heuristic | info | A parameter has no description. | "id": {"type": "integer"} → "id": {"type": "integer", "description": "The id of the note."} |
param-example-missing | heuristic | info | A free-form object parameter has no example of its keys. | "filter": {"type": "object"} → "filter": {"type": "object", "examples": [{"status": "open"}]} |
required-missing | heuristic | info | The input schema has parameters but no “required” list. | properties with no required → "required": [] when every parameter is optional |
name-style-mismatch | heuristic | warn | The name does not follow the naming style of the other tools. | getNote beside list_notes and set_status → get_note |
name-not-snake | heuristic | info | The name is not snake_case. | getNote → get_note |
annotations-missing | deterministic | info | The tool has no annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint). | no annotations → "annotations": {"readOnlyHint": true, "destructiveHint": false} |
hint-readonly-writes | heuristic | warn | The tool is marked read-only, but its name says it changes something. | delete_note with "readOnlyHint": true → "readOnlyHint": false |
hint-destructive-understated | heuristic | warn | The tool says its updates are additive, but its name says it overwrites or removes. | set_status with "destructiveHint": false → "destructiveHint": true |
hint-idempotent-missing | heuristic | info | A tool that changes things does not say whether repeating a call is safe. | set_status with no idempotentHint → "idempotentHint": true when a repeated call changes nothing more |
list-no-paging | heuristic | warn | A tool that returns a list by its name cannot be asked for less. | list_notes with no parameters → a limit parameter (and a cursor for the next page) |
list-size | measure | warn | The whole tool list costs more tokens on every request than the limit. | a long tool list with long descriptions and schemas → fewer tools, shorter descriptions |
call-result-large | measure | warn | One call answers with more tokens than the limit; every such answer goes into the context of the model. | list_notes answers with every note → it answers with one page and a cursor |
call-error-no-text | deterministic | warn | A call fails (isError) without a text that says what went wrong. | {"isError": true, "content": []} → {"isError": true, "content": [{"type": "text", "text": "No note with id 7."}]} |
call-structured-duplicates-text | heuristic | info | The text of a result is only the JSON of its structuredContent, so the same data is sent twice. | the text is the JSON of structuredContent → a short summary in the text, the data in structuredContent |
call-output-schema-mismatch | deterministic | error | A tool with an outputSchema answers without structuredContent, or with structuredContent the schema rejects. | an outputSchema and an answer without structuredContent → structuredContent that the schema accepts |
Several rules build on the rule groups of an open-source project; its author and licence are in the CLI’s third-party notices.
The exceptions file
Section titled “The exceptions file”A finding you have decided to keep goes in plune-mcp-ignore.yaml, which lint reads from the
current folder (--ignore-file <path> names another). Each entry needs a reason; expires is
optional:
ignore: - rule: list-no-paging tool: list_notes reason: "The notebook holds at most 20 notes; a page parameter would add nothing." expires: 2027-06-30$ npx -y @plune-ai/cli@0.39.9 mcp lint -- node server.mjsServer: mcp-sample-server 1.0.0 · stdio · 3 tools
warn get_note desc-missing The tool has no description. expected: a description; actual: none fix: Describe what the tool does, when to use it and when not to: the model chooses tools by name and description alone. The specification does not require a description; this is advice on quality. spec: https://modelcontextprotocol.io/specification/2025-11-25/schema#tool-descriptionwarn set_status.status param-enum-in-text The parameter description lists a closed set of values, but the schema does not. expected: an enum; actual: a free string described as "The new status: one of open, done, archived." fix: List the allowed values in "enum" rather than in the description, so the client can check them.suppressed: warn list_notes list-no-paging: The notebook holds at most 20 notes; a page parameter would add nothing.
0 errors, 2 warnings, 0 info, 1 suppressed · failing on: error$ echo $?0The suppressed finding is still listed, with its reason, and counted in the summary.
- An entry without a
reasonstops the run with exit2and the line number. toolandparamnarrow an entry; withouttoolit covers the rule on every tool.- An entry past its
expiresdate no longer applies and is printed as a warning, so an exception comes back for review on the day you chose. - An entry that matched no finding is printed as stale: the defect it excused is gone, and so can the entry be.
- No entry hides a rule that could not run: that finding stays, and the run is still not measured.
--call: check the answers too
Section titled “--call: check the answers too”Without --call, lint only reads the tool list. With it, lint also calls each tool that says
readOnlyHint: true, does not say it is destructive and needs no argument, always with {}, and runs
the call- rules on the answer: an answer too large for a model’s context, an error with no text, a
text that repeats the structured content, a result that does not match the tool’s outputSchema.
$ npx -y @plune-ai/cli@0.39.9 mcp lint --call -- node server-fixed.mjsServer: mcp-sample-server 1.0.0 · stdio · 3 tools
Calls (--call, at most 10, arguments {}): called list_notes passed skipped get_note required-arguments skipped set_status not-read-only
0 errors, 0 warnings, 0 info, 0 suppressed · failing on: error$ echo $?0get_note is not called because it requires an id, and set_status because it is not read-only. A
tool whose schema could require something without a top-level required (allOf, anyOf, oneOf,
$ref), or whose destructiveHint is not a boolean, is not called either. --call-limit (default
10) caps the calls, --call-timeout (default 15s) caps each one, and a call with no answer is
could-not-run, never a pass. --call is off by default.
Exit codes
Section titled “Exit codes”| Exit | Meaning |
|---|---|
0 | No finding at the --fail-on level, and everything was measured. |
1 | At least one finding at the --fail-on level or above. |
2 | The server did not start or did not answer (the last lines of its stderr are printed, secrets masked), or a flag or the exceptions file is wrong. |
3 | Nothing measured: the server lists no tools, a rule could not run, or with --call a call could not run or no tool could be called. A server with no tools is not a clean one. |
Reports for CI
Section titled “Reports for CI”--format json prints one document (kind: mcp-lint-report), the same bytes for the same server.
--format github prints annotations for a GitHub Actions step, --format markdown a pull request
comment, and --reporter junit-xml --out lint.xml a JUnit file for plune run import. Examples of
each are on MCP server checks in CI and
Test an MCP server.