@yeepay/awesome-components-mcp

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