微信扫一扫article
README
🚀 钢笔墨水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颜色空间以获得更好的感知准确性。
- 为钢笔墨水特性设置加权颜色分量。
- 语义颜色描述。
贡献
- 分叉仓库。
- 创建功能分支。
- 进行更改。
- 如有必要，添加测试。
- 提交拉取请求。
📄 许可证
本项目采用GNU通用公共许可证v3.0（GPL - 3.0）。详情请参阅 LICENSE 文件。
🔗 链接
- Wilder Writes - 墨水数据来源和详细墨水信息。
- 模型上下文协议 - MCP文档和示例。