z-mcp-codesign 0.1.1

package/README.md

@@ -0,0 +1,132 @@
+# 前言
+
+
+
+这是一个基于 `@modelcontextprotocol/sdk` 实现的 **MCP stdio 服务**，用于在本机通过 Edge 打开腾讯 CoDesign 页面并抓取当前画板图片。
+
+
+
+# 配置说明
+
+
+
+在 Cursor 工作区根目录创建或编辑 `.cursor/mcp.json`。保存后在 Cursor 的 MCP 相关设置中启用该服务，必要时重新加载窗口或刷新 MCP 列表。
+
+
+
+**前提**：本机需已安装 **Microsoft Edge**；服务通过 Playwright 使用系统 Edge（`channel: "msedge"`）。
+
+
+
+## 使用已发布的 npm 包（推荐）
+
+
+
+在任意项目中均可使用，无需克隆本仓库：
+
+
+
+```json
+
+{
+
+  "mcpServers": {
+
+    "z-mcp-codesign": {
+
+      "command": "npx",
+
+      "args": ["-y", "z-mcp-codesign", "--stdio"]
+
+    }
+
+  }
+
+}
+
+```
+
+
+
+## 使用本地源码（开发与调试）
+
+
+
+在克隆后的仓库根目录配置 `.cursor/mcp.json`，并先执行 `npm install` 与 `npm run build`（生成 `dist/`）。`args` 中的 `"."` 表示使用当前目录作为 npm 包：
+
+
+
+```json
+
+{
+
+  "mcpServers": {
+
+    "z-mcp-codesign": {
+
+      "command": "npx",
+
+      "args": ["-y", ".", "--stdio"]
+
+    }
+
+  }
+
+}
+
+```
+
+
+
+若 MCP 启动时工作目录不是仓库根目录，可在该条目中增加 `"cwd"`，值为本仓库的绝对路径（Windows 下 JSON 字符串里反斜杠需写成 `\\`）。
+
+
+
+## 环境变量与用户数据目录
+
+
+
+调用 **`codesign_open_login`** 成功后，进程会设置环境变量 **`Z_MCP_CODESIGN_EDGE_USER_DATA`**，指向本次使用的 Edge 用户数据根目录；随后在同一 MCP 会话里调用 **`codesign_screen_inspect`** 且不显式传 `userDataDir` 时，会自动复用该目录下的登录态。
+
+
+
+也可在两条工具调用里显式传入相同的 **`userDataDir`**（绝对路径）；若使用非 `Default` 的 Edge profile，请在登录与抓图两次调用中传入相同的 **`profileDirectory`**。
+
+
+
+# 使用 MCP 登录 CoDesign
+
+
+
+1. 按上文在 Cursor 中启用本 MCP 服务。
+
+2. 在对话中让助手调用工具 **`codesign_open_login`**（参数可全部省略；默认打开 `https://codesign.qq.com/app/login`）。
+
+3. 在弹出的 **Edge** 窗口中完成腾讯 CoDesign 登录（扫码或账号密码等）。
+
+4. **关闭该 Edge 窗口**（释放用户数据目录锁），否则后续抓图可能启动失败。
+
+5. 再调用 **`codesign_screen_inspect`**，传入目标 CoDesign 页面 **`url`**（例如设计稿 inspect 链接）；返回的 JSON 中含 **`imageBase64`**（PNG），供客户端展示或落盘。
+
+
+
+# 提供的工具
+
+
+
+| 工具名 | 说明 |
+
+| ------ | ---- |
+
+| `codesign_open_login` | 有界面打开 CoDesign 登录页，用于在本机 Edge 用户数据目录中完成登录 |
+
+| `codesign_screen_inspect` | 打开指定 CoDesign 页面，截取最大的可见 `.screen-inspect` 区域，以 PNG 的 base64 返回 |
+
+
+
+# 使用示例
+
+
+
+在已登录（步骤见上一节）的前提下，调用 **`codesign_screen_inspect`**，传入 `url`（CoDesign 页面地址）。工具成功时返回的文本内容为 JSON，字段包括 `imageBase64`、`title`、`boundingBox` 等；将 `imageBase64` 解码即可得到 PNG 二进制数据。
+