Skip to main content

mcp-contrast

CI License: MIT Python 3.11+

Lint MCP servers for tools a model cannot tell apart.

mcp-contrast finds pairs of tools that look interchangeable to an LLM: get_user next to fetch_user, list_deals next to an unexplained list_all_deals, two differently named tools with the same description. It runs in CI, fully in memory, in under a second once its 30 MB model is cached.

$ mcp-contrast check examples/crm.json
crm (10 tools)
  error    synonym-contrast   get_person <-> fetch_person  examples/crm.json:3
           'get_person' and 'fetch_person' differ only by near-synonyms "get" / "fetch", which
           give a model nothing to choose on.
           fix: Merge the tools, or rename so the differing word states the real difference
                (scope, target, side effect).

  warning  unmarked-contrast  list_deals <-> list_all_deals  examples/crm.json:7
           'list_all_deals' adds "all" to 'list_deals', but its description never says what
           "all" changes (similarity 0.83).
           fix: State the difference in each description using the word that differs in the
                name, or name the other tool explicitly.

  warning  hidden-overlap     search_notes <-> find_notes_by_text  examples/crm.json:9
           'search_notes' and 'find_notes_by_text' have near-identical descriptions (similarity
           1.00) and neither says when to use it instead of the other.
           fix: Merge the tools, or add a line to each description such as "Use
                find_notes_by_text instead when ...".

✖ 3 problems (1 error, 2 warnings) - 10 tools in 1 server, 3 clean contrasts

Why

Linguists call it the principle of contrast: listeners assume that two different words mean two different things. Eve Clark proposed it to explain how children learn words (Clark 1987), and it is the idea this project is built on. Models do the same. Given get_user and fetch_user, a model looks for a difference, finds none in the descriptions, and picks one at random.

The naive fix, flagging tools whose descriptions are similar, does not work. Well-designed families like update_person / update_company are supposed to look alike: they differ in exactly the word the model needs. An earlier linter (mcp-doctor) tried a similarity score, found it mostly flagged these families, and fell back to near-exact matching.

mcp-contrast keeps the semantic signal and asks a second question: where do the two names differ, and do the descriptions say so?

Pair Names differ by Descriptions Result
update_person / update_company person / company each mentions its own noun clean
get_user / fetch_user get / fetch (synonyms) n/a synonym-contrast
list_deals / list_all_deals inserted "all" "all" never explained unmarked-contrast
search_notes / find_notes_by_text no shared structure near-identical hidden-overlap
read_file / read_text_file inserted "text" read_file says "use read_text_file instead" clean

Compared with other MCP linters

Several linters flag confusable tools. They differ in how they decide two tools are too alike:

How it finds confusable tools Catches paraphrases Lets clean families pass Reads Also checks
mcp-contrast Description embeddings, plus where the names differ and whether each description states it Yes (embeddings) Yes: each description must use its own differing word Snapshots, client configs, live stdio and HTTP servers Nothing else
lintlang Word overlap (Jaccard), plus a synonym list over name and description terms Partly, through its synonym list Yes, when each tool has a term the other lacks MCP and tool definitions in repository files Prompts, schemas, skills
mcplint Descriptions with 75% or more word overlap No No word-level check Live stdio servers, client configs Token cost, naming, schemas, hidden text
mcp-lint Names that are reordered, plural, or close by edit distance No No word-level check tools.json Per-tool design scores
mcp-doctor Identical descriptions after normalizing No Yes, by flagging only exact copies Server source code, live tools/list Quality grades, fuzzing, fixes
mcp-tef Embedding similarity matrices and LLM tool-selection tests Yes Not automatically: it reports scores to review A running evaluation service LLM selection accuracy

What mcp-contrast adds is the per-word check. Word overlap can't tell update_person / update_company (a good family) from list_deals / list_all_deals (an unexplained difference), because both pairs share almost every word. Exact matching misses paraphrases. LLM evaluation catches both but needs a model and a running service. mcp-contrast runs in CI in under a second with a 30 MB static model and no API key, and each finding names the exact word a description fails to explain.

It does only this one check. Use it alongside a broader linter: lintlang, mcplint, or mcp-doctor for schemas, safety, and token cost, and mcp-tef to measure real selection accuracy with a model.

Install

uvx mcp-contrast check tools.json          # run without installing
pipx install mcp-contrast                  # or install the CLI
pip install mcp-contrast                   # or into an environment

Requires Python 3.11+. No PyTorch, no GPU, no API keys.

Usage

# A saved tools/list response (or a bare array of tools)
mcp-contrast check tools.json

# A live stdio server
mcp-contrast check --stdio 'npx -y @modelcontextprotocol/server-filesystem /tmp'

# A live Streamable HTTP server
mcp-contrast check --http https://mcp.example.com/mcp --header "Authorization: Bearer $TOKEN"

# Every server in a client config (Claude, Cursor, or VS Code format)
mcp-contrast check .mcp.json
mcp-contrast check .mcp.json --cross-server   # also compare tools across servers

# Save a live server's tools for linting in CI
mcp-contrast snapshot --stdio 'node dist/index.js' -o tools.json

mcp-contrast only performs the MCP handshake and tools/list. It never calls a tool.

Flag Default
--format text text, json, sarif, or github (workflow annotations)
-o, --output stdout write the report to a file
--sarif PATH also write SARIF, alongside the main format
--fail-on error lowest severity that exits 1: error, warning, info, never
--show-clean off list the similar pairs that passed, and why
--baseline PATH ignore findings recorded in a baseline
--write-baseline record current findings into --baseline and exit 0
--cross-server off compare tools across servers, as a client loading all of them would
--embedder model2vec lexical for a zero-download fallback
--threshold 0.85 description similarity that makes an unrelated pair a candidate
--aligned-threshold 0.70 the same, for pairs whose names differ in one word
--near-identical 0.95 similarity above which descriptions count as the same

Exit codes: 0 clean, 1 findings at or above --fail-on, 2 usage or input error.

Run mcp-contrast rules for the rule list, or see docs/rules.md.

CI

GitHub Action

name: MCP tools
on: [pull_request]

permissions:
  contents: read
  security-events: write   # only for the SARIF upload

jobs:
  contrast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tchoedak/mcp-contrast@v0.1.0
        with:
          sources: tools.json
      - uses: github/codeql-action/upload-sarif@v4
        if: always()
        with:
          sarif_file: mcp-contrast.sarif

Findings appear as annotations on the pull request. The SARIF upload is optional and puts them in the repository's code scanning tab.

To lint a server you build in the same job, start it through args:

      - run: npm ci && npm run build
      - uses: tchoedak/mcp-contrast@v0.1.0
        with:
          args: --stdio 'node dist/index.js'
Input Default
sources space-separated snapshots or client configs
args extra CLI arguments, shell-quoted
fail-on error
sarif-file mcp-contrast.sarif empty to skip
working-directory .

The action caches the embedding model between runs.

Anywhere else

The CLI is the integration: uvx mcp-contrast check tools.json --format sarif -o report.sarif works in GitLab CI, CircleCI, Buildkite, or a pre-commit hook.

Adopting on an existing server

mcp-contrast check tools.json --baseline .mcp-contrast-baseline.json --write-baseline

Commit the baseline. Later runs with --baseline fail only on new findings. Fingerprints are the rule plus the pair of tool names, so unrelated edits do not invalidate them.

Configuration

Settings live in mcp-contrast.toml, .mcp-contrast.toml, or [tool.mcp-contrast] in pyproject.toml, discovered from the working directory up to the repository root. CLI flags win.

# mcp-contrast.toml
fail-on = "warning"
threshold = 0.85
aligned-threshold = 0.70

# Domain words your users treat as interchangeable.
synonyms = [["ticket", "issue"], ["workspace", "project"]]

# Known pairs to skip. Names or globs, in either order.
ignore = [
  { tools = ["search_logs", "analyze_logs"], rule = "hidden-overlap" },
  { tools = ["legacy_*", "*"] },
]

[severity]
unmarked-contrast = "error"   # error, warning, info, or off

How it works

  1. Load each server's tools from a snapshot, a client config, or a live connection.
  2. Embed every description in memory with model2vec's potion-base-8M: a 30 MB static embedding model (a lookup table plus mean pooling) downloaded once from the Hugging Face Hub at a pinned revision and cached. A few hundred tools take milliseconds.
  3. Find candidates: pairs whose names are equal or differ in one word (found by bucketing name tokens), plus pairs whose descriptions score above --threshold.
  4. Align the two names token by token and classify the pair:
    • names equal apart from case or separators: name-collision
    • the differing words are near-synonyms (a curated, extensible list): synonym-contrast
    • names differ in one slot and each description mentions its own word: clean
    • names differ in one slot and a description does not: unmarked-contrast
    • names unrelated, descriptions near-identical: hidden-overlap
    • a description names the other tool (use read_text_file instead): clean

Servers are analyzed independently unless you pass --cross-server.

Synonyms come from a reviewable list rather than the embedding model, because static word embeddings score get/fetch (0.36) lower than many unrelated pairs.

Offline CI: set HF_HUB_OFFLINE=1 with a warm cache, point --model at a local copy of the model directory, or use --embedder lexical (TF-IDF, no download, misses paraphrases).

Limitations

  • Thresholds are starting points. They come from a small set of hand-built examples and the MCP reference servers, not a labeled benchmark. Tune them, and please report false positives.
  • It checks that a contrast is stated, not that it is meaningful. If search_logs says "Search logs..." and analyze_logs says "Analyze logs...", each description mentions its word and the pair passes.
  • English only. Tokenizing, stemming, and the synonym list assume English names.
  • Legacy HTTP+SSE servers are not supported. Use Streamable HTTP, stdio, or a snapshot.
  • Code scanning needs file locations, so live --stdio/--http findings carry none. Lint a snapshot or a client config to get annotations on a line.

References

  • Clark, E. V. (1987). The principle of contrast: A constraint on language acquisition. In B. MacWhinney (Ed.), Mechanisms of Language Acquisition (pp. 1-33). Lawrence Erlbaum Associates.

Contributing

See CONTRIBUTING.md. False-positive reports with the two tool definitions are the most useful contribution right now.

License

MIT

Metadata

Release files for mcp-contrast 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-contrast 0.1.0
File Size Uploaded Provenance Actions
mcp_contrast-0.1.0.tar.gz 43.8 kB With provenance Details for mcp_contrast-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-contrast 0.1.0
File Interpreter ABI Platform Actions
mcp_contrast-0.1.0-py3-none-any.whl Python 3 none any Details for mcp_contrast-0.1.0-py3-none-any.whl

Total release size: 81.3 kB

Release files / mcp_contrast-0.1.0.tar.gz

Download URL mcp_contrast-0.1.0.tar.gz
Size 43.8 kB
Tags Source
SHA-256 checksum
How to use checksums
0eab97c4f4b7d35e5ab148e936e651ddb5464f73a639d74ed1ac6526e900b4ab
BLAKE2b-256 checksum
How to use checksums
d35a5582f658a645667c3b7da28925106fcfab9ccaa648a928727886d51c9013
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / mcp_contrast-0.1.0-py3-none-any.whl

Download URL mcp_contrast-0.1.0-py3-none-any.whl
Size 37.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2090224b0dee06427e2b7b35c56f09be76d11362f1af2049ed0da283faecefd7
BLAKE2b-256 checksum
How to use checksums
9eaa1999bd5a071fbfe9e225dd952a83bb574a0aa866a404c40408fc989b3b55
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Security for mcp-contrast 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_contrast-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page