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>
This commit is contained in:
parent
5a76c5ed06
commit
029ef9fc13
3
.gitignore
vendored
3
.gitignore
vendored
@ -53,3 +53,6 @@ coverage/
|
||||
*.textClipping
|
||||
|
||||
scripts/__pycache__/
|
||||
|
||||
# local MCP debug secrets (contains a real PAT) — never commit
|
||||
config/mcp/local-mcp.env
|
||||
|
||||
8
config/mcp/bin/github-mcp-server.sh
Executable file
8
config/mcp/bin/github-mcp-server.sh
Executable file
@ -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
|
||||
3
config/mcp/bin/mcp-ssh-manager.sh
Executable file
3
config/mcp/bin/mcp-ssh-manager.sh
Executable file
@ -0,0 +1,3 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
exec npx -y mcp-ssh-manager@latest
|
||||
5
config/mcp/bin/terraform-mcp-server.sh
Executable file
5
config/mcp/bin/terraform-mcp-server.sh
Executable file
@ -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
|
||||
13
config/mcp/local-mcp-config.json
Normal file
13
config/mcp/local-mcp-config.json
Normal file
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
1
config/mcp/local-mcp.env.example
Normal file
1
config/mcp/local-mcp.env.example
Normal file
@ -0,0 +1 @@
|
||||
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_REPLACE_WITH_YOUR_TOKEN
|
||||
35
docs/en/local-mcp-debug.md
Normal file
35
docs/en/local-mcp-debug.md
Normal file
@ -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
|
||||
41
docs/zh/local-mcp-debug.md
Normal file
41
docs/zh/local-mcp-debug.md
Normal file
@ -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
|
||||
100
scripts/setup-local-mcp-debug.sh
Normal file
100
scripts/setup-local-mcp-debug.sh
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user