HeroUI MCP服务器
](https://www.npmjs.com/package/heroui-mcp)  
一个高质量的开源模型上下文协议（MCP）服务器，为AI代理提供全面的上下文和工具，用于 Heroui 组件库。该服务器将AI系统和HeroUI连接起来，为使用HeroUI组件的开发人员提供智能帮助。
🚀 特性
- 组件发现：列出并浏览所有可用的HeroUI组件
- 文档访问：检索全面的组件文档和使用示例
- api参考：访问详细的组件道具、插槽和数据属性
- 可访问性信息：获取每个组件的无障碍指南和最佳实践
- 使用模式学习常见的实施模式和最佳实践
- TypeScript支持：完全支持TypeScript，具有全面的类型定义
- 缓存系统：高效的基于Git的缓存，可快速检索文档
- RESTful API：干净的HTTP端点，便于集成
📋 先决条件
- Node.js 18.0或更高
- pnpm （推荐）或npm
- Git （用于存储库缓存）
- 包子 （可选，建议更快开发）或 多伦多证券交易所 用于执行TypeScript
🛠️ 安装
来源
- 克隆存储库:
git clone https://github.com/T-Hash06/heroui-mcp.git
cd heroui-mcp- 安装依赖项:
pnpm install- 构建项目:
pnpm build- 启动服务器:
pnpm start服务器将于启动 http://localhost:3000 默认情况下。
🎯 快速开始
基本用法
服务器运行后，与之交互的最佳方式是通过 MCP检查员 该工具为探索和测试MCP服务器提供了一个用户友好的界面。
- 安装MCP检查器:
npx @modelcontextprotocol/inspector- 连接到您的服务器:
- 在浏览器中打开MCP检查器 - 添加您的服务器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检查器，您可以：
- 浏览可用工具 -在可视化界面中查看所有与组件相关的工具
- 交互式测试工具 -运行以下工具
list_components或get_component_docs实时结果 - 探索组件数据 -获取任何HeroUI组件的详细信息
- 查看格式化输出 -请以可读格式参阅文档和API信息
MCP检查器为探索服务器的功能提供了最佳体验，而无需编写代码或使用命令行工具。
🏗️ 发展
开发设置
- 安装依赖项:
pnpm install- 启动开发服务器 （选择一个选项）：
选项A：使用Bun（建议更快启动）
# Install Bun if you don't have it
curl -fsSL https://bun.sh/install | bash
# Start development server
pnpm dev选项B：使用tsx（如果你更喜欢Node.js）
# Install tsx globally or use npx
npm install -g tsx
# Run directly with tsx
npx tsx src/index.ts- 用于生产部署:
# Build the project
pnpm build
# Start production server
pnpm start- 运行测试:
pnpm test- 格式代码:
pnpm format- 检查代码质量:
pnpm check项目结构
src/
├── app.ts # Main application setup
├── index.ts # Entry point
├── cache/ # Git caching system
├── config/ # Configuration management
├── http/ # HTTP server and routes
├── resources/ # MCP resources
├── server/ # MCP server factory
├── tools/ # MCP tools implementation
│ └── components/ # HeroUI component tools
├── transport/ # Session management
├── types/ # TypeScript type definitions
└── utils/ # Utility functions可用脚本
| 脚本 | 描述 |
|---|---|
pnpm dev | 使用Bun启动开发服务器（快速执行TypeScript） |
pnpm build | 构建用于生产的项目（TypeScript编译） |
pnpm start | 启动生产服务器（需要先构建） |
pnpm test | 在监视模式下运行测试 |
pnpm test:run | 运行一次测试 |
pnpm test:coverage | 使用覆盖率报告运行测试 |
pnpm check | 进行所有质量检查（棉绒、类型检查、测试） |
pnpm format | 使用生物特征格式化代码 |
pnpm lint | 带有Biome的棉绒编码 |
开发vs生产
- 发展：使用
pnpm dev（Bun）或npx tsx src/index.ts用于快速执行TypeScript - 生产：使用
pnpm build然后pnpm start用于优化编译的JavaScript
🔧 配置
服务器可以通过环境变量或配置文件进行配置：
环境变量
# Server configuration
PORT=3000
HOST=localhost
# Cache configuration
CACHE_DIR=./cache
REPO_URL=https://github.com/heroui-inc/heroui.git
BRANCH=main配置文件
src/config/server.config.ts-服务器配置src/config/cache.config.ts-缓存配置
🧪 测试
该项目使用 速度 用于测试：
# Run all tests
pnpm test
# Run tests once
pnpm test:run
# Run tests with coverage
pnpm test:coverage
# Run specific test file
pnpm test src/tools/components/list-components.test.ts🤝 贡献
快速贡献指南
- 分叉存储库
- 创建要素分支:
git checkout -b feature/amazing-feature - 进行更改
- 进行质量检查:
pnpm check - 提交您的更改:
git commit -m 'Add amazing feature' - 推到分支:
git push origin feature/amazing-feature - 打开拉取请求
开发标准
- 跟随 常规承诺
- 保持TypeScript严格模式合规性
- 为新功能编写测试
- 确保所有质量检查通过(
pnpm check) - 记录新功能和API
🐞 故障排除
常见问题
服务器无法启动
- 检查端口是否已在使用中
- 验证Node.js版本（需要18.0+）
- 确保安装了所有依赖项
缓存初始化失败
- 检查Git存储库访问的互联网连接
- 验证Git是否已安装且可访问
- 检查存储库URL和分支配置
工具执行错误
- 确保HeroUI存储库缓存已初始化
- 检查组件名称拼写和区分大小写
- 验证文档中是否存在所请求的组件
调试模式
启用调试日志记录：
NODE_ENV=development pnpm dev📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
🔗 链接
______________________________________________________________________
Made with ❤️ for the HeroUI community
HeroUI • MCP • GitHub