luban-dev-mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,319 @@
-# Temporary Holding Version
+# Luban Dev MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把 Luban（知行）平台的开发助手能力，通过 MCP 接进 opencode / Claude Code / workbuddy 等外部 Agent。
+
+- **模型由宿主提供**：MCP 不保存、不调用任何模型 Key；平台不承担 token 成本。
+- **工具实现单源**：直接复用平台 Agent 的同一份技能实现，不是第二套。
+- **自助接入**：`init` 向导处理 TLS、登录、应用选择、工具面、宿主配置。
+
+---
+
+## 1. 前置
+
+- Node.js **20+**
+- 一个 Luban 账号（能访问目标应用）
+- 平台地址，例如 `https://113.249.105.235:3003`（**不要带 `/api/v1`**）
+
+## 2. 第一次接入
+
+推荐一条命令（自签证书自动记住，详见 4.6）：
+
+```bash
+npx -y luban-dev-mcp connect --base-url https://<平台> --token lbp_... --app <应用ID>
+```
+
+想走交互向导：
+
+```bash
+npx luban-dev-mcp init
+```
+
+本地开发（当前仓库）：
+
+```bash
+node frontend/mcp/dist/luban-dev-mcp.mjs connect --base-url http://localhost:8080 --token lbp_... --app 4310
+```
+
+向导会依次处理：
+
+1. 平台地址；
+2. TLS（自签名证书会显示指纹并询问是否记住；也可 `--ca` / `--insecure`）；
+3. 登录（PAT，或账号密码）；
+4. 选择应用；
+5. 选择工具面（full / main / flow / page）；
+6. 打印 opencode / Claude Code / workbuddy 配置片段。
+
+配置写入 `~/.luban/mcp/config.json`，凭据写入 `~/.luban/mcp/credentials.json`（0600）。
+
+> 多环境：`~/.luban/mcp/config.json` 支持多个 environment；用 `--env <name>` / `LUBAN_ENV` 切换。
+
+## 3. 自检
+
+```bash
+luban-dev-mcp doctor
+```
+
+会检查：TLS/连通性 → 登录态 → 应用访问 → 模式（只读/锁定）→ 工具面大小。失败时给中文修法。
+
+常用：
+
+```bash
+luban-dev-mcp doctor --json
+luban-dev-mcp whoami
+luban-dev-mcp logout
+luban-dev-mcp print-config --host opencode
+luban-dev-mcp page-check --app 4310 --page 1398 --screenshot out.png --json
+```
+
+## 4. TLS：自签名 / CA
+
+你的线上地址 `https://113.249.105.235:3003` 目前是**自签名证书**（CN/SAN = IP，有效期到 2027-11-10）。Node 默认会拒绝，三种处理：
+
+| 方式 | 命令 | 适用 |
+|---|---|---|
+| **首次信任并记住（最省事）** | `--trust-server`（`connect` 默认开启）；宿主配置用 `LUBAN_TRUST_SERVER=1` | 自签名/内网；只做一次，不用导出证书 |
+| 内联 CA（宿主配置） | `LUBAN_CA_PEM`（PEM 文本） | 不想在客户机放证书文件 |
+| 跳过校验（试用） | `--insecure` 或 `LUBAN_INSECURE=1` | 自签名临时环境；有中间人风险 |
+| 提供 CA（推荐生产） | `--ca /path/ca.pem` 或 `LUBAN_CA_CERT=/path/ca.pem` | 有内部 CA |
+| 换受信任证书 | 运维替换 | 长期生产 |
+
+`--trust-server` 是 SSH 式的首次信任（TOFU）：CLI 会显示服务器证书的 SHA-256 指纹，确认后存到
+`~/.luban/mcp/trusted-<host>_<port>.pem`，之后所有请求都用它校验；平台换证后重新信任一次即可。
+首次连接请与平台管理员核对指纹，防止中间人。
+
+`doctor` 会区分：`DEPTH_ZERO_SELF_SIGNED_CERT`、`CERT_HAS_EXPIRED`、`ERR_TLS_CERT_ALTNAME_INVALID`、`ECONNREFUSED` 等，并给出对应修法。
+
+> **不要用 `http://IP:端口` 访问平台 UI**：浏览器在非安全上下文（非 HTTPS、非 localhost）会禁用 `crypto.subtle`，平台登录的 RSA 加密会直接失败。MCP 的 API 调用可以走 HTTP，但平台 UI 登录需要 HTTPS 或 `http://localhost`（可用 SSH 隧道）。
+
+## 4.5 PAT（推荐，尤其 SSO 部署）
+
+在平台「平台管理 → 访问令牌」新建一个令牌（`lbp_` 开头，只显示一次），然后：
+
+```bash
+luban-dev-mcp init --base-url https://<平台> --token lbp_...
+# 或已配置好地址后：
+luban-dev-mcp login --token lbp_...
+```
+
+PAT 的权限就是你本人的平台权限；可在同一页面随时撤销。SSO 部署下不需要把账号密码交给 CLI。
+
+## 4.6 命令行接入（可选，主要用于排障/运维）
+
+拿到 PAT 后，不需要先导证书、不用记 `--ca`：
+
+```bash
+luban-dev-mcp connect \
+  --base-url https://113.249.105.235:3003 \
+  --token lbp_... \
+  --app 2
+```
+
+`connect` 会自动：
+
+1. 连服务器，发现自签名证书；
+2. 显示证书主题、有效期、SHA-256 指纹；
+3. 记住证书（`~/.luban/mcp/trusted-*.pem`）并写入配置；
+4. 校验 PAT、列出应用、保存环境（默认 `main` profile）；
+5. 打印 opencode/Claude Code 配置片段。
+
+之后 `doctor`、`serve`、`page-check` 都直接复用已记住的证书，**不需要再传 `--ca`**。
+
+> `init` 在非交互环境需要显式加 `--trust-server`；`connect` 默认开启。
+> 普通客户不需要这一步：平台「访问令牌」弹窗会生成完整 WorkBuddy 配置（含 `LUBAN_TOKEN` 与
+> `LUBAN_TRUST_SERVER=1`），粘贴即可。
+
+## 5. 宿主配置
+
+### opencode（1.18 当前格式）
+
+```json
+{
+  "mcp": {
+    "luban": {
+      "type": "local",
+      "command": ["node", "/绝对路径/frontend/mcp/dist/luban-dev-mcp.mjs", "serve"],
+      "enabled": true,
+      "timeout": 3600000
+    }
+  }
+}
+```
+
+发布到 npm 后可以用 `["npx","-y","luban-dev-mcp","serve"]`。
+
+opencode V2 用：
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "luban": { "type": "local", "command": ["npx", "-y", "luban-dev-mcp", "serve"] }
+    }
+  }
+}
+```
+
+### Claude Code / Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "luban": {
+      "command": "npx",
+      "args": ["-y", "luban-dev-mcp", "serve"]
+    }
+  }
+}
+```
+
+### workbuddy
+
+配置文件是 `~/.workbuddy/mcp.json`（注意不是 `.mcp.json`）。WorkBuddy 使用
+`mcpServers` + `command/args` 的 stdio 格式。
+
+**客户最短路径（不需要终端）**：平台「访问令牌」新建成功后，弹窗会生成一段完整配置，
+直接粘贴到 `~/.workbuddy/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "luban": {
+      "command": "npx",
+      "args": ["-y", "luban-dev-mcp", "serve"],
+      "env": {
+        "LUBAN_BASE_URL": "https://113.249.105.235:3003",
+        "LUBAN_TOKEN": "lbp_...",
+        "LUBAN_PROFILE": "main",
+        "LUBAN_TRUST_SERVER": "1"
+      }
+    }
+  }
+}
+```
+
+保存 → WorkBuddy 连接器管理 → 对 `luban` 点「信任」→ 对话里问
+“你现在能用到哪些 MCP 工具？”验证。
+
+- `LUBAN_TRUST_SERVER=1`：首次连接自签名平台时自动抓取并记住证书，指纹会打到 MCP 日志；
+  正式 CA 环境改用 `LUBAN_CA_CERT`（文件）或 `LUBAN_CA_PEM`（PEM 文本），并去掉这一项。
+- PAT 已包含在这段配置里；**不要贴到聊天框，也不要提交到代码仓库**。
+  配置保存在本机 `~/.workbuddy/mcp.json`，离职/换机时撤销令牌即可。
+- 更安全（可选，需要一次终端）：先 `connect` 把 PAT 存到 `~/.luban/mcp/credentials.json`（0600），
+  再把 `mcp.json` 写成不带 token 的版本：
+
+```json
+{
+  "mcpServers": {
+    "luban": {
+      "command": "npx",
+      "args": ["-y", "luban-dev-mcp", "serve"]
+    }
+  }
+}
+```
+
+- WorkBuddy 运行在沙箱/不同 HOME 时，在 `env` 里补 `"LUBAN_MCP_HOME": "/Users/你/.luban/mcp"`。
+- 已全局安装时可把 `npx -y luban-dev-mcp` 换成 `luban-dev-mcp`。
+- **opencode** 用另一份格式（`mcp.luban` + `environment`，不是 `env`），平台「访问令牌」弹窗里有单独的
+  opencode Tab，可直接复制，不需要手写。
+
+### opencode（平台生成的版本）
+
+```json
+{
+  "mcp": {
+    "luban": {
+      "type": "local",
+      "command": ["npx", "-y", "luban-dev-mcp", "serve"],
+      "environment": {
+        "LUBAN_BASE_URL": "https://113.249.105.235:3003",
+        "LUBAN_TOKEN": "lbp_...",
+        "LUBAN_PROFILE": "main",
+        "LUBAN_TRUST_SERVER": "1"
+      },
+      "enabled": true,
+      "timeout": 3600000
+    }
+  }
+}
+```
+
+opencode V2 把 `mcp.luban` 换成 `mcp.servers.luban`，其余字段相同。
+
+## 6. 工具面（按模型上下文选）
+
+| profile | 业务工具 | 工具面字符 | 估算 token | 适用 |
+|---|---|---|---|---|
+| `full` | 15 | ~95K | ~63K | 256K 上下文 |
+| `main` | 14 | ~64K | ~43K | 128K 上下文（查询/页面/组织） |
+| `flow` | 8 | ~48K | ~32K | 只做流程/编排 |
+| `page` | 7 | ~20K | ~13K | 只做页面 |
+
+`init` 会按选择保存；`doctor` 会打印实际读数。
+
+## 7. 安全
+
+- 不在平台保存用户模型 Key；MCP 不调用 `/agent/dev/chat/stream`。
+- token 存 `~/.luban/mcp/credentials.json`（0600）；日志/错误/doctor 全部脱敏。
+- 危险/不可逆操作仍走 `luban_confirm`；页面重名/数据源选择走 `luban_resume`。
+- 建议生产环境用 `--ca`，不要长期用 `--insecure`。
+- **只读试用**：`--read-only`（只暴露读工具，写工具直接拒绝）；**应用锁定**：`--lock-app`（`luban_use_app` 不能切到别的应用）。`init` 会询问，默认推荐只读 + 锁定。
+
+## 8. 页面验证
+
+MCP 工具面没有 DOM，不能跑平台 `page_behavior`。用 `page-check`（Playwright）补页面运行态：
+
+```bash
+# 浏览器二选一：
+# A) 下载 Playwright 的 Chromium（约 190MB，需要网络）
+npx playwright install chromium
+# B) 直接用本机 Chrome/Chromium（不需要下载；page-check 也会自动探测）
+luban-dev-mcp page-check --app 4310 --page 1398 \
+  --browser-executable "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+
+# 打开页面，检查 console/pageerror、表格行数、预警 Tag、截图
+luban-dev-mcp page-check --app 4310 --page 1398 --screenshot out.png
+
+# 自签名线上地址：先 connect --trust-server，之后 page-check 直接跑
+luban-dev-mcp page-check --app 4310 --page 1398 --screenshot out.png --json
+```
+
+> `page-check` 只做本机验证：配置里是 `--ca` / `--trust-server` / `--insecure` 时，浏览器侧自动跳过证书校验，
+> **不需要把 CA 导入系统 Keychain**。MCP 的 API 调用仍按 `--ca` / `--trust-server` 的信任链走。
+> 只有 `--insecure` 会跳过 API 调用的校验，`--ca` / `--trust-server` 不会。
+
+本地开发如果 API 在 8080、前端在 5173：
+
+```bash
+luban-dev-mcp page-check --app 4310 --page 1398 --frontend-url http://localhost:5173 --json
+```
+
+输出 JSON：`ok / title / tables / rows / redTags / alerts / stats / buttons / consoleErrors / pageErrors / screenshot`。
+
+> 覆盖范围：页面打开、console/pageerror、行数、预警/统计、按钮、截图。
+> 不覆盖：`viewAsUserId` 角色预览、平台桥调用计数、`PageBehaviorSmoke` 内部原子。
+> 仓库内调试可用 `LUBAN_PLAYWRIGHT_MODULE=/绝对路径/e2e/node_modules/playwright/index.mjs` 复用 e2e 的 Playwright。
+> 本机 Chrome 路径也可用 `LUBAN_BROWSER_EXECUTABLE` 环境变量；Playwright 浏览器缺失时 page-check 会自动尝试本机 Chrome/Chromium。
+
+
+## 9. 常见问题
+
+| 现象 | 修法 |
+|---|---|
+| `DEPTH_ZERO_SELF_SIGNED_CERT` | 用 `connect --trust-server` 自动记住证书；或 `--ca` 提供 CA；或 `--insecure` 试用 |
+| 自签名证书不想手动导出 | `luban-dev-mcp connect ... --trust-server`（显示指纹并记住） |
+| `crypto.subtle 不可用` | 不要用 `http://IP:端口` 访问平台；用 HTTPS、域名 + CA，或 SSH 隧道到 `http://localhost` |
+| 401 | `luban-dev-mcp login` 重新登录；token 过期 |
+| 403 | 账号没有该应用权限 |
+| 404 | 地址不要带 `/api/v1`；应用 ID 是否正确 |
+| 工具没出现 | 重启宿主；`doctor` 看工具面；opencode 用 `mcp.luban`（V1）或 `mcp.servers`（V2） |
+| 上下文太大 | `--profile main` / `flow` / `page` |
+
+## 10. 本地开发
+
+```bash
+cd frontend
+npx tsc -p mcp/tsconfig.json --noEmit
+node scripts/build-agent-mcp.mjs
+node mcp/dist/luban-dev-mcp.mjs --help
+```