mosaic-probe-harness
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
画像(PSD などのレイヤー付きファイルを含む)を受け取り、**「モザイク処理が必要な部位が存在しない、または十分に処理されている確率(p_ok)」**を 0 〜 1 の数値 1 個で返すローカル API サーバーです。
推論バックエンド: 同一ホスト(またはローカルネットワーク)上の
llama.cpp(llama-server、マルチモーダル対応 Qwen VLM)を利用します。確率算出: モデルの 4 語(
none/processed/forgot/nori)の先頭トークン確率を集計し、複数モデル構成では描画ごとに重み付き平均を取ります。詳細応答の総合判断と確率はok・ngの 2 つにまとめて返します(4 語は内部計算専用です)。呼び出し方法: REST API(ブラウザ・Node.js などの HTTP クライアント)および MCP(Streamable HTTP)に対応しています。
判定の委譲: 既定の応答は確率値
p_okです。しきい値に基づく OK / NG の最終判定は呼び出し側で行ってください。前段の検出(任意・既定オフ):
DETECT=1にすると、画風(写真かイラストか)に合った検出器で部位を見つけ、その切り出しも同じ判定器で判定して、全体と切り出しのうち最も悪い候補を採用します。API の応答形式は変わりません(設定)。
関連ドキュメント
変更履歴・移行時の確認項目(v1.3 / v1.2 / v1.1): CHANGELOG.md
AI エージェント向けの呼び出し仕様・注意事項: docs/agent-usage.md
実機での前提確認・ルール同期・評価・較正・複数台の手順: docs/operations.md
設計の要点(確率の作り方、Pi の使い方、レイヤー安全): docs/design.md
クライアント実装例: examples/browser.html / examples/call.mjs
目次
Related MCP server: readpic MCP Server
動作要件
Node.js: 22.19 以上
llama.cpp(
llama-server):--mmprojを指定した PNG での VLM 推論、logprobs、/tokenizeのwith_piecesに対応したビルドonnxruntime-node1.31.1(任意):DETECT=1のときだけ必要です。optionalDependenciesとしてnpm ciで入ります(導入に失敗しても他の機能は動きます)。Windows で読み込めないときは、VC++ 再頒布可能パッケージを確かめてください。モデルファイルは別に用意します(docs/operations.md)。
セットアップと起動
1. 依存パッケージのインストール
npm ci2. llama-server の起動(ローカル限定)
llama-server は必ずループバック(127.0.0.1)のみで待ち受けてください。外部(LAN)へ公開するのは本ハーネスだけにします。
llama-server -m <モデル.gguf> --mmproj <mmproj.gguf> --host 127.0.0.1 --port 8080 --jinja -c 8192llama-server が本ハーネスの前提(画像入力、logprobs、1 トークン出力など)を満たすか事前に確認するには、docs/operations.md の手順を実行してください。
3. ハーネスの起動
既定では 127.0.0.1:8790(ループバックのみ)で起動します。設定は環境変数のほか、アプリのルートの .env でも指定できます(設定ファイル .env)。環境変数の設定例は start.sh / start.bat の冒頭コメントを参照してください。
# macOS / Linux
./start.sh
# Windows(コマンドプロンプト)
start.bat
# または npm scripts から直接起動
npm startLAN へ公開する場合
ループバック以外のアドレス(0.0.0.0 など)で待ち受ける場合は、MOSAIC_API_KEY の設定が必須です(未設定の場合は起動を拒否します)。
macOS / Linux:
export MOSAIC_BIND=0.0.0.0
export MOSAIC_API_KEY=<十分に長いランダム文字列>
./start.shWindows (PowerShell):
$env:MOSAIC_BIND = "0.0.0.0"
$env:MOSAIC_API_KEY = "<十分に長いランダム文字列>"
.\start.batファイアウォール設定の注意:
Windows: 受信側 PC で TCP
8790の受信を許可してください(プロファイルは「プライベートネットワーク」のみに限定推奨)。macOS: 「システム設定 > ネットワーク > ファイアウォール」で
nodeの受信接続が許可されているか確認してください。llama-serverは127.0.0.1のままにし、ポートを開放しないでください。
API 仕様
エンドポイント | メソッド | 認証 | 用途 |
|
| 必要(キー設定時) | REST API による画像判定 |
|
| 必要(キー設定時) | MCP(Streamable HTTP)による画像判定 |
|
| 不要 | ヘルスチェック( |
送信方法 | ヘッダー | リクエストに入れる画像 |
REST の生バイト |
| ファイルのバイト列を本文に直接入れる |
REST の JSON |
| JSON の |
MCP の |
| ツール引数の |
1回の判定につき画像1ファイルを送ります。画像データの既定上限は 15 MiB で、Base64 は復号後のバイト数で判定します。キーを設定したサーバーには Authorization: Bearer <APIキー> を付けます。
REST: POST /v1/check
成功時は HTTP 200 で、レスポンスボディに数値 1 個だけを返します(例: 0.8732)。既定の応答は今までどおり数値だけです。失敗時は数値を返しません。
詳細を取得する(detail)
問題の種類を知りたいときだけ、クエリに detail=1(または detail=true)を付けます。detail=0 や無指定は数値 1 個の応答のままです。
curl -X POST "http://<サーバーのIP>:8790/v1/check?detail=1" \
-H "Authorization: Bearer $MOSAIC_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @image.psd成功時の応答(200、application/json)の例:
{
"p_ok": 0.12,
"judgment": "ng",
"confidence": 0.88,
"render": "モザイク名のレイヤーを非表示",
"classes": { "ok": 0.12, "ng": 0.88 },
"per_model": { "default": { "ok": 0.12, "ng": 0.88 } }
}p_ok: 全描画の最小値です(較正を設定している場合は適用済み)。judgment:okまたはngです。okの確率と NG 側の確率(かけ忘れ・処理不足とノリのうち大きい方)を比較し、同率ならokを選びます(NG の種類は返しません)。confidence: 選ばれたjudgmentの較正前の確率です。render:p_okが最小だった描画の名前です。アニメーションでは「フレーム 4/12」のように表示します。
DETECT=1で切り出しが最悪だったときは、「見えているとおりの切り出し 2」(PSD の例)や「ラスターの切り出し 1」(ラスター画像)のように描画名に「の切り出し k」が付きます(箱の座標はdetectに入ります)。
classes: その描画の統合済みの確率です。okは対象なしと処理済みの合計、ngはかけ忘れ・処理不足とノリ(黒や白の帯・線・塗りで隠したもの)のうち大きい方です。per_model: その描画のモデル別のok・ngで、classesと同じ式でまとめた値です(キーはJUDGESのname)。detect(DETECT=1のときのみ付与):p_okが最小だった候補の描画について、画風分類と検出器が見つけた箱を返します。style: 使用した検出器(illust: イラスト用 /photo: 写真用 /both: 判別できず両方)。分類器がない場合はnull。p_real: 写真である確率。分類器がない場合はnull。width/height: 判定に使った描画(MAX_EDGEなどで縮小したあと)の寸法(px)。元画像に重ねる場合は、この寸法との比で拡大してください。boxes: 検出された箱の配列。各要素はlabel(クラス名)、score、左上x0・y0、右下x1・y1(上記の寸法に基づく画素座標)を持ちます。切り出さなかった箱(描画全体と同じ範囲)も含まれます。
失敗時は、既定の応答と同じエラー(
{"error": …})だけを返し、数値も詳細も返しません。detailを付けても、判定の内容・時間は変わりません(同じ描画を判定し、結果の表示を増やすだけです)。
返す項目を選ぶ(fields)
必要な項目だけを返させるには、detail の代わりに fields を付けます(カンマ区切り)。p_ok は常に含まれます。 総合判断まわりの 3 パターンは次のとおりです。
欲しいもの | クエリ | 応答 |
総合判断だけ |
|
|
総合判断の確率だけ |
|
|
両方 |
|
|
選べる項目は
judgment、confidence、render、classesです(例?fields=render,classes)。per_modelとdetectを取得するにはfieldsを省略し、detail=1を指定します。項目の並びは、指定した順に関わらず固定です(
p_ok、judgment、confidence、render、classes)。重複は 1 つにまとめます。fieldsを付けるとdetailは不要です。併記した場合はfieldsが優先されます。**不正な指定は黙って捨てず
400(bad_input)**になり、判定も行いません。空(fields=)、未知の項目、空の要素(fields=judgment,)が対象です。数値も詳細も返りません。
生バイトで送信する(推奨)
ブラウザの fetch で File / Blob をそのまま渡す場合や、PSD ファイルを送信する場合に適しています。Content-Type が application/json 以外(application/octet-stream や image/* など)の場合は生バイトとして読み取ります。
curl -X POST http://127.0.0.1:8790/v1/check \
-H "Authorization: Bearer $MOSAIC_API_KEY" \
-H "Content-Type: application/octet-stream" \
--data-binary @image.psdJSON(Base64 / Data URI)で送信する
Content-Type: application/json の場合は、image_base64 フィールドに Base64 文字列または Data URI を指定します。
curl -X POST http://127.0.0.1:8790/v1/check \
-H "Authorization: Bearer $MOSAIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image_base64":"data:image/png;base64,iVBORw0KGgo..."}'MCP: POST /mcp
ステートレスな Streamable HTTP(JSON 応答)エンドポイントです。HTTP リクエスト時はヘッダに Accept: application/json, text/event-stream を指定してください。
公開ツール:
check_mosaic({ image_base64: string, detail?: boolean, fields?: string[] })(公開するツールはcheck_mosaicの 1 つだけです)成功時:
content[0].textに数値文字列(例:"0.8732")のみを返します。fields(["judgment"]など)かdetail: trueのときは、content[0].textに REST の詳細応答と同じ JSON 文字列を入れます(JSON.parseで読めます。形式は上の「詳細を取得する」を参照)。失敗時:
isError: trueとなり、content[0].textはerror: <種別>: <メッセージ>で始まります(数値は含みません)。HTTP ステータスは200のままなので、必ずisErrorを確認してください。initializeやセッション ID は不要で、tools/callだけで呼べます。
tools/call の本文例です。<PNGのBase64> はファイルをエンコードした文字列に置き換えてください。
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "check_mosaic",
"arguments": {
"image_base64": "<PNGのBase64>",
"fields": ["judgment", "confidence"]
}
}
}REST の JSON 送信ではContent-Type を小文字の application/json で始めてください(大文字小文字を区別します。外れると生バイト扱いになり、415 になります)。https:// のページから http:// の API は、ブラウザの混在コンテンツ制限で呼べません。
ヘルスチェック: GET /healthz
認証不要で 200 ok を返します。内部設定や機密情報は含みません。
curl http://<サーバーのIP>:8790/healthzエラーレスポンス
エラー時は {"error": "<種別>"}(画像判定・処理系のエラーでは message フィールドを含む場合があります)を返します。
HTTP | 種別 ( | 発生条件・備考 |
400 |
| JSON 不正、Base64 不正、画像データ破損、画素数超過など |
401 |
| API キー未指定または不一致( |
403 |
| 接続元 IP が |
404 |
| 存在しないパス |
405 |
| 許可されていない HTTP メソッド |
413 |
| 受信サイズ、フレーム・ページ数、再生時間、または PSD の描画候補数が上限を超過 |
415 |
| 未対応の画像形式(APNG・HEIC・BMP・SVG・PSB・16/32bit PSD・PDF 等) |
500 |
| サーバー内部エラー(設定ファイル読込不可など) |
501 |
|
|
502 |
|
|
503 |
| 実行待ちが |
判定値(p_ok)の意味
p_ok は、**「モザイクが必要な部位が写っていない、または写っている部位がすべて十分に処理されている」**とモデルが判断した確率(0 〜 1、較正適用済み)です。
値が低いほど危険(未処理・処理不十分である可能性が高い)ことを意味します。
「何未満を NG・要確認とするか」のしきい値は利用者が運用要件に合わせて決定してください(評価スクリプト
eval/run_eval.tsが算出する推奨しきい値は参考表示用であり、サーバーには自動反映されません)。
モデルの4語と集計
語 | 意味 |
| 対象が写っていない |
| 対象が十分に処理されている |
| 対象が未処理、または範囲・粗さ・濃さなどが不足して読み取れる |
| 黒い・白い帯、線、枠、塗りで隠している(白線・白抜きも含む) |
モデルの出力を描画ごとに統合し、okMass = P(none) + P(processed)、ngMass = max(P(forgot), P(nori)) を求めます。q = ngMass / (okMass + ngMass) を Platt 較正し、p_ok = 1 - cal(q) とします。確率の設計
測定結果(参考値)
この数字から、精度が高いとも低いとも断言できません。 評価に使えた正解付きの画像は 25 枚だけで、統計的に意味のある結論を出すには少なすぎます。導入前に、運用する画像の傾向に近いデータで必ず測り直してください。
前段の検出(DETECT)の有無だけを変え、同じ判定器(Qwen3.8-27B)と同じ判定基準で、25 枚(正解は ok 19・NG 6)を 1 枚ずつ判定した結果です。
設定 | OK/NG の一致 | 過剰検出(正解 ok → NG) | 見逃し(正解 NG → ok) | 平均時間 |
| 21/25(84%) | 3/19 | 1/6 | 6.9 秒 |
| 22/25(88%) | 3/19 | 0/6 | 9.7 秒 |
差は 1 枚だけです。
DETECT=1で変わったのはnori-data1.pngの見逃しが拾われた 1 枚で、悪化した画像はありません。誤差が大きすぎます。 95% 信頼区間(Wilson)は
DETECT=0が 65〜94%、DETECT=1が 70〜96% で、大きく重なります。McNemar 検定は p=1.0 で、差は示せません。NG は 6 枚しかなく、見逃し率は特に不安定です。偏りがあります。 画像は特定の収集元の 25 枚で、種類・画風・モザイクの方式に偏りがあります。判定基準もこの 25 枚を見ながら調整しているため、未知の画像ではこれより悪くなる可能性があります。
時間は判定器の混み具合でぶれます。
DETECT=1は判定回数が増えるため、時間が長くなります(25 回 → 35 回)。RECHECKは含みません。精度 99% という目標には届いていません。
設定(環境変数・設定ファイル)
環境変数の既定値は src/config.ts で定義されています。空(空白だけを含む)の値は、すべての項目で未設定として扱い、既定値になります(例: MOSAIC_BIND= は 127.0.0.1)。
設定ファイル .env
アプリのルート(サーバーや評価 CLI を起動するディレクトリ)に .env を置くと、環境変数と同じ名前で設定を読みます(設定例: .env.example)。
環境変数の優先: 同じ名前が OS の環境変数にもあれば、環境変数が優先されます(空の環境変数はファイル側の値を上書きしません)。
ファイル形式・パス:
必ず UTF-8(BOM なし) で保存してください(BOM 付き UTF-8 や CP932 等だと起動を止めます)。
Windows のパス区切りは
/で記述してください(例:models/anime_det.onnx)。
文字のエスケープ: 値に
#や空白を含む場合は、必ず単引用符(')で囲んでください。囲まないと#以降がコメントとして捨てられ、API キーなどが黙って短くなります(Node 24.17 のutil.parseEnvで確認済み)。秘密情報の保護:
.envは Git 管理外(.gitignore済み)です。macOS ではchmod 600 .envにし、Windows では利用者のみが読めるフォルダに配置してください。共有フォルダや配布物には含めないでください(API キーは環境変数でも渡せます)。未知の項目の検査:
DETECT_やSTYLE_で始まる未知の項目(綴りの誤り)は、DETECTの値に関係なく変数名を示して起動を止めます。この検査は.envだけでなく OS の環境変数にも適用され、大文字・小文字を区別しません(小文字のdetectも未知の項目として止まります)。
.env はアプリのルートにあれば DETECT の設定に関わらず読み込まれます。旧版で .env を配置していた場合は、更新前に中身を確認してください(CHANGELOG.md)。
VLM・推論設定
変数名 | 既定値 | 説明 |
|
|
|
| なし | 複数台の |
|
| 1 台あたりの同時実行数。 |
| 未設定 | モデル別の設定を JSON 配列で指定。各要素は |
|
|
|
| なし |
|
|
|
|
| なし | リクエスト JSON のトップレベルにマージする追加設定(JSON オブジェクト文字列。例 |
|
| 分類 logits を割る温度パラメータ。 |
画像・レイヤー制限
変数名 | 既定値 | 説明 |
|
| VLM 入力時の長辺最大ピクセル数(拡大はせず縮小のみ) |
|
| 受信画像サイズの上限(MiB)。超過時はメモリに蓄積せず |
|
| 画像デコード時の総画素数上限(展開爆弾対策) |
|
| PSD の描画候補数の上限。2以上の安全な整数 |
|
| GIF・WebP のフレーム数と TIFF のページ数の上限。超過は |
|
| GIF・WebP の1周分の再生時間上限(秒)。超過は |
|
| モザイク層とみなすレイヤー名の正規表現(大文字・小文字を区別しない) |
サーバー公開・セキュリティ
変数名 | 既定値 | 説明 |
|
| 待受 IP アドレス。ループバック以外は |
|
| 待受ポート番号 |
| なし | Bearer 認証用 API キー。ループバック以外で待ち受ける場合は必須 |
| キーあり: |
|
|
| 接続を許可する送信元 IP の CIDR リスト |
|
| 同時実行待ちの上限時間(秒)。超過すると |
再判定オプション(試験機能・既定オフ)
変数名 | 既定値 | 説明 |
|
|
|
|
| 再判定を発動する |
|
| 1 枚の画像に対して再判定で切り出す領域数の上限 |
前段の画風分類・部位検出と切り出し判定(試験機能・既定オフ)
無効時(
DETECTが空または0): 下表の項目は値を検査せず(未知の変数名の検査のみ実施)、onnxruntime-nodeもモデルも読み込みません。有効化の条件(
DETECT=1):検出器(
DETECT_ANIME_MODELまたはDETECT_PHOTO_MODEL)が 1 つ以上必要です。検出器が 2 つの場合は
STYLE_MODELが必須、1 つの場合はSTYLE_MODELを設定してはいけません。
エラー時の挙動: 不正な値が設定されている場合は、変数名だけを示して起動を止めます(値は表示しません)。
モデル入手と SHA-256: 詳細は docs/operations.md を参照してください。
変数名 | 既定値 | 範囲・説明 |
| なし | 空・ |
| なし | イラスト用の検出器(ONNX)。アプリのルートからの相対パスか絶対パス |
| なし | 64 桁の 16 進数。設定すると起動時にモデルファイルと照合 |
| なし | クラス名のカンマ区切り。ONNX の付属情報 |
|
| イラスト用の検出対象クラス。空でなく、重複なし |
|
| イラスト用のスコアしきい値。 |
|
| イラスト用の前処理。 |
| なし | 写真用の検出器(ONNX)。指定方法は |
|
| 写真用の検出対象クラス。空でなく、重複なし |
|
| 写真用のスコアしきい値。 |
|
| 写真用の前処理。 |
| なし | 画風の分類器(ONNX)。検出器が 2 つのときだけ設定する |
| なし | 64 桁の 16 進数。設定すると起動時にモデルファイルと照合 |
|
| 出力の並び順のラベル。 |
|
| 振り分けの境目( |
|
| 描画ごとの切り出しの上限。1〜32 の整数 |
|
| 箱を各辺へ広げる割合(幅・高さに対する倍率)。0〜4 |
|
| 切り出しの最小の短辺(px)。1 以上で |
|
| 箱の重なりを除く NMS の IoU。 |
|
| ONNX の intra-op スレッド数。1〜64 の整数 |
較正の制約: 有効時は、較正の傾き
aが0より大きいことも求めます(a ≤ 0なら起動を止めます。評価 CLI の--writeも同様です)。再判定(
RECHECK)との併用: 切り出しは再判定に回さず、再判定は全体の最悪の描画に対してのみ実行します。最終のp_okは「再判定後の全体の結果」と「切り出しの最悪」のうち低い方となり、同じ入力のDETECT=0の値以下になります。起動ログ: 起動時に「
前段の検出: 有効(検出器 n、分類器あり/なし)」を 1 行出力します(パスと設定値は出しません)。処理回数とタイムアウト: 判定回数は最悪で「描画数 ×(
1 + DETECT_MAX_CROPS)」回になります。クライアントのタイムアウトとQUEUE_TIMEOUT_Sを見直してください(docs/operations.md)。ライセンス確認: 3 つのモデルのライセンスは、組み込み先の法務で確認してください(docs/operations.md)。
その他の設定ファイル(プロンプト・較正)
rules.local.md/rules.md: モデルへ渡す判定基準プロンプト。rules.local.mdが存在する場合は優先され、なければ公開用のrules.mdが使われます。calibration.json: 評価スクリプト(--write)で生成される確率較正パラメータ(version: "v1.1"と Platt スケーリングのa,b)。未生成時や旧式のファイルがある場合は恒等変換を使います。DETECT=1のときに--writeで生成したファイルはDETECT=1専用です(戻し方は docs/operations.md)。
入力形式とレイヤー安全対策
対応フォーマット
ファイル形式の判定には**ファイルの先頭バイト(マジックバイト)**を使います。
形式 | 検査内容と既定上限 |
PNG・JPEG | 静止画1枚を判定 |
GIF・WebP | 静止画は1枚。アニメーションは1周10秒以下かつ100フレーム以下なら全フレームを判定 |
TIFF | 100ページ以下なら全ページを判定。再生時間の上限は適用外 |
PSD(8bit) | レイヤー構成を保持した原本を送信。候補が既定32件以下なら全件を判定 |
APNG・AVIF・HEIC・BMP・SVG・PSB・16/32bit PSD・CLIP・XCF・PDF などは未対応です。REST は 415 unsupported、MCP は unsupported のツールエラーを返します。
モデルには各描画を減色なしの8bit RGB PNGとして送ります。向きを整え、長辺の上限を超える画像は縮小し、透過は白に合成します。切り出し再判定も PNG を使います。PSD やアニメーションは原本のまま API に送ってください。
アニメーションの上限
GIF・WebP は既定で 10秒以下、合計100フレーム以下です。1周分のフレーム遅延を合計し、0 以下の遅延は 10 ms として数えます。上限内は全フレームを判定して最小値を採用します。上限を超えると、REST は 413、MCP は isError: true の too_large を返します。TIFF はページ数の上限だけを適用します。
1フレームあたり約2.5秒で直列処理する構成では、100フレームで約4分かかります。クライアントのタイムアウトは5分以上を目安にし、モデルの速度と並列数に合わせて調整してください。
レイヤー検査の仕組み
モザイクが別レイヤーに分かれているファイルでは、後からレイヤーを非表示・削除することでモザイクが解除できてしまうリスクがあります。これを防ぐため、レイヤー付きファイル(PSD)は以下の複数パターンの描画をすべて判定し、最も低い(厳しい)p_ok を返します。
見えているとおりの状態(PSD 内の Photoshop 合成画像
imageDataを優先利用)非表示レイヤーもすべて表示した状態
名前が
MOSAIC_LAYER_PATTERNに一致するレイヤーを非表示にした状態可視レイヤーを上から 1 枚ずつ外した状態(名前が変更されたモザイク層も検出するため)
PSD ごとに候補数を数え、上限内なら全件を判定します。上限は既定32件で、管理者が MAX_RENDERS で変更できます。最初の3候補がそろう場合、既定値では可視レイヤーを1枚ずつ外す検査を29件まで実行できます。
上限を超えた場合は、画像の合成・モデル判定に進まずエラーを返します。REST は 413、MCP は isError: true とし、REST の本文と MCP の structuredContent に次の情報を含めます。
{
"error": "too_large",
"reason": "psd_render_limit",
"required_renders": 62,
"max_renders": 32,
"message": "PSD の検査には62件の描画が必要ですが、上限は32件です"
}描画やモデル判定に失敗した場合も、リクエスト全体をエラーにします。
前段の検出有効時(DETECT=1)の切り出し仕様
DETECT=1 では、各描画の全体に加えて、検出した部位の切り出し(最大 DETECT_MAX_CROPS 件)も同じ判定器で判定し、全描画の全体と切り出しのうち最も低い p_ok を返します。
切り出し範囲: 検出箱を
DETECT_MARGINの割合で広げ、短辺がDETECT_MIN_SIDE未満の場合は中心を保ったまま軸ごとに広げます(拡大・縮小はせず PNG で切り出します)。境界の補正: 範囲が画像の外へ出る場合は、大きさを保ったまま画像の内側へずらします(画像より大きい場合は画像全体とします)。範囲が描画全体と同じになる切り出しは判定対象から除きます。
エラー時の扱い: 検出・切り出し・切り出し判定のいずれかが失敗した場合は、リクエスト全体をエラーにします(検出・切り出しの失敗は
500 internal、切り出し判定の失敗は502 vlm)。
PSD 合成の制限事項
本ハーネスの自前レイヤー合成は normal ブレンドのアルファ合成のみに対応しており、Photoshop の描画結果とは完全には一致しません。以下は検出・再現できないためご注意ください。
2 枚以上のレイヤーにまたがって構成されたモザイク
スマートフィルター
レイヤー効果(ドロップシャドウ等)
normal以外のブレンドモードクリッピングマスクおよび塗りの不透明度(
fillOpacity)
セキュリティと CORS の注意点
IP 制限の仕組み: 接続元 IP は
socket.remoteAddressのみで判定し、X-Forwarded-Forヘッダは信頼しません。前段にリバースプロキシを置かないでください。CORS プリフライト:
OPTIONSリクエストは認証チェックの前に204で応答し、必要に応じてAccess-Control-Allow-Private-Network: trueも返します。非許可 Origin には CORS ヘッダを付与しません。ブラウザ利用時のキー露出: ブラウザ上の JavaScript に
MOSAIC_API_KEYを埋め込むと、そのページを閲覧できる全員にキーが露出します。LAN 内の信頼できるユーザー限定で運用してください。examples/browser.html はキーをコードに埋め込まず、画面上の入力欄から受け取る設計になっています。file://での制限: HTML ファイルをブラウザで直接(file://)開くと Origin がnullになり CORS で失敗します。examples/browser.html等を使う場合はpython3 -m http.server等で配信し、その Origin(例:http://127.0.0.1:8000)をMOSAIC_CORS_ORIGINSに含めるか、MOSAIC_API_KEYを設定して*を許可してください。
判定基準の同期(DocBase)
社内などの DocBase で管理している詳細な判定基準を反映したい場合は、以下の手順でローカル専用の rules.local.md を作成します(docbase.json・rules/docbase/・rules.local.md はいずれも Git 管理外です)。
ルートディレクトリに
docbase.jsonを作成します。{ "team": "<チーム名>", "postIds": ["<投稿ID>", "..."] }環境変数
DOCBASE_TOKENを設定して同期スクリプトを実行します。DOCBASE_TOKEN=<トークン> npx tsx scripts/sync-rules.ts取得した記事は
rules/docbase/に保存されます(トークン自体はファイルにもログにも出力されません)。取得した内容を基に
rules.local.mdを作成・調整します。
詳しい運用・チューニング手順は docs/operations.md を参照してください。
プライバシーとデータ取り扱い
画像非保存: 送信された画像はメモリ上でのみ処理し、ディスクへは一切保存しません。
機密情報の非出力: ログおよびエラー応答には、画像本体・Base64 文字列・API キーを出力しません。アクセスログに記録するのは、HTTP メソッド・パス・ステータスコード・所要時間・画像データの SHA-256 先頭 12 桁・バイトサイズのみです。
制限事項と前提
同時実行: リクエストの同時実行上限は、各モデルの「接続先数 × 1 台あたりのスロット数」の合計です。既定の 1 台・1 スロットでは直列処理になります。空きがなく待機し、
QUEUE_TIMEOUT_Sを超えると503エラーになります。複数台の振り分け: 各モデルの接続先プールで空きスロットに配分します。複製のうち失敗した台は 15 秒間プールから外し、同じモデルの別の台で 1 回だけ再試行します。どれか 1 モデルでも最終的に失敗すると
502を返します。再判定では最初の接続先に領域を提案させ、切り出し後の判定を全モデルで行います(複数台の運用)。実機要件: 判定基準の確定、評価用データの用意、
llama-serverの起動条件(GGUF モデル / mmproj 選定)は運用者側で行います。llama-serverが前提条件を満たしているかは docs/operations.md で確認してください。
開発・テスト
npm test # Vitest によるテスト実行
npm run typecheck # TypeScript 型チェック (tsc --noEmit)評価・較正の方法は docs/operations.md、呼び出しサンプルは examples/ を参照してください。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
AI-powered image processing via GPU. Remove backgrounds and upscale images (2x/4x) directly from any MCP client. OAuth 2.1 authenticated, returns processed images inline with download links. Free credits on signup at maskr.io.
MCP server for Qwen Image 3 AI image generation
Paid remote MCP for LLM security scans, jailbreak checks, analytics, checkout, and readiness.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA full-featured image processing MCP server for AI assistants, exposing ~55 tools across 11 categories for editing, layers, conversion, AI segmentation/cleanup/generation, design analysis, and screenshot-to-code.-
- FlicenseNot gradedqualityDmaintenanceEnables AI clients like Claude to understand, analyze, and describe local images via VL models through the MCP protocol.-
- AlicenseNot gradedqualityCmaintenanceEnables image analysis via OpenAI-compatible vision APIs, supporting local files, URLs, and base64 inputs with intelligent tiling for high-resolution images. Provides a secure, configurable MCP stdio server for structured vision analysis.85 npm3MIT
- AlicenseAqualityCmaintenanceEnables any MCP client to perform image understanding and OCR via any OpenAI-compatible vision-language model. Supports local, private inference without images leaving the machine.227 npmMIT