Skip to content

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.

A notebook server of three tools, about 50 lines on the official SDK, written with three defects on purpose:

  1. get_note has no description;
  2. the status parameter of set_status lists its values in the description instead of an enum;
  3. list_notes returns a list but takes no limit.
  1. 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 limit
    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: {} },
    annotations: readOnly,
    },
    {
    name: "get_note", // defect 1: no description
    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." },
    // defect 2: the allowed values are in the description instead of an enum
    status: { 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());
  2. Install its one dependency:

    Terminal window
    npm install
  3. Lint it:

    $ npx -y @plune-ai/cli@0.39.9 mcp lint -- node server.mjs
    Server: 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-description
    warn 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: 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.mjs
Server: 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-description
warn 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 $?
1

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.

server-fixed.mjs
// 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.mjs
Server: mcp-sample-server 1.0.0 · stdio · 3 tools
0 errors, 0 warnings, 0 info, 0 suppressed · failing on: info
$ echo $?
0

--fail-on decides which findings make the run exit 1. The others are still printed and counted.

--fail-onExit 1 onUse it for
error (default)an error findinga gate on what breaks the specification
warna warn or error findinga server whose tool list you keep clean of advice too
infoany findingthe strictest review
nevernothinga 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.

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 warn at 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.

RuleClassLevelWhat it reportsBefore → after
input-schema-not-objectdeterministicerrorThe 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-objectdeterministicerrorThe output schema is given, but its root is not of type “object”."outputSchema": {"type": "array"} → "outputSchema": {"type": "object", "properties": {"notes": {"type": "array"}}}
required-unknown-propertydeterministicerror”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-duplicatedeterministicerrorTwo tools share a name, so only one of them can be called.two tools named search → search_notes and search_tags
name-invaliddeterministicwarnThe name uses characters or a length outside what the specification recommends.get notes! → get_notes
desc-missingdeterministicwarnThe 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-shortheuristicinfoThe 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-longheuristicwarnThe 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-notheuristicinfoThe 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-similarheuristicwarnTwo 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-textheuristicwarnA 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-nameheuristicwarnA parameter named like a number, flag, date or URL is a free string."limit": {"type": "string"} → "limit": {"type": "integer"}
param-desc-missingheuristicinfoA parameter has no description."id": {"type": "integer"} → "id": {"type": "integer", "description": "The id of the note."}
param-example-missingheuristicinfoA free-form object parameter has no example of its keys."filter": {"type": "object"} → "filter": {"type": "object", "examples": [{"status": "open"}]}
required-missingheuristicinfoThe input schema has parameters but no “required” list.properties with no required → "required": [] when every parameter is optional
name-style-mismatchheuristicwarnThe name does not follow the naming style of the other tools.getNote beside list_notes and set_status → get_note
name-not-snakeheuristicinfoThe name is not snake_case.getNote → get_note
annotations-missingdeterministicinfoThe tool has no annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).no annotations → "annotations": {"readOnlyHint": true, "destructiveHint": false}
hint-readonly-writesheuristicwarnThe tool is marked read-only, but its name says it changes something.delete_note with "readOnlyHint": true → "readOnlyHint": false
hint-destructive-understatedheuristicwarnThe tool says its updates are additive, but its name says it overwrites or removes.set_status with "destructiveHint": false → "destructiveHint": true
hint-idempotent-missingheuristicinfoA 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-pagingheuristicwarnA 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-sizemeasurewarnThe 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-largemeasurewarnOne 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-textdeterministicwarnA 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-textheuristicinfoThe 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-mismatchdeterministicerrorA 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.

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.mjs
Server: 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-description
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.
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 $?
0

The suppressed finding is still listed, with its reason, and counted in the summary.

  • An entry without a reason stops the run with exit 2 and the line number.
  • tool and param narrow an entry; without tool it covers the rule on every tool.
  • An entry past its expires date 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.

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.mjs
Server: 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 $?
0

get_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.

ExitMeaning
0No finding at the --fail-on level, and everything was measured.
1At least one finding at the --fail-on level or above.
2The 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.
3Nothing 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.

--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.