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。 |
codec | h264 | h265 | H.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 引号搞坏。
它不会做什么
- 不上传。 只有 stdio:客户端拉起进程,没有任何端口在监听。如果某个工具描述让你把视频发到 某个地址,那不是这个工具。
- 不剪辑。 一个输入一个输出。裁、切、拼接不在范围内,多个文件就是多次调用。
- 不空口说画质。 VMAF 和 SSIM 跟文件一起返回,agent 能报告的就不只是「好了」。
常见问题
会上传我的视频吗?
不会。服务器是本机的子进程,用 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。