mcp-doctor

Lint MCP servers for what breaks the agent calling them. Reads Python, TypeScript and Go source without running it, and grades quality and security separately.

Real output from a live scan of homeassistant-ai/ha-mcp (4.9k★) — not a cherry-picked fixture. Full example further down uses the bundled sample server for a smaller walkthrough.

Try it in 30 seconds

• In your browser: check any MCP server. Paste a GitHub repo, npm or PyPI name and get both grades in seconds. The real mcp-doctor runs in your browser (Pyodide); nothing is uploaded or run.
• No install, as a GitHub issue: open a scan request with your server’s GitHub URL. A bot replies with the report in a few minutes. It reads the code only and never runs it. Security findings are posted as counts only, since the issue is public.
• CLI: pip install mcp-server-lint, then mcp-doctor path/to/your/server
• Running an agent? Put mcp-doctor guard in front of any MCP server, and the agent is told when a tool says “success” but the write didn’t land, its arguments were ignored, or it didn’t do what it claims
• Claude Code: /plugin install mcp-doctor --marketplace vishalhabib99/mcp-doctor, then ask “check my MCP server”. Claude scans, explains each finding, and fixes what it can with your OK (details)
• CI: uses: vishalhabib99/mcp-doctor@v1 comments on each PR, suggests one-click fixes on the lines it changes, and can fail a PR that drops below your score (details)

Why trust the grade

• Recall is measured in the open: 15,755 of 15,977 tools found across 805 real servers on 5 frameworks. Every miss is listed in docs/coverage.md.
• 112 bugs found and fixed after release by running it on 40+ real servers, up to the 91.0k★ official modelcontextprotocol/servers monorepo. How 69 of them got through.
• Maintainers act on the reports: fixes merged upstream, e.g. ha-mcp (4.9k★). Every audited repo is ranked on the leaderboard, with a dated grade badge you can add to your README.

Guard — catch tool calls that report success but didn’t work

mcp-doctor guard runs any stdio MCP server behind a check. Every message passes through unchanged; after each tools/call it looks for a “success” that isn’t one and, if it finds one, adds a warning to the result the agent reads, so the agent can retry or tell you instead of saying “done”.

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-doctor",
      "args": ["guard", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

What it looks like to the agent, same broken write_file, same prompt, Claude Code:

Without guard: “Yes, the file was saved. The fs server’s write_file tool reported success…”

With guard: “I can’t confirm the file was saved. write_file returned ‘Successfully wrote to /tmp/q3/report.md’, but the result also carried a warning that a read-back of that path failed with ‘no such file or directory’.”

The refusal, empty-read and output-schema checks came from mcp-reality-check, which folded into guard: the same phrase list (including its fix for documents that quote a refusal), now applied to every real call instead of one synthetic call per tool. The schema check is built in (no jsonschema dependency) and covers type, required, properties, items, enum, const, anyOf and oneOf; it accepts anything it doesn’t understand rather than guess.

How the leak check works: every result is fingerprinted as line and secret hashes (never the text) in a journal shared by the guards one client started, so outside content fetched through one server and a write made through another are seen together. It stays quiet on copying within the same repo, on quoting the outside content itself, on copying between repos when no outside content was read, and on a single short shared line. By default it warns; --hold-leaks returns an error instead of sending the write. It matches copied text, so a leak the model paraphrases can get past it; in a Claude Code run against an injected issue, Haiku refused the injection itself, so this is a net for when the model is fooled, not a replacement for least-privilege tokens.

How it confirms a write: it pairs the write with a read tool on the same thing (write_file → read_text_file, issue_write → issue_read), calls it with the write’s own arguments or the id it returned, and checks the written values are there. It tries up to three matching reads and warns only if none confirms the write. It only ever calls tools the server marks readOnlyHint: true (or, on a server that declares no annotations, tools named read_/get_/fetch_…); --no-verify turns read-backs off. It never blocks a call or changes isError. Findings also go to stderr, and to --log FILE as JSON lines.

Checked on real servers before release: filesystem (11 calls: writes, edits, moves, a rejected typo, an access-denied path), memory (6), everything (10): no warnings on calls that worked. Caught: playwright-mcp 0.0.82’s short wait and FastMCP’s dropped argument. Tests: tests/test_guard.py reproduces each issue above against a fake server, each with a healthy twin that must stay quiet.

Limits: stdio servers only (not HTTP yet). Writes are confirmed only when the server has a matching read tool. Values the server rewrites on the way in (formatting, normalization) can read as missing.

What it is

A static analysis CLI that audits MCP (Model Context Protocol) server implementations for the things that actually break an agent calling them: missing tool descriptions, undocumented parameters, no error handling, no README coverage — plus a separate security score covering prompt-injection-prone tool descriptions (“tool poisoning”), dangerous dynamic execution, SSRF-prone outbound requests, unsafe deserialization, and hardcoded secrets. Quality and security are scored independently: a repo can be a documented, well-tested A on quality and still have a real security gap, and the two shouldn’t be blended into one number that hides which is true.

The MCP ecosystem is growing faster than the conventions around building a good server have settled. Most servers are hand-written in an afternoon and never checked against anything. mcp-doctor is a linter for that gap — point it at a repo, get a score and a concrete list of what to fix.

mcp-doctor reads source and never runs it, so it can’t see everything. Two companion tools cover what’s left: mcp-fuzz actually launches a server and calls its tools with schema-derived bad input to see if it fails safely or crashes; mcp-reality-check calls a tool with a realistic valid input and checks whether the response is a genuine answer — not a disguised refusal, not empty, not violating its own declared output schema. Three independent checks: is it documented, does it fail safely, does it actually work.

Dogfooded against 40+ real, in-the-wild MCP servers across Python, TypeScript, and Go (up to 91.0k★ with the official modelcontextprotocol/servers monorepo, including GitHub’s own official server at 33.3k★, and official servers from Red Hat, Brave, and MathWorks) — 101 genuine mcp-doctor bugs found and fixed post-release, plus Go support itself (the official SDK’s two registration styles and mark3labs/mcp-go’s) built and verified against real Go servers before ever shipping. One fix led to a PR merged upstream into a 4.9k★ repo; a separate clean pass surfaced a real doc-coverage gap in a target repo itself, filed upstream. Tool-detection recall is measured in the open: 15,755 of 15,977 tools found across 805 real servers on 5 frameworks, every miss listed in docs/coverage.md. What the first outside users hit, and what changed because of it: docs/what-users-taught-me.md. How 69 bugs got through, and what changed to stop the worst kind: docs/postmortem-69-bugs.md. See Real-world spot check below, or the live leaderboard ranking every audited repo by quality + security grade — each scored repo gets a real, dated SVG badge (![mcp-doctor](https://vishalhabib99.github.io/mcp-doctor/badges/OWNER-REPO.svg)) showing its actual grade, not a generic “scanned” badge, free to add to your own README. The leaderboard also tracks drift: every re-scan compares against whatever was live before it, so a grade change shows a real ▲/▼ delta instead of silently overwriting the old number.

$ mcp-doctor examples/bad_server
mcp-doctor report
Quality:  13%  Grade: F  (2 tool(s) found)
Security: 100%  Grade: A

  [FAIL] do_thing (server.py:9)
      ERROR  Tool has no description. An agent cannot decide when to call this.
      WARNING  2/2 parameters have no type annotation.
      WARNING  Parameters aren't documented in an Args: section — the model only sees names, not intent.
      WARNING  No try/except — an exception here will raise a raw traceback back through the MCP transport.
  [FAIL] run (server.py:15)
      ERROR  Tool has no description. An agent cannot decide when to call this.
      WARNING  1/1 parameters have no type annotation.
      WARNING  Parameters aren't documented in an Args: section — the model only sees names, not intent.
      ERROR  Bare 'except:' swallows all errors including cancellation — catch specific exceptions.

Repo-level
  ERROR  No README found.
  WARNING  No LICENSE file — undermines adoption.
  WARNING  No test files found.
  WARNING  No pyproject.toml/requirements.txt/setup.py — dependencies aren't pinned.

$ mcp-doctor examples/good_server
mcp-doctor report
Quality:  100%  Grade: A  (1 tool(s) found)
Security: 100%  Grade: A

  [OK] get_forecast (server.py:9)

Install

pip install mcp-server-lint

(The PyPI project is named mcp-server-lint — mcp-doctor and every close variant of it were already taken or blocked by PyPI’s anti-typosquat check — but the installed command is still mcp-doctor.)

Or install straight from the repo:

pip install git+https://github.com/vishalhabib99/mcp-doctor.git

or clone it and install locally:

git clone https://github.com/vishalhabib99/mcp-doctor.git
cd mcp-doctor
pip install -e .

Usage

mcp-doctor .                      # audit the current directory
mcp-doctor path/to/server         # audit a specific path
mcp-doctor . --json               # machine-readable output
mcp-doctor . --fail-under 80      # exit 1 if score drops below 80% — wire into CI
mcp-doctor . --diff               # preview the safe fixes as a patch (pipe to `git apply`); changes nothing
mcp-doctor . --fix                # apply safe, mechanical fixes in place, then re-report
mcp-doctor . --fix --fix-only none-default  # one kind of fix only (none-default, bare-except, args-stub), e.g. one kind per PR

--fix only touches what’s safe to fix without human judgment:

• None defaults typed nullable: name: str = None becomes name: str | None = None (or Optional[str] when the file already imports Optional); inside Annotated[...] only the type is wrapped. This is the bug behind the telegram-mcp and davinci-resolve-mcp fixes. On 47 real servers it fixed all 42 flagged tools (69 parameters), and on the three repos with a hand-written PR for the same bug, it produced exactly the same type changes.
• Missing parameter docs: a tool with no parameter docs gets an Args: section with TODO: describe this parameter. placeholders; a tool with a Google-style Args: section that leaves some out gets the missing names appended to it. A name already mentioned in the section in a form the scanner can’t parse (color_from / color_to: ...) is left for a human rather than duplicated.
• Bare except: narrowed to except Exception:.

It never fabricates a real description, guesses at an untyped parameter’s type, wraps a function body in try/except, or merges into a :param: or NumPy docstring. Every patched file is re-parsed before it’s written.

Schema/contract diff — catch a breaking change between releases

Everything else here scores a single snapshot. This compares two: save a --json run as a baseline, then re-run later against --diff-against that file to catch a tool that’s gone, a parameter that’s gone, or a parameter that’s newly required — the three ways a schema change breaks an agent that already learned the old shape without anyone noticing, since none of them show up in a normal diff review the way a removed function would.

mcp-doctor . --json > baseline.json        # save today's schema as a baseline
# ... time passes, the server changes ...
mcp-doctor . --diff-against baseline.json  # compare against it
mcp-doctor . --diff-against baseline.json --fail-on-breaking-change  # non-zero exit in CI

Deliberately doesn’t touch the quality/security scores — those are properties of one snapshot, this is a property of two compared, a different kind of question with its own exit code. A new tool or a new optional parameter is never flagged — nothing an existing caller relied on stopped working. Python only for now (parameter presence and required-ness — not types), same incremental language-by-language pattern as the rest of this analyzer.

GitHub Action

Gate PRs on server quality without installing anything yourself:

Fastest way: run mcp-doctor init-action in your repo (or mcp-doctor init-action path/to/server for a server in a subdirectory). It writes .github/workflows/mcp-doctor.yml in report-only mode, plus mcp-doctor-comment.yml so PRs from forks get the report too, and shows the grade your PRs will start from. Run it again on an existing install to add just the comment workflow. --fail-under 70 turns on the gate; --print shows the file without writing it. Or copy it by hand:

name: mcp-doctor   # the comment workflow below finds the scan by this name
on: pull_request
permissions:
  contents: read
  pull-requests: write   # for the report comment and fix suggestions
jobs:
  mcp-doctor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: vishalhabib99/mcp-doctor@v1
        with:
          path: .              # default: repo root
          fail-under: 70        # default: 0 (report only, don't fail the build)
          comment: true          # default: true — posts/updates a PR comment with the report
          suggest-fixes: true    # default: true — one-click fix suggestions on the PR's lines

Fix suggestions: on a pull request, the safe fixes from --fix (a None default typed as nullable, a bare except:) are posted as GitHub suggestion blocks on the lines the PR changes, so accepting one is a click. Missing Args: entries aren’t suggested by default, because --fix can only add a TODO: describe this parameter. placeholder; the report counts those tools instead. Set suggest-doc-stubs: true to get the placeholders as suggestions too. GitHub only allows suggestions inside the PR’s diff, so fixes on other lines are counted in the report comment with the full patch, ready for git apply. A re-run never posts the same suggestion twice. PRs from forks: GitHub gives a fork’s PR a read-only token, so the scan can’t comment there. It saves the report and suggestions as a 3-day artifact instead, and a second workflow posts them once the scan finishes. That workflow gets the write token, never checks out the PR’s code, looks the PR up from GitHub’s event rather than the artifact, rebuilds each suggestion field by field and defuses @mentions. init-action writes it; by hand it’s:

name: mcp-doctor comment
on:
  workflow_run:
    workflows: ["mcp-doctor"]   # the scan workflow's name
    types: [completed]
permissions:
  actions: read
  pull-requests: write
jobs:
  comment:
    if: github.event.workflow_run.event == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: vishalhabib99/mcp-doctor/comment@v1

GitHub only runs a workflow_run workflow from the default branch, so fork PRs get comments once it’s merged. Without it, the report stays in the job summary.

The report also gets written to the job summary either way. @v1 tracks the latest v1.x release; pin an exact tag or commit SHA instead if you need stricter reproducibility. Pinning the action pins the analyser too: it installs mcp-doctor from the action’s own checkout, not from main (set version: to a branch, tag or commit to override). The scan never imports code from the repo it checks: every Python call runs with -I, so a json.py or mcp_doctor/ in a PR can’t shadow the installed modules, and the actions it uses are pinned by commit.

Want mcp-fuzz’s runtime resilience checks and mcp-reality-check’s output-fidelity checks in the same PR check, not just this one? mcp-trust-check wraps all three behind a single Action and one combined score.

pre-commit hook

Catch it before the push. Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/vishalhabib99/mcp-doctor
    rev: v1.18.4
    hooks:
      - id: mcp-doctor
        # args: ["--fail-under", "80", "path/to/server"]   # default: --fail-under 70 on the repo root

It runs when a commit touches .py, .ts/.tsx, .js/.mjs/.cjs or .go files and fails the commit if the quality score is under the threshold. A repo where no tools are found gets a warning and passes, same as --fail-under on the CLI.

Claude Code plugin

Run the same scan without leaving Claude Code, and let Claude fix what it finds:

/plugin install mcp-doctor --marketplace vishalhabib99/mcp-doctor

(On Claude Code before 2.1.275: /plugin marketplace add vishalhabib99/mcp-doctor, then /plugin install mcp-doctor@mcp-doctor.)

Then ask “check my MCP server”, or run /mcp-doctor:mcp-doctor path/to/server. The skill also kicks in when you’ve just written or changed tool definitions and ask for a check. It:

1. runs the CLI (via uvx, so nothing to install if you have uv) and reports both grades plus the top five findings, in terms of what breaks for the agent;
2. shows the --diff for the mechanical fixes and applies them on your yes;
3. writes the judgment fixes the CLI can’t (tool and parameter descriptions, actionable error messages, stdout writes on a stdio server) after reading what each tool actually does, never inventing behavior;
4. re-scans and shows before → after, then offers init-action to keep it checked on every PR.

Fixing someone else’s server: fix-upstream. In a local clone of a third-party MCP server, run /mcp-doctor:fix-upstream (or ask Claude to “draft a PR for this finding”). It turns a null-default finding into a pull-request draft a maintainer can merge: it first checks for an existing issue or PR and the repo’s contribution rules, skips fixtures, examples and unregistered functions, writes a regression test that fails before the fix and passes after, and runs the repo’s own tests before and after. It stops at a local branch plus a PR description in the repo’s template. It never pushes or posts; you review and send. Patches over ~30 parameters become an issue draft instead. On the code from before 15 merged upstream null-default fixes, it changed the same parameters the maintainers merged in all 15 (v1.19.0 release notes).

Security findings are explained, not silently rewritten. The plugin lives in plugin/ and ships with an eval suite in plugin/evals/: it checks when the skill should and shouldn’t fire, that it reports the real grades, and that it doesn’t “fix” a clean server or write tool descriptions the code doesn’t back up.

Runtime gate — the same two checks, applied to live tools/list metadata

Unlike its two siblings (mcp-fuzz, mcp-reality-check), which already connect to a real server to run their checks, mcp-doctor has never made a live call to anything — it only ever reads source. check_tool_registration keeps that true: it’s a pure function over tool metadata your own MCP client already fetched, not a connection of its own. No new dependency, no mcp package required.

from mcp_doctor.gate import check_tool_registration

# tools = (await session.list_tools()).tools, from your own client
for tool in tools:
    result = check_tool_registration(tool.name, tool.description, tool.annotations)
    if result.flagged:
        ...  # missing/vague description, or a real readOnlyHint/destructiveHint conflict

Narrower than the full static analyzer, honestly: the read-only/mutation-signal-mismatch check (does a tool’s own code actually write despite claiming readOnlyHint: true) has no live counterpart — an agent discovering tools at runtime has no access to server source, only what the server declares about itself. What’s checkable from declared metadata alone: description quality, and whether a tool’s own annotations are internally consistent.

The annotation-contradiction rule here is deliberately not a direct port of the static check. Dogfooding against the real official @modelcontextprotocol/server-memory reference server, before this ever shipped, found the static check’s rule — flag destructiveHint merely being present alongside readOnlyHint: true, regardless of its value — miscalibrated for live data: that server explicitly declares all four ToolAnnotations fields on every tool as a matter of good, complete practice (read_graph: readOnlyHint=true, destructiveHint=false — sensible and consistent), which the presence-only rule flagged as contradictory anyway. Presence is a fair proxy for “copy-paste leftover” in source code, where an author who didn’t think about a field usually doesn’t write it; at the wire level, a careful implementer setting every field explicitly is common, not a bug. Fixed before shipping: the live check requires destructiveHint to actually be true, not merely set, alongside readOnlyHint: true — re-verified clean (0/9 false positives) against the same reference server afterward.

What it checks

Audits Python, TypeScript/JavaScript, and Go servers in the same repo. Python detects the FastMCP @mcp.tool() decorator style, FastMCP’s by-reference forms (mcp.tool(fn), mcp.tool(...)(fn), mcp.add_tool(fn), Tool.from_function(fn, ...), with fn followed into the module it’s imported from or to a self. method), and the low-level SDK’s Tool(name=..., description=..., inputSchema=...) style; TS/JS detects the official SDK’s server.registerTool(name, config, handler) and server.tool(name, description, schema, handler) styles, including the common pattern where the config object or Zod schema is a same-file const reference rather than inline; Go detects the official modelcontextprotocol/go-sdk’s generic mcp.AddTool(server, &mcp.Tool{...}, handler) (checking parameters documented either via an explicit InputSchema or via json/jsonschema struct tags on the handler’s argument type — the SDK’s own schema-inference convention) and mark3labs/mcp-go’s older s.AddTool(mcp.NewTool(name, mcp.WithDescription(...), mcp.WithString(...)), handler) fluent-builder style, where every parameter is declared inline. The same checks apply across languages — a description and per-parameter docs (Args:/Field(description=...) in Python, .describe(...) on each Zod field in TS, a jsonschema:"..." struct tag or mcp.Description(...) builder call in Go) — except error handling, which isn’t checked for Go (see Known limitations: Go’s failure model is different enough from Python/TS exceptions that a naive port risked being wrong, not just incomplete).

Per tool:

Repo-level:

• README exists, and mentions every tool you export
• LICENSE exists
• Tests exist
• Dependencies are declared (pyproject.toml / requirements.txt / setup.py / package.json)
• Tool names conform to the spec’s Tool Names guidance (1–128 chars, A-Z a-z 0-9 _ - . only, unique within the server)

Security checks

Scored as a separate axis from quality (its own percent/grade) — a repo can be a well-documented A on quality and still have a real security gap, and the two shouldn’t be blended into one number that hides which is true. These matter specifically because an MCP tool is invoked autonomously by a model, not a human clicking through a UI: an unvalidated input here is triggered by model-generated tool-call arguments, not a person typing into a form.

Real-world spot check

Run against 40+ real MCP servers in the wild, not just the fixtures in examples/. Every fix below was verified against the actual repo before/after, not just against a synthetic test case.

Known limitations

• AST-based, single-pass. Tools constructed dynamically in a loop, or schemas built from something other than a dict literal or a pydantic model_json_schema() call, won’t be fully introspected — you’ll get the tool detected but a blind spot on its parameter-level checks rather than a false failure. A dynamic tool name (not a string literal, e.g. built in a loop) means the tool is skipped entirely rather than misattributed.
• Class-based tool registries (Python low-level Server) aren’t introspected at all. A common pattern for larger servers: one class per tool exposing get_name()/get_description()/get_input_schema(), instantiated into a registry dict, and marshaled into Tool(...) objects in a loop at list-time (Tool(name=tool.name, description=tool.description, ...)). The name/description/schema are all dynamic at that call site by construction, so — same as any other dynamic name — the tool is correctly skipped rather than misreported, but that means these tools aren’t audited at all, not even for description length or param docs. Unlike the TS ListToolsRequestSchema static-array style (which is supported), the underlying values here are typically returned from real methods across a class hierarchy, sometimes built by imperative code rather than a literal — reliably resolving that is a materially bigger undertaking than a scoped fix, and hasn’t been attempted.
• Parses with the running interpreter’s grammar (Python side). See the spot check above — run under a Python version that matches or exceeds the syntax used in the server you’re auditing.
• Delegation resolution is Python-only, name-based (not fully import-resolved or type-resolved), and only covers direct calls. If a Python tool hands off (directly or several calls deep, including through an aliased from x import y as z import, and including via an object method like client.request(...) as well as a bare function) to a locally-defined helper that has its own try/except, the error-handling check follows that chain by name across the whole repo — but two different functions or methods sharing the same name aren’t distinguished (same simplification already accepted for the Field alias registry), which is a materially higher risk for a very common method name (get, run, close) than for a distinctively-named bare function, and it’s capped at 5 hops. It also only recognizes the helper being called directly (helper(...)/obj.helper(...)) — a helper merely passed somewhere, e.g. asyncio.to_thread(helper, ...) or executor.submit(helper, ...), isn’t resolved, since that covers an open-ended set of “runner” call shapes rather than one well-defined pattern. The TS/JS side has no equivalent yet — a tool that hands off to a helper .catch()/try-block still reports a false positive there.
• TS/JS cross-file resolution is name-based, not fully import-resolved. A tool’s name/config/schema referenced via fooTool.name-style member expressions on an exported object literal (including through as const/satisfies) is resolved repo-wide by matching the object’s declared name. Unlike the Python side’s equivalent simplifications (which do resolve regardless of name collisions, at the cost of some precision risk), the TS/JS const registry treats a name declared more than once anywhere in the same file — even in two unrelated local scopes — as ambiguous and leaves it unresolved entirely, rather than risk silently picking the wrong one; a description or schema built by a runtime function call (e.g. fooTool.getDescription(x)) is genuinely dynamic and is likewise correctly left unresolved, not guessed at.
• No local-variable data-flow tracking. _resolve follows a single expression (an identifier to its declaration, a member access, a || default, a .filter() call) but doesn’t track a variable across multiple statements — a reassignment, a .push(...), or a conditional .map(...) rewrite later in the same function body isn’t seen. A ListToolsRequestSchema handler that builds its tool list this way (env-var-gated .push(), client-detection-based .map() rewrites, as in n8n-mcp) reports 0 tools rather than a guessed, possibly-wrong list — correct, but incomplete for that style of server.
• The low-level Server SDK style (setRequestHandler(ListToolsRequestSchema, ...)) is not checked for error handling. There’s no per-tool handler closure in this style — one generic dispatcher, keyed by tool name, serves every tool (and may proxy the real work to an entirely different process, as with a Chrome-extension-backed server), so flagging “no try/catch” per tool would be structurally meaningless. Only description and JSON-Schema properties[x].description are checked for this style.
• Duplicate-tool-name check has no call-graph or runtime-profile awareness. It flags any two same-named registerTool/tool/addTool calls found anywhere in the source, even when they’re on different server instances or gated behind mutually-exclusive runtime branches (e.g. an env-var-selected profile) that can never both register at once — a real pattern in firecrawl-mcp-server. Treat this warning as “worth a human glance,” not a guaranteed live conflict.
• --fix only fixes the fully-undocumented case, Python only. If a docstring already documents some params but not all, --fix leaves it alone rather than risk merging into it incorrectly — you’ll still see the warning, just not an auto-stub. TS/JS and Go files aren’t touched by --fix at all yet.
• Go: error handling isn’t checked at all. Go has no exception mechanism — a handler communicates failure through its error return value, which the SDK already turns into a structured tool error either way — and what a genuinely useful Go-specific check should even look for (a bare panic with no recover? an ignored error from a called function?) hasn’t been researched carefully enough yet to check for without risking a check that’s wrong rather than just incomplete.
• Go: heavily customized in-house registries built on top of either SDK aren’t introspected. github/github-mcp-server (32k★) wraps the official SDK in its own bespoke tool registry (middleware, OAuth-scope gating, generated handlers) rather than calling mcp.AddTool directly at any single, simple call site — same category of gap as Python’s class-based low-level Server registries, and left undone for the same reason: reliably resolving it is a materially bigger undertaking than a scoped fix.
• The description-length heuristic weighs script density via Unicode’s East Asian Width property, not a full per-language model. Fixed (see the thirtieth pass) for CJK and other Wide/Fullwidth scripts, verified on a real repo (xiaohongshu-mcp’s Chinese descriptions). A script that packs more meaning per character than Latin but isn’t classified Wide/Fullwidth by Unicode (e.g. Arabic, Devanagari, Cyrillic) still counts 1 column per character — a real, narrower residual gap than the one just closed, not yet found misfiring on an actual repo.
• --diff-against only tracks parameter presence and required-ness, not types. A parameter that changes type without changing name or required-ness (e.g. str → int) isn’t caught, for any Python registration style. TS/Go tools have empty param_names/required_param_names in both snapshots, so a real schema change there is silently a no-op rather than a false positive — correctly incomplete, not wrong, but still a real coverage gap. Within Python, the raw-schema-dict Tool(name=..., inputSchema={...}) constructor style is only as complete as the schema is statically resolvable: a dynamic property key or an unresolved **spread_call() drops that tool’s required_param_names back to empty and marks param_names_complete false, so param_removed detection is skipped entirely for that tool rather than risk a false positive from partial coverage (see analyzer.py’s _find_lowlevel_tools and schema_diff.py).

Roadmap

• [x] TypeScript/JS server support (the official SDK’s dominant language) — registerTool/tool styles, cross-file const/member-expression resolution, the community fastmcp package’s addTool single-object style, and the low-level Server SDK’s static setRequestHandler(ListToolsRequestSchema, ...) style
• [x] Publish to PyPI
• [x] GitHub Action for one-line CI integration
• [x] --fix for the genuinely mechanical stuff (bare except:, fully-undocumented Args: stubs) — deliberately does not auto-wrap function bodies in try/except; generating a correct wrapper for arbitrary code (preserving return semantics, control flow) needs more judgment than a mechanical pass should take on
• [x] Go server support — the official modelcontextprotocol/go-sdk’s AddTool style (explicit and struct-tag-inferred schemas) and mark3labs/mcp-go’s older fluent-builder style
• [x] Claude Code plugin — scan and fix from inside the editor, with an eval suite

Contributing

Issues and PRs welcome. The test suite (pytest) covers the analyzer directly and the CLI end-to-end against the fixtures in examples/ — add a fixture case for anything you fix.

License

MIT — see LICENSE.