TUI5 文档库 MCP 服务器 (Node.js版本)

📖 项目简介

这是 TUI5 文档库 MCP 服务器的 Node.js/TypeScript 版本，基于 Model Context Protocol (MCP) 构建。专门用于管理和查询 TUI5 项目的文档，支持组件、Hook、示例和设计文档的智能检索和管理。

✨ 功能特性

• 🚀 智能文档扫描: 自动递归扫描 src 目录下的所有 Markdown 文档
• 📂 多类型文档支持: 支持组件(component)、Hook、示例(example)、设计(design)四种文档类型
• 🎯 智能分类: 根据文件路径自动识别文档类型和分类
• 🔍 强大搜索功能: 支持按名称、标题、内容进行全文检索
• 📱 Demo 源码管理: 自动解析和加载 <Demo> 标签对应的源码文件
• 📊 统计分析: 提供详细的文档库统计信息
• 🔧 实时重建: 支持重新扫描目录，实时更新文档索引
• ⚡ 高性能: TypeScript 编写，性能优异
• 📦 易于安装: 支持 npx 直接运行

🛠️ 安装和使用

环境要求

• Node.js >= 18.0.0
• npm 或 yarn

使用 npx 运行（推荐）

# 直接使用内置的TUI5组件库文档（无需指定目录）
npx tui5-docs-mcp

# 或者指定自定义 src 目录路径
npx tui5-docs-mcp <src_directory>

# 示例：扫描自定义目录
npx tui5-docs-mcp ./my-project/src

本地安装

# 克隆或下载项目
git clone <repository-url>
cd mcp

# 安装依赖
npm install

# 构建项目
npm run build:publish

# 运行服务器
node dist/index.js <src_directory>

🔧 配置 MCP 客户端

推荐配置（使用固定版本）

在您的 MCP 客户端配置文件中添加：

{
  "mcpServers": {
    "tui": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]"
      ]
    }
  }
}

使用最新版本（可能有缓存问题）

{
  "mcpServers": {
    "tui": {
      "command": "npx",
      "args": [
        "-y",
        "tui5-docs-mcp@latest"
      ]
    }
  }
}

⚠️ 注意: 使用 @latest 时可能遇到npx缓存问题，建议添加 -y 参数强制重新下载最新版本。

自定义目录配置

如果需要使用自定义目录：

{
  "mcpServers": {
    "tui-custom": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "/path/to/your/src"
      ]
    }
  }
}

本地开发配置

使用本地安装的版本：

{
  "mcpServers": {
    "tui-local": {
      "command": "node",
      "args": [
        "D:/reactwork/TUI5/mcp/dist/index.js",
        "D:/reactwork/TUI5/src"
      ]
    }
  }
}

📚 API 接口

文档查询接口

get_components(limit?: number = 50)

获取所有组件文档列表

get_hooks(limit?: number = 50)

获取所有 Hook 文档列表

get_design_docs(limit?: number = 50)

获取所有设计文档列表

文档详情接口

get_document_with_demos(name: string, doc_type?: string)

获取文档详情，包含完整的 Demo 源码

搜索接口

search_documents(query: string, doc_type?: string, limit?: number = 20)

全文搜索文档

• query: 搜索关键词
• doc_type: 可选，限制搜索的文档类型
• limit: 返回结果的最大数量

管理接口

get_document_statistics()

获取文档库统计信息

list_all_documents()

列出所有文档（简要信息）

rebuild()

重新扫描src目录，重建文档索引

📁 支持的目录结构

src/
├── components/
│   └── Button/
│       ├── README.md          # 组件文档
│       └── demos/
│           ├── basic.tsx      # Demo 源码
│           └── advanced.tsx
├── hooks/
│   ├── useThemeHook.md        # Hook 文档
│   └── usePaginationHooks.md
├── examples/
│   └── TodoApp/
│       ├── README.md          # 示例文档
│       └── demos/
│           └── demo.tsx
└── design/
    └── design-system.md       # 设计文档

📝 文档格式规范

Markdown 前置元数据

---
title: "组件标题"
subGroup: "分组名称"
---

Demo 标签使用

在 Markdown 文档中使用 <Demo> 标签引用示例：

<Demo src="./demos/basic.tsx" />
<Demo src="./demos/advanced.tsx" />

Demo 文件 JSDoc 注释

Demo 文件支持 JSDoc 注释来定义元信息：

/**
 * @title 基础示例
 * @description 展示组件的基本用法
 * @order 1
 */
export default function BasicDemo() {
  return <div>Hello World</div>;
}

🔧 开发说明

项目结构

mcp/
├── src/
│   ├── index.ts             # 主程序文件
│   ├── documentManager.ts   # 文档管理器
│   ├── formatters.ts        # 输出格式化
│   └── types.ts            # 类型定义
├── scripts/                # 发布脚本
│   ├── copy-docs.cjs       # 文档拷贝
│   └── release.cjs         # 发布流程
├── dist/                   # 编译输出
├── package.json            # 项目配置
├── tsconfig.json          # TypeScript 配置
└── README.md              # 本文档

核心类说明

DocumentManager

文档管理器，负责：

• 扫描和加载 Markdown 文档
• 解析前置元数据和内容
• 管理文档分类和索引
• 提供查询和搜索功能

DocumentFile 接口

文档文件数据结构，包含：

• 文档元数据和内容
• 文档类型和分类信息
• 关联的 Demo 文件列表

DemoFile 接口

Demo 文件数据结构，包含：

• Demo 源码和路径
• 标题、描述和排序信息

可用脚本

# 构建发布版本
npm run build:publish

# 拷贝文档文件
npm run copy-docs

# 发布版本（patch）
npm run release

# 发布小版本
npm run release:minor

# 发布大版本
npm run release:major

调试信息

程序运行时会在 stderr 输出调试信息：

• 文档加载进度
• 各类型文档统计
• Demo 文件加载状态
• 错误和警告信息

🚀 发布流程

项目使用自动化发布流程：

1. 版本更新: 自动更新版本号
2. 文档构建: 拷贝并构建最新文档
3. npm发布: 发布到npm仓库
4. 清理: 清理临时文件

# 发布补丁版本 (1.1.3 -> 1.1.4)
npm run release

# 发布小版本 (1.1.3 -> 1.2.0)
npm run release:minor

# 发布大版本 (1.1.3 -> 2.0.0)
npm run release:major

🐛 常见问题

1. npx @latest 版本问题

问题: 使用 tui5-docs-mcp@latest 时可能获取不到最新版本

解决方案:

• 添加 -y 参数: npx -y tui5-docs-mcp@latest
• 或使用固定版本号: npx [email protected]
• 清理npx缓存: npx clear-npx-cache

2. 文档加载失败

问题: 文档扫描或加载出现错误

解决方案:

• 检查src目录路径是否正确
• 确保Markdown文件格式正确
• 使用 rebuild() 接口重新构建索引

3. Demo文件无法加载

问题: <Demo> 标签对应的源码文件无法找到

解决方案:

• 检查Demo文件路径是否正确
• 确保Demo文件存在且可读
• 验证文件扩展名(.tsx, .jsx, .ts, .js)

🆚 与 Python 版本的区别

• ✅ 更好的性能: Node.js 原生性能
• ✅ 更简单的部署: 支持 npx 直接运行
• ✅ TypeScript 支持: 更好的类型安全
• ✅ 现代化依赖: 使用最新的 MCP SDK
• ✅ ES Modules: 使用现代 JavaScript 模块系统
• ✅ 自动化发布: 完整的CI/CD流程

🤝 贡献指南

1. Fork 本项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• Model Context Protocol TypeScript SDK
• TUI5 项目文档
• Python 版本
• npm 包页面

💡 提示: 如果您在使用过程中遇到问题，请检查控制台输出的调试信息，或使用 rebuild() 接口重新构建文档索引。建议使用固定版本号而非@latest以避免缓存问题。