vercel-deployment-mcp

vercel-deployment-mcp

一个基于标准输入/输出观察 Vercel 项目和部署的参考 Model Context Protocol 服务。

这是一个社区参考实现，专注于部署工作流模式。它并非 Vercel 自有 MCP 产品的替代品。本项目旨在通过一个小巧、易读的代码库，展示面向部署的 MCP 服务如何妥善处理配置，并在短生命周期基础设施上保持行为可预测。

工具

工具	描述
list_projects	列出配置的账户/团队可见的项目（搜索、数量限制）
get_project	按 ID 或名称获取一个项目
list_deployments	列出近期部署（按项目、状态、数量限制筛选）
get_deployment	按 ID 或 URL 获取一个部署，包括当前状态

list_projects 和 list_deployments 各自返回一页结果，最多 limit 条（默认 20 条，最多 100 条）。不支持游标分页；可以通过 search、projectId 或 state 缩小请求范围，以查看更具体的结果。

安装

从 npm 安装：

npm install @addiplus/vercel-deployment-mcp

也可以直接运行，无需安装：

npx @addiplus/vercel-deployment-mcp

从源码安装：

git clone https://github.com/addiplus/vercel-deployment-mcp.git
cd vercel-deployment-mcp
npm install
npm run build
npm test

运行测试套件所需的 Node 版本比运行服务所需的更新。vitest 4.1.10 声明的 engines.node 为 ^20.0.0 || ^22.0.0 || >=24.0.0，而此锁文件固定的 vite 8.1.3 将范围缩小为 ^20.19.0 || >=22.12.0。测试套件可运行于两者的交集：^20.19.0 || ^22.12.0 || >=24.0.0，即从 20.19.0 开始的 20 系列、从 22.12.0 开始的 22 系列，以及 24 及以上版本。23 系列不在此范围内，因为 vitest 不支持 23。CI 使用 22 和 24。根据 engines，已发布的软件包本身仍可在 Node >=18 上运行。

配置

变量	必需	用途
VERCEL_TOKEN	是	Vercel 访问令牌（在账户设置中创建）
VERCEL_TEAM_ID	否	将请求限定到某个团队
VERCEL_MCP_MIN_INTERVAL_MS	否	一次 Vercel API 请求开始到下一次请求开始之间的最短毫秒数（默认 250）
VERCEL_MCP_MAX_CONCURRENT	否	同时进行中的 Vercel API 请求的最大数量（默认 4）

当 HTTP 429 响应带有数值型 Retry-After 标头，且值不超过 10 秒时，服务会等待相应时长并重试一次请求；其他任何 429 都会在首次尝试时作为错误返回。

限制

限制	值
search 值的最长长度	4096 个字符
projectId、state、idOrName、idOrUrl 值的最长长度	512 个字符
接受的协议帧最大长度	10485760 字节
VERCEL_MCP_MIN_INTERVAL_MS 接受的最高值	60000

帧长度限制只计算消息，不包括用于分隔消息的换行符，因此长度恰好为 10485760 字节的消息会被接受。换行符之前的所有内容都属于消息，包括紧挨在换行符前的回车符。

每项限制超过表中数值时，都有各自的处理方式。参数过长会导致输入验证失败：调用返回 JSON-RPC -32602 无效参数结果，不会发出 Vercel API 请求，也不会为此向 stderr 写入内容。超出帧长度限制的帧会被丢弃，stderr 会写入一行说明，连接继续提供服务。间隔超过上限时不会被拒绝，而是会被缩减至上限：服务端以缩减后的值运行，并在首次发出 Vercel API 请求时向 stderr 写入一行说明。相同的 stderr 报告连续重复时最多写入两次，第二次会说明后续相同报告将被抑制。

initialize 和 ping 可随时响应。只有在客户端完成初始化握手后，才会响应 tools/list 和 tools/call：先发送服务端能够响应的 initialize 请求，再发送 notifications/initialized。两部分缺一不可，因此仅发送通知并不能完成握手，服务端拒绝的 initialize 也不能完成握手。客户端在一次写入中同时发送这两部分和第一次调用时，服务端会处理该调用，而不会因为客户端没有等待 initialize 响应而拒绝。在握手完成前，这两个方法会被拒绝，并返回 JSON-RPC 错误 -32600，且不会发出 Vercel API 请求。

客户端配置示例（Claude Desktop / Claude Code）：

{
  "mcpServers": {
    "vercel-deployment": {
      "command": "npx",
      "args": ["-y", "@addiplus/vercel-deployment-mcp"],
      "env": { "VERCEL_TOKEN": "…" }
    }
  }
}

从源代码检出目录运行时，请使用 "command": "node" 和 "args": ["/path/to/vercel-deployment-mcp/dist/index.js"]。

设计原则

首次编写于 2026-07-10，此后始终与代码保持同步；声明 1 曾在错误文本开始被脱敏时重新表述一次，脱敏发生在文本变为客户端可见内容的环节。以下每项声明均已在代码中实现，并在可测试的情况下由测试套件验证（test/）；设计属性会标明实现它们的代码。

1. 错误中绝不出现配置值。 访问令牌仅从环境变量读取。错误文本经过格式处理、长度限制，并在变为客户端可见文本时通过一次脱敏保护，因此上游 API 消息无法回显令牌或团队 ID（src/vercel.ts）；在长度限制后附加的固定提示由本服务端写入，不含任何需要替换的内容。成功结果是对上游响应正文的固定投影，不会经过脱敏，因此 Vercel API 自身在部署 URL 中返回的团队标识符仍会显示在其中。
2. stdout 专用于协议。 所有诊断信息都写入 stderr（src/index.ts），因此日志行不会泄漏到工具响应中。
3. 保持最小资源占用。 这些工具只读地查看项目和部署；服务端不会请求读取所需内容之外的任何信息。
4. 采用无状态设计。 每次工具调用都会重新从环境变量读取配置（已在 test/tools.test.ts 中验证），因此长时间运行的主机和短时间运行的工作进程行为一致。唯一的模块级状态是请求节流器（src/vercel.ts），用于控制 Vercel API 调用的间隔并限制并发数量；其间隔和并发设置在首次使用时读取，不保存任何凭据或响应数据。

路线图

• 部署操作需包含明确的带外审批步骤（探索 MCP 规范议题 #2919/#2920 中讨论的模式，即在无状态传输中处理多轮工具结果）。
• 标准化 server.json 描述 stdio 软件包安装清单的方式，以及客户端将其转换为本地配置文件的方式（规范议题 #2963，注册表议题 #749）。

许可证

MIT