@yeepay/awesome-components-mcp

v1.0.0

Published

5 months ago

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

English | 中文

🚀 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

Clone the repository:

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

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Start the server:
```
npm start
```

Development Installation

For development with hot-reload:

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:

# 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

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

Method 3: Docker Environment

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:

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"
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
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
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)

{
  "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:

{
  "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:

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

For Continue IDE Extension:

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

For Cursor IDE:

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

For Augment:

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

For Trae:

Access Trae configuration settings
Go to "MCP Configuration" or "Server Management"
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:

npm run dev

Production Mode

Build and start the server for production deployment:

npm run build
npm start

Testing

Run all tests:

npm test

Run tests in watch mode:

npm run test:watch

Run tests with coverage report:

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:

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

Sample Response (JSON Format):

{
  "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:

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

Advanced Usage with Absolute URL:

{
  "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:

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:

npm run build

Watch Mode (Auto-rebuild):

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:

# 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:

# 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:

# 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

Fork & Clone

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

Create Feature Branch

git checkout -b feature/your-feature-name

Development Setup
```
npm install
npm run build
npm test
```
Make Changes
- Follow TypeScript best practices
- Add comprehensive tests for new functionality
- Update documentation as needed
- Ensure code passes all linting rules

Testing Requirements

# All tests must pass
npm test

# Coverage must meet minimum thresholds
npm run test:coverage

# Integration tests must pass
npm run test:integration

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 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 | | Discussions | Community Q&A and general discussion | GitHub 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.)