ddversionctl-mcp

刀刀上线（VersionCtl）的 Model Context Protocol 服务：用个人中心生成的 ddvc_ API Token 调用后端 HTTP 接口。

核心工具：verctl_package_catalog（查可改版本的 npm 包名）→ verctl_set_package_version（改某分支上单个包的待上线版本，对应 GET /verctl/packagecatalog 与 POST /verctl/setpackageversion）。

构建

cd packages/versionctl-mcp
npm install
npm run build

本地打包（上传私服 / 离线安装）

npm pack
# 生成 ddversionctl-mcp-1.1.0.tgz

发布到 npm 官方仓库

本包在 package.json 里配置了 publishConfig.registry 为 https://registry.npmjs.org/，因此即使用户全局 npm config 指向公司私服，在本目录执行 npm publish 仍会发到 npm 线上（需使用有 npmjs.org 发布权限的账号登录：npm login --registry https://registry.npmjs.org/）。

prepublishOnly / prepack 会自动执行 npm run build。

若临时要发到其它 registry，可覆盖：

npm publish --registry https://你的私服/npm/

发布时出现 404 Not Found - PUT .../ddversionctl-mcp

npm 在未正确鉴权或 Token 不能发包时，经常会误报成 404（而不是 401/403）。请逐项检查：

1. 确认登录的是官方源（不要用公司只读 CI 用户）：

   npm whoami --registry https://registry.npmjs.org/

   若失败，执行：npm login --registry https://registry.npmjs.org/
2. 账号：邮箱已验证；若开启 2FA，发布时需加一次性密码：
   npm publish --otp=123456
3. Automation / Granular Token：在 npm Access Tokens 创建时勾选 Publish 权限；只读 Token 无法发包。
4. 包名：ddversionctl-mcp 在 npm 上未被占用即可首发包；若仍异常，可改为组织下 scoped 包名（如 @your-org/ddversionctl-mcp）并加上 publishConfig.access: "public"。

E403：Two-factor authentication or granular access token with bypass 2fa…

说明你的 npm 账号已开启 2FA。发布时必须二选一：

方式 A — 交互发布（推荐个人本机）
在 Authenticator 里取 6 位动态码，执行：

npm publish --otp=123456

（123456 换成当前码；码过期就换新的再执行一次。）

方式 B — CI / 自动化
在 npm Access Tokens 创建 Granular Access Token：勾选 Publish；并开启 Bypass two-factor authentication (2FA)（仅用于可信自动化）。把该 Token 写入 CI 的 NPM_TOKEN / ~/.npmrc 的 //registry.npmjs.org/:_authToken=…，再执行 npm publish（无需 --otp）。

环境变量

| 变量 | 说明 | |------|------| | VERSIONCTL_BASE_URL | 服务根地址，如 https://host:60063（不要尾斜杠） | | VERSIONCTL_API_TOKEN | 完整 API Token（ddvc_…） |

工具只报「fetch failed」、没有 HTTP 状态码

说明 TCP/TLS 层就失败了（连不上、证书不信任、DNS 失败等），请求没到 Gin。常见原因：

1. VERSIONCTL_BASE_URL 错：端口、协议（http/https）与线上一致；不要用浏览器里的前端地址代替后端 API 地址。
2. 本机访问不到该主机：需 VPN / 内网；在运行 MCP 的同一台机器上执行 curl -v "${VERSIONCTL_BASE_URL}/verctl/ping" 应能通。
3. 自签或内网 HTTPS：系统或 Node 不信任证书会导致 fetch failed；需信任 CA 或改用内网 HTTP（若安全策略允许）。
4. 客户端限制出站：少数环境对 MCP 子进程禁网，需放行。

更新到含详细 cause 的 MCP 版本后，错误文案里会带上具体原因（如 ECONNREFUSED）和完整请求 URL，便于对照排查。

主流 MCP 客户端配置

以下均需配置两个环境变量：

• VERSIONCTL_BASE_URL：刀刀上线后端根地址（无尾斜杠），如 https://10.68.0.8:60063
• VERSIONCTL_API_TOKEN：个人中心生成的 ddvc_ 完整令牌

安全提示：不要把真实 Token 写进会被 Git 提交的仓库文件；可用本机/IDE 私密配置或系统环境变量。

通用 mcpServers 片段（多数客户端结构相同）

{
  "mcpServers": {
    "versionctl": {
      "command": "npx",
      "args": ["-y", "ddversionctl-mcp@latest"],
      "env": {
        "VERSIONCTL_BASE_URL": "https://你的地址:60063",
        "VERSIONCTL_API_TOKEN": "ddvc_你的令牌"
      }
    }
  }
}

Cursor

• 用户级（全局）：设置 → MCP → 添加服务器，或编辑配置文件（路径因版本略有差异，常见为 ~/.cursor/mcp.json）。
• 项目级：仓库根目录 .cursor/mcp.json（若团队共享，请只用占位符或 env 引用，勿提交真实 Token）。

将上文「通用片段」整段合并进配置文件的 mcpServers 即可。若已存在其它服务器，只合并 versionctl 这一项。

使用本仓库源码（不经过 npx）：

{
  "mcpServers": {
    "versionctl": {
      "command": "node",
      "args": ["/你的本机路径/imock-version-ctl/packages/versionctl-mcp/dist/index.js"],
      "env": {
        "VERSIONCTL_BASE_URL": "https://你的地址:60063",
        "VERSIONCTL_API_TOKEN": "ddvc_你的令牌"
      }
    }
  }
}

发布前请先在该目录执行 npm run build 生成 dist/。

Claude Desktop（Anthropic）

编辑配置文件（保存后完全退出 Claude 再打开）：

| 系统 | 路径 | |------|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

在根对象中增加或合并 mcpServers，内容与上文「通用片段」一致。官方说明见 Model Context Protocol - Claude Desktop。

Windsurf（Codeium）

在 Windsurf 设置中的 Cascade / MCP 相关项添加 MCP 服务器；若支持 JSON 配置，同样使用 command + args + env 形式，与「通用片段」一致。部分版本配置路径类似 ~/.codeium/windsurf/mcp_config.json，以当前软件内文档为准。

Continue（VS Code / JetBrains 插件）

编辑 Continue 配置文件（常见为 ~/.continue/config.json），在支持 MCP 的版本中增加 mcpServers 字段，结构同「通用片段」。详见 Continue MCP 文档。

Cline（VS Code 扩展）

在 Cline 的 MCP 设置里新增服务器：command 为 npx，args 为 ["-y", "ddversionctl-mcp@latest"]，环境变量同上。

命令行自检（stdio）

安装包后可直接测进程是否拉起（无 MCP 宿主时仅验证能启动；按 Ctrl+C 结束）：

export VERSIONCTL_BASE_URL="https://你的地址:60063"
export VERSIONCTL_API_TOKEN="ddvc_你的令牌"
npx -y ddversionctl-mcp@latest

无报错挂起即表示入口正常；具体工具调用需在上述任一客户端内使用。

命令行入口

• ddversionctl-mcp
• versionctl-mcp（别名）