Skip to main content
Glama
mcurmi05

vdiff

by mcurmi05
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

vdiff

A breaking-change diff API for npm packages. Given a package and two versions, it returns a structured, machine-readable list of what actually broke: removed exports, changed function signatures, and removed or changed class and interface members. Each entry includes the before and after signatures plus a short migration note.

Live at https://vdiff-api.onrender.com. Most easily consumed through the MCP server, vdiff-mcp:

claude mcp add vdiff -- npx -y vdiff-mcp

Or call the REST API directly:

curl "https://vdiff-api.onrender.com/v1/diff?ecosystem=npm&package=zod&from=3.24.0&to=4.0.0"

Why this exists

LLMs learn a package's API surface during training, then the package moves on. When a coding agent writes code against zod or express, it writes for the version it remembers, which is often not the version in your lockfile. The result is confident code that calls functions that were renamed or removed two majors ago.

Existing tools only solve part of this. Version lookup tools tell the agent what the current version is. Documentation tools tell it what the docs say today. Neither answers the question the agent actually has mid-edit: "what changed between the version I know and the version installed here?"

vdiff answers exactly that. Diffs are computed from the package's own type declarations rather than changelogs, so the output reflects the real exported surface, and every response carries a confidence score so the consumer knows how much to trust it.

Endpoint reference: docs/api.md.

Related MCP server: docpilot-mcp

How it works

  1. Resolve. Fetch package metadata, versions and dist-tags from the npm registry.

  2. Extract. For each of the two versions, download the tarball, keep only the .d.ts files, and build a table of public exports (functions, classes, members, normalized call signatures) using the TypeScript compiler API. Bundled declarations are preferred; packages that ship none fall back to the matching DefinitelyTyped @types/* package, version-matched by major.minor.

  3. Compare. Diff the two export tables into typed change entries (export_removed, signature_changed, member_removed and so on), each with before/after signatures and a migration note.

  4. Cache and meter. Results are stored in Postgres keyed on (package, from, to), so each version pair is computed once, ever. Every request is logged with cache-hit status and user agent.

  5. Guard. Per-IP rate limits, a cap on simultaneous diff computations, size limits on tarballs and extracted declarations, and fetch timeouts keep the service safe to expose publicly.

Diffs are type-level: a runtime behavior change that leaves the types untouched is invisible. Responses using bundled types carry confidence 0.9; responses using community-maintained @types/* declarations carry 0.8.

API overview

Endpoint

Purpose

GET /v1/diff

Breaking-change diff between two versions (from required, to defaults to latest)

GET /v1/resolve

Latest version and dist-tags for a package

GET /healthz

Liveness check

See docs/api.md for parameters, response shapes, change types, error codes and rate limits.

Stack

Layer

Choice

Why

Runtime

Node 20+, TypeScript

npm-only .d.ts diffing needs the TS compiler API, so one language

API

Fastify 5

Fast, minimal, good TypeScript support

Diffing

typescript compiler API

Structured symbol tables from .d.ts files, the core of the product

Database

Postgres 18 (Docker local, Neon prod)

JSONB for variable-shape diff payloads, SQL for billing and analytics

Registry

npm registry HTTP API + tar

Packuments and tarball extraction, declarations only

Tests

Vitest

Unit tests for compare logic and @types version matching

The code is cloud-agnostic: a plain container plus a DATABASE_URL. It currently runs on Render with Neon Postgres.

Running it yourself

docker compose up -d      # Postgres 18 on :5432
npm install
npm run db:migrate        # apply src/db/schema.sql
npm run dev               # API on :3000

Or containerized, the way a PaaS runs it (applies the schema on boot, then serves):

docker build -t vdiff-api .
docker run -p 3000:3000 -e DATABASE_URL="postgres://user:pass@host:5432/db" vdiff-api

Configuration

All configuration is via environment variables:

Env var

Default

Purpose

PORT

3000

Listen port

DATABASE_URL

local Docker Postgres

Postgres connection string

RATE_LIMIT_DIFF_MAX

30

Per-IP /v1/diff requests per minute

RATE_LIMIT_RESOLVE_MAX

120

Per-IP /v1/resolve requests per minute

COMPUTE_CONCURRENCY

2

Max simultaneous diff computations

TRUST_PROXY

unset

Set true behind a PaaS proxy so the rate limiter sees real client IPs

Hardening notes

  • Rate limiting: per-IP, in-memory (fine while single-instance). /healthz is exempt for platform health checks.

  • Compute cap: at most COMPUTE_CONCURRENCY uncached diffs compile at once; excess requests get a 503 with retry-after. Cached diffs are always served.

  • Size guards: tarball downloads are capped at 50 MB (checked via content-length and counted bytes), extracted declarations at 15 MB per version. Oversized packages fail with a clear 422.

  • Fetch budgets: 10 s for packuments, 30 s for tarballs. Tarballs are only fetched from registry.npmjs.org over HTTPS.

Project layout

src/
  index.ts          Fastify bootstrap, /healthz
  routes.ts         /v1/resolve, /v1/diff: validation, cache, dedup, metering
  registry/npm.ts   packument fetch, tarball download, .d.ts extraction
  diff/
    symbols.ts      .d.ts to symbol table (TS compiler API)
    compare.ts      symbol table diff to breaking changes
    engine.ts       orchestration, @types/* fallback, confidence
  db/
    schema.sql      packages, versions, diffs, diff_requests_log
    migrate.ts      applies schema
mcp/                vdiff-mcp, the MCP server wrapping this API (published to npm)
docs/
  api.md            endpoint reference, kept current with the code

Tests

npm test          # unit tests (Vitest)
npx tsc --noEmit  # typecheck

License

The API and diff engine are licensed under the Functional Source License, v1.1, MIT Future License (FSL-1.1-MIT): free to use, read and modify for anything except offering a competing service, and each release automatically becomes MIT two years after publication.

The MCP server wrapper in mcp/ is MIT licensed.

Available Tools

2 tools
get_breaking_changesGet breaking changes between package versionsA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
toNoexact semver of the version to compare against; omit to use the latest published version
fromYesexact semver of the version you know or currently have installed, e.g. "3.24.0" (from a lockfile); ranges like "^3.0.0" are not accepted
packageYesnpm package name, e.g. "zod" or "@scope/pkg"

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses computation from TypeScript type declarations, confidence score based on bundled types vs DefinitelyTyped, latency (first request may take minutes), and caching behavior. It also describes response content (before/after signatures, migration note). No contradictions observed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four well-organized sentences with no fluff: first sentence introduces purpose, second explains response contents, third gives usage scenario, fourth warns about latency and caching. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (breaking changes diff, confidence score, caching), the description covers key behavioral aspects and response content adequately. No output schema but description compensates by describing entry structure. Could have mentioned response format or edge cases, but still quite complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 3 parameters. The description adds value by explaining default behavior for 'to' (latest published version), that 'from' must be exact semver (no ranges), and reinforces the role of 'package'. Baseline 3, and extra context raises it to 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it computes a structured breaking-change diff between two npm package versions from TypeScript type declarations. It specifies the resource (npm package versions) and action (get breaking changes diff), and distinguishes from sibling tool 'resolve_package' which likely resolves package info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage context: 'Use this before writing or upgrading code that targets a dependency version you are not certain about.' It also provides an example situation. However, it does not explicitly state when not to use the tool, but the context strongly implies its specific use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_packageResolve npm package versionA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
packageYesnpm package name, e.g. "zod" or "@scope/pkg"

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not mention whether the operation is read-only, if network calls are made, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no waste. The first sentence defines the action, the second provides usage context. Efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description covers purpose and usage. It mentions dist-tags as output but lacks full format specification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description and example. The tool description adds no additional semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb 'Resolve' and resource 'npm package', and specifies outputs 'latest published version and dist-tags'. It does not fully distinguish from sibling but provides usage context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('when you only know the package name and need the current version') and suggests next step ('before calling get_breaking_changes').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedget_breaking_changes
    • First observedresolve_package
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

The two tools have distinct purposes: one resolves package versions, the other computes breaking changes. There is no ambiguity or overlap.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with snake_case (resolve_package, get_breaking_changes), making them predictable.

Tool Count4/5

With only two tools, the server is minimal but well-suited to its niche purpose of version analysis. It could benefit from additional utilities like listing versions, but the count is not inappropriate.

Completeness4/5

The tools cover the essential workflow: resolve a package name to a version, then get breaking changes. While there are no additional features like changelog retrieval or multi-package comparison, the core functionality is complete.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • docpilot-mcp

    neromtoobad
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that provides tools to fetch live, version-accurate documentation, changelogs, examples, and method signatures for npm and PyPI packages, preventing AI coding agents from hallucinating stale APIs.
    21
    ISC

  • ts-docs-mcp

    xvantz
    A
    license
    A
    quality
    B
    maintenance
    An MCP server that gives AI coding agents accurate, version-aware API documentation for any npm package — straight from the source.
    1
    29
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mcurmi05/vdiff'

If you have feedback or need assistance with the MCP directory API, please join our Discord server