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文档和示例。