Sharp MCP

🚀 Sharp MCP

Sharp MCPは、画像セッションの管理と処理を行うMCP（Model Context Protocol）サーバーです。セッション内に画像を保存し、画像のメタデータや色を抽出するツールを提供します。

🚀 クイックスタート

Sharp MCPは、画像セッション管理と処理のためのMCPサーバーです。画像をセッションに保存し、メタデータや色を抽出するツールを提供します。

✨ 主な機能

• create_session：一意のIDを持つメモリセッションにBase64画像を保存します。
• create_session_by_path：画像ファイルのパスからセッションを作成します（自動でBase64に変換）。
• list_session：すべてのアクティブな画像セッションをリストします。
• get_dimensions：画像の寸法とMIMEタイプを取得します。
• pick_color：指定された領域から平均色を抽出します。
• remove_background：MLベースのセグメンテーションを使用して画像から背景を削除します。
• extract_region：画像から矩形領域を切り抜きます。
• compress_image：画像を圧縮し、形式を変換します（JPEG、PNG、WebP）。
• 型安全性のためにTypeScriptで構築されています。
• 高性能な画像処理のためにsharpを使用しています。

📦 インストール

NPM

npm install -g sharp-mcp

Smithery

Smitheryを介して任意のクライアントにSharp MCPを自動的にインストールするには：

npx -y @smithery/cli@latest install sharp-mcp --client <CLIENT_NAME>

利用可能なクライアント：cursor、claude、vscode、windsurf、cline、zedなど。

MCPクライアント統合

Sharp MCPは、Model Context Protocol (MCP) をサポートするさまざまなAIコーディングアシスタントやIDEと統合できます。

要件

• Node.js >= v18.0.0
• MCP互換のクライアント（Cursor、Claude Code、VS Code、Windsurfなど）

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

claude mcp add sharp -- npx -y sharp-mcp

"mcp": {
  "servers": {
    "sharp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sharp-mcp"]
    }
  }
}

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

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

[mcp_servers.sharp]
command = "npx"
args = ["-y", "sharp-mcp"]

利用可能なツール

create_session

指定された画像ペイロードで新しいセッションを作成し、一意のセッションIDを返します。

パラメーター:

• image_payload (文字列、必須): Base64エンコードされた画像データ
• description (文字列、オプション): 画像のオプションの説明

戻り値:

{ "sessionId": "img_abc123xyz" }

例:

{
  "image_payload": "iVBORw0KGgoAAAANSUhEUgAA...",
  "description": "ホームページのスクリーンショット"
}

create_session_by_path

指定された絶対ファイルパスから画像を読み取り、新しいセッションを作成します。自動的にファイルをBase64に変換し、有効な画像であることを検証します。

パラメーター:

• path (文字列、必須): 画像ファイルの絶対パス
• description (文字列、オプション): 画像のオプションの説明

戻り値:

{
  "sessionId": "img_abc123xyz",
  "source_path": "/path/to/image.png",
  "file_size": 46849
}

例:

{
  "path": "/Users/username/images/screenshot.png",
  "description": "ホームページのスクリーンショット"
}

エラーレスポンス:

• 相対パス: Path must be absolute. Received relative path: "./image.png"
• ファイルが見つからない: File not found: "/path/to/image.png"
• 無効な画像: Invalid or corrupted image file: "/path/to/file.txt"

list_session

すべてのアクティブなセッションのセッションID、画像ペイロード、および説明をリストします。

パラメーター: なし

戻り値:

[
  {
    "sessionId": "img_abc123xyz",
    "image_payload": "iVBORw0KGgoAAAANSUhEUgAA...",
    "description": "ホームページのスクリーンショット"
  }
]

get_dimensions

セッションに保存された画像の寸法とMIMEタイプを取得します。

パラメーター:

• sessionId (文字列、必須): create_sessionまたはcreate_session_by_pathから返されたセッションID

戻り値:

{
  "width": 1920,
  "height": 1080,
  "mimeType": "image/png"
}

エラーレスポンス（無効なセッション）:

Invalid or non-existent session ID. Please call create_session first to obtain a valid session ID.

pick_color

指定された座標を中心とする正方形領域から平均色を抽出します。

パラメーター:

• sessionId (文字列、必須): create_sessionから返されたセッションID
• x (数値、必須): 中心点のX座標
• y (数値、必須): 中心点のY座標
• radius (数値、オプション、デフォルト: 5): サンプリング領域の半径。サンプリング領域は(radius × 2)の正方形になります。

戻り値:

{
  "r": 255,
  "g": 128,
  "b": 64,
  "hex": "#FF8040"
}

エラーレスポンス（範囲外）:

Coordinates (2000, 500) exceed image bounds (1920x1080).

remove_background

MLベースのセグメンテーションを使用して画像から背景を削除します。透過性のあるPNGを返します。正確な被写体検出のために@imgly/background-removal-nodeを使用しています。

パラメーター:

• sessionId (文字列、必須): create_sessionから返されたセッションID
• output_path (文字列、オプション): 出力PNGファイルを保存する絶対パス。指定されない場合は、Base64ペイロードを返します。

戻り値（output_pathなし）:

{
  "image_payload": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mime_type": "image/png"
}

戻り値（output_pathあり）:

{
  "path": "/path/to/output.png"
}

例:

{
  "sessionId": "img_abc123xyz"
}

注意: 初回実行時は、MLモデルファイル（約10 - 50MB）がダウンロードされてキャッシュされるため、時間がかかる場合があります。

変更前と変更後:

extract_region

セッションに保存された画像から矩形領域を切り抜きます。切り抜いた画像をファイルまたはBase64ペイロードとして返します。

パラメーター:

• sessionId (文字列、必須): create_sessionから返されたセッションID
• x (数値、必須): 切り抜き領域の左上隅のX座標
• y (数値、必須): 切り抜き領域の左上隅のY座標
• width (数値、必須): 切り抜き領域の幅
• height (数値、必須): 切り抜き領域の高さ
• output_path (文字列、オプション): 切り抜いた画像を保存する絶対パス。指定されない場合は、Base64ペイロードを返します。

戻り値（output_pathなし）:

{
  "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mimeType": "image/png"
}

戻り値（output_pathあり）:

{
  "success": true,
  "path": "/path/to/cropped.png"
}

例:

{
  "sessionId": "img_abc123xyz",
  "x": 100,
  "y": 50,
  "width": 200,
  "height": 150,
  "output_path": "/path/to/cropped.png"
}

エラーレスポンス:

• 範囲外: Region (100, 50, 200x150) exceeds image bounds (150x100)
• 無効な座標: Invalid coordinates: x and y must be non-negative values.
• 無効な寸法: Invalid dimensions: width and height must be positive values.

compress_image

指定された形式と品質で画像を圧縮します。JPEG、PNG、WebP形式をサポートします。圧縮された画像をファイルまたはBase64ペイロードとして返します。

パラメーター:

• sessionId (文字列、必須): create_sessionから返されたセッションID
• format (文字列、オプション): 出力形式: 'jpeg'、'png'、または 'webp'。指定されない場合は、元の形式を保持します。
• quality (数値、オプション、デフォルト: 80): 圧縮品質（1 - 100）。値が高いほど品質が良くなりますが、ファイルサイズが大きくなります。
• output_path (文字列、オプション): 圧縮された画像を保存する絶対パス。指定されない場合は、Base64ペイロードを返します。

戻り値（output_pathなし）:

{
  "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mimeType": "image/jpeg",
  "format": "jpeg",
  "originalSize": 245632,
  "compressedSize": 98234,
  "compressionRatio": "60.01%"
}

戻り値（output_pathあり）:

{
  "success": true,
  "path": "/path/to/compressed.jpg",
  "format": "jpeg",
  "originalSize": 245632,
  "compressedSize": 98234,
  "compressionRatio": "60.01%"
}

例:

{
  "sessionId": "img_abc123xyz",
  "format": "webp",
  "quality": 75,
  "output_path": "/path/to/output.webp"
}

注意: PNG形式の場合、品質パラメーターは圧縮レベルに変換されます（品質100 → レベル0、品質0 → レベル9）。

💻 使用例

例1: 画像を分析する

Cursor/Claude Codeで:

./screenshot.pngのスクリーンショットを読み取り、セッションを作成し、その寸法を教えてください。

例2: UIから色を抽出する

Cursor/Claude Codeで:

UIのスクリーンショットがあります。セッションを作成し、これらの座標(100, 50)、(200, 150)、(300, 200)の色を抽出してください。

例3: 画像のメタデータを取得する

Cursor/Claude Codeで:

./logo.pngをセッションに読み込み、そのサイズと形式を取得してください。

例4: 画像から背景を削除する

Cursor/Claude Codeで:

./product-photo.jpgでセッションを作成し、背景を削除してください。結果を./product-transparent.pngに保存してください。

例5: 画像を圧縮し、形式を変換する

Cursor/Claude Codeで:

./large-image.pngをセッションに読み込み、75%の品質でWebP形式に圧縮してください。./optimized.webpに保存してください。

コマンドラインでの使用

サーバーを直接実行するには：

# stdioトランスポートを使用する（デフォルト）
sharp-mcp

# HTTPトランスポートを使用する
sharp-mcp --transport http --port 5000

CLIオプション:

• --transport <stdio|http>: トランスポートタイプ（デフォルト: stdio）
• --port <number>: HTTPトランスポートのポート（デフォルト: 5000）

開発

# 依存関係をインストールする
npm install

# 開発モードで実行する
npm run dev

# テストを実行する
npm test

# ビルドする
npm run build

# 型チェックを実行する
npm run typecheck

# リントを実行する
npm run lint

アーキテクチャ

このプロジェクトはモジュール化されたアーキテクチャに従っています：

• services/: セッションストレージと画像処理サービス
  • session-store.ts: メモリ内のセッション管理
  • image-processor.ts: Sharpベースの画像分析
• tools/: MCPツールの実装
  • create-session.ts: Base64からのセッション作成
  • create-session-by-path.ts: ファイルパスからのセッション作成
  • list-session.ts: セッションのリスト表示
  • get-image-size.ts: 画像寸法の抽出（get_dimensions）
  • pick-color.ts: 色の抽出
  • remove-background.ts: MLベースの背景削除
  • extract-region.ts: 画像の切り抜き
  • compress-image.ts: 画像の圧縮
• utils/: 共有ユーティリティ
  • validation.ts: セッションIDの検証
• server.ts: メインのMCPサーバーのセットアップと構成

サポートされる画像形式

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)
• TIFF (.tiff)
• AVIF (.avif)

📄 ライセンス

MIT

コントリビューション

コントリビューションは大歓迎です！プルリクエストを送信してください。

作者

choesumin