rive-docs-mcp CLAUDE.md

Rive Docs MCP - Claude AI 项目指南

项目概述

Rive Docs MCP 是一个基于 Model Context Protocol (MCP) 的服务器，专门为 Rive 动画平台提供文档访问功能。它允许 Claude、Cursor 等 AI 助手直接访问和搜索 Rive 的完整文档，包括运行时集成指南、编辑器功能、教程和 API 参考。

主要目的

• 为 AI 助手提供 Rive 文档的智能访问
• 支持跨平台运行时（Web、React、Flutter、iOS、Android、Unity、Unreal 等）
• 简化 Rive 开发工作流程
• 提供实时的文档搜索和内容提取

核心功能

🔍 智能搜索工具

• search_rive_docs: 跨所有 Rive 文档进行智能搜索
• get_rive_doc_content: 获取特定文档页面的详细内容
• check_feature_support: 检查功能在不同运行时的兼容性

🏃 运行时支持工具

• list_runtimes: 列出所有可用的运行时平台
• get_runtime_guide: 获取特定运行时的实现指南
• get_api_reference: 访问运行时特定的 API 文档

🎨 编辑器功能工具

• list_editor_features: 浏览 Rive 编辑器的功能和能力
• get_tutorials: 按主题、难度或运行时查找教程

支持的平台

• Web 运行时: JavaScript、React、React Native
• 移动运行时: Flutter、iOS、Android
• 游戏运行时: Unity、Unreal Engine、Defold
• 社区运行时: C#、Qt

技术架构

主要组件

1. 内容提取器 (content-extractor.ts)

   • 处理 JavaScript 渲染的 Rive 文档
   • 使用 JSDOM 解析动态内容
   • 提取标题、内容、代码块、链接和图片

2. 搜索引擎 (search.ts)

   • 智能搜索与相关性评分
   • 支持分类和运行时过滤
   • 缓存搜索结果以提高性能

3. 导航爬虫 (navigation-crawler.ts)

   • 发现和索引所有文档页面
   • 构建运行时列表和教程目录
   • 生成内容标签

4. HTTP 客户端 (http-client.ts)

   • 带有重试逻辑的健壮请求处理
   • 速率限制和并发控制
   • 性能监控和统计

5. 缓存系统 (cache.ts)

   • TTL（生存时间）缓存
   • 不同内容类型的智能缓存策略
   • 自动清理过期项目

6. 错误处理 (error-handler.ts)

   • 全面的错误分类和处理
   • 用户友好的错误消息和建议
   • 工具特定的故障排除提示

数据流

用户查询 → MCP 工具调用 → 内容提取/搜索 → 缓存检查 → HTTP 请求 → 内容解析 → 格式化响应

使用示例

搜索 React 集成信息

search_rive_docs({
  query: "React component setup",
  category: "runtimes",
  runtime: "react"
})

获取 Flutter 入门指南

get_runtime_guide({
  runtime: "flutter",
  section: "getting-started"
})

查找状态机教程

get_tutorials({
  topic: "state machine",
  difficulty: "beginner"
})

检查 Unity 功能支持

check_feature_support({
  feature: "timeline events",
  runtime: "unity"
})

开发指南

项目结构

src/
├── index.ts              # 主 MCP 服务器
├── tools/                # 工具实现
│   ├── definitions.ts    # 工具定义
│   ├── handlers.ts       # 工具处理器
│   ├── search.ts         # 搜索功能
│   └── doc-fetcher.ts    # 文档获取
├── utils/                # 工具类
│   ├── constants.ts      # 配置常量
│   ├── http-client.ts    # HTTP 客户端
│   ├── cache.ts          # 缓存系统
│   ├── logger.ts         # 日志工具
│   ├── error-handler.ts  # 错误处理
│   ├── content-extractor.ts  # 内容提取
│   └── navigation-crawler.ts # 导航发现
└── types/                # TypeScript 类型
    └── index.ts          # 类型定义