MCP サーバーリファレンス

miseru mcp は、AI エージェント(Claude Code など)から Miseru を直接操作するための MCP サーバーです。stdio で動作し、追加の依存はありません。

セットアップ

MCP クライアントの設定に次を追加します。

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

認証は環境変数 MISERU_TOKEN で行います(ツール呼び出し時に評価)。MCP サーバーを起動するプロセスに MISERU_TOKEN を渡してください
MISERU_API で接続先を上書きできます(既定: https://api.miseru.dev)
pr_number を使うときの repo は、引数 repo → MISERU_REPO → GITHUB_REPOSITORY → git remote の順で解決します

Claude Code での具体的な連携手順は Claude Code 連携ガイドを参照してください。

ツール一覧

miseru_push

スクリーンショット画像を Miseru にアップロードし、貼り付け用の markdown を返します。画像は配信コンテキスト(GitHub PR や任意の共有単位)にまとめられ、その単位で失効します。自動コメント投稿は行いません(それは GitHub Action の役割です)。

パラメータ	型	必須	説明
`file`	string	✅	画像ファイルの絶対パス(png/jpg/webp、5MB 未満)
`name`	string	✅	論理名(例: `home`, `login`, `checkout@mobile`)。同じコンテキストで `name` と `viewport` が同じ画像は、古い画像を失効させて置き換えます
`context_key`	string	✅※	コンテキストのキー。`github_pr` では `owner/repo#<PR番号>`、`manual` では任意のラベル
`context_type`	string	—	`github_pr` / `manual`。既定は `manual`
`context_label`	string	—	人間向けの表示名
`pr_number`	integer	✅※	`context_type=github_pr` / `context_key=<owner/repo>#<n>` のショートハンド
`repo`	string	—	`pr_number` と組み合わせる GitHub リポジトリ(`owner/repo`)
`commit_sha`	string	—	省略時はカレントの git HEAD を使用。取れなくても失敗しません
`viewport`	string	—	例 `1280x800`
`tags`	string[]	—	タグ。複数指定可。存在しなければワークスペース内に作成
`project`	string	—	プロジェクト名。存在しなければ作成し、新しいコンテキストを紐づける。省略時はトークンの既定
`compare`	boolean	—	`true` ならベースラインと比べ（Kurabe）、結果を最大 30 秒待って返します。既定は `false`。PNG の画像だけです。PNG 以外で `true` にするとアップロードごと失敗します
`max_diff_ratio`	number	—	「変化なし」とみなす差分率の上限。0〜1 の比率（例: `0.001` = 0.1%）。既定は 0。値の検査は API が行います。承認の権限の無いトークンで 0 より大きい値を送ると 403
`masks`	object[]	—	比較から外す矩形の配列。各要素は `{ x, y, width, height }`。画像の画素の座標（CSS の px ではありません）。整数で `x`・`y` は 0 以上、`width`・`height` は 1 以上、各値は 99999 以下。最大 20 個。値の検査は API が行います。承認の権限の無いトークンで空でない配列を送ると 403。付けずに push し、ノイズは撮る側で止めてください

※ context_key か pr_number のどちらか一方が必須です(同時指定はエラー)。

返り値(テキスト):

アップロード完了(id: <id>)

PR に貼る markdown:
![<name>](<配信URL>)

compare: true のとき、返り値の末尾に 比較: <結果> の 1 行が付きます（ベースラインとして登録 / 変化あり・差分率と次の操作 / 変化なし / 失敗 / 計算中）。30 秒で終わらなければ「計算中」を返すので、miseru_diff で取りに行ってください。

成功時は、次の項目を structuredContent でも返します（形は outputSchema で公開）。上のテキストの直後に、同じ内容を字下げなしの JSON にした text ブロックも返すので、構造化データを扱わないクライアントでも値を読み取れます。

項目	内容
`image_id`	アップロードした画像の id
`view_url`	画像の配信 URL
`markdown`	貼り付け用の markdown
`diff_requested`	アップロード API が返した比較依頼の有無。API が項目を返さなければ `false`
`diff`	`compare: true` かつ `diff_requested: true` のとき、最大 30 秒待った後の比較状態（`miseru_diff` と同じ形）。それ以外は `null`

compare を省略した場合は、API が diff_requested: true を返しても diff は null です。isError: true の結果には structuredContent を付けません。

commit_sha は GitHub 文脈の証跡メタデータなので任意です。git リポジトリ外でも自動検出に失敗するだけで、アップロード自体は成功します。

miseru_expire

アップロード済み画像を失効させます(オリジンから削除し、配信を止めます)。

パラメータ	型	必須	説明
`image_id`	string	✅	`miseru_push` が返した画像 id

返り値(テキスト): 失効しました: <image_id>

miseru_comment

PR の全スクリーンショットを集約した「1 PR = 1 コメント」用の markdown を返します。

パラメータ	型	必須	説明
`pr_number`	integer	✅	対象 PR 番号
`repo`	string	—	対象 GitHub リポジトリ(`owner/repo`)。省略時は環境変数と git remote から解決

miseru_close_context

配信コンテキストを閉じ、その失効ポリシーを適用します(on_close なら画像を失効させます)。冪等です。画像を1枚だけ失効させたいときは miseru_expire を使ってください。

パラメータ	型	必須	説明
`context_key`	string	✅※	コンテキストのキー
`context_type`	string	—	`github_pr` / `manual`
`pr_number`	integer	✅※	`context_type=github_pr` / `context_key=<owner/repo>#<n>` のショートハンド
`repo`	string	—	`pr_number` と組み合わせる GitHub リポジトリ(`owner/repo`)
`reason`	string	—	`merged` / `closed` / `manual`。merged なら PR のベースラインを共有のベースラインへ上げ、closed・manual(既定)なら捨てる

※ context_key か pr_number のどちらか一方が必須です。

返り値(テキスト): <type>:<key> を閉じました(policy: …, marked: …, expired: …)

miseru_diff

比較（Kurabe）の結果を返します。比較済みなら、差分画像（変化した画素を赤、サイズの違う領域を青、マスクの中を灰色で塗った PNG）を MCP の画像として返すので、エージェントがそのまま目で確かめられます。

パラメータ	型	必須	説明
`image_id`	string	✅	`miseru_push` が返した画像 id
`images`	string[]	—	返す画像。`baseline`（比較した時点のベースライン）/ `candidate`（今回の画像）/ `diff`（差分画像）。既定は `["diff"]`

返り値: 状態の一文（テキスト）、構造化データと同じ内容の字下げなし JSON の text ブロック、画像ごとの <kind>: のテキストと画像の順に返します。base64 にする前で 5MB 以上の画像は返さず、miseru diff <image_id> --out <dir> での保存を案内します。

成功時の structuredContent は GET /v1/images/:id/diff の応答そのものです。必ず image_id と state を含み、状態に応じて requested_at・baseline_id・baseline_scope（context / shared / null）・diff_id・diff_ratio・max_diff_ratio・changed・status・stale・failure_reason を含みます。比較済みでなくても、その状態を構造化データと JSON の text ブロックで返します。outputSchema は state を文字列とし、将来追加される状態や項目も許容します。isError: true の結果には structuredContent を付けません。

miseru_approve

差分を承認し、比べたベースラインをその差分の画像に置き換えます。取り消せません。PR（github_pr）の push の差分なら、その PR のベースラインだけを置き換え（無ければ作り）、PR を merged で閉じたときに共有へ反映されます。miseru_diff で意図した変化だと確かめてから使ってください。冪等です。

パラメータ	型	必須	説明
`diff_id`	string	✅	`miseru_push` / `miseru_diff` が返した差分 id

返り値(テキスト): PR の承認なら 承認しました: <diff_id>。この PR のベースラインを更新しました。PR を merged で閉じると、共有のベースラインに反映されます。共有・scope を返さない古い API・baseline が null の応答では従来の文言を返します。比較した後にベースラインが更新された差分は承認できず、エラーになります（compare: true で push し直してください）。閉じた PR の未承認の差分は、stale が false でも 409 context is closed になります。ベースラインの権限が無いトークンでは 承認失敗 (403): … を isError: true で返すので、message のとおり人に承認を頼んでください。

miseru_list_baselines

ベースライン（比べる基準の画像）の一覧を 1 ページ（最大 200 件）返します。PR ごとのベースライン（context_id がその PR のコンテキストの id）も混ざります。共有のベースラインは context_id: null です。

パラメータ	型	必須	説明
`project`	string	—	プロジェクトの id。`none` ならプロジェクトに属さないものだけ
`cursor`	string	—	前の結果の `next_cursor`。続きを取るときに渡す

返り値(テキスト): GET /v1/baselines の応答の JSON。

miseru_delete_baseline

ベースラインを 1 件削除します。取り消せません。次に同じ名前を compare: true で push すると、PR のベースラインがあればそれと、無ければ共有のベースラインと比べ、どちらも無ければその画像が新しいベースライン（PR の push なら PR のベースライン）になります。共有・PR ごとのどちらの層も削除できます。

パラメータ	型	必須	説明
`baseline_id`	string	✅	`miseru_list_baselines` が返した id

返り値(テキスト): 削除しました: <baseline_id>。…。存在しない id などはエラーになります。ベースラインの権限が無いトークンでは 削除失敗 (403): … を isError: true で返すので、message のとおり人に削除を頼んでください。

Kurabe の使い方の流れ

miseru_push を compare: true で呼ぶ。その PR と共有のどちらにもベースラインが無ければ登録される
2 回目以降は「変化あり / 変化なし」が返る
変化があったら miseru_diff で差分画像を見る
意図した変化なら miseru_approve。権限の無いトークンでは 403 になるので、message のコマンドを権限を持つ人に実行してもらう。意図しない変化ならコードを直して、もう一度 compare: true で push する
ストレージ枠が埋まったら、使わなくなった名前のベースラインを miseru_list_baselines で探し、miseru_delete_baseline で消す

PR ごとのベースラインになるのは、pr_number または context_type: github_pr を指定して push したときだけです。context_type の既定は manual なので、context_key だけを渡す場合は共有のベースラインを使います。

共有へ反映するには、PR を merged で閉じたことを Miseru に伝える必要があります。GitHub Action の close を置くか、miseru_close_context に pr_number と reason: merged を渡す（CLI なら miseru close --pr <n> --reason merged）ことで伝えます。comment だけの Action では伝わりません。既定の manual で閉じると捨てられ、閉じたことを伝えないまま放置した PR のベースラインは残ります。

比較から外す領域の座標を求める

時計など毎回変わる場所は、push ごとに masks へ指定できます。候補（今回の画像）のマスクだけが使われ、ベースラインに付けたマスクは引き継ぎません。矩形の重なりは 1 回だけ数え、比べる 2 枚の大きい方の画面からはみ出した部分は切り捨てます。

Playwright の locator.boundingBox() は、ビューポートからの CSS 座標を返します。以下は、対象の矩形がビューポート内にあり、計測から撮影までレイアウトとスクロールが変わらない場合の例です。撮影は scale: "device" にそろえ、devicePixelRatio を掛けて画像の画素へ変換します。

const box = await page.getByTestId("clock").boundingBox();
if (!box) throw new Error("時計の領域を取得できません");
const dpr = await page.evaluate(() => window.devicePixelRatio);
const x = Math.floor(box.x * dpr);
const y = Math.floor(box.y * dpr);
const right = Math.ceil((box.x + box.width) * dpr);
const bottom = Math.ceil((box.y + box.height) * dpr);
const masks = [{ x, y, width: right - x, height: bottom - y }];
await page.screenshot({ path: "shot.png", scale: "device" });
// miseru_push に file: "shot.png", compare: true, masks を渡す

左上は Math.floor、右下は Math.ceil で外側へ丸めます。小数のまま送ると API は 400 を返します。scale: "css" で撮影した画像では、devicePixelRatio を掛けず倍率 1 で計算してください。

フルページの撮影では、通常の文書内にある要素の box.x・box.y に、計測時の window.scrollX・window.scrollY を足してから倍率を掛けます。例えば x = Math.floor((box.x + scrollX) * dpr)、右端は Math.ceil((box.x + scrollX + box.width) * dpr) です。縦方向も同じように計算し、撮影に fullPage: true を指定します。

マスクの中は差分率の分子・分母の両方から除きます。画面のほとんどをマスクすると、外側に残った少しの違いでも差分率が大きく見えます（例: 残った 10 画素のうち 1 画素が違えば 10%）。全部がマスクなら差分率は 0 です。max_diff_ratio は、このマスクを除いた差分率に適用されます。

プロトコル仕様

プロトコルバージョン: 2025-06-18
capabilities: tools のみ(resources / prompts は未対応)
サポートメソッド: initialize / tools/list / tools/call(notifications/* は応答なしで受理)
標準入力の不正な JSON 行は無視します(stdio ノイズ耐性)