@visualization-hub/dev-mcp

Visualization Hub Developer MCP Toolkit (@visualization-hub/dev-mcp)

低空前端组件资产知识库 — 开发者 MCP 工具链
面向 AI Agent（Cursor、Claude Desktop、VS Code、Deepfish）与前端工程师的本地全生命周期组件研发工作站。

🌟 核心特性

• 🚀 极速物理直传：本地一键打包 ZIP 并通过底层 HTTP Multipart 流式推送平台，耗时 < 0.1 秒，Token 消耗趋近于 0。
• 🛠️ 完整工程脚手架：一键生成 Vue 3 + TypeScript + Less + Vite 标准多文件工程，默认满足平台 13 项沙箱合规规范。
• 📦 本地 Vite 构建：在本地直接执行编译打包，输出沙箱专属的 dist/index.js 与 dist/index.css，直接捕获 TypeScript 与语法错误。
• 🛡️ 13 项合规静态扫描：自动化代码扫描（检查 pointer-events: auto !important、杜绝 emoji、onUnmounted 资源销毁等），提供精准代码行号与修复建议。
• 🧭 全流程智能引导：内置 get_developer_guide 导航工具，支持分阶段按需下发研发步骤与输入范例。
• 🔍 云端全量检索代理：100% 具备知识库资产搜索、分类统计、文件树查询、单文件源码读取与全局正则 grep 检索能力。

⚙️ 环境变量配置 (Environment Variables)

开发者 MCP 在启动时自动读取环境变量或当前目录下的 .env 文件。优先级为：工具入参 > 环境变量 > 默认兜底值。

工作区目录规范：无需配置环境变量，工作区目录默认为当前命令的执行目录 (process.cwd())；各工具亦支持通过参数（如 targetDir / projectDir）显式指定自定义路径。

💻 主流 AI Agent 客户端接入配置

1. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "visualization-dev-mcp": {
      "command": "npx",
      "args": ["-y", "@visualization-hub/dev-mcp"],
      "env": {
        "VIZ_BASE_URL": "http://localhost:3000",
        "VIZ_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxx",
        "VIZ_TIMEOUT_MS": "-1"
      }
    }
  }
}

2. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "visualization-dev-mcp": {
      "command": "node",
      "args": ["D:/.../dev-mcp/dist/index.js"],
      "env": {
        "VIZ_BASE_URL": "http://localhost:3000",
        "VIZ_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

3. VS Code (Roo Code / Cline MCP Settings)

{
  "mcpServers": {
    "viz-dev": {
      "command": "npx",
      "args": ["@visualization-hub/dev-mcp"],
      "env": {
        "VIZ_BASE_URL": "http://localhost:3000",
        "VIZ_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxx",
        "VIZ_TIMEOUT_MS": "60000"
      }
    }
  }
}

🛠️ 命令行工具使用

安装与别名

安装后，您可以使用以下两个命令之一启动开发者 MCP 服务器：

• viz-dev-mcp：原始命令名
• dkhub：简短别名（推荐）

# 通过 npx 直接使用
npx -y @visualization-hub/dev-mcp

# 或使用 dkhub 别名
npx -y @visualization-hub/dev-mcp dkhub

本地开发使用

在本地开发环境中，可以直接使用以下命令：

# 使用原始命令
./bin/viz-dev-mcp.js

# 或使用 dkhub 别名（需在 package.json 中配置）
dkhub

配置示例

在 AI Agent 客户端配置中，您可以使用 dkhub 作为命令名：

{
  "mcpServers": {
    "visualization-dev-mcp": {
      "command": "dkhub",
      "env": {
        "VIZ_BASE_URL": "http://localhost:3000",
        "VIZ_API_KEY": "ak_live_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

注意：dkhub 别名需要在全局安装或使用 npx 时才可用。本地开发时，建议使用 ./bin/viz-dev-mcp.js 直接启动。

🔀 两种运行模式

# CLI 命令模式：终端直接传参，立即执行
dkhub create_component_project --projectName my-comp --pageType cesium --title "我的组件"

# MCP 服务器模式：不带任何参数，常驻进程供 AI Agent 调用
dkhub

✍️ 参数传递语法（怎么传参）

在 CLI 命令模式下，参数以 --参数名 值 的形式传递，支持三种写法：

# 写法 1：空格分隔（推荐）
dkhub build_component_project --projectDir ./my-comp

# 写法 2：等号分隔
dkhub build_component_project --projectDir=./my-comp

# 写法 3：布尔开关（省略值，写上即为 true）
dkhub upload_component_project --projectDir ./my-comp --skipPreflight

参数对照示例（以 create_component_project 为例）：

dkhub create_component_project --projectName my-cesium-component --pageType cesium --title "三维量测组件"
        │                          │                                  │                    │
        │                          │                                  │                    └─ 值：中文标题（含空格需加引号）
        │                          │                                  └─ 参数名 --pageType，值 cesium
        │                          └─ 参数名 --projectName，值 my-cesium-component
        └─ 命令名

数组参数（keywords / libraries / tags）支持逗号或空格分隔：

dkhub create_component_project --libraries turf,tween.js ...
dkhub search_projects --keywords 无人机,三维

Shell 提示：部分 Shell（如 PowerShell）在未加引号时会将逗号转为空格。dkhub 已同时兼容逗号与空格分隔，两种写法均可正确解析为数组。含空格或中文的参数值建议用双引号包裹。

📋 dkhub 命令全清单

dkhub 提供以下 19 个命令，支持在终端直接传参调用（CLI 模式），也可由 AI Agent 通过 MCP 协议调用（服务器模式）。命令名可省略 dkhub_ 前缀。

0. 环境与配置类命令

1. 引导与规范类命令

2. 资产检索与源码查阅类命令

3. 本地工程化研发与发布类命令

🚀 工程创建命令详解：dkhub create_component_project

组件研发的第一步，一键生成符合平台 13 项沙箱合规规范的 Vue 3 + TypeScript + Vite 标准工程脚手架。

终端命令（直接复制执行）：

dkhub create_component_project --projectName my-cesium-component --pageType cesium --title "三维量测组件" --description "基于 Cesium 的三维空间量测 HUD 组件" --libraries turf,tween.js --targetDir D:/projects

参数逐项对照：

等价的 MCP 调用参数（仅 AI Agent 在服务器模式下使用，终端用户无需关心）：

{
  "projectName": "my-cesium-component",
  "pageType": "cesium",
  "title": "三维量测组件",
  "description": "基于 Cesium 的三维空间量测 HUD 组件",
  "libraries": ["turf", "tween.js"],
  "targetDir": "D:/projects",
  "overwrite": false
}

参数说明：

生成的标准工程结构：

命令执行成功后，将在目标目录生成以下开箱即满足 13 项沙箱合规骨架的工程：

my-cesium-component/
├── project.json            # 组件元数据清单 (name, title, pageType, entry, libraries, tags)
├── package.json            # 依赖与构建脚本 (vue, element-plus, @element-plus/icons-vue, pinia)
├── tsconfig.json           # TypeScript 编译配置
├── vite.config.ts          # Vite 构建配置 (external 排除 vue / element-plus / cesium 等全局库)
└── src/
    ├── index.vue           # 主视图 SFC (使用 Element Plus 组件，无底图容器、无 Emoji)
    ├── index.ts            # 核心逻辑 Composable (useComponentLogic) 与 onUnmounted 资源销毁
    ├── index.less          # 独立样式 (pointer-events: auto !important + 左上角定位)
    ├── util.ts             # localStorage 持久化工具纯函数
    ├── type.ts             # TypeScript 接口契约定义
    ├── env.d.ts            # 全局变量类型声明 (window.viewer / Cesium / THREE 等)
    └── components/
        └── StatusPanel.vue # 私有子组件示例 (引导多组件拆分)

返回值示例：

{
  "success": true,
  "message": "组件工程 [my-cesium-component] 成功生成在 D:/projects/my-cesium-component",
  "project_dir": "D:/projects/my-cesium-component",
  "project_name": "my-cesium-component",
  "page_type": "cesium",
  "created_files": [
    "project.json",
    "package.json",
    "tsconfig.json",
    "vite.config.ts",
    "src/env.d.ts",
    "src/type.ts",
    "src/util.ts",
    "src/components/StatusPanel.vue",
    "src/index.less",
    "src/index.ts",
    "src/index.vue"
  ],
  "next_steps": [
    "1. 进入工程目录: cd \"D:/projects/my-cesium-component\"",
    "2. (可选) 安装依赖: npm install",
    "3. 编写业务逻辑: 修改 src/index.vue, src/index.ts, src/index.less",
    "4. 本地编译打包: 调用 build_component_project(projectDir: \"D:/projects/my-cesium-component\")",
    "5. 沙箱合规自检: 调用 check_sandbox_compliance(projectDir: \"D:/projects/my-cesium-component\")",
    "6. 极速发布平台: 调用 upload_component_project(projectDir: \"D:/projects/my-cesium-component\")"
  ]
}

后续研发流程（由 AI Agent 按序调用）：

1. dkhub create_component_project — 生成标准工程脚手架（或 dkhub download_component_project 拉取已有组件二次开发）
2. 编码实现业务逻辑（按功能拆分私有子组件至 src/components/，单文件控制在 400 行内）
3. dkhub build_component_project — 本地编译打包，输出 dist/index.js 与 dist/index.css
4. dkhub check_sandbox_compliance — 13 项合规自检（需 ≥ 75 分且无阻断项）
5. dkhub upload_component_project（uploadType: "test"）— 测试版发布
6. dkhub get_project_url — 获取沙箱预览 URL 验证
7. dkhub upload_component_project（uploadType: "final"）— 正式定版发布

命名提示：projectName 必须使用小写字母、数字、中划线或下划线（如 my-cesium-component、drone_route_plan），不可包含大写字母或中文，否则将触发参数校验错误。

🎯 组件发布命令详解：dkhub upload_component_project

组件发布是研发闭环的最后一步，将本地工程以物理流方式直传至知识库平台。

终端命令（直接复制执行）：

dkhub upload_component_project --projectDir D:/projects/my-cesium-component --uploadType test --changelog "新增三维量测功能"

参数逐项对照：

等价的 MCP 调用参数（仅 AI Agent 在服务器模式下使用，终端用户无需关心）：

{
  "projectDir": "D:/projects/my-cesium-component",
  "uploadType": "test",
  "changelog": "新增三维量测功能",
  "skipPreflight": false
}

参数说明：

完整发布流程（终端依次执行，可直接复制）：

# 1. 创建工程脚手架
dkhub create_component_project --projectName my-cesium-component --pageType cesium --title "三维量测组件" --targetDir D:/projects

# 2. 编写业务代码后，本地编译打包
dkhub build_component_project --projectDir D:/projects/my-cesium-component

# 3. 13 项沙箱合规自检（需 ≥ 75 分且无阻断项）
dkhub check_sandbox_compliance --projectDir D:/projects/my-cesium-component

# 4. 测试版发布
dkhub upload_component_project --projectDir D:/projects/my-cesium-component --uploadType test

# 5. 获取预览链接，在浏览器验证渲染与交互
dkhub get_project_url --project_name my-cesium-component

# 6. 验证无误后，正式定版发布并归档
dkhub upload_component_project --projectDir D:/projects/my-cesium-component --uploadType final

调用方式总结：

• 终端用户 / CI：使用 CLI 命令模式，通过 --参数名 值 在命令行传参（如 dkhub build_component_project --projectDir ./my-comp），立即得到 JSON 结果。
• AI Agent（Cursor / Claude / VS Code 等）：使用 MCP 服务器模式，运行 dkhub（不带参数），由 Agent 通过 MCP 协议调用，工具全名为 dkhub_xxx，参数以 JSON 对象传入。
• 两种模式能力完全等价，共用同一套业务逻辑；命令名在 CLI 模式下可省略 dkhub_ 前缀。