🚀 Ravelry MCP 服务器

该服务器基于模型上下文协议 (MCP) 构建，为 AI 助手提供了与 Ravelry API 交互的工具，能让其搜索、探索并获取编织图案，极大地提升了编织图案数据的获取效率。

🚀 快速开始

此服务器采用 TypeScript 和 Node.js 构建，支持 AI 助手借助 Model Context Protocol (MCP) 与 Ravelry API 进行交互。其核心功能有搜索编织图案、获取详细信息，并且支持多模式查询。

开发模式

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. 配置环境变量。

💻 使用示例

基础用法

将服务器作为 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 数组（必填）

📚 详细文档

集成指南

将服务器作为 MCP 工具集成到 AI 系统中，通过上述接口调用相应功能。

工作原理

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 进行部署。

🔧 技术细节

该服务器使用 TypeScript 和 Node.js 构建，通过 Model Context Protocol (MCP) 与 Ravelry API 进行交互。在实现过程中，利用 Basic Auth 鉴权访问 Ravelry API 的相关端点，解析返回的数据并以结构化形式呈现。同时，通过 MCP 接口将工具暴露给 AI 助手，实现搜索、获取详细信息等功能。

📄 许可证

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