halfsize

halfsize / MCP 服务器

给 agent 一个解大小的工具

「压到指定大小」恰恰是助手靠嘴说不完的那一步。halfsize --mcp 把它变成一个工具调用: agent 要 20 MB,拿回一个真实文件,同一次返回里还带着实测的画质损失。

为什么是工具,不是提示词

让模型压小一个视频,它会写 -crf 28,压一遍、看大小、再猜一次;更糟的情况是没验证就告诉 你已经塞得进去了。算术本身不难,但它依赖模型看不到的状态:真实时长、真实音频码率、容器开销,以及 这份预算能撑住哪一档分辨率。

compress_video 要藏起来的正好就是这些。它返回输出路径、字节数、相对目标的误差,以及 对着原片测的 VMAF/SSIM。于是 agent 能说清这个体积付出了什么,而不是承诺什么都没损失。

接进你的客户端

下面每种客户端启动的都是同一个本地进程:没有 key、没有账号、没有托管接口。

Claude Code

$ claude mcp add halfsize -- npx -y halfsize --mcp

Claude Desktop

编辑 claude_desktop_config.json(Settings → Developer → Edit Config):

{
  "mcpServers": {
    "halfsize": {
      "command": "npx",
      "args": ["-y", "halfsize", "--mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json(或者项目里的 .cursor/mcp.json)用的是同样的 mcpServers 结构。

VS Code

.vscode/mcp.json 的键名是 servers:

{
  "servers": {
    "halfsize": { "command": "npx", "args": ["-y", "halfsize", "--mcp"] }
  }
}

Windows 上部分客户端需要把 command 写成 npx.cmd。客户端继承的 PATH 里必须有 Node.js 18 以上。

唯一的那个工具

参数类型作用
input字符串,必填本地视频路径。
target字符串,必填20mb、16mb、800k、1.5gb。不写单位按 MB。
output字符串默认是输入旁边的 <输入>.<目标>.mp4。
codech264 | h265H.265 同样字节下能保住更多分辨率,代价是兼容性。
verify布尔是否测 VMAF/SSIM,默认 true;设 false 更快。
dryRun布尔只返回方案(码率、分辨率、警告),不编码。

返回里既有给人看的一句话摘要,也有完整的 JSON(structuredContent),所以读结构的客户端和 读文本的客户端看到的是同一组数字。

$ npx halfsize 输入.mp4 --to 20mb

  136 MB  →  19.45 MB   小 7.0 倍   比目标小 2.7%
  VMAF 88.3   SSIM 0.971   轻微变软

客户端不支持 MCP 怎么办

还有 agent 技能这一条路,本质上就是一份说明加一条命令: npx skills add YKLovePython/halfsize。Claude Code、Codex、Cursor、OpenCode 都能用。 MCP 这条路更硬一点:参数有类型、结果是结构化的,不会被 shell 引号搞坏。

它不会做什么

常见问题

会上传我的视频吗?

不会。服务器是本机的子进程,用 stdin/stdout 说 JSON-RPC,没有 HTTP 端点也没有遥测。

需要 API key 吗?

不需要。客户端启动的是一条本地命令,没有要认证的东西。

直接让 agent 调 ffmpeg 不行吗?

可以,然后它会猜 CRF。出问题的不是命令,是预算:时长、音频码率、容器开销、分辨率选择。这个工具包的就是这一层。

能离线用吗?

压缩本身可以。第一次运行需要网络让 npx 取包,以及 FFmpeg(作为可选依赖下载)。之后除了手动跑一次 halfsize --fix,不再联网。

Windows 能用吗?

能,包括 Windows on ARM(x64 的 FFmpeg 在模拟层里跑)。如果客户端找不到 npx,把 command 改成 npx.cmd,参数不变。

agent 要了一个不可能的大小呢?

CLI 会直接以「这个时长能做到的最小体积」失败退出,而不是产出一个六分钟的幻灯片。工具会把这句话当作错误返回给 agent。

相关