> 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/ja/rifarensu/mcp.md).

# MCP サーバー

MCP サーバーは、次のものとまったく同じエンジンの薄いラッパーです: [CLI](/squish/ja/rifarensu/cli.md) — パイプラインも出力ファイルもウィンドウの意味論も同じです。完全にお使いのマシン上で動作し、MCP を介して **stdio**。クライアントがコネクタ URL（Claude Desktop、claude.ai）しか受け取らない場合は、ホスト型の [リモート MCP エンドポイント](/squish/ja/rifarensu/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/ja/hajimeni/quickstart-mcp.md) 各クライアントごとの設定用です。

## ツール: squish\_video

サーバーが公開するのはちょうど **1 つのツール**。ファイル名は `squish_video` （名前は固定です — 参照: [安定性とバージョニング](/squish/ja/rifarensu/stability.md)）。そのタイトルは次のとおりです: *「動画をタイムスタンプ付きコンタクトシートに圧縮する」*.

ツールの説明自体がモデルに次を教えます。 [ナビゲーションループ](/squish/ja/purimitibu/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`；1 セルあたり 2 ミリ秒未満のウィンドウは拒否されます（参照: [ウィンドウの意味論](/squish/ja/rifarensu/cli.md#window-semantics)). |
| `out_dir`    | string                                   | いいえ    | 入力ファイルと同じ場所に  | 出力シートの保存先ディレクトリです。存在しない場合は作成されます。                                                                                                                                                       |

`start`/`end` シートに印字されるすべての値を受け入れます — 次を参照: [往復特性](/squish/ja/rifarensu/sheet-format.md#round-trip-property).

### 結果ペイロード

成功すると、ツールはテキストコンテンツブロックを 1 つ返します。そのテキストは JSON オブジェクトで、次の内容を含みます: [CLI `--json` 契約項目](/squish/ja/rifarensu/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       | 常に                           | サンプリングされた総フレーム数（`シート数 × セル数`).                                                                                                                                                                                                                              |
| `sheets`    | number       | 常に                           | 生成されたシートファイルです。                                                                                                                                                                                                                                             |
| `files`     | string\[]    | 常に                           | シート JPEG への絶対パスを、順序どおりに並べたものです。これらは vision で読み取ってください。                                                                                                                                                                                                      |
| `warnings`  | string\[]    | 常に                           | 致命的ではない問題です（例: 読み取れないフレームによりセルが黒のまま残った）。                                                                                                                                                                                                                    |
| `timecodes` | string\[]\[] | 常に                           | シートごとに 1 つの配列 **シートごとに**、フレームごとに 1 つの文字列 **フレームごとに**、セル順（左→右、上→下）で並びます。シートのピクセルに印字されたラベルと完全に一致し、JSON と画像が食い違うことはありません。形式 `m:ss`；サブ秒 `m:ss.d` （最小で `m:ss.ddd`）です。ウィンドウが短い場合に適用されます — 次を参照: [適応的精度](/squish/ja/rifarensu/sheet-format.md#adaptive-precision). |
| `契約`        | string       | 常に                           | `「squish-mcp-v0」` — これを解析して破壊的変更を検出します。                                                                                                                                                                                                                     |

想定される流れは、ツールを呼び出し、次のファイルを読み取り: `files` vision で確認し、タイムコードを引用し、次でズームします: `start`/`end` 不確実性が残る箇所です。

### エラー動作

失敗すると MCP ツールエラーが返ります — `isError: true` エラーメッセージを含むテキストコンテンツブロックが 1 つだけ返されます。結果 JSON は生成されません。発生するメッセージは次のとおりです:

| 失敗                        | メッセージ                                                                                                     |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| 解析不能 `start`/`end`        | `開始位置 "<value>" を解析できませんでした — 秒数（90）またはタイムコード（1:30、1:07.3）を使用してください` （同じ形式で `end`)                        |
| 入力ファイルがありません              | `入力が見つかりません: <absolute path>`                                                                             |
| 負の値 `start`               | `開始は 0 以上の時刻でなければなりません`                                                                                   |
| `start` クリップ終了時またはそれ以降    | `開始 (<t>) がクリップの終了 (<duration>) と同時かそれ以降です`                                                               |
| 空のウィンドウ                   | `ウィンドウが空です — 終了 (<t>) は開始 (<t>) より後でなければなりません`                                                            |
| 1 セルあたり 2 ms の下限を下回るウィンドウ | `ウィンドウが小さすぎて個別に指定できません: <X> ms に <N> セル（エンジンはミリ秒精度でシークします — この密度での最小値は約 <2N> ms です）；ズームアウトするか、密度を下げてください` |

ウィンドウのエラーは意図的に *学習用のエラーです*：次の呼び出しをどう修正すべきか（ズームアウトする、または密度を下げる）をモデルに伝え、曖昧に失敗するのを防ぎます。

## CLI との関係

両方の入口は同じエンジン関数を呼び出しており、どちらもパイプラインのロジックを再実装していません。MCP の結果は CLI のレポートに加えて `timecodes[][]`、独自の `契約` string が付与されます。形が異なるためです。テンポラリフレームは、成功時もエラー時も、ちょうど次の場合と同じようにクリーンアップされます。 [CLI](/squish/ja/rifarensu/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/ja/rifarensu/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.