Jabali Panel

jabali-mcp

Jabali Panel 用の Model Context Protocol サーバーです。

インストール  |  セットアップ  |  ツール  |  安全性  |  生成

AI アシスタントが、自然言語を通じてドメイン、DNS、メール、アプリケーション、 データベース、バックアップなどのパネル操作を実行できるようにします。パネルの 既存の REST API を薄くラップした生成コードであり、認証、検証、スコープ管理は 再実装せず、既存のものを利用します。

ステータス： 動作する MVP です。読み取りツールに加え、制限付きの書き込み／破壊的操作ツールと フリートレジストリを備えています。パネルの OpenAPI 仕様から生成されており、 チェックイン済みのコードが仕様と異なるとゴールデンテストが失敗します。

インストール

前提条件： Go 1.25 以降と、API トークンで接続できる Jabali Panel （セットアップを参照）。サーバーは stdio 経由で 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]

環境から設定を読み込み、1 行のステータスを stderr に出力してから、stdin/stdout で MCP を 提供します（EOF で終了します。そのため、< /dev/null を使ったスモークテストはすぐに終了します）。

セットアップ

最短手順：ガイド付きの設定

jabali-mcp init

各パネルについて（名前、URL、トークン）の入力を求め、パネルに対してトークンを検証し、 設定ディレクトリ（~/.config/jabali-mcp/panels.json）に 0600 の panels.json を書き込みます。 パネルはいくつでも追加できます。単一のインスタンスでも、複数のパネルからなるフリートでも構いません。 このパスがデフォルトなので、サーバーは 環境変数なしで設定ファイルを見つけます。したがって、 クライアントへの登録は次のコマンドだけで完了します。

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

いつでも init を再実行して設定を変更できます。以下の手動手順でも同じ設定を行えます。

手動設定

1. API トークンを発行します。 パネルでテナントシェル → API Tokens に移動し、トークンを作成します。平文の jat_… は一度だけ表示されるため、コピーしてください。サーバーをそのアカウントだけに制限するため、非管理者 （テナント）トークンを使用してください。

2. 次の環境変数を使って、サーバーの接続先をパネルに設定します。

変数	必須	意味
JABALI_PANEL_URL	✓	例：https://panel.example:8443/api/v1
JABALI_API_TOKEN	✓	jat_… ベアラートークン
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 上にあることを前提としています（ない場合はフルパスを使用してください）。必須の環境変数 2 つはインラインで示しています。これは 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 であり、キーは JSON の mcpServers ではなく、 mcp_servers（アンダースコア）であることに注意してください。

[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

標準の mcpServers JSON を使用する Cursor、Windsurf、Cline、Gemini CLI、およびその他のクライアントでは、上記の 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 トークンで認証します。このトークンは所有者であるユーザーとして機能し、パネルはすべてのエンドポイントで所有権を適用するため、サーバーがアクセスできるのは、そのトークンのユーザーが所有するリソースに限られます。テナントのトークンは、そのテナント内に制限されます。そのため、デフォルトでは非管理者トークンが安全です。

安全性

これはホスティングのコントロールプレーンを制御するため、変更操作は次の4層で制限されています。

1. デフォルトは読み取り専用です。 書き込みツールは、JABALI_MCP_ALLOW_WRITE=1 の場合にのみ登録されます。
2. 破壊的なツールには confirm: true が必要です。 すべての delete_*／revoke_*／rotate_*_password ツール（および restore_backup、disable_ssl）はプレビューを返し、confirm: true を指定して再度呼び出した場合にのみ実行されます。モデルは1回の操作で状態を破壊できません。これは、プロンプトインジェクションによるツール呼び出しへの対策です。
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 + 最近のエラー + 帯域幅を1つの回答にまとめます。プローブが失敗しても、ほかの処理は失敗として扱わずに結果を報告します）、report_issue（jabali-panel または jabali-mcp の GitHub リポジトリ向けのバグ報告／機能リクエストを、事前入力済みリンクとして作成します。書き込みモードでは、confirm: true を条件に gh 経由で直接登録することもできます）、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 — これらに加え、confirm が必要な破壊的操作のセットとして、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 が2つのファイルを結合し、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 General Public License v3.0 — LICENSE を参照してください。Jabali Panel と同じライセンスです。