toolclash

toolclash

Find MCP tool collisions before your agent loads them.

toolclash compares multiple MCP tool catalogs for exact names, normalization collisions, incompatible schemas, annotation disagreement, near-duplicate purpose, and combined context cost—then produces a deterministic namespace plan.

npx --yes github:jovial-liu/toolclash#v1 scan files.json docs.json --strict

No server startup, tool execution, model call, account, telemetry, or upload. Node.js 20+; zero runtime dependencies.

Why this exists

MCP servers are usually tested one at a time, but agents consume a combined tool surface. Two healthy servers can still create an unhealthy catalog:

• both export search, with different arguments;
• one exports read_file, another read-file;
• identical-looking tools disagree about whether they are read-only;
• several tools describe nearly the same action and waste selection context;
• the combined schemas consume thousands of tokens before any result appears.

toolclash checks the composition boundary.

workspace-files/search  ↔  team-docs/search
  TC001 exact name collision
  TC003 incompatible input schema

workspace-files/read_file  ↔  team-docs/read-file
  TC002 normalized name collision
  TC003 incompatible input schema

Create catalogs

The recommended input is a JSON report from mcpdoctor:

npx --yes github:jovial-liu/mcpdoctor#v1 \
  --format json --out files.json -- npx -y @modelcontextprotocol/server-filesystem .

Any JSON object with a tools array also works. Server identity is read from serverName, server, or name, falling back to the input filename.

Scan the combined surface

toolclash scan files.json docs.json database.json \
  --similarity 0.72 \
  --budget 8000 \
  --format html \
  --out toolclash.html \
  --strict

Formats are json, markdown, and self-contained offline html. --strict exits 1 when errors or warnings exist.

Generate a namespace plan

toolclash aliases files.json docs.json --format json

Example:

{
  "server": "workspace-files",
  "tool": "search",
  "alias": "workspace-files__search",
  "reason": "collision"
}

Only colliding names are changed. If multiple catalogs claim the same server name, stable catalog ordinals keep aliases unique. The plan is advisory: apply it in your MCP host, gateway, or wrapper according to that product's configuration model.

Finding codes

Code	Meaning
TC001	Exact tool name appears in multiple servers
TC002	Names differ only after punctuation/case normalization
TC003	Colliding names expose different input schemas
TC004	Colliding tools disagree on readOnlyHint
TC005	Names/descriptions indicate a near-duplicate purpose
TC006	Combined definitions exceed the configured token budget

Near-duplicate matching is a transparent Jaccard score over normalized words, not an embedding or model judgment. Tune --similarity; inspect every result before removing or aliasing a tool.

Context estimate

Each tool's description, input/output schemas, and annotations are serialized deterministically, measured as UTF-8 bytes, and divided by four. Reports say ~tokens because real tokenization depends on the host, model, and wire representation.

Use prompttax when you also need repository instruction costs. toolclash stays focused on cross-server composition.

Safety boundary

• Catalogs are parsed as local data.
• Server commands in reports are ignored.
• No MCP lifecycle request or tool call is made.
• Absolute input paths are reduced to basenames.
• Tool descriptions can be untrusted text; HTML output escapes them.
• A clean report is not proof that tools are safe, authorized, or semantically correct.

For live protocol negotiation and individual-server checks, use mcpdoctor. For call authorization policy, use toolgate.

Development

npm run check
node src/cli.mjs scan examples/files.json examples/docs.json

Contributions should include minimal catalog fixtures. See CONTRIBUTING.md and SECURITY.md.

MIT licensed.