museav-mcp

系统中有两个提供 MCP 通道的组件，分别承担不同职责：

分工原则：获取 CortexOS 规则、技能与系统上下文使用 cs mcp serve；调用图像生成、排版、浏览器与质检等外部能力使用 cs-mcp。

说明：具备 Shell 执行权限的环境可直接运行 cs CLI；cs-mcp 主要为跑在 MCP 协议上的客户端提供标准化工具调用通道。

核心机制

分层原则：能力在 CLI 中，MCP 仅负责标准化串联与发现。本仓库工具均为对应 CLI 的薄封装。

Related MCP server: DreamLayer image tools

能力分组

各分组的执行位置、联网和账号要求独立：museav 的云调用需要账号与配额，wechat 读取本机数据，browser 访问网站需要网络，scorecard 等工具也可能依具体功能联网。本地运行不代表每项操作都离线。 分层定位：cs 为系统核心，museav 为云能力扩展。

默认策略是探测式：某个分组的 CLI 在 PATH 上，它的工具才会注册。理由是工具 schema 会随每一次模型请求发出去 —— 聚合 MCP 越串越多，不该让用户为「他机器上根本没装的工具」 付 token。没启用的分组不会消失：groups_list 始终可用，它会告诉你这个 MCP 还能干什么、 该装什么。

想强开或裁剪，用环境变量 CS_MCP_GROUPS：

CS_MCP_GROUPS=all              # 全开（缺 CLI 的分组也注册，调用时才报装什么）
CS_MCP_GROUPS=facet,contrast   # 只开这几个
CS_MCP_GROUPS=-museav          # 默认集里去掉这几个

3.0.0 之前的旧名 MUSEAV_MCP_GROUPS 仍兼容（新名优先，同时设置且不同时以新名为准并在 stderr 提示）。之所以必须留旧名：变量被忽略不会报错 —— 它会静默回落成探测式， 原来写 all 的人那些强开的分组会悄悄消失，连告警都没有。

⚡ 30 秒上手

装（一条命令，不需要 Node，也不需要 npm）：

curl -fsSL https://raw.githubusercontent.com/cortexos-dev/cs-mcp/main/install.sh | bash

装完会自报版本（cs-mcp --version），并把接法一并打出来：

claude mcp add cs -- ~/.local/bin/cs-mcp

为什么不是 npx -y cs-mcp：这个网关底下包着 museav-cli、mlx-vlm-kit、 contrast-guard、facet、reel-kit、lite-browser 一堆东西 —— 用户为了用上全套能力， 已经要付 6 种安装方式的代价（npm / pipx / brew / curl）。如果网关自己还得 npm i -g 或 npx -y，等于在最前面再加一道 Node + npm + registry 网络的门槛， 而它本该是把门槛降到一条命令的那一层。多数用户会卡在起手第一步。 （npm 上的 cs-mcp 早已撤下、本仓不再发 npm —— 装法只有上面这一条。）

想要哪组能力就装哪个 CLI —— 装了哪个 CLI 就自动长出哪组工具，没装的不会白占上下文：

npm i -g museav-cli                    # 这一行是出图那组

从源码起（改这个仓、或不想下二进制）：

git clone git@github.com:cortexos-dev/cs-mcp && cd cs-mcp
pnpm install && pnpm build
claude mcp add cs -- node "$PWD/dist/index.js"

Windows 暂时没有一键脚本，用 WSL 或走「从源码起」那条。

然后在 Agent 里说「用 museav 出一张图」，或者先问一句「这个 MCP 有哪些能力分组」。

工具（43 个）

museav 组 —— MUSE AV 出图中台（17）

本地后期那四个不联网、不消耗中台额度。

vlm 组 —— 本地看图理解（4）

四个都免登录、零成本、不联网（本地 Qwen3-VL）；需要 Apple Silicon。

contrast 组 —— 对比度门禁（3）

check 查「对不对」，measure 查「多少」——丑的每一处单看往往都『对』，所以两个都要跑。 不达标时工具会照常把完整报告交回来（CLI 用退出码当判据，不是调用失败）。

facet 组 —— Markdown 排版成成品（2）

reel 组 —— 竖版短视频合成（3）

素材与文案按顺序一一对应，数量不等时取较少的一方并明确报出来，不会静默丢弃。 不给 voice 时镜头时长由 perShot 决定（不需要任何模型）；给了才走本地 Qwen3-TTS。 硬依赖系统里的 ffmpeg（不在 npm 包里）。

museav 出的是原料（图、无声片），reel 出的是能发的成品 —— 这两段是一条业务线的前后半截。

browser 组 —— 浏览器操控（13）

人类交接协议是这个组的核心价值：撞到登录墙不是死路，而是一条有契约的路径 —— status 看它在等什么 → await_human 阻塞等人（退出码 3/4 是状态不是故障， 工具会原样把「需要人类介入 / 等待超时」交回来）→ resume 继续。

身份隔离：lite-browser 的会话按 agent 隔离，而默认身份是 default。本 MCP 每次都 显式传自己的身份（默认 mcp，可用 CS_MCP_BROWSER_AGENT 改；旧名 MUSEAV_MCP_BROWSER_AGENT 仍兼容），不会跟别的 agent 抢会话——这是实测踩出来的（第一次没传，直接开在别人正在用的 default 会话上）。

刻意不暴露（是判断，不是遗漏）：exec -- <命令>（把输入变成任意 shell 命令）、 cdp（裸协议通道）、cookie export / cookie pull-system（导出/解密 Cookie = 直接交出凭据， 与 kyvault 不进公开 MCP 同一条理由）。

发 Skill 之前必读

museav_skillhub_publish 默认只预演（本地打包校验，不上传不提交），把待提交内容返回给你核对。 只有用户明确说「提交 / 确认 / submit」才带 submit=true —— 提交不可逆，Skill ID 是 平台主键、跨版本不可改名。

真提交前会先查登录态。未登录时 MCP 不会挂在那儿等你：二维码要等进程结束才能 返回给用户，硬等就是死锁，所以会直接报错，让你引导用户去终端跑一次 museav skillhub login 扫码。

CLI 自带平台资产护栏：Skill 正文里抄了 MUSE AV 平台公共模板的提示词会被拒绝发布， 只引用模板 slug（museav gen --template xxx）则放行——搬运是重新分发资产，引用是正常集成。 被拒时按提示把正文换成调用方式。

两个「先查再调」

museav_gen_background 的 template / skill 是必填二选一，但 id 和 slug 只能从中台实时拉： 先用 museav_list_templates / museav_list_skills 查真实清单，再传进去。凭印象编一个，中台只会报 「模板不存在」，Agent 分不清是自己拼错了还是真没有。

模板自带哪些占位符看清单里「字段:」那一列，取值用 museav_gen_background 的 fields 传 （JSON 对象字符串）。

facet_build 的 template 同理 —— 先用 facet_templates 拿清单。

前置条件

npm i -g museav-cli        # museav 组：出图 / 后期 / 素材 / SkillHub（需要 >= 3.9.0）
pipx install git+https://github.com/webkubor/mlx-vlm-kit.git   # vlm 组
npm i -g contrast-guard    # contrast 组
npm i -g github:webkubor/facet   # facet 组（git 分发，不在 npm 上更新）
npm i -g github:webkubor/reel-kit   # reel 组（git 分发；另外要 brew install ffmpeg）
curl -fsSL https://raw.githubusercontent.com/webkubor/lite-browser/main/install.sh | bash   # browser 组

装哪几个由你决定 —— 没装的组就是不会注册，不会报错。

museav_gen_background 还需要中台 apiKey（按 museav-cli 的说明配置）。 本地工具首次运行会下载对应模型（抠图 ~214MB、超分 ~65MB、去水印 ~200MB、 vlm 的 Qwen3-VL-4B 约 2.9GB）。

可执行文件不在全局 PATH 时，用环境变量指定绝对路径： MUSEAV_BIN、MLX_VLM_BIN、CONTRAST_GUARD_BIN、FACET_BIN。

接到 Agent 上

下面三段的 command 都是装好的那个二进制（cs-mcp）。如果它不在 PATH 里， 就写绝对路径 —— 装完 cs-mcp --version 会告诉你装在哪。

Claude Code 一行：

claude mcp add cs -- cs-mcp

DSH 在 profile 的 cordis.patch.yml 里加一行：

- id: mcp-cs
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: cs
    transport: stdio
    command: cs-mcp
    args: []

serverName 决定客户端里的工具命名空间：cs 让工具叫 mcp__cs__museav_gen_background。 3.0.0 之前是 museav，于是加了 museav_ 前缀后会变成 mcp__museav__museav_gen_background 这种双重前缀 —— 所以这次一并改成了 cs。 DSH 与 WorkBuddy 是 GUI 工具、不是 Agent（见 cs rule agent_governance 的 gui-not-agent 红线）， 这份配置是修工具本身，不是给它派活。

或手写配置（任意支持 MCP 的客户端）：

{
  "mcpServers": {
    "cs": {
      "command": "cs-mcp",
      "args": []
    }
  }
}

想让某个没装 CLI 的分组也出现在工具列表里（调用时才报装什么），加上 env：

{
  "mcpServers": {
    "cs": {
      "command": "cs-mcp",
      "args": [],
      "env": { "CS_MCP_GROUPS": "all" }
    }
  }
}

本机微信读取：wechat（Mac 专用）

本组包装 wx-cli 的六个本地命令：wechat_status、 wechat_decrypt、wechat_sessions、wechat_contacts、wechat_messages、wechat_search。 把 wx-cli 安装在运行 cs-mcp 的那台 Mac 的 PATH 上，分组就会自动出现。 Agent 只读到同一台 Mac 的微信库，跨机器的 MCP 客户端如果在各自机器启动 cs-mcp， 读到的也是各自机器的库；不会把 owner 的微信数据从 Mac 传到服务器。

首次使用先调用 wechat_status。CLI 需要数据库密钥；上游的 wx-cli key extract 要求关闭 macOS SIP 并重启微信，这是 owner 本人的系统设置选择，本 MCP 不提供该操作。 有密钥后调用 wechat_decrypt 生成本地缓存，再用其他四个工具查。所有查询结果 都是真实私人聊天内容；wechat_search 不套用 wx-cli 的联系人隐藏规则， 可能搜到隐藏联系人，使用时要留意。

本机 Hermes 也可直接挂同一份 cs-mcp，~/.hermes/config.yaml 的 mcp_servers 下增加：

  cs:
    command: node
    args:
      - /绝对路径/cs-mcp/dist/index.js

配置改完后重启 Hermes 会话，再用 groups_list / wechat_status 验证。

本地开发（改这个仓库时）

pnpm install && pnpm build     # 产物在 dist/，package.json 的 bin 指向它

配置里把 command 换成 node、args 指向 /绝对路径/cs-mcp/dist/index.js 即可。

还没进来的项目（以及为什么）

这张版图是逐步长出来的，不是一次列全。没进来分三种情况，都不是「忘了」：

想加一组？ 三步：给那个项目确认 CLI 能装、在 src/clis.ts 加一份 CliSpec、 在 src/groups/ 加一个分组文件并挂到 src/registry.ts 的 GROUPS。 MCP 侧不写任何业务逻辑。

验证

node test-mcp.mjs      # 起 server 跑 initialize + tools/list
                       # 断言：55 个工具；每个名字以所属分组 id 开头；旧变量名仍生效

CS_MCP_GROUPS=all 是测试用的启动方式 —— CI 机器上什么 CLI 都没装， 走默认的探测策略会一组都不启用，那就测不到工具集本身了。旧名 MUSEAV_MCP_GROUPS 会被再起一次 server 验证，确认与新名等价（改名的静默降级只在这条路上暴露）。

说明

museav_gen_background 的 prompt / skill / template 三者必须且只能提供一个：prompt 是直接给提示词，skill 和 template 是让中台在服务端展开提示词（配合 input 传一句业务描述）。

四个本地后期工具的 out 已存在时，CLI 会拒绝覆盖 —— 这是防手滑的语义，MCP 保留它： 要覆盖就显式传 overwrite: true，否则报错原文会回到 Agent 手里。

museav_list_templates / museav_list_skills 取的是 CLI 的人类可读表格（stderr），因为 stdout 只有裸 id； museav_list_jobs 取 stdout 的完整 JSON（含 cdn_url / status / error）。清单超过 8000 字会截断， 并附一句「输出已截断」——不附的话 Agent 会把截断处当成清单结尾。

本地工具的超时上限是 10 分钟 —— 超分和 LaMa 修复在大图上确实会慢。

License

MIT