使用说明

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许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

Heroui -此服务器支持的惊人组件库
模型上下文协议 -协议规范

🔗 链接

Made with ❤️ for the HeroUI community

HeroUI • MCP • GitHub