cardbuddy 0.12.2 → 0.13.0

package/README.md

@@ -95,6 +95,58 @@ cardbuddy --preview          # 等价短参 -p
 
 ---
 
+## MCP：把 `card_*` 工具挂给外部 AI agent
+
+```bash
+cardbuddy --mcp        # stdio JSON-RPC 2.0；不启 HTTP 服务、不占端口
+```
+
+编辑器内置的网页 AI 助手走 `POST /__ai/chat`；`--mcp` 把**同一套** 16 个 `card_*` 工具
+（实现同为 `mcp/tools.mjs` + `mcp/client.mjs`，不存在第二份契约逻辑）以 stdio 暴露给
+Codex / Claude 这类外部 agent。工具清单与用法见 `skills/dsl-card-ai/SKILL.md`。
+
+agent 侧配置（`cwd` 必须是卡片工程根，读写才落在 `src/cards/`）：
+
+```jsonc
+{
+  "mcpServers": {
+    "dsl-card": {
+      "command": "<工程绝对路径>/node_modules/.bin/cardbuddy",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+> **stdout 是协议信道。** 经 `npm run` 调用必须加 `--silent`：`npm run mcp` 会把
+> `> 包名 脚本名` 横幅打到 stdout，多一行客户端就解析失败；直接调
+> `node_modules/.bin/cardbuddy --mcp` 无此问题。诊断一律走 stderr 且默认静默，
+> `CARDBUDDY_MCP_VERBOSE=1` 打开（会打出注入后的 `root=` / `apiBase=`）。
+
+`cardbuddy init` 生成的工程已带 `npm run mcp` 脚本。回归见 `tools/tests/cardbuddy-mcp.test.mjs`。
+
+### 工具对本地服务的依赖分档
+
+`--mcp` 自己不启服务。启动时自动注入 `CARD_ROOT=<工程根>` 与
+`CARD_API_BASE=http(s)://127.0.0.1:<端口>`（端口取 `FINMALL_CARD_PORT` / `DSL_DEV_PORT`，默认
+8787；已有同名环境变量时不覆盖），工具据此决定走 HTTP 还是本地降级：
+
+| 档 | 工具 |
+| --- | --- |
+| 纯本地，从不需要服务 | `card_route_input` `card_scaffold` `card_add_component` |
+| 优先服务，连不上自动降级为直接读写盘（`validate` 跑 Python 校验器） | `card_list` `card_read` `card_write` `card_validate` `card_history` `card_rollback` |
+| 优先服务，降级到包内独立离线渲染器 | `card_screenshot` |
+| **必须**另起一个 `cardbuddy` | `card_render_status` `card_node_models` `card_import_meta` |
+| **必须**另起服务 **且**已登录 FinMall | `card_sync` `card_save` `card_slice_upload` |
+
+> **别直接跑包内 `dist/vendored/mcp/server.mjs`。** `mcp/client.mjs` 在**模块顶层**就 resolve
+> `CARD_ROOT` / `CARD_API_BASE`（不是每次调用时读），绕过 CLI 包装层时前者会落到包内快照目录
+> （`card_list` 返回 0 张卡）、后者回退 `devApiBase()` 的 5180（消费者工程没有 Vite 把 `/__*`
+> 代理到 8787，`card_render_status` 直接 `dev-server-required`）。仓库内跑源码时入口回退
+> `<repo>/mcp/server.mjs`，无需先 build。
+
+---
+
 ## 配置（环境变量 / `.env`）
 
 在仓库根目录的 `.env` 中配置，或直接用环境变量：

package/dist/cli.js

@@ -17,9 +17,14 @@ import { installLogMirror } from './core.js'
 import { loadConfig } from './config.js'
 import { runInit } from './init.js'
 
+const args = process.argv.slice(2)
+const mcpMode = args.includes('--mcp')
+
 // 尽早镜像 stdout/stderr：让启动期日志（配置解析、端口占用提示等）也进入
 // 编辑器底部「服务日志」面板的环形缓冲。幂等，CARDBUDDY_STREAM_LOGS=0 时自动跳过。
-installLogMirror()
+// --mcp 下整个跳过：该模式不启 HTTP 服务，/__logs 没有消费者，让镜像去逐帧拦截
+// JSON-RPC 报文纯属白做功；协议信道的纯净由「这条路径上不打日志」保证（见 src/mcp.js）。
+if (!mcpMode) installLogMirror()
 
 // 被 dev.mjs 拉起时让出来源前缀（由启动器带背景色 chip 标注），避免双重来源标签。
 const srcTag =
@@ -40,12 +45,11 @@ for (const p of ['.env', '.env.cb', '.env.cb.local']) {
   }
 }
 
-const args = process.argv.slice(2)
 if (args.includes('--help') || args.includes('-h')) {
   console.log(`cardbuddy — CardBuddy 本地开发服务
 
 用法:
-  cardbuddy [--preview] [--help]
+  cardbuddy [--preview] [--mcp] [--help]
   cardbuddy init [目标目录] [--force] [--dry-run] [--no-skills] [--no-sample]
 
 命令:
@@ -61,6 +65,13 @@ if (args.includes('--help') || args.includes('-h')) {
 选项:
   --preview, -p  同时托管打包后的编辑器前端（本地预览），替代线上地址，并自动打开浏览器
                  旧名 --offline / -o 仍可用，已废弃
+  --mcp          以 stdio 起 MCP server（JSON-RPC 2.0），把 16 个 card_* 工具挂给 Codex / Claude
+                 等外部 agent；不启 HTTP 服务、不占端口。stdout 只走协议（经 npm run 调用要加
+                 --silent，否则横幅污染协议流），诊断走 stderr（CARDBUDDY_MCP_VERBOSE=1 打开）。
+                 本命令自身不起服务，工具按依赖分档：route_input / scaffold / add_component 纯本地；
+                 list / read / write / validate / history / rollback 降级为直接读写盘；screenshot
+                 降级到包内离线渲染器；render_status / node_models / import_meta 必须另起一个
+                 cardbuddy；sync / save / slice_upload 还必须已登录 FinMall。
   --help, -h     显示帮助
 
 环境变量:
@@ -117,26 +128,32 @@ if (subCommand === 'init') {
   }
 }
 
-const previewFlag = args.includes('--preview') || args.includes('-p')
-const legacyOfflineFlag = args.includes('--offline') || args.includes('-o')
-if (legacyOfflineFlag) {
-  console.warn(
-    srcTag + chalk.yellow('⚠ --offline 已废弃，请改用 --preview（本次仍按 preview 模式启动）')
-  )
+if (mcpMode) {
+  // stdio MCP server：不碰端口 / TLS / Vite，由 server.mjs 常驻监听 stdin 直到对端关闭。
+  const { startMcpServer } = await import('./mcp.js')
+  await startMcpServer(loadConfig())
+} else {
+  const previewFlag = args.includes('--preview') || args.includes('-p')
+  const legacyOfflineFlag = args.includes('--offline') || args.includes('-o')
+  if (legacyOfflineFlag) {
+    console.warn(
+      srcTag + chalk.yellow('⚠ --offline 已废弃，请改用 --preview（本次仍按 preview 模式启动）')
+    )
+  }
+  // 只在显式给了 flag 时才覆盖配置：无条件传 { preview: false } 会把 DSL_DEV_PREVIEW=1 顶成
+  // false —— 旧实现正因如此，环境变量开关一直是失效的。
+  startServer(previewFlag || legacyOfflineFlag ? { preview: true } : {})
+    .then(({ shutdown }) => {
+      const stop = async () => {
+        console.log('\n' + srcTag + chalk.cyan('正在关闭…'))
+        await shutdown().catch(() => {})
+        process.exit(0)
+      }
+      process.on('SIGINT', stop)
+      process.on('SIGTERM', stop)
+    })
+    .catch((e) => {
+      console.error(srcTag + chalk.red('启动失败：') + e)
+      process.exit(1)
+    })
 }
-// 只在显式给了 flag 时才覆盖配置：无条件传 { preview: false } 会把 DSL_DEV_PREVIEW=1 顶成
-// false —— 旧实现正因如此，环境变量开关一直是失效的。
-startServer(previewFlag || legacyOfflineFlag ? { preview: true } : {})
-  .then(({ shutdown }) => {
-    const stop = async () => {
-      console.log('\n' + srcTag + chalk.cyan('正在关闭…'))
-      await shutdown().catch(() => {})
-      process.exit(0)
-    }
-    process.on('SIGINT', stop)
-    process.on('SIGTERM', stop)
-  })
-  .catch((e) => {
-    console.error(srcTag + chalk.red('启动失败：') + e)
-    process.exit(1)
-  })

package/dist/config.js

@@ -94,6 +94,12 @@ export function loadConfig(env = process.env) {
     vendoredRuntimeDir: path.join(vendorRoot, 'card-editor'),
     // 仓库内开发回退：从仓库根运行时（cwd=仓库根）能直接命中 card-editor/，无需先 build。
     repoEditorDir: path.resolve(process.cwd(), 'card-editor'),
+    // MCP stdio server 入口（`cardbuddy --mcp`）：发布态命中包内快照 vendored/mcp/server.mjs；
+    // 仓库内跑源码时 src/vendored 不存在，回退到 <repo>/mcp/server.mjs —— src 与 dist 同深度，
+    // 故 __dirname 相对路径在两种情形下都对（不像 root 那样依赖 cwd）。
+    mcpServerEntry: fs.existsSync(path.join(vendorRoot, 'mcp', 'server.mjs'))
+      ? path.join(vendorRoot, 'mcp', 'server.mjs')
+      : path.resolve(__dirname, '../../../mcp/server.mjs'),
     // 包内技能快照（build 阶段从仓库 skills/ 全量内联，排除 .local / node_modules / __pycache__）：
     // 既是运行时的只读回退，也是 `cardbuddy init` 释放到项目根的源。
     vendoredSkillsDir,

package/dist/init.js

@@ -9,7 +9,7 @@
  *                             释放后既跑得快也写得了（FinMall 凭据落在项目内，不进 node_modules）
  *   tools/link-skills.mjs     把 skills/ 链到 Codex / Claude / WorkBuddy 等 AI 工具的项目级技能目录
  *   .env.cb                   共享配置模板（端口 / 远端基址 / AI 网关占位；密钥写 .env.cb.local）
- *   package.json              声明 cardbuddy 依赖与 dev / preview / link:skills 脚本
+ *   package.json              声明 cardbuddy 依赖与 dev / preview / mcp / link:skills 脚本
  *   .gitignore                私密层与产物不入库
  *   README.md                 上手说明
  *
@@ -188,6 +188,43 @@ skills/               AI 协作技能库（校验 / 同步 / 建卡管线脚本
 npm run link:skills   # 交互式选择 Codex / Claude / WorkBuddy 等，建立项目级技能软链
 \`\`\`
 
+## 把卡片工具挂给外部 AI agent（MCP，可选）
+
+编辑器内置的网页 AI 助手走 \`POST /__ai/chat\`。若要让 Codex / Claude 这类**外部** agent
+直接操作卡片，用随包提供的 MCP stdio server（16 个 \`card_*\` 工具，清单见
+\`skills/dsl-card-ai/SKILL.md\`）：
+
+\`\`\`jsonc
+// agent 的 MCP 配置；cwd 必须是本工程根，卡片读写才落在 src/cards/
+{
+  "mcpServers": {
+    "dsl-card": {
+      "command": "<本工程绝对路径>/node_modules/.bin/cardbuddy",
+      "args": ["--mcp"]
+    }
+  }
+}
+\`\`\`
+
+也可用 \`npm run --silent mcp\`。**\`--silent\` 不能省**：\`npm run\` 会把
+\`> 包名 脚本名\` 横幅打到 **stdout**，而 stdout 是 JSON-RPC 协议信道，多一行就让客户端解析失败。
+
+\`--mcp\` 自身不启服务、不占端口，工具按对本地服务的依赖分档：
+
+| 档 | 工具 |
+| --- | --- |
+| 纯本地，从不需要服务 | \`card_route_input\` \`card_scaffold\` \`card_add_component\` |
+| 优先服务，连不上自动降级为直接读写盘（\`validate\` 跑 Python 校验器） | \`card_list\` \`card_read\` \`card_write\` \`card_validate\` \`card_history\` \`card_rollback\` |
+| 优先服务，降级到包内独立离线渲染器 | \`card_screenshot\` |
+| **必须**另起一个 \`npm run dev\` | \`card_render_status\` \`card_node_models\` \`card_import_meta\` |
+| **必须**另起服务 **且**已登录 FinMall | \`card_sync\` \`card_save\` \`card_slice_upload\` |
+
+\`--mcp\` 会自动把 \`CARD_ROOT\` 指到本工程根、\`CARD_API_BASE\` 指到 \`.env.cb\` 的
+\`FINMALL_CARD_PORT\`（默认 8787）。**别直接跑包内 \`vendored/mcp/server.mjs\`**：那样
+\`CARD_ROOT\` 会落到 node_modules 里的快照目录（\`card_list\` 返回 0 张卡），端口也回退到
+5180（\`card_render_status\` 直接报 \`dev-server-required\`）。排查时可设
+\`CARDBUDDY_MCP_VERBOSE=1\` 让启动信息打到 stderr。
+
 ## FinMall 远端能力（可选）
 
 同步 / 保存 / 切图上传需要已登录的 FinMall 会话与 \`playwright\`
@@ -208,6 +245,10 @@ function projectPackageJson(projectName, version) {
           dev: 'cardbuddy',
           start: 'cardbuddy',
           preview: 'cardbuddy --preview',
+          // 给外部 agent（Codex / Claude）挂 card_* 工具的 stdio MCP server。
+          // 注意：MCP 客户端要走 `npm run --silent mcp` 或直接调 node_modules/.bin/cardbuddy --mcp，
+          // 因为 `npm run` 的横幅会打到 stdout、污染 JSON-RPC 协议流（详见生成的 README）。
+          mcp: 'cardbuddy --mcp',
           'link:skills': 'node tools/link-skills.mjs',
         },
         devDependencies: {
@@ -382,7 +423,7 @@ export async function runInit({
   const pkgState = writeFileSafe(path.join(target, 'package.json'), projectPackageJson(projectName, version), opts)
   pkgState === 'skipped'
     ? dim('package.json 已存在（跳过，--force 可覆盖）')
-    : ok(`${dryRun ? '将生成' : '已生成'} package.json（cardbuddy ^${version} + dev / preview / link:skills 脚本）`)
+    : ok(`${dryRun ? '将生成' : '已生成'} package.json（cardbuddy ^${version} + dev / preview / mcp / link:skills 脚本）`)
 
   // 6) tools/link-skills.mjs（把 skills/ 链给 AI 工具）
   const linkSrc = resolveLinkSkillsSource(config)

package/dist/mcp.js

@@ -0,0 +1,54 @@
+/**
+ * `cardbuddy --mcp` —— 以 stdio 起 MCP server（JSON-RPC 2.0，newline-delimited）。
+ *
+ * 为什么要有它：包内快照早就带了 mcp/tools.mjs + client.mjs（AI 工具调度的实现真身），
+ * 却没带 server.mjs 这个 stdio 入口 —— 于是消费者工程只能用编辑器内置的网页 AI 助手
+ * （/__ai/chat），没法把同一套 card_* 工具挂给 Codex / Claude 这类外部 agent。而随包释放的
+ * dsl-card-ai 技能整篇是以「只调 dsl-card MCP 工具、绝不重实现契约逻辑」为前提写的，
+ * 缺了入口那份技能在消费者工程里就落不了地。
+ *
+ * 两个必须守住的前提：
+ *   1. **stdout 是协议信道**，多一行非 JSON 就让客户端解析失败（`npm run` 的 `> 包名 脚本名`
+ *      横幅正是典型污染源，故推荐 `.bin/cardbuddy --mcp` 或 `npm run --silent mcp`）。这条路径
+ *      上因此一律不打日志：cli.js 跳过 installLogMirror()（该镜像服务于编辑器「服务日志」面板，
+ *      MCP 模式没有 HTTP 服务、/__logs 无消费者），启动诊断只走 stderr 且默认静默。
+ *   2. **CARD_ROOT / CARD_API_BASE 必须在 import 之前落定**。mcp/client.mjs 在模块顶层
+ *      就读这两个变量（不是每次调用时读），晚一步注入就无效：
+ *        - CARD_ROOT 不给，client 会把「mcp/ 的上一级」当工程根 —— 发布态那是包内快照目录，
+ *          根本找不到 src/cards；
+ *        - CARD_API_BASE 不给，client 回退 devApiBase() 即 5180（仓库里由 Vite 把 /__* 代理到
+ *          8787），而消费者工程通常只有 cardbuddy 的 8787、没有 Vite，于是连不上，
+ *          且 render_status / sync / save 这三个不支持离线降级的工具直接不可用。
+ *
+ * 本地服务没起也能用一部分：client.mjs 对 list / read / write / validate 有「直接读盘 + 跑
+ * Python 校验器」的离线降级；render_status / sync / save 依赖服务与 FinMall 登录态，不降级。
+ */
+import fs from 'node:fs'
+import { pathToFileURL } from 'node:url'
+
+/** 启动信息只在对 stderr 可见时才打（交互式调试）；被 MCP 客户端接管时保持静默。 */
+function diag(line) {
+  if (process.stderr.isTTY || process.env.CARDBUDDY_MCP_VERBOSE === '1') {
+    process.stderr.write(`[cardbuddy --mcp] ${line}\n`)
+  }
+}
+
+/**
+ * @param {ReturnType<import('./config.js').loadConfig>} config
+ * @returns {Promise<void>} 解析后 server.mjs 自行常驻监听 stdin，本函数不返回直到进程结束
+ */
+export async function startMcpServer(config) {
+  const entry = config.mcpServerEntry
+  if (!entry || !fs.existsSync(entry)) {
+    // 走 stderr + 非 0 退出：MCP 客户端会把它显示成 server 启动失败，而不是静默挂着
+    process.stderr.write(`[cardbuddy --mcp] 找不到 MCP server 入口：${entry || '(未解析)'}\n`)
+    process.exit(1)
+  }
+  if (!process.env.CARD_ROOT) process.env.CARD_ROOT = config.root
+  if (!process.env.CARD_API_BASE) {
+    process.env.CARD_API_BASE = `${config.https ? 'https' : 'http'}://127.0.0.1:${config.port}`
+  }
+  diag(`root=${process.env.CARD_ROOT}`)
+  diag(`apiBase=${process.env.CARD_API_BASE}（本地服务未起时 list/read/write/validate 自动降级为直接读盘）`)
+  await import(pathToFileURL(entry).href)
+}

package/dist/vendored/mcp/server.mjs

@@ -0,0 +1,84 @@
+import readline from 'node:readline'
+import { TOOLS, dispatch } from './tools.mjs'
+
+/**
+ * 无依赖的 MCP stdio server（JSON-RPC 2.0，newline-delimited）。
+ *
+ * 支持的方法：
+ *   - initialize      → 返回 protocolVersion / capabilities / serverInfo
+ *   - ping            → 返回 {}
+ *   - tools/list      → 返回 TOOLS
+ *   - tools/call      → 分发到 client 函数，结果转成 MCP content
+ *   - notifications/* → 不回复
+ *
+ * 设计：零第三方依赖（项目未装 @modelcontextprotocol/sdk），手写最小可用实现；
+ * 仅用 Node 22 内置 fetch / readline。截图 png 以 image content 块返回，供多模态直接阅读。
+ */
+
+const rl = readline.createInterface({ input: process.stdin, terminal: false })
+
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n')
+}
+
+/** 把 client 返回结果转成 MCP tools/call 的 result（content + isError） */
+function resultToContent(name, args, result) {
+  // 截图 png：base64 直接转 image 块
+  if (name === 'card_screenshot' && args.format !== 'json' && result && result.base64 && !result.error) {
+    return { content: [{ type: 'image', data: result.base64, mimeType: result.mime || 'image/png' }], isError: false }
+  }
+  const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2)
+  const isError = !!(result && typeof result === 'object' && result.error)
+  return { content: [{ type: 'text', text }], isError }
+}
+
+rl.on('line', async (line) => {
+  const t = line.trim()
+  if (!t) return
+  let msg
+  try {
+    msg = JSON.parse(t)
+  } catch {
+    return
+  }
+  const { id, method, params } = msg
+  try {
+    if (method === 'initialize') {
+      send({
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: params?.protocolVersion || '2024-11-05',
+          capabilities: { tools: {} },
+          serverInfo: { name: 'dsl-card-mcp', version: '1.0.0' },
+        },
+      })
+    } else if (method === 'ping') {
+      if (id != null) send({ jsonrpc: '2.0', id, result: {} })
+    } else if (method === 'tools/list') {
+      send({ jsonrpc: '2.0', id, result: { tools: TOOLS } })
+    } else if (method === 'tools/call') {
+      const name = params?.name
+      const args = params?.arguments || {}
+      let result
+      try {
+        result = await dispatch(name, args)
+      } catch (e) {
+        result = { error: 'dispatch-failed', message: String((e && e.message) || e) }
+      }
+      send({ jsonrpc: '2.0', id, result: resultToContent(name, args, result) })
+    } else if (method && method.startsWith('notifications/')) {
+      // 通知类（如 notifications/initialized）不回复
+    } else {
+      if (id != null) {
+        send({ jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } })
+      }
+    }
+  } catch (e) {
+    if (id != null) {
+      send({ jsonrpc: '2.0', id, error: { code: -32603, message: String((e && e.message) || e) } })
+    }
+  }
+})
+
+process.stdin.on('end', () => process.exit(0))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cardbuddy",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Local dev service for the CardBuddy card editor — decouples card CRUD (sync/save/validate/render-status/screenshot) from the static public editor, so the editor can be deployed to any static host while each developer runs a local service against their own card source.",
   "type": "module",
   "bin": {