@yeepay/awesome-components-mcp/README.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
- 🎯 **Structured Output**: Returns JSON-formatted structured data for programmatic processing
- ⚡ **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

| Variable | Description | Default Value | Required |
|----------|-------------|---------------|----------|
| `GITLAB_BASE_URL` | Base URL for GitLab raw file access | `http://gitlab.yeepay.com/awesome/awesome-components/-/raw/main/` | No |
| `MAIN_LLMS_URL` | URL to the main llms.txt file | `http://gitlab.yeepay.com/awesome/awesome-components/-/raw/main/llms.txt` | No |
| `GITLAB_PERSONAL_ACCESS_TOKEN` | GitLab Personal Access Token for authentication | None | No* |
| `PORT` | Port for the MCP server | `3000` | No |
| `DEBUG` | Enable debug logging | `false` | No |

**Note:** `GITLAB_PERSONAL_ACCESS_TOKEN` is required for accessing private repositories but optional for public ones.

### Configuration Methods

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

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

```bash
# GitLab Configuration
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 Authentication (required for private repositories)
GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token_here

# Server Configuration
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/ \
           -e GITLAB_PERSONAL_ACCESS_TOKEN=your_token_here \
           awesome-components-mcp
```

#### GitLab Personal Access Token Setup

To access private repositories, you need to create a GitLab Personal Access Token:

1. **Navigate to GitLab Settings:**
   - Go to your GitLab instance (e.g., `https://gitlab.yeepay.com`)
   - Click on your avatar in the top-right corner
   - Select "Edit profile" or "Settings"

2. **Create Personal Access Token:**
   - In the left sidebar, click "Access Tokens"
   - Fill in the token details:
     - **Name**: `awesome-components-mcp` (or any descriptive name)
     - **Expiration date**: Set according to your security policy
     - **Scopes**: Select the following required scopes:
       - ✅ `read_api` - Read access to the API
       - ✅ `read_repository` - Read access to repository content

3. **Copy and Store Token:**
   - Click "Create personal access token"
   - **Important**: Copy the token immediately and store it securely
   - The token will not be shown again after you leave the page

4. **Configure the Token:**
   - Add the token to your `.env` file or environment variables
   - Never commit the token to version control

## 🚀 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`

**Purpose:** Intelligently discovers and categorizes all available components from the main llms.txt file.

**Parameters:**

This tool requires no parameters.

**Output Format:**
- Returns structured JSON data with component metadata and categorization
- Includes source information, total component count, categorization by type, and detailed component list

**Example Usage:**

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

**Sample Response (JSON Format):**

```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`

**Purpose:** Retrieves comprehensive integration guides for specific components with intelligent path resolution.

**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 |
|-------|----------|----------|
| **Authentication failed** | `401 Unauthorized` errors | Check `GITLAB_PERSONAL_ACCESS_TOKEN` is valid and has correct scopes |
| **Access forbidden** | `403 Forbidden` errors | For private repos: provide token; for public repos: check repository permissions |
| **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** | `404 Not Found` errors | Verify `GITLAB_BASE_URL` configuration and file paths |
| **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` |
| **Token validation** | Token appears invalid | Ensure token is at least 10 characters and has required scopes |

### 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.)