Inks MCP

🚀 鋼筆墨水MCP服務器

這是一個模型上下文協議（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種預定義主題（暖色調、冷色調、大地色、海洋色、秋季色、春季色、夏季色、冬季色、柔和色、鮮豔色、單色、日落色、森林色）。
  • 顏色和諧生成（互補色、類似色、三色組、分裂互補色）。
  • 自定義十六進制顏色調色板。

🚀 快速開始

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（十六進制字符串），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（十六進制字符串），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。

📚 詳細文檔

數據源

服務器使用兩個主要數據文件：

• 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：在一個命令中完成構建和運行。
• 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. 創建功能分支。
3. 進行更改。
4. 如有必要，添加測試。
5. 提交拉取請求。

📄 許可證

本項目採用GNU通用公共許可證v3.0（GPL - 3.0）。詳情請參閱 LICENSE 文件。

🔗 鏈接

• Wilder Writes - 墨水數據來源和詳細墨水信息。
• 模型上下文協議 - MCP文檔和示例。