@wubaoqi/guanvm

观远 BI 虚拟工作站 MCP Server。把 shell 工具链（coreutils/jq/rg/sed/find）、js 脚本引擎与观远 BI CLI（guancli/guanetl/guanvis/guands/guanmetric/guanwf）编译为 WASI wasm，运行在纯 Go 沙箱（wazero）中，对外提供 MCP Streamable HTTP 端点。AI 客户端通过少量通用工具（execute_command / read_file / …）操作一台"虚拟工作站"完成 BI 查询、ETL 编辑、可视化构建等任务。

所有 wasm 资产与技能资料随包分发，安装后开箱即用。

快速启动

BI_BASE_URL=https://app.guandata.com \
MCP_TRUSTED_GATEWAY=true \
npx @wubaoqi/guanvm

默认监听 127.0.0.1:9090，MCP 端点 POST /mcp，健康探针 GET /healthz。

MCP 客户端（如 Cursor / Claude Code）配置示例：

{
  "mcpServers": {
    "guanvm": {
      "url": "http://127.0.0.1:9090/mcp",
      "headers": {
        "X-Personal-Token": "<你的观远 BI Personal Token>"
      }
    }
  }
}

MCP_TRUSTED_GATEWAY=true 表示入口鉴权由部署侧（本机回环 / 前置网关）负责，适合本机自用。 对外暴露端口时请改用 MCP_ENTRYPOINT_TOKEN=<入口凭证>，客户端以 Authorization: Bearer <凭证> 访问。

目录约定

npm 包装层在启动时注入以下默认值（已设置的环境变量不会被覆盖）：

| 环境变量 | 默认值 | 说明 | |---|---|---| | GUANVM_WASM_DIR | <包内>/assets | wasm 资产（随包分发） | | GUANVM_SKILLS_DIR | <包内>/skills-bundle | 技能资料（随包分发） | | GUANVM_WORKSPACE_DIR | <当前目录>/guanvm-run/ws | 工作区数据（VM 内 / 的宿主落盘） | | GUANVM_COMPILE_CACHE_DIR | <当前目录>/guanvm-run/cache | wasm AOT 编译缓存（加速二次启动） |

workspace 与编译缓存落在启动时所在目录下，便于按项目隔离；换目录启动即得到干净环境。

常用环境变量

| 变量 | 默认 | 说明 | |---|---|---| | BI_BASE_URL | （必填） | 目标观远 BI 地址，身份验证与 BI API 出网白名单都依赖它 | | MCP_TRUSTED_GATEWAY | false | true 时跳过入口 Bearer 鉴权（由部署侧负责） | | MCP_ENTRYPOINT_TOKEN | 空 | 入口凭证；与 MCP_TRUSTED_GATEWAY 二选一 | | MCP_HTTP_HOST / MCP_HTTP_PORT | 127.0.0.1 / 9090 | 监听地址 | | BI_APP_TOKEN | 空 | 启用 loginId / 用户属性身份路径时的服务端换 token 凭证 | | GUANVM_TZ | Asia/Shanghai | 机内时区（IANA 名称），影响 date、js Date 与 CLI 本地时间 | | GUANVM_IMAGE_CONTENT | auto | read_file 读图片的返回形态：auto 以图像内容返回（超高长页自动分块）；off 只返回文本元信息——接入的模型不支持图像理解（纯文本 Agent）时显式关闭 | | GUANVM_MEM_LIMIT_MB | 512 | 单 wasm 实例线性内存上限（1..4096） | | GUANVM_CMD_TIMEOUT_S | 60 | 前台命令默认超时 | | GUANVM_WORKSPACE_TTL_H | 168 | 工作区闲置回收时长 |

BI 用户身份按请求解析，支持 4 条路径（优先级从高到低）：X-Personal-Token > X-GuanBI-Uid-Token > x-guanbi-login-id（需 BI_APP_TOKEN）> 用户属性头（需 BI_USER_PROPERTY_KEY）。每次工具调用都必须携带有效 BI 身份；BI 凭证由宿主注入，wasm 沙箱内全程零凭证。

子命令

npx @wubaoqi/guanvm            # 启动服务器
npx @wubaoqi/guanvm version    # 打印版本
npx @wubaoqi/guanvm help       # 打印帮助

支持平台

macOS (arm64/x64)、Windows (x64，实验性)。

License

见 LICENSE（观远开发者工具免费评估许可，中文版 LICENSE.zh-CN）。