vdiff-mcp

vdiff

用于 npm 包的破坏性变更差异 API。给定一个包和两个版本，它会返回结构化、机器可读的实际破坏内容列表：已移除的导出、已更改的函数签名，以及已移除或更改的类和接口成员。每条记录都包含变更前后的签名以及简短的迁移说明。

服务地址：https://vdiff-api.onrender.com。最简便的使用方式是通过 MCP 服务 vdiff-mcp：

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

也可以直接调用 REST API：

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

为什么要创建它

大模型在训练期间学习某个包的 API，之后这个包却不断迭代。当编码 Agent 使用 zod 或 express 编写代码时，它会针对自己记忆中的版本来编写，而这个版本往往不是 lockfile 中安装的版本。结果就是，Agent 自信地调用了早在两个大版本前就已重命名或移除的函数。

现有工具只能解决部分问题。版本查询工具会告诉 Agent 当前版本是什么；文档工具会告诉它如今的文档写了什么。但两者都无法回答 Agent 在编辑过程中真正关心的问题：“我所了解的版本和这里安装的版本之间有什么变化？”

vdiff 正是为此而生。它根据包自身的类型声明计算差异，而不是依据变更日志，因此输出反映的是实际导出的 API；每个响应还会附带置信度评分，让使用方知道结果的可信程度。

端点参考：docs/api.md。

工作原理

1. 解析。 从 npm 注册表获取包元数据、版本和 dist-tags。
2. 提取。 对两个版本分别下载 tarball，仅保留 .d.ts 文件，并使用 TypeScript 编译器 API 构建公共导出表（包括函数、类、成员和规范化的调用签名）。优先使用包内置的声明文件；如果包未提供，则回退到对应的 DefinitelyTyped @types/* 包，并按 major.minor 匹配版本。
3. 比较。 对两个导出表进行差异比较，生成带类型的变更条目（例如 export_removed、signature_changed、member_removed 等），每条都包含变更前后的签名以及迁移说明。
4. 缓存和统计。 结果存储在 Postgres 中，以（包、from、to）为键，因此每个版本对只会计算一次。每个请求都会记录缓存命中状态和用户代理。
5. 防护。 按 IP 限制请求频率、限制同时进行的差异计算数量、限制 tarball 和提取后的声明文件大小，并设置获取超时，以确保服务公开后仍然安全。

差异仅针对类型层面：如果运行时行为发生变化而类型保持不变，则无法检测到。使用包内置类型的响应置信度为 0.9；使用社区维护的 @types/* 声明的响应置信度为 0.8。

API 概览

端点	用途
GET /v1/diff	两个版本之间的破坏性变更差异（必需参数为 from，to 默认为最新版本）
GET /v1/resolve	获取包的最新版本和 dist-tags
GET /healthz	存活状态检查

有关参数、响应结构、变更类型、错误代码和频率限制，请参阅 docs/api.md。

技术栈

层	选择	原因
运行时	Node 20+、TypeScript	仅支持 npm 的 .d.ts 差异比较需要使用 TS 编译器 API，因此采用单一语言
API	Fastify 5	速度快、精简，TypeScript 支持良好
差异比较	typescript 编译器 API	从 .d.ts 文件生成结构化符号表，是产品的核心
数据库	Postgres 18（本地 Docker，生产环境 Neon）	使用 JSONB 存储形状可变的差异数据，使用 SQL 处理计费和分析
注册表	npm 注册表 HTTP API + tar	获取 Packument 并解压 tarball，仅处理声明文件
测试	Vitest	为比较逻辑和 @types 版本匹配编写单元测试

代码与云平台无关：只需一个普通容器和 DATABASE_URL。目前运行在 Render 上，使用 Neon Postgres。

自行运行

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

也可以通过容器运行，方式与 PaaS 相同（启动时应用数据库架构，然后开始提供服务）：

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

配置

所有配置均通过环境变量设置：

环境变量	默认值	用途
PORT	3000	监听端口
DATABASE_URL	本地 Docker Postgres	Postgres 连接字符串
RATE_LIMIT_DIFF_MAX	30	每个 IP 每分钟可发送的 /v1/diff 请求数
RATE_LIMIT_RESOLVE_MAX	120	每个 IP 每分钟可发送的 /v1/resolve 请求数
COMPUTE_CONCURRENCY	2	同时进行的差异计算上限
TRUST_PROXY	未设置	在 PaaS 代理之后设置为 true，使速率限制器能够获取真实客户端 IP

加固说明

• 速率限制：按 IP 限制，存储在内存中（单实例运行时足够）。平台健康检查使用的 /healthz 不受限制。
• 计算上限：同时编译的未缓存差异最多为 COMPUTE_CONCURRENCY 个；超出的请求会收到带有 retry-after 的 503 响应。始终提供缓存的差异。
• 大小限制：tarball 下载上限为 50 MB（通过 content-length 检查并统计字节数），每个版本解压出的声明文件上限为 15 MB。超出大小限制的包会返回清晰的 422 错误。
• 获取时限：Packument 为 10 秒，tarball 为 30 秒。tarball 仅通过 HTTPS 从 registry.npmjs.org 获取。

项目结构

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

测试

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

许可证

API 和差异引擎采用 Functional Source License, v1.1, MIT Future License（FSL-1.1-MIT）授权：可免费用于任何用途，并可阅读和修改，但不得提供竞争性服务；每个版本发布两年后会自动转为 MIT 许可证。

mcp/ 中的 MCP 服务封装采用 MIT 许可证。