> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/zh/can-kao/mcp.md).

# MCP server

MCP 服务器只是对完全相同的引擎做了一层很薄的封装，和 [CLI](/squish/zh/can-kao/cli.md) ——管线相同、输出文件相同、窗口语义也相同。它完全在你的机器上运行，并通过 **stdio**通信。如果你的客户端只接受连接器 URL（Claude Desktop、claude.ai），请改用托管的 [远程 MCP 端点](/squish/zh/can-kao/remote-mcp.md) 。

## 启动服务器

```bash
squish mcp
```

`squish mcp` 不需要任何参数（尾随参数会被视为用法错误）。stdout 只用于 MCP 传输——服务器不会向其中打印任何其他内容，因此 stdio 帧格式始终保持干净。要求与 CLI 相同：Node ≥ 20， `ffmpeg` + `ffprobe` 已加入 PATH。

## 客户端配置

可与 Claude Code、Claude Desktop、Cursor、Hermes 以及任何 stdio MCP 客户端配合使用：

```json
{
  "mcpServers": {
    "squish": { "command": "npx", "args": ["-y", "@getsquish/squish", "mcp"] }
  }
}
```

参见 [快速开始：MCP](/squish/zh/ru-men/quickstart-mcp.md) 用于按客户端单独配置。

## 工具：squish\_video

服务器只暴露 **一个工具**，命名为 `squish_video` （名称是固定的——见 [稳定性与版本控制](/squish/zh/can-kao/stability.md)）。它的标题： *“将视频压缩成带时间戳的缩略图表”*.

工具描述本身会教模型 [导航循环](/squish/zh/primitive/the-navigation-loop.md)：时间码相对于源视频是绝对的，所以如果要更仔细地查看在表格中发现的某个范围，模型会再次调用该工具，并将 `start`/`end` 设置为那些时间码——每次放大都会得到更精细的时间码（概览 → 范围 → 瞬间）。代理无需额外提示就能发现这个循环。

### 参数

| 参数           | 类型                                       | 必填    | 默认值        | 约束 / 语义                                                                                                                                    |
| ------------ | ---------------------------------------- | ----- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `video_path` | string                                   | **是** | —          | 指向一个 **本地** 视频文件的绝对路径（ffmpeg 能解码的都可以）。                                                                                                     |
| `density`    | `“3x3”` \| `“4x4”` \| `“5x5”` \| `“6x6”` | 否     | `“3x3”`    | 网格密度：每张表 9 / 16 / 25 / 36 帧。 `3x3` 能恢复发生了什么；更密的网格（`4x4`–`6x6`）能恢复它是怎么做的。                                                                   |
| `start`      | number \| string                         | 否     | `0` （剪辑开始） | 缩放窗口开始——秒数（`67.5`）或表格上标注的时间码（`"1:07"`, `"1:07.3"`). **在源视频中是绝对值。** 必须 ≥ 0 且早于剪辑结束。                                                         |
| `end`        | number \| string                         | 否     | 剪辑结束       | 缩放窗口结束——格式与 `start`相同。数值 **超过剪辑结束的部分会被截断** 到剪辑结束。必须落在 `start`之后；每个单元格低于 2 毫秒的窗口会被拒绝（见 [窗口语义](/squish/zh/can-kao/cli.md#window-semantics)). |
| `out_dir`    | string                                   | 否     | 位于输入文件旁边   | 输出表格所在目录；如果不存在会自动创建。                                                                                                                       |

`start`/`end` 接受表格上标注的所有内容——参见 [往返属性](/squish/zh/can-kao/sheet-format.md#round-trip-property).

### 结果载荷

成功时，工具会返回一个文本内容块，其文本是一个 JSON 对象： [CLI `--json` 契约字段](/squish/zh/can-kao/cli.md#--json-output) **以及** `timecodes`，并带有它自己的契约字符串：

```json
{
  "input": "/abs/path/clip.mov",
  "duration": 20.275,
  "frames": 9,
  "sheets": 1,
  "files": ["/abs/path/clip.sheet-1.jpg"],
  "warnings": [],
  "timecodes": [["0:01", "0:03", "0:05", "0:07", "0:10", "0:12", "0:14", "0:16", "0:19"]],
  "contract": "squish-mcp-v0"
}
```

| 键           | 类型           | 存在                    | 含义                                                                                                                                                                                           |
| ----------- | ------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input`     | string       | 始终                    | 解析后的输入绝对路径。                                                                                                                                                                                  |
| `duration`  | number       | 始终                    | 完整剪辑时长（秒）（绝不是窗口长度）。                                                                                                                                                                          |
| `window`    | object       | 仅在 `start`/`end` 已传入时 | `{ "start": <s>, "end": <s> }` ——默认值和结束截断后解析得到的边界，单位为秒，精确到毫秒。出现在 `duration` 和 `帧`.                                                                                                           |
| `帧`         | number       | 始终                    | 采样的总帧数（`表格数 × 单元格数`).                                                                                                                                                                        |
| `表格`        | number       | 始终                    | 生成的表格文件。                                                                                                                                                                                     |
| `files`     | string\[]    | 始终                    | 按顺序排列的表格 JPEG 绝对路径。请用视觉能力读取这些文件。                                                                                                                                                             |
| `warnings`  | string\[]    | 始终                    | 非致命问题（例如某一帧无法读取，导致某个单元格是黑色）。                                                                                                                                                                 |
| `timecodes` | string\[]\[] | 始终                    | 每张表 **一个数组**，每帧 **一个字符串**，按单元格顺序（从左到右、从上到下）。与表格像素上标注的标签完全一致——JSON 和图像永远不会不一致。格式 `m:ss`；亚秒级 `m:ss.d` （低至 `m:ss.ddd`）当窗口很短时——见 [自适应精度](/squish/zh/can-kao/sheet-format.md#adaptive-precision). |
| `契约`        | string       | 始终                    | `"squish-mcp-v0"` ——请解析它以检测破坏性变更。                                                                                                                                                            |

预期流程：调用工具，用视觉能力读取 `files` 中的文件，引用时间码，并在 `start`/`end` 仍有不确定之处时进行放大。

### 错误行为

任何失败都会返回一个 MCP 工具错误—— `isError: true` 并带有一个只包含错误消息的文本内容块。不会生成结果 JSON。你会遇到的消息：

| 失败                 | 消息                                                                      |
| ------------------ | ----------------------------------------------------------------------- |
| 无法解析 `start`/`end` | `无法解析开始值“<value>”——请使用秒数（90）或时间码（1:30、1:07.3）` （同样的格式适用于 `end`)         |
| 输入文件缺失             | `未找到输入：<absolute path>`                                                 |
| 负值 `start`         | `start 必须是 ≥ 0 的时间`                                                     |
| `start` 在/晚于剪辑结束   | `start（<t>）在剪辑结束（<duration>）处或之后`                                       |
| 空窗口                | `窗口为空——end（<t>）必须晚于 start（<t>）`                                         |
| 低于 2 毫秒/单元格下限的窗口   | `窗口太小，无法清晰定位：<N> 个单元格跨越 <X> 毫秒（引擎以毫秒精度搜索——在这种密度下最小约为 <2N> 毫秒）；请放大或降低密度` |

这些窗口错误是刻意设计的 *教学型错误*：它们会告诉模型下一次调用该如何修正（放大，或降低密度），而不是含糊地失败。

## 与 CLI 的关系

两种入口调用的是同一个引擎函数；都没有重新实现任何管线逻辑。MCP 结果等于 CLI 报告再加上 `timecodes[][]`，并使用它自己的 `契约` 字符串，因为二者的结构不同。临时帧会在成功或出错时清理掉，和在 [CLI](/squish/zh/can-kao/cli.md#temp-frame-cleanup).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://getsquish.gitbook.io/squish/zh/can-kao/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.