gpaul-mcp
服务介绍
Ravelry MCP 服务器
一个提供与 Ravelry API 交互工具的模型上下文协议（MCP）服务器，允许 AI 助手搜索、探索和检索编织和钩针图案。
🌟 概览
此 MCP 服务器封装了 Ravelry API，创建了一个可靠的接口，可供 AI 助手使用。它提供了以下工具：
- 搜索编织和钩针图案
- 获取详细的图案信息
- 一次性检索多个图案的详细信息
这个项目是受我女朋友启发而创建的，她对编织和钩针的热情促使我架起了 AI 助手与 Ravelry 手工艺社区之间的桥梁。由于她不太懂技术，并且对 AI 有些怀疑，这成为了我连接她的兴趣并展示技术如何增强而不是取代她的手工艺体验的一种方式。
🚀 特性
- 🔍 图案搜索：使用关键词和过滤器搜索 Ravelry 的图案数据库
- 📋 图案详情：获取特定图案的全面信息
- 🧶 手工艺过滤：按手工艺类型（编织或钩针）过滤图案
- 💰 价格选项：按可用性（免费、付费等）过滤图案
- 🤖 AI 助手集成：通过模型上下文协议设计为与 AI 助手配合工作
📋 前提条件
- Node.js (v14 或更高版本)
- npm 或 yarn
- Ravelry API 凭证（用户名和密码）
🔧 安装
-
克隆仓库
bash
git clone
cd ravelry-mcp -
安装依赖
bash
npm install -
设置环境变量
bash创建开发环境文件
cp .env.example .env.development
创建生产环境文件
cp .env.example .env.production
-
配置 API 凭证
-
获取您的 Ravelry 用户名和密码
-
将您的凭证添加到
.env.development和.env.production文件中：AUTH_USER=your_ravelry_username
AUTH_PASS=your_ravelry_password
-
🎮 使用
开发模式
bash
npm run dev
这将以带有热重载的开发模式启动 MCP 服务器。
生产模式
bash
npm run build
npm start
或者使用简写：
bash
npm run prod
🔗 与 Claude Desktop 集成
要将此 MCP 服务器添加到 Claude Desktop 并启用 Ravelry 浏览功能：
-
启动 MCP 服务器
确保您的服务器在本地运行或在 Claude Desktop 可以访问的远程主机上运行。 -
打开 Claude Desktop 设置
- 启动 Claude Desktop
- 单击右上角的个人资料图片或图标
- 从下拉菜单中选择“设置”
-
导航到扩展设置
- 在设置侧边栏中，单击“扩展”
- 选择“添加自定义 MCP”
4.1 配置 MCP 连接
- 名称：
Ravelry MCP（或您喜欢的任何名称） - URL：输入您的 MCP 服务器正在运行的 URL（例如，对于本地开发为
http://localhost:3000） - 单击“添加 MCP”
4.2 替代方法：通过命令配置 MCP 连接
- 您首先需要构建项目并提供编译后服务器的完整路径
- 将以下内容添加到您的 Claude Desktop 配置中：
json
"ravelry": {
"command": "node",
"args": [
"YOUR_CUSTOM_PATH/dist/index.js"
]
}
-
启用 MCP
- 切换您新添加的 Ravelry MCP 旁边的开关以启用它
- Claude Desktop 将尝试连接到您的 MCP 服务器
-
验证连接
- 与 Claude 开始新的对话
- 输入“Can you help me find some knitting patterns on Ravelry?”- Claude 现在应该能够使用 Ravelry 工具来搜索和浏览图案
-
故障排除
- 如果 Claude 无法连接到您的 MCP 服务器，请检查：
- 服务器正在运行，并且可以从 Claude Desktop 访问
- 在 Claude Desktop 设置中配置了正确的 URL
- 您的 API 凭证有效并在服务器上正确配置
- 如果 Claude 无法连接到您的 MCP 服务器，请检查：
使用 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 发出经过身份验证的请求：
- 使用 Basic Auth 和您的 Ravelry 凭证进行请求认证
- 向各种 Ravelry API 端点发出请求
- 解析并以结构化格式返回数据
- 将端点作为 MCP 工具暴露出来，供 AI 助手调用
🛠️ 项目结构
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- 在生产模式下运行时使用
测试
运行测试套件：
bash
npm test
代码检查和格式化
bash
运行 ESLint
npm run lint
修复 ESLint 错误
npm run lint:fix
使用 Prettier 格式化代码
npm run format
📝 部署注意事项
在部署到生产环境时：
- 确保您的
.env.production文件包含有效的 Ravelry 凭证 - 构建过程会将这些凭证嵌入编译后的代码中
- 使用
npm run prod来构建并启动生产服务器
📄 许可证
该项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。
