Ravelry

🚀 Ravelry MCP 服务器

本服务器基于模型上下文协议（MCP）构建，为 AI 助手提供了与 Ravelry API 交互的工具。借助该服务器，AI 助手能够便捷地搜索、探索并获取编织图案，为编织爱好者和相关开发者带来了极大的便利。

🚀 快速开始

该服务器使用 TypeScript 和 Node.js 构建，允许 AI 助手通过 Model Context Protocol (MCP) 与 Ravelry API 交互。其主要功能包括搜索编织图案、获取详细信息并支持多模式查询。

安装步骤

1. 克隆仓库：

   git clone https://github.com/your-repository.git
   cd your-repository
   

2. 安装依赖项：

   npm install
   

3. 配置环境变量。

使用方法

开发模式

npm run dev

生产模式

npm start

✨ 主要特性

• 搜索图案：根据关键字搜索编织图案。
• 获取详细信息：检索特定图案的详细信息。
• 批量查询：一次获取多个图案的详细信息。
• 过滤功能：支持按工艺类型（如编织或钩针）和价格筛选。

📦 安装指南

先决条件

1. 安装 Node.js 和 npm（推荐使用版本 14 或更高）。
2. 安装 TypeScript 和其他项目依赖项。
3. 配置 Ravelry API 凭证。

安装步骤

1. 克隆仓库：

   git clone https://github.com/your-repository.git
   cd your-repository
   

2. 安装依赖项：

   npm install
   

3. 配置环境变量。

💻 使用示例

开发模式

npm run dev

生产模式

npm start

📚 详细文档

集成指南

将服务器作为 MCP 工具集成到 AI 系统中，通过以下接口调用功能：

• search-patterns：搜索图案。
• get-pattern-details：获取特定图案的详细信息。
• get-multiple-pattern-details：批量获取多个图案的详细信息。

可用工具

search-patterns

根据关键字搜索编织图案。

参数：

• query：搜索关键字（必填）
• page：页码（默认：1）
• craft：工艺类型（如“knitting”或“crochet”）
• availability：价格筛选（默认：免费，选项包括“free”，“ravelry”，“online”）

get-pattern-details

获取特定图案的详细信息。

参数：

• id：图案 ID（必填）

get-multiple-pattern-details

批量获取多个图案的详细信息。

参数：

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

🔧 技术细节

工作原理

1. 使用 Basic Auth 鉴权访问 Ravelry API。
2. 调用 Ravelry API 的相关端点。
3. 解析并返回结构化数据。
4. 通过 MCP 接口暴露工具供 AI 助手调用。

项目结构

src/
  ├── class/
  │   └── ravelry.class.ts       # 主要 Ravelry 客户端实现
  ├── 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

格式化与代码检查

# 运行 ESLint
npm run lint

# 修复 ESLint 错误
npm run lint:fix

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

部署注意事项

1. 确保 .env.production 文件包含有效的 Ravelry 凭证。
2. 构建时会将凭据嵌入到编译后的代码中。
3. 使用 npm run prod 进行部署。

📄 许可证

项目使用 MIT 许可证，具体内容见 LICENSE 文件。