HeroUI MCP Server

一个高质量、开源的模型上下文协议（MCP）服务器，为使用 HeroUI 组件库的AI代理提供全面的上下文和工具。该服务器连接了AI系统与HeroUI，为使用HeroUI组件的开发者提供了智能辅助。

🚀 功能

• 组件发现: 列出并探索所有可用的HeroUI组件
• 文档访问: 获取全面的组件文档和使用示例
• API 参考: 访问详细的组件属性、插槽和数据属性
• 无障碍信息: 获取每个组件的无障碍指南和最佳实践
• 使用模式: 学习常见的实现模式和最佳实践
• TypeScript 支持: 完整的TypeScript支持，包括全面的类型定义
• 缓存系统: 基于Git的高效缓存系统，用于快速文档检索
• RESTful API: 清晰的HTTP端点，便于集成

📋 先决条件

• Node.js 18.0或更高版本
• pnpm（推荐）或npm
• Git（用于仓库缓存）
• Bun（可选，推荐用于更快的开发）或tsx用于TypeScript执行

🛠️ 安装

从源代码安装

1. 克隆仓库：

   git clone https://github.com/T-Hash06/heroui-mcp.git
   cd heroui-mcp
   

2. 安装依赖：

   pnpm install
   

3. 构建项目：

   pnpm build
   

4. 启动服务器：

   pnpm start
   

默认情况下，服务器将在http://localhost:3000上运行。

🎯 快速开始

基本用法

一旦服务器运行起来，通过MCP Inspector工具与之交互是最好的方式，它提供了一个用户友好的界面来探索和测试MCP服务器。

1. 安装MCP Inspector：

   npx @modelcontextprotocol/inspector
   

2. 连接到你的服务器：

   • 在浏览器中打开MCP Inspector
   • 添加你的服务器URL：http://localhost:3000
   • 以交互的方式探索可用的工具和资源

可用工具

服务器提供的MCP工具如下：

工具	描述
list_components	列出所有可用的HeroUI组件
get_component_docs	获取组件的全面文档
get_component_api	获取API参考（属性、方法、事件）
get_component_slots	获取组件的插槽信息
get_component_data_attributes	获取组件的数据属性
get_component_accessibility	获取组件的无障碍信息和指南
get_component_usage	获取组件的使用示例和模式

示例：探索组件

使用MCP Inspector，你可以：

1. 浏览可用工具 - 在视觉界面上查看所有与组件相关的工具
2. 交互式测试工具 - 运行如list_components或get_component_docs等工具，并实时查看结果
3. 探索组件数据 - 获取任何HeroUI组件的详细信息
4. 查看格式化输出 - 以可读格式查看文档和API信息

MCP Inspector提供了最好的体验，无需编写代码或使用命令行工具即可探索服务器的功能。

🏗️ 开发

开发设置

1. 安装依赖：

   pnpm install
   

2. 启动开发服务器（选择一个选项）：

   选项A：使用Bun（推荐用于更快的启动）

   # 如果没有Bun，请先安装
   curl -fsSL https://bun.sh/install | bash
   
   # 启动开发服务器
   pnpm dev
   

   选项B：使用tsx（如果你更喜欢Node.js）

   # 全局安装tsx或使用npx
   npm install -g tsx
   
   # 直接使用tsx运行
   npx tsx src/index.ts
   

3. 生产部署：

   # 构建项目
   pnpm build
   
   # 启动生产服务器
   pnpm start
   

4. 运行测试：

   pnpm test
   

5. 格式化代码：

   pnpm format
   

6. 检查代码质量：

   pnpm check
   

项目结构

src/
├── app.ts                # 主应用程序设置
├── index.ts              # 入口点
├── cache/                # Git缓存系统
├── config/               # 配置管理
├── http/                 # HTTP服务器和路由
├── resources/            # MCP资源
├── server/               # MCP服务器工厂
├── tools/                # MCP工具实现
│   └── components/       # HeroUI组件工具
├── transport/            # 会话管理
├── types/                # TypeScript类型定义
└── utils/                # 实用函数

可用脚本

脚本	描述
pnpm dev	使用Bun启动开发服务器（快速TypeScript执行）
pnpm build	为生产构建项目（TypeScript编译）
pnpm start	启动生产服务器（需要先构建）
pnpm test	监视模式下运行测试
pnpm test:run	一次性运行测试
pnpm test:coverage	带覆盖率报告运行测试
pnpm check	运行所有质量检查（lint、类型检查、测试）
pnpm format	使用Biome格式化代码
pnpm lint	使用Bi的Biome进行代码检查

开发与生产

• 开发: 使用pnpm dev（Bun）或npx tsx src/index.ts进行快速TypeScript执行
• 生产: 使用pnpm build然后pnpm start进行优化后的编译JavaScript

🔧 配置

服务器可以通过环境变量或配置文件进行配置：

环境变量

# 服务器配置
PORT=3000
HOST=localhost

# 缓存配置
CACHE_DIR=./cache
REPO_URL=https://github.com/heroui-inc/heroui.git
BRANCH=main

配置文件

• src/config/server.config.ts - 服务器配置
• src/config/cache.config.ts - 缓存配置

🧪 测试

该项目使用Vitest进行测试：

# 运行所有测试
pnpm test

# 一次性运行测试
pnpm test:run

# 带覆盖率运行测试
pnpm test:coverage

# 运行特定的测试文件
pnpm test src/tools/components/list-components.test.ts

🤝 贡献

快速贡献指南

1. 分叉仓库
2. 创建功能分支: git checkout -b feature/amazing-feature
3. 进行更改
4. 运行质量检查: pnpm check
5. 提交更改: git commit -m '添加神奇功能'
6. 推送到分支: git push origin feature/amazing-feature
7. 打开拉取请求

开发标准

• 遵循常规提交
• 维护TypeScript严格模式合规性
• 为新功能编写测试
• 确保所有质量检查通过（pnpm check）
• 文档新的特性和API

🐞 故障排除

常见问题

服务器无法启动

• 检查端口是否已被占用
• 验证Node.js版本（需要18.0+）
• 确保所有依赖项已安装

缓存初始化失败

• 检查互联网连接以访问Git仓库
• 验证Git已安装且可访问
• 检查仓库URL和分支配置

工具执行错误

• 确保HeroUI仓库缓存已初始化
• 检查组件名称的拼写和大小写敏感性
• 验证请求的组件在文档中存在

调试模式

启用调试日志：

NODE_ENV=development pnpm dev

📄 许可证

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

🙏 致谢

• HeroUI - 此服务器支持的出色组件库
• 模型上下文协议 - 协议规范

🔗 链接

• HeroUI 文档
• 模型上下文协议
• 项目问题
• 项目讨论

---

<div align="center"> <p>为HeroUI社区制作 ❤️</p> <p> <a href="https://heroui.com/">HeroUI</a> • <a href="https://modelcontextprotocol.io/">MCP</a> • <a href="https://github.com/T-Hash06/heroui-mcp">GitHub</a> </p> </div>