Websupport

websupport-mcp

一个 MCP 服务（TypeScript、ESM、stdio），封装了 Websupport REST API v1 + v2，涵盖 DNS、FTP、托管、数据库、邮箱、VPS 和发票，并通过带签名的 HMAC-SHA1 认证将其公开为 MCP 工具。

状态：早期阶段。 全部 50 个工具均已实现并发布，但大多数仅验证到能够访问 API 为止——路由、签名和错误处理已验证；响应结构大多尚未验证。依赖任何工具前，请先阅读 docs/verification-matrix.md，并参阅 IMPLEMENTATION_PLAN.md 了解进度。

风险等级

工具分为三个等级注册，等级控制的是注册——只读部署在 tools/list 中根本不会看到写入工具，因此不会占用客户端上下文，也不会提供相应操作入口。

等级	启用选项	每次调用的额外门槛	当前数量
read	始终启用	—	30 个工具
write	WEBSUPPORT_ALLOW_WRITE=1	—	13 个工具
destructive	WEBSUPPORT_ALLOW_DESTRUCTIVE=1	confirm: true 参数	7 个工具

当工具会破坏无法轻易重建的状态时，它属于 destructive，而不只是因为它会执行写入。平稳重启 VPS 属于 write；强制断电重启属于 destructive，因为它可能损坏正在进行的写入。创建快照属于 write；恢复快照属于 destructive，因为这会丢弃此后产生的所有内容。

两个启用选项相互独立：仅设置 WEBSUPPORT_ALLOW_DESTRUCTIVE=1 不会解锁写入工具，反之亦然。

安全边界由 confirm: true 参数而非 MCP elicitation 提供。协议协商可能会采用远低于支持 elicitation 的版本——此服务使用的 SDK 目前最高支持 2025-11-25——而在旧版客户端上会消失的门槛不算真正的门槛。

安装

需要 Node >= 22。无需提前安装任何内容——npx 会在首次运行时获取软件包。

将以下内容添加到 MCP 客户端的配置中：

{
  "mcpServers": {
    "websupport": {
      "command": "npx",
      "args": ["-y", "websupport-mcp"],
      "env": {
        "WEBSUPPORT_API_KEY": "…",
        "WEBSUPPORT_API_SECRET": "…"
      }
    }
  }
}

这样即可使用 30 个只读工具。该配置中的任何内容都无法更改你的账户。

若要允许更改，只添加所需的启用选项——参见上文的风险等级：

"env": {
  "WEBSUPPORT_API_KEY": "…",
  "WEBSUPPORT_API_SECRET": "…",
  "WEBSUPPORT_ALLOW_WRITE": "1",
  "WEBSUPPORT_ALLOW_DESTRUCTIVE": "1"
}

examples/mcp-config/ 中提供了适用于各种组合的现成配置。可将 websupport-mcp 替换为 [email protected]，以固定版本。

配置完成后，让客户端运行 ws_auth_check。凭据有效时，该工具会返回 {"verified": true}，这是快速判断问题是否出在密钥上的方法。

Docker

项目中包含 Dockerfile，适用于运行容器而非 npx 的主机，以及仓库构建沙盒：

docker build -t websupport-mcp .
docker run -i --rm -e WEBSUPPORT_API_KEY -e WEBSUPPORT_API_SECRET websupport-mcp

-i 不能省略——传输方式为 stdio。镜像中不会烘焙任何凭据；请在每次运行时传入。

从本地检出版本运行

用于开发或运行尚未发布的更改：

npm install
npm run build

然后将 command 指向 node，并将 args 指向构建后的入口文件（<checkout>/dist/index.js），而不是 npx。

凭据

在 WebAdmin（Security → API keys）中生成一组 Standard API 访问密钥对。仅用于 DynDNS 的密钥对只能通过 /nic/update 进行身份验证，不能用于其他任何操作。

变量	必填	默认值	说明
WEBSUPPORT_API_KEY	是	—	密钥对的标识符。
WEBSUPPORT_API_SECRET	是	—	密钥对的密钥。用于 HMAC-SHA1 签名；绝不会记录日志，也绝不会在错误中返回。
WEBSUPPORT_API_BASE_URL	否	https://rest.websupport.sk	市场选择——见下文。
WEBSUPPORT_ACCEPT_LANGUAGE	否	en_us	可选值：en_us、sk、cs_cz、hu。
WEBSUPPORT_ALLOW_WRITE	否	关闭	设置为 1 以注册写入工具。
WEBSUPPORT_ALLOW_DESTRUCTIVE	否	关闭	设置为 1 以注册破坏性工具。

本地开发时请复制 .env.example。.env 已加入 gitignore。

缺少凭据不会导致服务停止。服务仍会启动、注册工具，并在未经身份验证的情况下响应 tools/list——注册表构建沙盒、MCP Inspector 和客户端配置探测都会在有人持有密钥之前执行此操作——而首次工具调用会失败，并指出缺少哪个变量。

市场

Websupport 是 team.blue/Loopia 的一个区域品牌，因此 API 主机决定了市场。同一应用服务于所有主机——所有主机上的 GET /v2/docs/openapi.json 字节完全相同——因此切换市场只需修改配置，无需更改代码。

市场	WEBSUPPORT_API_BASE_URL
斯洛伐克（默认）	https://rest.websupport.sk
捷克	https://rest.websupport.cz
匈牙利	https://rest.websupport.hu
瑞典	https://rest.websupport.se

对于无法识别的主机，程序会向 stderr 输出警告，但仍会使用该主机，因此新增市场无需等待发布即可使用。

文档

文档	内容
docs/tools.md	每个工具的层级、方法 + 路径以及确认要求。根据注册表生成，绝不手动编辑。
docs/verification-matrix.md	每个工具已验证和未验证的内容。在生产环境中信任任何工具之前，请先阅读此文档。
docs/system-architecture.md	请求路径、签名约定及其三条反直觉规则，以及层级模型的工作方式。
docs/codebase-summary.md	模块图——各部分的所在位置及其原因。
examples/mcp-config/	可直接编辑的客户端配置，涵盖各类层级组合。

范围

订单创建和发票／订单支付端点明确不在范围内，并通过测试断言确认不存在。v1 DNS 记录 CRUD 和 v1 FTP 账户 CRUD 已被上游弃用，因此不会对外提供——v2 工具涵盖这两项功能。

开发

npm test              # offline suite
npm run test:network  # live, unauthenticated probes (market hosts + OpenAPI drift)
npm run typecheck
npm run lint
npm run build

网络测试套件经过刻意隔离：Websupport 服务中断不应导致构建失败。

工具链

运行或构建均需 Node >= 22。Node 20 已于 2026-04-30 停止维护，不受支持。CI 覆盖当前仍受支持的两个 LTS 版本 22 和 24，并会在两者上构建和对打包文件进行冒烟测试。

构建还需要 npm >= 11：npm 10 无法解析打包工具的依赖树，并报出难以理解的错误 Cannot read properties of null (reading 'edgesOut')。如果遇到此错误，请升级 npm，而不是排查代码库。

安全

此服务持有的凭据可完全控制 Websupport 账户——API 密钥对没有只读模式。SECURITY.md 介绍了凭据的处理方式、会返回敏感数据的工具，以及如何私下报告漏洞。

贡献

请参阅 CONTRIBUTING.md。注意，有两项边界由测试而非代码审查强制执行：不得使用订单或支付端点，且每个破坏性工具都必须声明 confirm: true。

许可证

MIT——请参阅 LICENSE。