Loading ToolBench

Reading the current corpus…

vdiff MCP server · B · ToolBench

vdiff

MCP server that gives coding agents structured breaking-change diffs for npm packages, so they stop writing code against removed or renamed APIs.

2026-07-28+STDIO2 tools

74/100

Definition Quality83

Protocol Readiness50

SupportabilityNot measured-

Spec posture

Inferred effective spec 2026-07-28+·current baseline 2026-07-28

Static source inference · medium confidence

Current-spec patterns detected

Summary

Two well-documented tools with clear verb-based names, comprehensive descriptions (194-280 chars), and proper input schemas using Zod. Both tools follow the read-only action pattern. However, output schemas are not formally documented in the code, and descriptions rely on narrative prose rather than structured WHAT/WHEN/HOW guidance. No parameter enums where they could tighten constraints. Error handling is present but generic (apiErrorMessage returns HTTP status + body without recovery guidance). Tool composition is sound, resolve_package → get_breaking_changes is a natural chain. The server is STDIO-only, which caps protocol readiness to 50 regardless of definition quality.

Tools (2)

get_breaking_changesread onlysource verified81/100

Structured breaking-change diff between two versions of an npm package, computed from its TypeScript type declarations: removed exports, changed signatures, removed/changed class or interface members, plus new exports. Each entry has before/after signatures and a short migration note. The response includes a confidence score: 0.9 when both versions ship bundled types, 0.8 when DefinitelyTyped @types/* declarations were used. Use this before writing or upgrading code that targets a dependency version you are not certain about — e.g. when the installed version is newer than the API surface you know. The first request for a version pair may take up to a couple of minutes while the diff is computed; results are cached after that.

resolve_packageread onlysource verified84/100

Resolve an npm package to its latest published version and dist-tags. Use this when you only know the package name and need the current version, typically before calling get_breaking_changes.

Issues (5)

HIGHtool-output-schema ↗

Output schemas not documented. Tools return raw JSON via apiGet() with no formal schema declaration for response fields (e.g., resolve_package returns latest version and dist-tags, but no structured spec). LLMs cannot predict response structure for planning or extraction.

resolve_packageget_breaking_changes

HIGHrecovery-guide ↗

Error messages lack recovery guidance. apiErrorMessage() returns 'vdiff API error (HTTP 404): ...' but never suggests what the LLM should do next (e.g., 'Package not found. Try a different ecosystem or check the spelling.'). Stack traces or bare HTTP status codes force the agent to guess.

resolve_packageget_breaking_changes

MEDIUMpaginated-result ↗

No pagination or result limiting for get_breaking_changes response. If a package has hundreds of breaking changes, the response could exceed context windows. Tool description mentions caching but not result caps.

get_breaking_changes

Recommendations

Add structured output schema documentation. Example: 'resolve_package returns {latest: string, dist_tags: {[key: string]: string}, engine: string, ecosystem: string}'. Use inline JSDoc or a types.ts file to formalize response shapes.
Enhance error messages with recovery steps. Replace 'vdiff API error (HTTP 404): Package not found' with 'Package not found. Check the spelling or try searching for similar package names. Verify it is published on npm.'
Add semver validation to 'from' and 'to' parameters. Use a regex pattern in Zod: z.string().regex(/^\d+\.\d+\.\d+$/, 'Must be exact semver like 3.24.0, not a range'). Validate server-side and return 'Invalid version format: got "^3.0.0", expected exact semver like 3.24.0'.
Document response structure for both tools. Include expected fields, types, and what they mean. Example: '{confidence: number (0.8-0.9), changes: [{type: "removed_export", before: string, after: string, note: string}]}'.
Add tool annotations to the registerTool calls: readOnlyHint=true for both tools, and idempotentHint=true (since they only fetch data). This guides agent planning.
Implement result capping for get_breaking_changes. If changes array exceeds 50 items, truncate with '... and 42 more changes. Use offset/limit pagination or filtering by change type.' Include a note in the description: 'Large diffs are paginated; the response includes at most 50 top-priority changes.'
Add context about polling behavior in description of get_breaking_changes. Clarify: 'First call for a version pair may return HTTP 202 (computing) or 503 (server busy). The tool polls internally for up to 2 minutes. If still not ready, try again in 30 seconds.'

Score history

Overall score trend

First recorded score · v2 rubric

74/100

Scored	Grade	Overall	Spec posture	Rubric
2026-09-23	B	74	2026-07-28+	v2