🧭 cs-mcp

CS 系统（CortexOS）的 MCP —— 一条命令，把个人工具链接进任意 AI Agent。
把各开源项目的 CLI 能力串成一张网：出图 / 看图 / 对比度门禁 / Markdown 排版……
按「能力分组」组织，装了哪个 CLI 就自动长出哪组工具，没装的不会白占你的上下文。

English · 更新日志

⚠️ 别和 cs mcp serve 搞混

系统里有两个都叫「cs 的 MCP」的东西。它们互补，不重合 —— 接错的那个会得到一堆你不需要的工具：

一句话分界：想知道「cs 系统里有什么规矩、有什么技能」用 cs mcp serve；
想「出一张图、把 Markdown 排成 PDF、开个真浏览器」用 cs-mcp。

顺带一句：Agent 侧其实不需要 MCP。 能跑 Bash 的 Agent 直接调 cs CLI 就够，
而且那是主干道（MCP 的通路管不到远端机器）。MCP 的价值只在跑不了 Bash 的客户端上。
见 cs rule 里 cmd/mcp.go 的定位说明。

🎯 为什么用它，而不是别的

分层是硬的：能力在 CLI 里，MCP 只做串联。 这个仓自己零实现 —— 每个工具都是对某个项目
CLI 的一次薄封装。所以 CLI 一升级，MCP 这边立刻就有新能力；MCP 不重写任何逻辑，也就不存在
「两边行为不一致」。

传输方式 stdio。文件以绝对路径传入，处理结果写回磁盘并返回路径 —— 不走 base64。

🧩 能力分组（这张就是版图）

六组里只有 museav 是在线服务：要登录、要网络、有余额配额、会花钱；其余五组是离线确定性计算。
这个差别在工具面上直接可读 —— 云能力那 17 个统一带 museav_ 前缀。owner 的口径就一句：
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 秒上手

⚠️ 3.0.0 尚未发到 npm（cs-mcp 这个名字 2025-04-25 被撤过、museav-mcp 2026-10-05 被撤过，
两个都还是空位）。发布前请用下面的「从源码起」那一种；npx -y cs-mcp 要等 3.0.0 真发出去才成立。

npm i -g museav-cli                    # 想要哪组能力，就装哪个 CLI（这一行是出图那组）

发布之后（一行接入，任何支持 MCP 的客户端都认）：

claude mcp add cs -- npx -y cs-mcp

现在就能用（从本地 clone 起）：

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

然后在 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 @webkubor/facet   # facet 组
npm i -g @kubor/reel-kit   # reel 组（另外要 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 上

Claude Code 一行（发布后）：

claude mcp add cs -- npx -y cs-mcp

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

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

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": "npx",
      "args": ["-y", "cs-mcp"]
    }
  }
}

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

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

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

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

配置里把 command 换成 node、args 指向 /绝对路径/cs-mcp/dist/index.js 即可
（3.0.0 发布前这是唯一可用的接法，见「30 秒上手」）。

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

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

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

验证

node test-mcp.mjs      # 起 server 跑 initialize + tools/list
                       # 断言：43 个工具；每个名字以所属分组 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