chore(mcp): add local MCP debug tooling (github/terraform/ssh servers)

Local MCP debug setup: launcher scripts, config, setup script, and EN/ZH docs.
Secrets live in config/mcp/local-mcp.env (gitignored); commit a sanitized
local-mcp.env.example template instead.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -53,3 +53,6 @@ coverage/
 *.textClipping
 
 scripts/__pycache__/
+
+# local MCP debug secrets (contains a real PAT) — never commit
+config/mcp/local-mcp.env

config/mcp/bin/github-mcp-server.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+. "${ROOT_DIR}/config/mcp/local-mcp.env"
+exec docker run --rm -i \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN \
+  -e GITHUB_TOOLSETS=default,actions \
+  ghcr.io/github/github-mcp-server:latest

config/mcp/bin/mcp-ssh-manager.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec npx -y mcp-ssh-manager@latest

config/mcp/bin/terraform-mcp-server.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec docker run --rm -i \
+  ghcr.io/hashicorp/terraform-mcp-server:latest \
+  --toolsets=registry

config/mcp/local-mcp-config.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "/Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console/config/mcp/bin/github-mcp-server.sh"
+    },
+    "terraform": {
+      "command": "/Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console/config/mcp/bin/terraform-mcp-server.sh"
+    },
+    "ssh-manager": {
+      "command": "/Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console/config/mcp/bin/mcp-ssh-manager.sh"
+    }
+  }
+}

config/mcp/local-mcp.env.example

@@ -0,0 +1 @@
+GITHUB_PERSONAL_ACCESS_TOKEN=ghp_REPLACE_WITH_YOUR_TOKEN

docs/en/local-mcp-debug.md

@@ -0,0 +1,35 @@
+# Local MCP Debug Pack
+
+This pack is tuned for local debugging with a small tool surface.
+
+## Included
+
+- `github-mcp-server`
+- `terraform-mcp-server`
+- `mcp-ssh-manager`
+- `ansible.mcp` as an Ansible collection dependency, not a standalone MCP daemon
+
+## One-step setup
+
+```bash
+cd /Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console
+./scripts/setup-local-mcp-debug.sh
+```
+
+The script writes:
+
+- `/Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console/config/mcp/local-mcp-config.json`
+- `/Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console/config/mcp/local-mcp.env`
+- `/Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console/config/mcp/bin/*.sh`
+
+## Recommended defaults
+
+- GitHub MCP stays on the minimal default toolset
+- Terraform MCP stays on `registry`
+- SSH Manager runs through `npx` to avoid a global install
+- The GitHub token stays local in `local-mcp.env`
+
+## Required env vars
+
+- `GITHUB_PERSONAL_ACCESS_TOKEN`
+- `TFC_TOKEN` only if you need Terraform Cloud / Enterprise access

docs/zh/local-mcp-debug.md

@@ -0,0 +1,41 @@
+# 本机 MCP 调试包
+
+这个调试包面向 `xworkspace-console` 的本地联调场景，目标是尽量少的安装步骤、尽量少的 MCP 工具暴露面。
+
+## 覆盖范围
+
+- `github-mcp-server`
+- `terraform-mcp-server`
+- `mcp-ssh-manager`
+- `ansible.mcp` 作为 Ansible collection 依赖安装，不是独立 MCP 服务
+
+## 一键准备
+
+```bash
+cd /Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console
+./scripts/setup-local-mcp-debug.sh
+```
+
+脚本会生成：
+
+- `/Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console/config/mcp/local-mcp-config.json`
+- `/Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console/config/mcp/local-mcp.env`
+- `/Users/shenlan/workspaces/ai-workspace-lab/xworkspace-console/config/mcp/bin/*.sh`
+
+## 推荐用法
+
+- GitHub MCP 默认只开 `default` 工具集对应的最小面，再补少量常用工具集
+- Terraform MCP 默认只开 `registry`
+- SSH Manager 用 `npx` 启动，避免全局安装
+- GitHub token 只写入本地 `local-mcp.env`，不会进入聊天内容
+
+## 需要的环境变量
+
+- `GITHUB_PERSONAL_ACCESS_TOKEN`
+- `TFC_TOKEN` 仅当你要连 Terraform Cloud / Enterprise 时才需要
+
+## 调试建议
+
+- 先用 GitHub MCP 复现 action / PR / repo 相关问题
+- 再按需打开 Terraform MCP 的 `terraform` 工具集
+- SSH Manager 用于远程主机调试，不影响前两个 server

scripts/setup-local-mcp-debug.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUT_DIR="${XWORKSPACE_MCP_OUT_DIR:-$ROOT_DIR/config/mcp}"
+BIN_DIR="${OUT_DIR}/bin"
+ENV_FILE="${OUT_DIR}/local-mcp.env"
+PROFILE_FILE="${OUT_DIR}/local-mcp-config.json"
+
+mkdir -p "$OUT_DIR" "$BIN_DIR"
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+need_cmd() {
+  local cmd="$1"
+  if ! have "$cmd"; then
+    printf '[ERROR] missing required command: %s\n' "$cmd" >&2
+    exit 1
+  fi
+}
+
+need_cmd docker
+
+if [ -n "${GITHUB_PERSONAL_ACCESS_TOKEN:-}" ]; then
+  umask 077
+  cat >"$ENV_FILE" <<EOF
+GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}
+EOF
+elif [ ! -f "$ENV_FILE" ]; then
+  cat <<EOF >&2
+[ERROR] GITHUB_PERSONAL_ACCESS_TOKEN is required.
+Set it in your shell once, or create:
+  ${ENV_FILE}
+EOF
+  exit 1
+fi
+
+cat >"${BIN_DIR}/github-mcp-server.sh" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+. "${ROOT_DIR}/config/mcp/local-mcp.env"
+exec docker run --rm -i \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN \
+  -e GITHUB_TOOLSETS=default,actions \
+  ghcr.io/github/github-mcp-server:latest
+EOF
+
+cat >"${BIN_DIR}/terraform-mcp-server.sh" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+exec docker run --rm -i \
+  ghcr.io/hashicorp/terraform-mcp-server:latest \
+  --toolsets=registry
+EOF
+
+cat >"${BIN_DIR}/mcp-ssh-manager.sh" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+exec npx -y mcp-ssh-manager@latest
+EOF
+
+chmod +x "${BIN_DIR}/github-mcp-server.sh" "${BIN_DIR}/terraform-mcp-server.sh" "${BIN_DIR}/mcp-ssh-manager.sh"
+
+if ! have ansible-galaxy; then
+  printf '[WARN] ansible-galaxy not found; skipping ansible.mcp collection install.\n' >&2
+else
+  printf '[INFO] installing ansible.mcp collection...\n' >&2
+  ansible-galaxy collection install ansible.mcp ansible.utils >/dev/null
+fi
+
+cat >"$PROFILE_FILE" <<JSON
+{
+  "mcpServers": {
+    "github": {
+      "command": "${BIN_DIR}/github-mcp-server.sh"
+    },
+    "terraform": {
+      "command": "${BIN_DIR}/terraform-mcp-server.sh"
+    },
+    "ssh-manager": {
+      "command": "${BIN_DIR}/mcp-ssh-manager.sh"
+    }
+  }
+}
+JSON
+
+cat <<EOF
+[SUCCESS] wrote ${ENV_FILE}
+[SUCCESS] wrote ${PROFILE_FILE}
+
+Point your MCP client at:
+  ${PROFILE_FILE}
+
+Notes:
+- The GitHub wrapper loads the token from ${ENV_FILE}, so you only need to run this once.
+- Terraform MCP stays on the minimal registry toolset.
+- SSH Manager runs through npx to avoid a global install.
+- ansible.mcp is a collection dependency, not a standalone MCP daemon.
+EOF