mcp-image-title-server 1.0.0

package/README.md

@@ -0,0 +1,532 @@
+# MCP Image Title Server
+
+背景画像にタイトル文字を合成するMCPサーバーです。背景の明るさに応じて文字色を自動調整し、読みやすさを確保します。
+
+## 特徴
+
+- 背景画像の明るさを自動分析
+- 明るさに応じた最適な文字色の自動選択
+- 影付きテキストによるコントラスト強化
+- **複数テキストレイヤーのサポート** - 1つの画像に異なるフォント/サイズ/位置で複数のテキストを合成
+- 柔軟な位置調整とカスタマイズオプション
+- カスタムフォント自動読み込み機能
+- PNG、JPEGなど主要画像フォーマットに対応
+
+## インストール
+
+### ローカル開発用
+```bash
+npm install
+```
+
+### グローバルインストール用
+```bash
+# パッケージを作成
+npm pack
+
+# グローバルインストール
+npm install -g mcp-image-title-server-1.0.0.tgz
+```
+
+### グローバルインストール後の使用
+```bash
+# どこからでも実行可能
+mcp-image-title-server
+```
+
+## 必要な依存関係
+
+- Node.js 18.0.0以上
+- Canvas（ネイティブ依存関係のため、システムによってはビルドツールが必要）
+
+### システム依存関係（Ubuntu/Debian）
+```bash
+sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev
+```
+
+### システム依存関係（macOS）
+```bash
+brew install pkg-config cairo pango libpng jpeg giflib librsvg
+```
+
+## 使用方法
+
+### ローカル開発
+```bash
+npm start
+```
+
+### グローバルインストール後
+```bash
+mcp-image-title-server
+```
+
+### 自動インストールスクリプト
+```bash
+chmod +x install.sh
+./install.sh
+```
+
+開発モード（ファイル変更時に自動再起動）:
+```bash
+npm run dev
+```
+
+## MCP設定
+
+グローバルインストール後のMCP設定例:
+```json
+{
+  "mcpServers": {
+    "image-title-server": {
+      "command": "mcp-image-title-server"
+    }
+  }
+}
+```
+
+## MCPツール
+
+### 1. composite_title
+
+背景画像にタイトル文字を合成します。
+
+**パラメータ:**
+- `backgroundPath` (必須): 背景画像のパス
+- `title` (必須): 合成するタイトルテキスト（改行文字 \n で複数行に分割可能）
+- `outputPath`: 出力ファイルパス (デフォルト: "output.png")
+- `fontSize`: フォントサイズ (デフォルト: 48)
+- `fontFamily`: フォントファミリー (デフォルト: "Arial")
+- `position`: テキスト位置 ("top", "center", "bottom") (デフォルト: "center")
+- `offsetX`: 水平オフセット (デフォルト: 0)
+- `offsetY`: 垂直オフセット (デフォルト: 0)
+- `enhanceContrast`: 影付きでコントラスト強化 (デフォルト: true)
+- `customColor`: カスタム文字色（16進数形式、自動検出を上書き）
+- `border`: 枠線の種類 ("rectangle", "rounded", "filled", "outline")
+- `borderWidth`: 枠線の太さ (デフォルト: 2)
+- `borderColor`: 枠線の色（16進数形式、未指定時は自動選択）
+- `borderRadius`: 角丸の半径 (デフォルト: 8)
+- `borderPadding`: テキスト周りの余白 (デフォルト: 16)
+- `borderOpacity`: 枠線の透明度 (0-1, デフォルト: 0.8)
+- `textEffect`: テキストエフェクト ("outline", "glow", "emboss")
+- `outlineWidth`: アウトライン幅（ピクセル、デフォルト: 3）
+- `outlineColor`: アウトライン/グロー色（16進数形式、未指定時は自動選択）
+- `glowRadius`: グロー半径（ピクセル、デフォルト: 10）
+- `glowIntensity`: グロー強度（0-1、デフォルト: 0.8）
+- `gradientSampling`: グラデーション背景用の複数点サンプリング（デフォルト: false）
+- `autoSize`: 画像に収まるよう自動的にフォントサイズを調整（デフォルト: false）
+- `autoWrap`: 長いテキストを自動的に複数行に折り返し（デフォルト: false）
+- `maxWidthPercent`: 自動調整時の最大幅（画像幅の割合、デフォルト: 0.8）
+- `maxHeightPercent`: 自動調整時の最大高さ（画像高さの割合、デフォルト: 0.8）
+- `minFontSize`: 自動調整時の最小フォントサイズ（デフォルト: 12）
+- `maxFontSize`: 自動調整時の最大フォントサイズ（デフォルト: 200）
+- `lineHeight`: 複数行テキストの行高さ倍率（デフォルト: 1.2）
+- `customFontPath`: カスタムフォントファイルのパス（.ttfまたは.otf）
+- `customFontPaths`: フォントバリアントの配列（通常・太字・斜体など）
+- `fontWeight`: フォントの太さ（"normal", "bold", "100"-"900"、デフォルト: "normal"）
+- `fontStyle`: フォントスタイル（"normal", "italic", "oblique"、デフォルト: "normal"）
+
+**使用例:**
+```json
+{
+  "backgroundPath": "./background.jpg",
+  "title": "Hello World",
+  "outputPath": "./result.png",
+  "fontSize": 60,
+  "position": "center",
+  "enhanceContrast": true,
+  "border": "rounded",
+  "borderWidth": 3,
+  "borderRadius": 12,
+  "borderPadding": 20,
+  "borderOpacity": 0.9
+}
+```
+
+**枠線の種類:**
+- `rectangle`: 四角形の枠線
+- `rounded`: 角丸の枠線
+- `filled`: 塗りつぶされた背景枠
+- `outline`: 二重線の枠線エフェクト
+
+**テキストエフェクトの種類:**
+- `outline`: テキストの周りにアウトラインを描画
+- `glow`: グロー（発光）エフェクトを適用
+- `emboss`: エンボス（浮き彫り）エフェクトで立体感を表現
+
+**グラデーション背景への対応:**
+`gradientSampling: true` を設定すると、グラデーション背景に対して5x5グリッドで複数点をサンプリングし、より正確な明るさ分析を実現します。
+
+
+**複数行テキスト（改行文字の使用）:**
+
+タイトルに改行文字（`\n`）を含めることで、明示的に複数行のテキストを作成できます。
+
+```json
+{
+  "backgroundPath": "./background.jpg",
+  "title": "1行目のタイトル\n2行目のタイトル",
+  "fontSize": 48,
+  "position": "center"
+}
+```
+
+改行文字と `autoWrap` を組み合わせることで、各行を個別に自動折り返しすることも可能です：
+
+```json
+{
+  "backgroundPath": "./background.jpg",
+  "title": "短いタイトル\nこれは長いタイトルで自動的に折り返されます",
+  "autoWrap": true,
+  "maxWidthPercent": 0.8
+}
+```
+
+### 2. composite_title_multi
+
+**複数のテキストレイヤー**を1つの画像に合成します。メインタイトル、サブタイトル、日付など、異なるスタイルのテキストを自由に配置できます。
+
+**主な用途:**
+- LLMに画像を読み込ませ、キャラクターや装飾を避けた位置にテキストを配置
+- 複雑なレイアウトのタイトル画像作成
+- 各要素に個別のフォント・サイズ・位置を指定
+
+**パラメータ:**
+- `backgroundPath` (必須): 背景画像のパス
+- `outputPath`: 出力ファイルパス (デフォルト: "output.png")
+- `layers` (必須): テキストレイヤーの配列（各レイヤーは独立した設定を持つ）
+
+**各レイヤーのパラメータ:**
+- `text` (必須): テキスト内容
+- `fontSize`, `fontFamily`, `fontWeight`, `fontStyle`: フォント設定
+- `position`: 位置プリセット ("top", "center", "bottom")
+- `x`, `y`: 絶対座標（指定した場合、positionより優先）
+- `offsetX`, `offsetY`: 位置の微調整
+- その他: `composite_title`と同じパラメータが全て使用可能
+
+**使用例:**
+```json
+{
+  "backgroundPath": "base01.png",
+  "outputPath": "output.png",
+  "layers": [
+    {
+      "text": "GitHub Actions",
+      "fontSize": 72,
+      "position": "top",
+      "offsetY": 50,
+      "fontFamily": "けいなんポップ体JP",
+      "border": "rounded"
+    },
+    {
+      "text": "セルフホストランナー構築ガイド",
+      "fontSize": 48,
+      "position": "top",
+      "offsetY": 150,
+      "enhanceContrast": true
+    },
+    {
+      "text": "2025年1月版",
+      "fontSize": 24,
+      "position": "bottom",
+      "offsetY": -30,
+      "customColor": "#888888"
+    }
+  ]
+}
+```
+
+**LLMとの連携:**
+
+1. 画像をLLM（Claude）に読み込ませる
+2. LLMがキャラクター、枠、装飾の位置を認識
+3. それらを避けた配置をLLMが提案
+4. `composite_title_multi`で複数レイヤーを合成
+
+**レイヤーの描画順:**
+配列の順番通りに描画されます（後のレイヤーが前面に表示）。
+
+### 3. analyze_brightness
+
+画像の指定領域の明るさを分析し、最適なテキスト色を推奨します。
+
+### 4. get_config
+
+現在の設定とパス解決情報を取得します（デバッグ用）。
+
+## 設定ファイル
+
+デフォルト設定をカスタマイズするには、`.mcp-image-title.json` ファイルをプロジェクトディレクトリまたはホームディレクトリに配置します。
+
+### 設定ファイルの場所の指定
+
+設定ファイルは以下の優先順位で読み込まれます：
+
+1. **コマンドライン引数**: `--config <path>` または `--config=<path>`
+2. **環境変数**: `MCP_IMAGE_TITLE_CONFIG`
+3. **カレントディレクトリ**: `./.mcp-image-title.json`
+4. **ホームディレクトリ**: `~/.mcp-image-title.json`
+
+**MCP クライアントでの設定例:**
+
+```json
+{
+  "mcpServers": {
+    "image-title-server": {
+      "command": "mcp-image-title-server",
+      "args": ["--config", "/path/to/custom/.mcp-image-title.json"]
+    }
+  }
+}
+```
+
+または環境変数を使用：
+
+```json
+{
+  "mcpServers": {
+    "image-title-server": {
+      "command": "mcp-image-title-server",
+      "env": {
+        "MCP_IMAGE_TITLE_CONFIG": "/path/to/custom/.mcp-image-title.json"
+      }
+    }
+  }
+}
+```
+
+**設定ファイル例:**
+```json
+{
+  "defaults": {
+    "backgroundsDirectory": "./images",
+    "outputsDirectory": "./output",
+    "fontsDirectory": "./fonts",
+    "fontSize": 60,
+    "fontFamily": "けいなんポップ体JP",
+    "position": "top",
+    "offsetY": 50,
+    "enhanceContrast": true,
+    "borderOpacity": 0.9,
+    "textEffect": "outline",
+    "outlineWidth": 3,
+    "gradientSampling": true
+  },
+  "fonts": {
+    "けいなんポップ体JP": "けいなんポップ体JPイロハ.ttf",
+    "Noto Sans JP": "NotoSansJP-VariableFont_wght.ttf"
+  }
+}
+```
+
+**カスタムフォントの自動読み込み:**
+
+`fonts` セクションでフォント名とファイルパスのマッピングを設定すると、`fontFamily` を指定するだけで自動的にフォントが読み込まれます。
+
+- フォントファイルパスは `fontsDirectory` を基準に解決されます
+- 複数のフォントバリアント（太字、斜体など）も配列で指定可能：
+  ```json
+  "fonts": {
+    "MyFont": ["Regular.ttf", "Bold.ttf", "Italic.ttf"]
+  }
+  ```
+
+設定ファイルのサンプルは `.mcp-image-title.example.json` として提供されています。
+
+### デフォルトフォルダ設定
+
+GitHub Actionsなどの自動化環境で便利なデフォルトフォルダ設定：
+
+- **backgroundsDirectory**: 背景画像のデフォルトフォルダ（相対パスの場合に適用）
+- **outputsDirectory**: 出力画像のデフォルトフォルダ（相対パスの場合に適用）
+- **fontsDirectory**: カスタムフォントのデフォルトフォルダ（相対パスの場合に適用）
+
+**動作:**
+- 絶対パスまたは `./`、`../` で始まるパスは、そのまま使用されます
+- それ以外の相対パス（例: `"background.jpg"`）は、デフォルトフォルダを基準に解決されます
+
+**使用例:**
+```json
+// 設定ファイル
+{
+  "defaults": {
+    "backgroundsDirectory": "./images",
+    "outputsDirectory": "./output"
+  }
+}
+
+// ツール呼び出し
+{
+  "backgroundPath": "bg.jpg",     // → ./images/bg.jpg として解決
+  "outputPath": "result.png",      // → ./output/result.png として解決
+  "customFontPath": "./fonts/custom.ttf"  // → そのまま ./fonts/custom.ttf として使用
+}
+```
+
+### デフォルトフォルダ設定
+
+GitHub Actionsなどの自動化環境で便利なデフォルトフォルダ設定：
+
+- **backgroundsDirectory**: 背景画像のデフォルトフォルダ（相対パスの場合に適用）
+- **outputsDirectory**: 出力画像のデフォルトフォルダ（相対パスの場合に適用）
+- **fontsDirectory**: カスタムフォントのデフォルトフォルダ（相対パスの場合に適用）
+
+**動作:**
+- 絶対パスまたは `./`、`../` で始まるパスは、そのまま使用されます
+- それ以外の相対パス（例: `"background.jpg"`）は、デフォルトフォルダを基準に解決されます
+
+**使用例:**
+```json
+// 設定ファイル
+{
+  "defaults": {
+    "backgroundsDirectory": "./images",
+    "outputsDirectory": "./output"
+  }
+}
+
+// ツール呼び出し
+{
+  "backgroundPath": "bg.jpg",     // → ./images/bg.jpg として解決
+  "outputPath": "result.png",      // → ./output/result.png として解決
+  "customFontPath": "./fonts/custom.ttf"  // → そのまま ./fonts/custom.ttf として使用
+}
+```
+
+## カスタムフォントの使用
+
+TTFまたはOTFフォーマットのカスタムフォントを使用できます。
+
+### 単一フォントファイルの使用
+
+```json
+{
+  "backgroundPath": "./background.jpg",
+  "title": "美しい日本語タイトル",
+  "customFontPath": "./fonts/NotoSansJP-Bold.otf",
+  "fontFamily": "Noto Sans JP",
+  "fontSize": 72
+}
+```
+
+### 複数フォントバリアントの使用
+
+```json
+{
+  "backgroundPath": "./background.jpg",
+  "title": "Bold Title",
+  "customFontPaths": [
+    "./fonts/Roboto/Roboto-Regular.ttf",
+    "./fonts/Roboto/Roboto-Bold.ttf",
+    "./fonts/Roboto/Roboto-Italic.ttf"
+  ],
+  "fontFamily": "Roboto",
+  "fontWeight": "bold",
+  "fontSize": 64
+}
+```
+
+### フォントウェイトとスタイルの使用
+
+```json
+{
+  "backgroundPath": "./background.jpg",
+  "title": "Styled Text",
+  "customFontPaths": [
+    "./fonts/Merriweather/Merriweather-Regular.ttf",
+    "./fonts/Merriweather/Merriweather-Bold.ttf",
+    "./fonts/Merriweather/Merriweather-Italic.ttf",
+    "./fonts/Merriweather/Merriweather-BoldItalic.ttf"
+  ],
+  "fontFamily": "Merriweather",
+  "fontWeight": "bold",
+  "fontStyle": "italic",
+  "fontSize": 56
+}
+```
+
+### サポートされているフォーマット
+
+- ✅ TTF (TrueType Font)
+- ✅ OTF (OpenType Font)
+- ❌ WOFF/WOFF2（未サポート）
+
+### フォントの配置
+
+`fonts/`ディレクトリにフォントファイルを配置してください。詳細は `fonts/README.md` を参照してください。
+
+**推奨フォント:**
+- Noto Sans JP: https://fonts.google.com/noto/specimen/Noto+Sans+JP
+- M PLUS 1: https://fonts.google.com/specimen/M+PLUS+1
+- その他のGoogle Fonts: https://fonts.google.com/
+
+### 注意事項
+
+- フォントのライセンスを確認してください
+- `fontFamily`には、フォントファイルに埋め込まれているフォント名を指定してください（ファイル名ではありません）
+- カスタムフォントはキャッシュされ、2回目以降の使用時は高速に読み込まれます
+
+### 2. analyze_brightness
+
+画像の指定領域の明度を分析します。
+
+**パラメータ:**
+- `imagePath` (必須): 分析する画像のパス
+- `x`: 領域のX座標 (デフォルト: 0)
+- `y`: 領域のY座標 (デフォルト: 0)
+- `width`: 領域の幅 (デフォルト: 画像全体の幅)
+- `height`: 領域の高さ (デフォルト: 画像全体の高さ)
+
+## 明度分析の仕組み
+
+1. **輝度計算**: RGB値から知覚輝度を計算（0.299×R + 0.587×G + 0.114×B）
+2. **自動文字色選択**: 
+   - 明るい背景（輝度 > 128）→ 黒文字 + 白影
+   - 暗い背景（輝度 ≤ 128）→ 白文字 + 黒影
+3. **コントラスト強化**: 影とぼかし効果で文字の視認性を向上
+
+## 出力例
+
+```json
+{
+  "success": true,
+  "outputPath": "./result.png",
+  "dimensions": { "width": 1920, "height": 1080 },
+  "textPosition": { "x": 960, "y": 540 },
+  "textStyle": {
+    "color": "#FFFFFF",
+    "shadow": "#000000",
+    "shadowBlur": 3
+  },
+  "borderInfo": {
+    "type": "rounded",
+    "color": "#000000",
+    "width": 3,
+    "radius": 12,
+    "padding": 20,
+    "opacity": 0.9
+  },
+  "brightness": 85.3
+}
+```
+
+## トラブルシューティング
+
+### Canvas のインストールエラー
+Canvasはネイティブ依存関係を持つため、システムにビルドツールが必要です：
+
+**Windows:**
+- Visual Studio Build Tools をインストール
+- Python 3.x をインストール
+
+**エラー対処法:**
+```bash
+npm rebuild canvas
+```
+
+### フォントが見つからない
+システムにインストールされているフォントのみ使用可能です。利用可能なフォント名を確認してください。
+
+## ライセンス
+
+MIT License