@yeepay/awesome-components-mcp/README_zh-CN.md

MCP server providing access to awesome-components documentation and integration guides with dual-mode operation: direct fetch and GitLab MCP instruction generation

# Awesome Components MCP Server

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](http://gitlab.yeepay.com/awesome/awesome-components-mcp)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/typescript-5.8.3-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.12.1-orange.svg)](https://modelcontextprotocol.io/)

[English](README.md) | [中文](README_zh-CN.md)

---

## 🚀 Overview

The Awesome Components MCP Server bridges the gap between AI assistants and component documentation, enabling intelligent discovery and retrieval of technical integration guides. It serves as a centralized hub for accessing distributed component documentation across GitLab repositories.

**Core Capabilities:**
- **`components_discovery`**: Intelligently discovers and categorizes all available components from the main llms.txt file
- **`get_components_guide`**: Retrieves comprehensive integration guides for specific components with smart path resolution

## ✨ Key Features

- 🔍 **Intelligent Discovery**: Advanced parsing and categorization of components from GitLab repositories
- 📖 **Smart Guide Retrieval**: Fetch detailed integration guides with support for both relative and absolute paths
- 🛡️ **Enterprise Security**: Built-in path validation and sanitization to prevent directory traversal attacks
- 🎯 **结构化输出**: 返回 JSON 格式的结构化数据，便于程序化处理
- ⚡ **Robust Error Handling**: Comprehensive error handling with detailed, user-friendly messages
- 🔧 **Highly Configurable**: Environment-based configuration supporting multiple GitLab instances
- 🧪 **Test Coverage**: Comprehensive test suite with unit and integration tests
- 📊 **Type Safety**: Full TypeScript implementation with strict type checking

## 📋 Prerequisites

- **Node.js**: LTS version 20.0.0 or higher
- **npm**: Version 8.0.0 or higher (comes with Node.js)
- **GitLab Access**: Valid access to the GitLab repository containing component documentation
- **Operating System**: Linux, macOS, or Windows

## 🛠️ Installation

### Quick Start

1. **Clone the repository:**

   ```bash
git clone https://gitlab.yeepay.com/awesome/awesome-components-mcp.git
   cd awesome-components-mcp
```

2. **Install dependencies:**

   ```bash
npm install
```

3. **Build the project:**

   ```bash
npm run build
```

4. **Start the server:**

   ```bash
npm start
```

### Development Installation

For development with hot-reload:

```bash
npm run dev
```

## ⚙️ Configuration

The server supports flexible configuration through environment variables, allowing deployment across different GitLab instances and environments.

### Environment Variables

服务器根据配置支持两种操作模式：

#### 核心配置变量

| 变量 | 描述 | 默认值 | 必需 |
|------|------|--------|------|
| `PORT` | MCP 服务器端口 | `3000` | 否 |
| `GITLAB_PERSONAL_ACCESS_TOKEN` | GitLab 个人访问令牌用于身份验证 | 无 | 否* |

#### 模式 1：直接获取模式（向后兼容）

| 变量 | 描述 | 默认值 | 必需 |
|------|------|--------|------|
| `GITLAB_BASE_URL` | GitLab 原始文件访问的基础 URL | `http://gitlab.yeepay.com/awesome/awesome-components/-/raw/main/` | 否 |
| `MAIN_LLMS_URL` | 主 llms.txt 文件的 URL | `http://gitlab.yeepay.com/awesome/awesome-components/-/raw/main/llms.txt` | 否 |
| `LLMS_TXT_URL` | llms.txt 文件的直接 URL（覆盖 MAIN_LLMS_URL） | 无 | 否 |

#### 模式 2：GitLab MCP 指令模式

| 变量 | 描述 | 默认值 | 必需 |
|------|------|--------|------|
| `GITLAB_PROJECT_ID` | 组件列表的 URL 编码 GitLab 项目 ID | 无 | 是* |
| `LLMS_TXT_FILE` | 项目中 llms.txt 文件的路径 | `llms.txt` | 否 |
| `INTERNAL_GITLAB_HOST` | 用于 URL 检测的内部 GitLab 主机名 | 无 | 否 |

**注意:**
- `*` 在使用相应模式时必需
- `GITLAB_PERSONAL_ACCESS_TOKEN` 对于访问私有仓库是必需的，但对于公共仓库是可选的
- 当配置了 `LLMS_TXT_URL` 时使用模式 1
- 当同时配置了 `GITLAB_PROJECT_ID` 和 `LLMS_TXT_FILE` 时使用模式 2
- 如果两种模式都没有正确配置，服务器将回退到默认 URL

### Configuration Methods

**Method 1: Environment File (.env)**

Create a `.env` file in the project root:

```bash
# GitLab 配置
GITLAB_BASE_URL=https://your-gitlab.com/group/project/-/raw/main/
MAIN_LLMS_URL=https://your-gitlab.com/group/project/-/raw/main/llms.txt

# GitLab 身份验证（私有仓库必需）
GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token_here

# 服务器配置
PORT=3000
DEBUG=true
```

**Method 2: Direct Environment Variables**

```bash
GITLAB_BASE_URL=https://your-gitlab.com/group/project/-/raw/main/ npm start
```

**Method 3: Docker Environment**

```bash
docker run -e GITLAB_BASE_URL=https://your-gitlab.com/group/project/-/raw/main/ awesome-components-mcp
```

## 🚀 Usage

### MCP Client Configuration

To use this MCP server with an MCP client (such as Claude Desktop, Continue, or other MCP-compatible applications), you have two options:

#### Option 1: Using Published Package (Recommended)

```json
{
  "mcpServers": {
    "yeepay-awesome-components-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@yeepay/awesome-components-mcp"
      ]
    }
  }
}
```

#### Option 2: Using Local Development Build

For development or if the package is not yet published:

```json
{
  "mcpServers": {
    "awesome-components-mcp": {
      "command": "node",
      "args": [
        "/path/to/awesome-components-mcp/dist/server.js"
      ],
      "cwd": "/path/to/awesome-components-mcp"
    }
  }
}
```

**Note:** Replace `/path/to/awesome-components-mcp` with the actual path to your project directory.

**For Claude Desktop:**

1. Open Claude Desktop settings
2. Navigate to the "Developer" or "MCP Servers" section
3. Add the above configuration to your `claude_desktop_config.json` file

**For Continue IDE Extension:**

1. Open your Continue configuration file (`.continue/config.json`)
2. Add the MCP server configuration under the `mcpServers` section

**For Cursor IDE:**

1. Open Cursor settings (Cmd/Ctrl + ,)
2. Navigate to "Extensions" → "Continue"
3. Edit the Continue configuration file
4. Add the MCP server configuration under the `mcpServers` section

**For Augment:**

1. Open Augment settings
2. Navigate to the "MCP Servers" or "Integrations" section
3. Add a new MCP server with the configuration above

**For Trae:**

1. Access Trae configuration settings
2. Go to "MCP Configuration" or "Server Management"
3. Add the MCP server configuration:
   - Server Name: `awesome-components-mcp`
   - Command: `npx`
   - Arguments: `["-y", "@yeepay/awesome-components-mcp"]`

**For Custom MCP Clients:**

Refer to your specific MCP client documentation for configuration instructions. The server will be available via the npx command shown above.

### Development Mode

For development with auto-reload and enhanced debugging:

```bash
npm run dev
```

### Production Mode

Build and start the server for production deployment:

```bash
npm run build
npm start
```

### Testing

**Run all tests:**

```bash
npm test
```

**Run tests in watch mode:**

```bash
npm run test:watch
```

**Run tests with coverage report:**

```bash
npm run test:coverage
```

## 🔧 MCP Tools Reference

The server provides two powerful MCP tools for component discovery and documentation retrieval:

### 1. `components_discovery`

**目的:** 从主 llms.txt 文件中智能发现和分类所有可用组件。使用此工具可以获取所有组件、其类型和路径的概览。返回结构化的 JSON 数据，包含组件元数据和分类。此工具非常适合在检索特定组件指南之前探索可用的组件。

**参数:**

此工具不需要参数。

**输出格式:**
- 返回结构化的 JSON 数据，包含组件元数据和分类
- 包括源信息、组件总数、按类型分类以及详细的组件列表

**使用示例:**

```json
{
  "method": "tools/call",
  "params": {
    "name": "components_discovery",
    "arguments": {}
  }
}
```

**示例响应（JSON 格式）:**

```json
{
  "source": "https://gitlab.example.com/repo/-/raw/main/llms.txt",
  "totalComponents": 25,
  "componentsByType": {
    "component": 15,
    "guide": 8,
    "documentation": 2
  },
  "components": [
    {
      "name": "dynamicpassword",
      "type": "component",
      "path": "yeepay/dynamicpassword"
    },
    {
      "name": "authentication",
      "type": "component",
      "path": "yeepay/authentication"
    },
    {
      "name": "getting-started",
      "type": "guide",
      "path": "guide/getting-started"
    }
  ]
}
```

### 2. `get_components_guide`

**目的:** 检索特定组件的详细集成指南。当您需要特定组件的完整文档、设置说明或实现细节时，请使用此工具。提供组件路径（例如 'yeepay/dynamicpassword/llms.txt'）以获取其综合指南。支持来自仓库的相对路径和外部组件的绝对 URL。

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `path` | `string` | Yes | Path to the component's llms.txt file (relative or absolute URL) |

**Path Resolution:**
- **Relative paths**: Automatically resolved against the configured GitLab base URL
- **Absolute URLs**: Used directly for external repositories
- **Security**: Built-in validation prevents directory traversal attacks

**Example Usage:**

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_components_guide",
    "arguments": {
      "path": "yeepay/dynamicpassword/llms.txt"
    }
  }
}
```

**Advanced Usage with Absolute URL:**

```json
{
  "method": "tools/call",
  "params": {
    "name": "get_components_guide",
    "arguments": {
      "path": "https://external-gitlab.com/project/-/raw/main/component/llms.txt"
    }
  }
}
```

## 📁 Project Architecture

The project follows a clean, modular architecture designed for maintainability and scalability:

```text
awesome-components-mcp/
├── 📁 src/                           # Source code
│   ├── 📄 config.ts                  # Configuration management & environment variables
│   ├── 📄 server.ts                  # Main MCP server entry point
│   ├── 📁 services/                  # Business logic services
│   │   └── 📄 gitlabClient.ts        # GitLab API client with error handling
│   ├── 📁 tools/                     # MCP tool implementations
│   │   ├── 📄 componentsDiscovery.ts # Component discovery & parsing logic
│   │   └── 📄 getComponentsGuide.ts  # Component guide retrieval logic
│   └── 📁 __tests__/                 # Comprehensive test suite
│       ├── 📄 setup.ts               # Test configuration & setup
│       ├── 📄 config.test.ts         # Configuration tests
│       ├── 📄 gitlabClient.test.ts   # GitLab client tests
│       ├── 📄 componentsDiscovery.test.ts # Discovery tool tests
│       ├── 📄 getComponentsGuide.test.ts  # Guide tool tests
│       └── 📁 integration/           # Integration test suites
├── 📁 dist/                          # Compiled JavaScript output
├── 📄 package.json                   # Project dependencies & scripts
├── 📄 tsconfig.json                  # TypeScript configuration
├── 📄 jest.config.js                 # Jest testing configuration
├── 📄 .env.example                   # Environment variables template
└── 📄 README.md                      # Project documentation
```

## 🏗️ Technology Stack

| Category | Technology | Version | Purpose |
|----------|------------|---------|---------|
| **Runtime** | Node.js | 20+ | JavaScript runtime environment |
| **Language** | TypeScript | 5.8.3 | Type-safe JavaScript development |
| **Framework** | MCP SDK | 1.12.1 | Model Context Protocol implementation |
| **Validation** | Zod | 3.23.8 | Runtime type validation & parsing |
| **Testing** | Jest | 29.7.0 | Unit & integration testing framework |
| **Development** | Nodemon | 3.1.10 | Development server with hot-reload |
| **Build** | TypeScript Compiler | 5.8.3 | Compilation to JavaScript |

## 🛠️ Development

### Building

**Development Build:**

```bash
npm run build
```

**Watch Mode (Auto-rebuild):**

```bash
npm run build -- --watch
```

### Testing Strategy

The project maintains high code quality through comprehensive testing:

**Test Categories:**

- **Unit Tests**: Individual module testing with mocking
- **Integration Tests**: End-to-end MCP tool functionality
- **Functional Tests**: Core business logic validation
- **Error Handling Tests**: Comprehensive error scenario coverage

**Test Commands:**

```bash
# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage
```

**Coverage Targets:**
- **Unit Tests**: >90% code coverage
- **Integration Tests**: >80% feature coverage
- **Critical Paths**: 100% coverage for security-sensitive code

### Code Quality Standards

- **TypeScript**: Strict type checking enabled
- **ESLint**: Code style and quality enforcement
- **Prettier**: Consistent code formatting
- **Jest**: Comprehensive testing framework
- **Zod**: Runtime type validation
- **Error Handling**: Graceful error recovery and user-friendly messages
- **Security**: Input validation and sanitization for all external inputs

## 🔧 Troubleshooting

### Common Issues & Solutions

| Issue | Symptoms | Solution |
|-------|----------|----------|
| **Package not found** | `npm error could not determine executable to run` | Use local configuration (Option 2) or wait for package publication |
| **Module not found** | `Cannot find module` errors | Run `npm install` and `npm run build` |
| **GitLab access errors** | `403 Forbidden` or `404 Not Found` | Verify `GITLAB_BASE_URL` configuration and repository access |
| **Port conflicts** | `EADDRINUSE` error | Change `PORT` environment variable or kill conflicting process |
| **TypeScript errors** | Compilation failures | Check `tsconfig.json` and ensure all dependencies are installed |
| **Test failures** | Jest test errors | Run `npm run test:coverage` to identify uncovered code paths |
| **MCP connection closed** | `MCP error -1: Connection closed` | Check if server starts correctly with `node dist/server.js` |

### Debug Mode

Enable comprehensive debug logging:

```bash
# Enable debug logging
DEBUG=awesome-components-mcp npm start

# Enable verbose logging with timestamps
DEBUG=awesome-components-mcp:* npm start
```

### Testing Local Configuration

To test the local MCP server configuration before using it with clients:

```bash
# Run the test script
node test-local-mcp.js
```

This will:
- Verify the server starts correctly
- Display the correct local configuration
- Test basic functionality

### Performance Optimization

- **Memory Usage**: Monitor with `node --inspect dist/server.js`
- **Response Times**: Use debug mode to track request processing times
- **GitLab Rate Limits**: Implement caching for frequently accessed components

## 🤝 Contributing

We welcome contributions! Please follow these guidelines:

### Development Workflow

1. **Fork & Clone**

   ```bash
git clone https://github.com/your-username/awesome-components-mcp.git
   cd awesome-components-mcp
```

2. **Create Feature Branch**

   ```bash
git checkout -b feature/your-feature-name
```

3. **Development Setup**

   ```bash
npm install
   npm run build
   npm test
```

4. **Make Changes**
   - Follow TypeScript best practices
   - Add comprehensive tests for new functionality
   - Update documentation as needed
   - Ensure code passes all linting rules

5. **Testing Requirements**

   ```bash
# All tests must pass
   npm test

   # Coverage must meet minimum thresholds
   npm run test:coverage

   # Integration tests must pass
   npm run test:integration
```

6. **Submit Pull Request**
   - Provide clear description of changes
   - Reference any related issues
   - Ensure CI/CD pipeline passes

### Code Standards

- **TypeScript**: Use strict type checking
- **Testing**: Minimum 80% code coverage
- **Documentation**: Update README for new features
- **Commit Messages**: Use conventional commit format
- **Code Style**: Follow existing patterns and ESLint rules

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

**Key Points:**
- ✅ Commercial use allowed
- ✅ Modification allowed
- ✅ Distribution allowed
- ✅ Private use allowed
- ❌ No warranty provided
- ❌ No liability accepted

## 🆘 Support & Community

### Getting Help

| Resource | Description | Link |
|----------|-------------|------|
| **Documentation** | Comprehensive guides and API reference | This README |
| **Issues** | Bug reports and feature requests | [GitHub Issues](http://gitlab.yeepay.com/awesome/awesome-components-mcp/issues) |
| **Discussions** | Community Q&A and general discussion | [GitHub Discussions](http://gitlab.yeepay.com/awesome/awesome-components-mcp/discussions) |
| **Examples** | Usage examples and integration guides | `/examples` directory |

### Quick Support Checklist

Before opening an issue:

- [ ] Check the troubleshooting section above
- [ ] Review existing issues and discussions
- [ ] Test with the latest version
- [ ] Provide minimal reproduction case
- [ ] Include environment details (Node.js version, OS, etc.)