Ravelry MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供与 Ravelry API 交互的工具，允许 AI 助手搜索、探索和检索编织和钩针图案。

🌟 概述

此 MCP 服务器封装了 Ravelry API，以创建一个可靠的接口，供 AI 助手使用。它提供以下工具：

• 搜索编织和钩针图案
• 获取详细的图案信息
• 一次检索多个图案的详细信息

这个项目的灵感来自我的女朋友，她对编织和钩针的热情鼓励我创建了 AI 助手和 Ravelry 手工艺社区之间的这座桥梁。由于她不太懂技术，并且对 AI 持怀疑态度，这可以作为我与她的兴趣建立联系的一种方式，并展示技术如何增强她的手工艺体验，而不是取代它。

🚀 功能

• 🔍 图案搜索：使用关键字和过滤器搜索 Ravelry 的图案数据库
• 📋 图案详情：获取有关特定图案的全面信息
• 🧶 手工艺过滤：按手工艺类型（编织或钩针）过滤图案
• 💰 价格选项：按可用性（免费、付费等）过滤图案
• 🤖 AI 助手集成：旨在通过模型上下文协议与 AI 助手一起使用

📋 前提条件

• Node.js (v14 或更高版本)
• npm 或 yarn
• Ravelry API 凭据（用户名和密码）

🔧 安装

1. 克隆存储库

   git clone <repository-url>
   cd ravelry-mcp
   

2. 安装依赖项

   npm install
   

3. 设置环境变量

   # 创建开发环境文件
   cp .env.example .env.development
   # 创建生产环境文件
   cp .env.example .env.production
   

4. 配置 API 凭据

   • 获取您的 Ravelry 用户名和密码
   • 将您的凭据添加到 .env.development 和 .env.production 文件中：

     AUTH_USER=your_ravelry_username
     AUTH_PASS=your_ravelry_password
     

🎮 用法

开发模式

npm run dev

这将在开发模式下启动 MCP 服务器，并启用热重载。

生产模式

npm run build
npm start

或者使用简写：

npm run prod

🔗 与 Claude Desktop 集成

要将此 MCP 服务器添加到 Claude Desktop 并启用 Ravelry 浏览功能，请执行以下操作：

1. 启动 MCP 服务器 确保您的服务器在本地或 Claude Desktop 可以访问的远程主机上运行。

2. 打开 Claude Desktop 设置

   • 启动 Claude Desktop
   • 单击右上角的个人资料图片或图标
   • 从下拉菜单中选择“设置”

3. 导航到扩展设置

   • 在“设置”侧边栏中，单击“扩展”
   • 选择“添加自定义 MCP”

4.1 配置 MCP 连接

• 名称：Ravelry MCP（或您喜欢的任何名称）
• URL：输入您的 MCP 服务器正在运行的 URL（例如，本地开发为 http://localhost:3000）
• 单击“添加 MCP”

4.2 替代方案：通过命令配置 MCP 连接

• 您首先需要构建项目并提供已编译服务器的完整路径
• 将以下内容添加到您的 Claude Desktop 配置中：

"ravelry": {
  "command": "node",
  "args": [
    "YOUR_CUSTOM_PATH/dist/index.js"
  ]
}

5. 启用 MCP

   • 切换您新添加的 Ravelry MCP 旁边的开关以启用它
   • Claude Desktop 将尝试连接到您的 MCP 服务器

6. 验证连接

   • 与 Claude 开始新的对话
   • 键入“你能帮我在 Ravelry 上找到一些编织图案吗？”
   • Claude 现在应该能够使用 Ravelry 工具来搜索和浏览图案

7. 故障排除

   • 如果 Claude 无法连接到您的 MCP 服务器，请检查：
     • 服务器正在运行并且可以从 Claude Desktop 访问
     • 在 Claude Desktop 设置中配置了正确的 URL
     • 您的 API 凭据有效并且已在服务器中正确配置

与 Claude 的用法示例

连接后，您可以要求 Claude：

• “在 Ravelry 上帮我找一些免费的钩针帽子图案”
• “搜索袜子编织图案”
• “获取有关图案 ID 12345 的更多详细信息”
• “查找适合初学者的图案”

🧠 可用工具

服务器公开了几个可供 AI 助手使用的工具：

search-patterns

根据查询参数搜索图案。

参数：

• query：搜索词（必需）
• page：分页的页码（默认值：1）
• craft：手工艺类型（例如，“knitting”、“crochet”）
• availability：价格过滤器（默认值：“free”，选项：“free”、“ravelry”、“online”）

get-pattern-details

检索特定图案的详细信息。

参数：

• id：图案 ID（必需）

get-multiple-pattern-details

一次检索多个图案的详细信息。

参数：

• ids：图案 ID 数组（必需）

🔍 工作原理

服务器使用 axios 向 Ravelry API 发出经过身份验证的请求：

1. 使用您的 Ravelry 凭据通过 Basic Auth 验证请求
2. 向各种 Ravelry API 端点发出请求
3. 以结构化格式解析并返回数据
4. 将端点公开为可由 AI 助手调用的 MCP 工具

🛠️ 项目结构

src/
  ├── class/
  │   └── ravelry.class.ts       # Ravelry API 的主要客户端
  ├── endpoints/
  │   ├── getMultiplePatternDetails.ts  # 获取多个图案的详细信息
  │   ├── getPatternDetails.ts         # 获取单个图案的详细信息
  │   ├── searchPatterns.ts           # 搜索图案
  │   └── index.ts                    # 端点导出
  ├── types/
  │   ├── patternDetailed.d.ts       # 详细图案的类型定义
  │   └── patternSimple.d.ts         # 简单图案的类型定义
  └── index.ts                      # 入口点和 MCP 服务器设置

⚙️ 开发

环境配置

服务器对开发和生产使用不同的环境文件：

• .env.development - 在开发模式下运行时使用
• .env.production - 在生产模式下运行时使用

测试

使用以下命令运行测试套件：

npm test

Linting 和格式化

# 运行 ESLint
npm run lint

# 修复 ESLint 错误
npm run lint:fix

# 使用 Prettier 格式化代码
npm run format

📝 部署注意事项

部署到生产环境时：

1. 确保您的 .env.production 文件包含有效的 Ravelry 凭据
2. 构建过程会将这些凭据嵌入到已编译的代码中
3. 使用 npm run prod 构建并启动生产服务器

📄 许可证

此项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。