Inks MCP

🚀 万年筆インクMCPサーバー

このModel Context Protocol (MCP) サーバーは、大規模言語モデル (LLMs) に万年筆インクに関する専門知識を提供し、インクのスマートな検索、色のマッチング、および推薦を可能にします。このサーバーを作成した私の記事を読む

✨ 主な機能

このMCPサーバーは、LLMsに以下のツールを提供します。

🔍 検索ツール

• search_inks_by_name：インクの名前またはメーカー名で曖昧検索を行います。
• search_inks_by_color：RGBマッチングを使用して、指定された色に似たインクを見つけます。
• get_inks_by_maker：特定のメーカーのすべてのインクをリストします。

📊 情報ツール

• get_ink_details：特定のインクに関する包括的な情報を取得します。
• analyze_color：任意の色を分析し、最も近いマッチングインクを見つけます。

🎨 推薦ツール

• get_color_palette：色彩理論をサポートした洗練されたテーマ別のインクパレットを生成します。
  • 13の事前定義されたテーマ（暖色系、寒色系、大地色、海洋色、秋、春、夏、冬、パステル、鮮やか、モノクロ、夕日、森林）
  • 色調和生成（補色、類似色、トライアディック、分割補色）
  • カスタム16進数カラーパレット

🚀 クイックスタート

git clone https://github.com/ewilderj/inks-mcp.git
cd inks-mcp
npm install
npm run build

# ツールをリストし、サンプルクエリを実行する
npm run tools:list
npm run client -- --tool search_inks_by_name --args '{"query":"sailor blue","max_results":5}'

📦 インストール

前提条件

• Node.js 18以上
• npmまたはyarn

セットアップ

# プロジェクトをクローンする
git clone https://github.com/ewilderj/inks-mcp.git
cd inks-mcp

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

# プロジェクトをビルドする
npm run build

💻 使用例

サーバーの実行

# 一度だけ実行する
npm start

# 自動再構築を伴う開発モード
npm run dev

# 開発用のウォッチモード
npm run watch

MCPクライアントの設定

このサーバーをMCPクライアントの設定に追加します。

{
  "servers": {
    "fountain-pen-ink-server": {
      "type": "stdio",
      "command": "node",
      "args": ["<path-to-project>/dist/index.js"]
    }
  }
}

CLIクライアント（汎用）

コマンドラインから任意のツールを実行するための小さなスクリプトが含まれています。

# ツールをリストする
npm run tools:list

# インラインJSON引数でツールを呼び出す
npm run client -- --tool search_inks_by_name --args '{"query":"sailor blue","max_results":5}'

# ファイルから引数を使用して呼び出す
npm run client -- --tool get_color_palette --args-file examples/palette.complementary.json

# 出力モードを変更する（auto | content | raw）
npm run client -- --tool search_inks_by_color --args '{"color":"#2E5984"}' --output content

スクリプトのオプション：

• --list：利用可能なツールをリストします。
• --tool <name>：呼び出すツールの名前です。
• --args '<json>'：インラインJSON引数です。
• --args-file <path>：引数が記載されたJSONファイルのパスです。
• --server <path>：コンパイルされたサーバーのパス（デフォルト：dist/index.js）
• --timeout <ms>：タイムアウト時間（ミリ秒）（デフォルト：10000）
• --output <mode>：出力モード（auto | content | raw）（デフォルト：auto）

利用可能なツール

search_inks_by_name

曖昧なテキストマッチングを使用して万年筆インクを検索します。

パラメータ：query (文字列), max_results (数値、オプション)

入力例：

{ "query": "sailor blue", "max_results": 10 }

プロンプト例：

• "sailor blue"に一致するインクを検索し、結果を10件に制限します。

search_inks_by_color

RGB色空間マッチングを使用して、指定された色に似たインクを見つけます。

パラメータ：color (16進数文字列), max_results (数値、オプション)

入力例：

{ "color": "#2E5984", "max_results": 15 }

プロンプト例：

• 色#2E5984に似たインクを検索し、最大15件の結果を表示します。

get_ink_details

特定のインクに関する完全な情報を取得します。

パラメータ：ink_id (文字列)

入力例：

{ "ink_id": "diamine-oxblood" }

プロンプト例：

• "diamine-oxblood"の情報を表示します。

get_inks_by_maker

特定のメーカーのすべてのインクをリストします。

パラメータ：maker (文字列), max_results (数値、オプション)

入力例：

{ "maker": "diamine", "max_results": 25 }

プロンプト例：

• Diamineのインクをリストし、結果を25件に制限します。

analyze_color

色を分析し、万年筆インクのコンテキストを提供します。

パラメータ：color (16進数文字列), max_results (数値、オプション)

入力例：

{ "color": "#2E5984", "max_results": 7 }

プロンプト例：

• #2E5984を分析し、最も近い7つのインクを表示します。

get_color_palette

色彩理論をサポートした、テーマまたは調和に基づく万年筆インクのパレットを生成します。

パラメータ：theme (文字列), palette_size (数値、オプション), harmony (文字列、オプション)

サポートされるテーマ：

• クラシック：暖色系、寒色系、大地色、海洋色、秋、春
• 季節：夏、冬
• ムード：パステル、鮮やか、モノクロ
• 雰囲気：夕日、森林

調和ルール：補色、類似色、トライアディック、分割補色

入力例：

{ "theme": "sunset", "palette_size": 4 }

プロンプト例：

• "夕日"テーマの4色のインクパレットを生成します。

詳細な例については、examples/USAGE.mdを参照してください。

データソース

サーバーは2つの主要なデータファイルを使用しています。

• ink-colors.json：RGB色値と基本的なインク情報が含まれています。
• search.json：メーカー、スキャン日、検索可能な名前を含むメタデータが含まれています。

すべてのインクデータは、詳細情報と画像についてWilder Writesにリンクされています。

開発

プロジェクト構造

inks-mcp/
├── src/
│   ├── index.ts      # メインのMCPサーバー実装
│   ├── types.ts      # TypeScriptの型定義
│   └── utils.ts      # 色マッチングのためのユーティリティ関数
├── data/
│   ├── ink-colors.json   # RGB色データ
│   └── search.json       # 検索メタデータ
├── dist/             # コンパイルされたJavaScript（生成される）

スクリプト

• npm run build：TypeScriptをJavaScriptにコンパイルします。
• npm run start：コンパイルされたサーバーを実行します。
• npm run dev：ビルドと実行を1つのコマンドで行います。
• npm run watch：変更を監視し、自動的に再構築します。
• npm run client：汎用のCLIクライアントを実行します。
• npm run tools:list：CLIクライアントを介して利用可能なツールをリストします。

テスト

すべての機能を検証するために、包括的なテストスイートを実行します。

npm test

# 個々のテストカテゴリを実行する
cd test
node test-enhanced-palette.js    # パレット生成機能
node test-mcp-palette.js        # MCPプロトコル準拠
node test-schema.js             # ツールスキーマの検証
node test-harmony-direct.js     # 色調和アルゴリズム

手動のアドホックテストには、上記のCLIクライアントを使用してください。

テストスイートは以下をカバーしています。

• ✅ 13の事前定義されたテーマ + 4つの調和ルール
• ✅ カスタムカラーパレット生成
• ✅ MCPプロトコル準拠
• ✅ エラー処理と検証
• ✅ 色空間変換（BGR→RGB、RGB↔HSL）

色マッチングアルゴリズム

サーバーはRGB色空間でのユークリッド距離を使用して、類似するインクを見つけます。

distance = √[(r₁-r₂)² + (g₁-g₂)² + (b₁-b₂)²]

将来的な改善点としては、以下が考えられます。

• 知覚的な精度を向上させるためのLAB色空間
• 万年筆インクの特性に応じた重み付き色成分
• 意味的な色の記述

コントリビュート

1. リポジトリをフォークします。
2. featureブランチを作成します。
3. 変更を加えます。
4. 適用可能な場合はテストを追加します。
5. プルリクエストを送信します。

📄 ライセンス

このプロジェクトはGNU General Public License v3.0 (GPL-3.0)の下でライセンスされています。詳細はLICENSEファイルを参照してください。

リンク

• Wilder Writes - インクデータと詳細なインク情報のソース
• Model Context Protocol - MCPのドキュメントと例