Jabali Panel

jabali-mcp

一个适用于 Jabali Panel 的 Model Context Protocol 服务。

安装  |  设置  |  工具  |  安全  |  生成

让 AI 助手通过自然语言管理面板操作，包括域名、DNS、邮件、应用、 数据库和备份。它是对面板现有 REST API 的轻量生成式封装：不重新实现身份验证、 验证或作用域处理，而是直接使用它们。

**状态：**可用的 MVP。包含读取工具、受限的写入／破坏性工具以及集群 注册表，均由面板的 OpenAPI 规范生成（如果检入的代码与规范不一致，黄金测试会失败）。

安装

**先决条件：**Go 1.25+，以及可访问的 Jabali Panel 和 API 令牌 （参见设置）。此服务通过标准输入输出与 MCP 通信——由 MCP 客户端 （Claude Code、Claude Desktop 等）启动；无需将其作为守护进程运行。

预编译二进制文件

从最新版本 下载适用于你平台的二进制文件（linux/darwin × amd64/arm64，附带 SHA256SUMS），然后：

chmod +x jabali-mcp_*_linux_amd64
sudo install -m 0755 jabali-mcp_*_linux_amd64 /usr/local/bin/jabali-mcp

使用 go install

go install github.com/shukiv/jabali-mcp/cmd/jabali-mcp@latest

二进制文件会放在 $(go env GOBIN)（或 $(go env GOPATH)/bin）中。

从源代码安装

git clone https://github.com/shukiv/jabali-mcp.git
cd jabali-mcp
make build            # -> ./jabali-mcp  (stamps the version from git describe)

更新

jabali-mcp update --check        # report the latest release, install nothing
jabali-mcp update                # re-installs the latest (go install …@latest)
jabali-mcp update --ref v1.2.3   # pin a tag/commit
jabali-mcp update --dry-run      # print the command only

自更新会运行 go install，因此 PATH 中必须有 Go。之后重启 MCP 客户端以加载新的二进制文件。（从检出目录安装的？运行 git pull && make build。安装的是预编译二进制文件？下载新版本。）

验证

JABALI_PANEL_URL=https://panel.example:8443/api/v1 \
JABALI_API_TOKEN=jat_… \
jabali-mcp < /dev/null
# -> jabali-mcp <version> — read-only; panels: [default]

程序从环境变量读取配置，将一行状态信息打印到标准错误， 然后通过标准输入／输出提供 MCP 服务（遇到 EOF 时退出，这就是为什么 < /dev/null 冒烟测试会立即返回）。

设置

最快方式：交互式引导

jabali-mcp init

程序会提示你输入每个面板的信息（名称、URL、令牌），并验证令牌是否可用于该 面板，然后在配置目录中创建权限为 0600 的 panels.json （~/.config/jabali-mcp/panels.json）。可按需添加任意数量的面板——单个实例可添加一个，集群可添加多个。由于这是默认路径， 服务无需任何环境变量即可找到该文件，因此只需这样注册客户端：

claude mcp add jabali -- jabali-mcp        # no --env needed after init

随时重新运行 init 即可重新配置。以下手动步骤与此操作相同，只是需要手动完成。

手动配置

1. 创建 API 令牌。 在面板中，进入租户 shell → API Tokens 并创建一个令牌。明文 jat_… 只会显示一次——请复制它。使用非管理员 （租户）令牌，这样服务就只能访问该账户。

2. 将服务指向你的面板，设置以下环境变量：

变量	必需	含义
JABALI_PANEL_URL	✓	例如 https://panel.example:8443/api/v1
JABALI_API_TOKEN	✓	jat_… bearer 令牌
JABALI_PANEL_NAME		逻辑名称（默认值为 default）
JABALI_CA_FILE		用于信任可自托管面板 CA 的 PEM 证书包
JABALI_MCP_ALLOW_WRITE		1 表示启用可修改数据的工具（默认：只读）
JABALI_MCP_DRY_RUN		1 表示强制所有写入操作仅预览、不执行
JABALI_MCP_ADMIN		1 表示同时公开 /admin/* 工具（需要管理员令牌）
JABALI_PANELS_FILE		用于多面板模式的面板 JSON 数组（覆盖单面板变量）

3. 在 MCP 客户端中注册。 以下所有示例均假设 jabali-mcp 位于你的 PATH 中（否则请使用其完整路径），并在行内展示了两个必需的环境变量。这是一个 stdio MCP 服务，因此任何支持 MCP 的客户端都能启动它。

Claude Code（CLI — 写入 .mcp.json / 你的 Claude 配置）：

claude mcp add jabali \
  --env JABALI_PANEL_URL=https://panel.example:8443/api/v1 \
  --env JABALI_API_TOKEN=jat_… \
  -- jabali-mcp

Claude Desktop — claude_desktop_config.json：

{
  "mcpServers": {
    "jabali": {
      "command": "jabali-mcp",
      "env": {
        "JABALI_PANEL_URL": "https://panel.example:8443/api/v1",
        "JABALI_API_TOKEN": "jat_…"
      }
    }
  }
}

OpenAI Codex（CLI — 写入 ~/.codex/config.toml）：

codex mcp add jabali \
  --env JABALI_PANEL_URL=https://panel.example:8443/api/v1 \
  --env JABALI_API_TOKEN=jat_… \
  -- jabali-mcp

或者手动编辑 ~/.codex/config.toml — 注意它是 TOML，键名为 mcp_servers（带下划线），而不是 JSON 中的 mcpServers：

[mcp_servers.jabali]
command = "jabali-mcp"

[mcp_servers.jabali.env]
JABALI_PANEL_URL = "https://panel.example:8443/api/v1"
JABALI_API_TOKEN = "jat_…"

OpenCode — opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jabali": {
      "type": "local",
      "command": ["jabali-mcp"],
      "environment": {
        "JABALI_PANEL_URL": "https://panel.example:8443/api/v1",
        "JABALI_API_TOKEN": "jat_…"
      },
      "enabled": true
    }
  }
}

Kimi Code CLI（写入 ~/.kimi/mcp.json）：

kimi mcp add --transport stdio jabali \
  -e JABALI_PANEL_URL=https://panel.example:8443/api/v1 \
  -e JABALI_API_TOKEN=jat_… \
  -- jabali-mcp

Cursor、Windsurf、Cline、Gemini CLI 和其他客户端若使用标准 mcpServers JSON，则可使用与上方 Claude Desktop 相同的条目——在该客户端配置文件的 mcpServers 下添加一个 { "command": "jabali-mcp", "env": { … } } 块。

先以只读模式启动。需要执行修改操作时，将 JABALI_MCP_ALLOW_WRITE=1 添加到 环境变量中（初期还可添加 JABALI_MCP_DRY_RUN=1，观察它会执行什么操作）。

通过 SSH 在远程主机上运行

由于它使用 stdio 通信，上述任一客户端都可以通过 SSH 在远程主机上 启动它，而不是在本地启动——工具流会通过 SSH 管道传输。将客户端的命令设为 ssh，并将远程调用作为参数传入，例如 Claude Desktop：

{
  "mcpServers": {
    "jabali-prod": {
      "command": "ssh",
      "args": ["operator@box",
        "JABALI_PANEL_URL=https://localhost:8443/api/v1 JABALI_API_TOKEN=jat_… jabali-mcp"]
    }
  }
}

在该主机上，面板 API 可通过 localhost 访问，令牌仍会将所有操作限定在其对应用户的范围内。客户端一侧除了 SSH 密钥外，无需安装任何内容。

多面板

最简单的方法是运行 jabali-mcp init——在它询问“添加另一个面板？”时添加多个面板。它会将这些面板写入默认的 panels.json，服务会自动加载该文件。

也可以将 JABALI_PANELS_FILE 指向一个 JSON 数组（这会覆盖单面板变量），或自行编写该数组：

[
  { "name": "prod-a", "url": "https://a:8443/api/v1", "token": "jat_…" },
  { "name": "prod-b", "url": "https://b:8443/api/v1", "token": "jat_…" }
]

配置解析顺序：JABALI_PANELS_FILE → 单面板环境变量 （JABALI_PANEL_URL + JABALI_API_TOKEN）→ 默认的 panels.json。在 多面板模式下，每个工具都接受可选的 panel 参数以选择面板；省略该参数时使用第一个（默认）面板。

管理员工具（同一二进制文件，单独选择启用）

管理员操作界面（列出 / 创建用户、读取 / 更新服务器设置、 运行面板更新并读取其状态）位于同一二进制文件中，但属于单独的注册组， 只有设置 JABALI_MCP_ADMIN=1 才会公开。它负责整个主机范围的操作—— 其影响范围远大于租户工具，因此默认不启用，并且需要管理员令牌（无论是否设置该标志，面板的 RequireAdmin 都会拒绝非管理员令牌并返回 403）。管理员写入工具仍需设置 ALLOW_WRITE，且 admin_run_updates 需要确认才能执行。admin_renew_ssl 和 admin_retry_ssl 也属于这一组：它们的路径看起来限定于租户，但面板会将它们注册在 RequireAdmin 保护之下。请为管理员服务单独配置管理员令牌； 其他所有用途均使用租户令牌。

身份验证模型 — 继承面板的租户隔离机制

工具使用每位用户专属的 Bearer 令牌进行身份验证。令牌以其所属用户的身份运行，面板会在每个端点强制执行所有权检查，因此服务器只能访问令牌所属用户拥有的资源——租户令牌仅限于该租户。这就是非管理员令牌默认更安全的原因。

安全性

此工具连接到托管控制平面，因此通过四层机制限制变更操作：

1. 默认只读。 只有设置 JABALI_MCP_ALLOW_WRITE=1 后，才会注册写入工具。
2. 破坏性工具需要 confirm: true。 每个 delete_* / revoke_* / rotate_*_password 工具（以及 restore_backup、disable_ssl）都会返回预览，并且仅在再次调用并传入 confirm: true 时执行操作。模型无法一步就破坏状态——这是防止提示词注入工具调用的防护措施。
3. 工具提示。 只读工具带有 readOnlyHint；破坏性工具带有 destructiveHint，以便客户端提示风险。
4. 试运行。 所有写入工具都接受 dry_run: true，以返回其将要发送的确切请求，但不执行操作；设置 JABALI_MCP_DRY_RUN=1 可强制全局启用此功能。

始终启用 TLS 验证。若要信任自托管面板的私有 CA，请将 JABALI_CA_FILE 指向其证书包——这会添加 CA，而不是禁用验证。

工具

各工具的完整参考文档，包含参数和限制：docs/TOOLS.md （自动生成 — make docs）。

读取（始终启用）： list_domains、get_domain、list_dns_records、 list_mailboxes、list_forwarders、list_applications、list_databases、 list_backups、list_api_tokens、list_mail_logs、tail_web_log、 get_ssl_status、get_domain_whois、get_domain_bandwidth、whoami、 get_disk_usage、list_activity、list_cron_jobs、get_cron_job、 get_cron_log、list_app_catalog、get_application、get_database、 list_database_users、get_mailbox、get_autoresponder、 get_backup_manifest、list_ssh_keys、get_php_settings、 list_php_versions、list_files、preview_file，以及复合工具 diagnose_domain（在一个答复中提供配置 + SSL + DNS + 近期错误 + 带宽；某项探测失败时会报告失败情况，但不会影响其他部分），report_issue（为 jabali-panel 或 jabali-mcp GitHub 仓库起草 Bug 报告 / 功能请求，并生成预填链接；在写入模式下，也可以通过 gh 直接提交，需通过 confirm: true 确认），以及 search_docs（在任务执行过程中查询 jabali-panel.com 上的官方面板文档——匿名、仅限来源的抓取；可通过 JABALI_DOCS_URL 更改来源）。

preview_file 会将文件内容（最多 1 MiB）读入对话——其中可能包含 wp-config.php 等机密信息。根据面板设计，create_database_user 和 rotate_*_password 工具只会返回一次明文密码。

写入（需要 JABALI_MCP_ALLOW_WRITE=1）： create_domain、update_domain、 create_dns_record、update_dns_record、create_mailbox、create_forwarder、 create_backup、install_application、create_database、enable_ssl、 create_cron_job、update_cron_job、run_cron_job、create_database_user、 grant_database_access、update_mailbox、set_autoresponder、add_ssh_key、 update_php_settings，以及需通过确认才能执行的破坏性工具：delete_domain、 delete_dns_record、delete_mailbox、restore_backup、 disable_ssl、delete_cron_job、delete_application、delete_database、 delete_database_user、revoke_database_access、rotate_database_password、 delete_autoresponder、rotate_mailbox_password、delete_backup、 delete_ssh_key。

工具生成

工具由生成器生成，而不是手工编写，因此工具接口不会与 API 脱节：

• openapi/openapi.yaml — 面板规范的随附副本。
• openapi/tools.yaml — 筛选配置：公开哪些操作、对应的工具名称、read/write 分组，以及 destructive/paginated 标记。此处未列出的操作不会公开（这样可将 admin/* 和 nic/update 排除在外）。
• internal/gen 将两者合并并生成 internal/tools/generated.go；运行 make gen 或 go generate ./... 即可。
• 若筛选配置中的操作在规范中不存在，则会报硬错误（防止脱节）；若已提交的文件不是最新版本，TestGeneratedIsUpToDate 会失败。
• openapi/panel-routes.txt 固定记录面板实际提供的路由，数据读取自面板内嵌的规范（panel-api/internal/api/openapi.yaml，面板自己的测试会确保其路由与已注册路由一致）。如果筛选配置中的操作不在此文件中，TestCuratedOpsArePanelRoutes 就会失败：对应工具会返回 404。仅靠随附的规范无法发现这一问题，因为它是手动编辑的副本。

面板 API 变更后，要更新内容：运行 make panel-routes（读取 ../jabali2 的 origin/main；可通过 PANEL_REPO= / PANEL_REF= 覆盖），手动将变更的操作合并到 openapi.yaml（整体复制会丢失此处编写的请求正文），调整 tools.yaml，运行 make gen，然后检查差异。

开发

make build     # build the binary
make gen       # regenerate internal/tools/generated*.go + docs/TOOLS.md
make docs      # regenerate docs/TOOLS.md only
make test      # go test -race ./...
make vet       # go vet ./...

# zero-mutation live smoke against your configured panel (run before a release):
make smoke

目录结构

cmd/jabali-mcp/     entry point (stdio MCP server)
cmd/gen-tools/      CLI wrapper over internal/gen
internal/client/    Bearer-token HTTP client + fleet registry
internal/tools/     tools.go (helpers + gate) + generated.go (the tools)
                    + composite.go (hand-written diagnose_domain)
internal/gen/       openapi.yaml + tools.yaml -> generated.go + docs/TOOLS.md
openapi/            vendored spec + curation
scripts/smoke/      zero-mutation live smoke client (pre-release check)
docs/TOOLS.md       generated tool reference (make docs)
docs/DESIGN.md      architecture, security model, roadmap
HANDOVER.md         full project handover: decisions, traps, release process

路线图

• M1 — 只读 MVP ✅ Bearer 客户端、MCP stdio 服务、读取工具、测试。
• M2 — 受限修改 ✅ 通过可选启用标志控制写入工具；破坏性操作需确认。
• M3 — 多面板管理 ✅ 多面板注册表 + panel 工具参数。
• 生成器 ✅ 根据规范和筛选配置生成工具，并通过黄金测试验证。
• 试运行 ✅ 单次调用的 dry_run + 全局 JABALI_MCP_DRY_RUN。
• 输入验证 ✅ 为规范中的值约束（enum、minLength、min/max）生成逐工具检查 — 在发送任何请求前快速失败。
• 管理工具 ✅ /admin/* 接口通过 JABALI_MCP_ADMIN=1 + 管理员令牌启用，使用同一个二进制文件。
• 日志 ✅ list_mail_logs + tail_web_log（面板新增了 GET /logs/tail）。
• 下一步： 更丰富的 InputSchema（让客户端可以看到约束）、组合式诊断（diagnose_domain）、CLI 模式。

许可证

GNU Affero 通用公共许可证 v3.0 — 详见 LICENSE。与 Jabali Panel 使用相同的许可证。