canpoint-ui-mcp 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# canpoint-ui-mcp
+
+UI 规范查询 MCP（npm 包装器）。真正的实现在 PyPI 的同名
+[Python 包](https://pypi.org/project/canpoint-ui-mcp/)中，本包通过
+[`uvx`](https://docs.astral.sh/uv/) 拉起它，方便在 Claude Code / Cursor 等
+支持 MCP 的工具里用 `npx` 直接配置。
+
+「成果不出门、能力出门」：设计数据源（研学小程序 / 研学后台两套 Design DNA）
+由远程服务做 allowlist 投影，客户端只拿到 token、组件规格、生成纪律与截图
+色彩校验结论。
+
+## 能做什么
+
+- `list_platforms`：列出可用平台（mini=研学小程序，admin=研学后台）与数据状态
+- `get_tokens(platform, category)`：按类别查设计 token（color/typography/spacing/shape/elevation/layout）
+- `list_components(platform)`：列出组件规范条目
+- `get_component_spec(platform, component)`：查单个组件完整规格（支持中文别名与模糊匹配）
+- `get_generation_rules(platform)`：生成 UI 前必须遵守的纪律包
+- `verify_ui(platform, image_base64)`：对生成页面截图做确定性色彩校验（CIEDE2000）
+
+## 前置条件
+
+- 已安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)（提供 `uvx` 命令）
+- 远程 UI 规范服务地址与服务管理员发放的 API key（`usk_` 前缀；本包不含服务端）
+
+## 配置
+
+两个环境变量**必填**：
+
+| 变量 | 说明 |
+|------|------|
+| `UI_SPEC_SERVER_URL` | 远程服务地址，如 `http://175.27.156.19:47393`（不带 `/mcp`） |
+| `UI_SPEC_API_KEY` | 服务管理员发放的 Bearer key（`usk_` 前缀） |
+
+可选：`UI_SPEC_TIMEOUT`（HTTP 超时秒数，默认 30）、`UI_SPEC_LOG_LEVEL`（默认 INFO）。
+
+Claude Code 配置示例（`.mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "canpoint-ui": {
+      "command": "npx",
+      "args": ["-y", "canpoint-ui-mcp"],
+      "env": {
+        "UI_SPEC_SERVER_URL": "http://175.27.156.19:47393",
+        "UI_SPEC_API_KEY": "usk_<你的key>"
+      }
+    }
+  }
+}
+```
+
+Cursor（`mcp.json`）同款。Windows 下若 `npx` 启动失败，可把 `command` 改为
+`cmd`、`args` 改为 `["/c", "npx", "-y", "canpoint-ui-mcp"]`（env 表不变）。
+
+不想走 npm 时也可直接用 PyPI 包：
+
+```bash
+UI_SPEC_SERVER_URL=http://175.27.156.19:47393 UI_SPEC_API_KEY=usk_xxx uvx canpoint-ui-mcp
+```
+
+或跳过本客户端，直连远程 streamable-http 端点（`http://<host>/mcp`，
+`Authorization: Bearer usk_xxx`）。
+
+完整文档见仓库 [README](https://github.com/mjwyr/ui-knowledge/tree/main/mcp-server)。
+
+## License
+
+Apache-2.0 © 若清风

package/bin/_run.js

@@ -0,0 +1,92 @@
+"use strict";
+
+/**
+ * 共享启动器：通过 `uvx` 拉起 PyPI 包 `canpoint-ui-mcp` 的 console script，
+ * 透传 stdio 并转发退出码。
+ *
+ * 真正的 MCP 服务器在 Python 包里；本包装器只是为了让
+ * `npx canpoint-ui-mcp` 像其他 npm MCP 服务器一样可用。
+ */
+
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const PYPI_PACKAGE = "canpoint-ui-mcp";
+
+function packageVersion() {
+  try {
+    // eslint-disable-next-line global-require
+    return require(path.join(__dirname, "..", "package.json")).version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Windows 下不带 shell 的 spawn("uvx") 不会按 PATHEXT 解析 uvx.exe，
+ * 而 shell:true 又会触发 DEP0190 告警；这里自行在 PATH 中解析可执行文件。
+ */
+function resolveUvx() {
+  if (process.platform !== "win32") {
+    return "uvx";
+  }
+  const extensions = (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM")
+    .split(";")
+    .filter(Boolean);
+  const dirs = (process.env.PATH || process.env.Path || "")
+    .split(";")
+    .filter(Boolean);
+  for (const dir of dirs) {
+    for (const ext of extensions) {
+      const candidate = path.join(dir, `uvx${ext.toLowerCase()}`);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch {
+        // 继续找下一个候选
+      }
+    }
+  }
+  return "uvx";
+}
+
+function run(entrypoint) {
+  const version = packageVersion();
+  // 按 npm 包自身版本钉死 PyPI 包版本，两平台必须同版本发布
+  const spec = version ? `${PYPI_PACKAGE}==${version}` : PYPI_PACKAGE;
+  const args = ["--from", spec, entrypoint, ...process.argv.slice(2)];
+
+  const child = spawn(resolveUvx(), args, {
+    stdio: "inherit",
+    env: process.env,
+  });
+
+  child.on("error", (err) => {
+    if (err.code === "ENOENT") {
+      console.error(
+        [
+          "[canpoint-ui-mcp] 未找到 `uvx` 命令。",
+          "此 npm 包是 Python MCP 的包装器，需要先安装 uv：",
+          "  Windows: powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"",
+          "  macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh",
+          "  或 pip install uv",
+          `原始错误: ${err.message}`,
+        ].join("\n")
+      );
+    } else {
+      console.error(`[canpoint-ui-mcp] 启动失败: ${err.message}`);
+    }
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+module.exports = { run };

package/bin/canpoint-ui-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+"use strict";
+
+// canpoint-ui-mcp（stdio 薄客户端，代理远程 streamable-http 服务）。
+// 等价于 `uvx canpoint-ui-mcp`。
+// 环境变量：UI_SPEC_SERVER_URL、UI_SPEC_API_KEY（必填）。
+require("./_run.js").run("canpoint-ui-mcp");

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "canpoint-ui-mcp",
+  "version": "0.1.0",
+  "description": "UI spec query MCP for design-DNA-driven generation: fetch design tokens, component specs and generation rules, and verify generated-page screenshots against the palette. Wrapper that runs the PyPI package via uvx.",
+  "author": "若清风",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/mjwyr/ui-knowledge",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mjwyr/ui-knowledge.git",
+    "directory": "mcp-server/npm"
+  },
+  "bugs": {
+    "url": "https://github.com/mjwyr/ui-knowledge/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ui",
+    "design-tokens",
+    "design-system"
+  ],
+  "bin": {
+    "canpoint-ui-mcp": "bin/canpoint-ui-mcp.js"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}