MCP Advisor

English | 简体中文

Introduction

MCP Advisor is a discovery and recommendation service that helps AI assistants explore Model Context Protocol (MCP) servers using natural language queries. It makes it easier for users to find and leverage MCP tools suitable for specific tasks.

User Stories

1. Discover & Recommend MCP Servers

   • As an AI agent developer, I want to quickly find the right MCP servers for a specific task using natural-language queries.
   • Example prompt: "Find MCP servers for insurance risk analysis"

2. Install & Configure MCP Servers

   • As a regular user who discovers a useful MCP server, I want to install and start using it as quickly as possible.
   • Example prompt: "Install this MCP: https://github.com/Deepractice/PromptX"

   

Demo

https://github.com/user-attachments/assets/7a536315-e316-4978-8e5a-e8f417169eb1

Nacos Provider Setup

The Nacos provider allows MCP Advisor to discover and recommend MCP servers registered in a Nacos service registry. This is particularly useful in microservices environments where MCP servers are dynamically registered with Nacos.

Prerequisites

• A running Nacos server (v2.0.0 or later recommended)
• Valid Nacos authentication credentials
• MCP servers registered in Nacos with appropriate metadata

Configuration

Configure the Nacos provider using the following environment variables:

# Required
NACOS_SERVER_ADDR=your-nacos-server:8848
NACOS_USERNAME=your-username
NACOS_PASSWORD=your-password

# Optional
MCP_HOST=localhost             # Default: localhost
MCP_PORT=3000                  # Default: 3000
AUTH_TOKEN=your-auth-token     # Optional: For MCP server authentication
NACOS_DEBUG=false              # Enable debug logging

Features

• Service Discovery: Automatically discovers MCP servers registered in Nacos
• Vector Search: Uses semantic search to find the most relevant MCP servers for a given query
• Real-time Updates: Periodically syncs with Nacos to keep the server list up-to-date
• Fallback Search: Falls back to keyword search if vector search is unavailable

Usage

Once configured, the Nacos provider will be automatically enabled and used when searching for MCP servers. You can query it using natural language, for example:

Find MCP servers for insurance risk analysis

Or more specifically:

Search for MCP servers with natural language processing capabilities

Documentation Navigation

• Installation Guide - Detailed installation and configuration instructions
• User Guide - How to use MCP Advisor
• Architecture Documentation - System architecture details
• Technical Details - Advanced technical features <<<<<<< HEAD
• Testing Guide - Comprehensive testing documentation =======

@{-1}

• Troubleshooting - Common issues and solutions
• Search Providers - Search provider details
• Roadmap - Future development plans
• Developer Guide - Development environment setup and code contribution
• Best Practices - Coding standards and best practices for contributors

Quick Start

Installation

The fastest way is to integrate MCP Advisor through MCP configuration:

{
  "mcpServers": {
    "mcpadvisor": {
      "command": "npx",
      "args": ["-y", "@xiaohui-wang/mcpadvisor"]
    }
  }
}

Add this configuration to your AI assistant's MCP settings file:

• MacOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %AppData%\Claude\claude_desktop_config.json

Installing via Smithery

To install Advisor for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @istarwyh/mcpadvisor --client claude

For more installation methods, see the Installation Guide.

Developer Guide

Architecture Overview

MCP Advisor adopts a modular architecture with clean separation of concerns and functional programming principles. The codebase has been recently refactored (2025) to improve maintainability and scalability:

graph TD
    Client["Client Application"] --> |"MCP Protocol"| Transport["Transport Layer"]
    
    subgraph "MCP Advisor Server"
        Transport --> |"Request"| SearchService["Search Service"]
        SearchService --> |"Query"| Providers["Search Providers"]
        
        subgraph "Search Providers"
            Providers --> MeilisearchProvider["Meilisearch Provider"]
            Providers --> GetMcpProvider["GetMCP Provider"]
            Providers --> CompassProvider["Compass Provider"]
            Providers --> NacosProvider["Nacos Provider"]
            Providers --> OfflineProvider["Offline Provider"]
        end
        
        OfflineProvider --> |"Hybrid Search"| HybridSearch["Hybrid Search Engine"]
        HybridSearch --> TextMatching["Text Matching"]
        HybridSearch --> VectorSearch["Vector Search"]
        
        SearchService --> |"Merge & Filter"| ResultProcessor["Result Processor"]
        
        SearchService --> Logger["Logging System"]
    end

Project Structure

The codebase follows clean architecture principles with organized directory structure:

src/
├── services/
│   ├── core/                    # Core business logic
│   │   ├── installation/        # Installation guide services
│   │   ├── search/             # Search providers
│   │   └── server/             # MCP server implementation
│   ├── providers/              # External service providers
│   │   ├── meilisearch/        # Meilisearch integration
│   │   ├── nacos/              # Nacos service discovery
│   │   ├── oceanbase/          # OceanBase vector database
│   │   └── offline/            # Offline search engine
│   ├── common/                 # Shared utilities
│   │   ├── api/                # API clients
│   │   ├── cache/              # Caching mechanisms
│   │   └── vector/             # Vector operations
│   └── interfaces/             # Type definitions
├── types/                      # TypeScript type definitions
├── utils/                      # Utility functions
└── tests/                      # Test suites
    ├── unit/                   # Unit tests
    ├── integration/            # Integration tests
    └── e2e/                    # End-to-end tests

Core Components

1. Search Service Layer

   • Unified search interface and provider aggregation
   • Support for multiple search providers executing in parallel
   • Configurable search options (limit, minSimilarity)

2. Search Providers

   • Meilisearch Provider: Vector search using Meilisearch
   • GetMCP Provider: API search from the GetMCP registry
   • Compass Provider: API search from the Compass registry
   • Nacos Provider: Service discovery integration
   • Offline Provider: Hybrid search combining text and vectors

3. Hybrid Search Strategy

   • Intelligent combination of text matching and vector search
   • Configurable weight balancing
   • Smart adaptive filtering mechanisms

4. Transport Layer

   • Stdio (CLI default)
   • SSE (Web integration)
   • REST API endpoints

For more detailed architecture documentation, see ARCHITECTURE.md.

Technical Highlights

Advanced Search Techniques

1. Vector Normalization

   • All vectors are normalized to unit length (magnitude = 1)
   • Ensures consistent cosine similarity calculations
   • Improves search precision by focusing on direction rather than magnitude

2. Parallel Search Execution

   • Vector search and text search run in parallel
   • Leverages Promise.all for optimal performance
   • Fallback mechanisms enabled if either search fails

3. Weighted Result Merging

   • Configurable weights between vector and text results
   • Default: vector similarity (70%), text matching (30%)

Error Handling and Logging System

MCP Advisor implements robust error handling and logging systems:

1. Contextual Error Formatting

   • Standardized error object enrichment
   • Stack trace preservation and formatting
   • Error type categorization and standardization

2. Graceful Degradation

   • Multi-provider fallback strategies
   • Partial result processing
   • Default responses for critical failures

For more technical details, see TECHNICAL_DETAILS.md.

Developer Quick Start

Development Environment Setup

1. Clone the repository
2. Install dependencies:

   pnpm install
   

3. Build the project:

   pnpm run build
   

4. Configure environment variables (see INSTALLATION.md)

Testing

MCP Advisor includes comprehensive testing suites to ensure code quality and functionality. For detailed testing information including unit tests, integration tests, end-to-end testing, and manual testing procedures, see the Testing Guide.

Quick Test Commands

# Run all tests
pnpm run check && pnpm run test && pnpm run test:e2e

# Automated E2E testing script
./scripts/run-e2e-test.sh

Library Usage

import { SearchService } from '@xiaohui-wang/mcpadvisor';

// Initialize search service
const searchService = new SearchService();

// Search for MCP servers
const results = await searchService.search('vector database integration');
console.log(results);

Transport Options

MCP Advisor supports multiple transport methods:

1. Stdio Transport (default) - Suitable for command-line tools
2. SSE Transport - Suitable for web integration
3. REST Transport - Provides REST API endpoints

For more development details, see DEVELOPER_GUIDE.md.

Contribution Guidelines

We welcome contributions to MCP Advisor! The project has been recently refactored to improve code organization and maintainability.

Development Workflow

1. Fork and Clone: Fork the repository and clone your fork
2. Setup Environment: Follow the development environment setup above
3. Create Branch: Create a feature branch from main
4. Make Changes: Implement your changes following our coding standards
5. Test: Run all tests to ensure your changes don't break existing functionality:

   pnpm run check          # Lint and format check
   pnpm run test           # Unit tests
   pnpm run test:e2e       # End-to-end tests
   

6. Commit: Follow conventional commit message format:

   feat: add new search provider integration
   fix: resolve vector search performance issue
   docs: update installation guide
   test: add e2e tests for recommendation workflow
   refactor: reorganize services directory structure
   

7. Pull Request: Submit a PR with clear description of changes

Code Quality Standards

• TypeScript: Use strict typing, avoid any
• Testing: Maintain test coverage above 80%
• Documentation: Update docs for new features
• Architecture: Follow clean architecture principles
• Performance: Consider performance implications

Recent Improvements (2025)

• ✅ Directory restructuring for better maintainability
• ✅ Comprehensive test suites with unit, integration, and E2E tests
• ✅ Automated testing workflows using Playwright
• ✅ Improved error handling and logging
• ✅ Clean architecture implementation

Usage Examples

Example Queries

Here are some example queries you can use with MCP Advisor:

"Find MCP servers for natural language processing"
"MCP servers for financial data analysis"
"E-commerce recommendation engine MCP servers"
"MCP servers with image recognition capabilities"
"Weather data processing MCP servers"
"Document summarization MCP servers"

Example Response

[
  {
    "title": "NLP Toolkit",
    "description": "Comprehensive natural language processing toolkit with sentiment analysis, entity recognition, and text summarization capabilities.",
    "github_url": "https://github.com/example/nlp-toolkit",
    "similarity": 0.92
  },
  {
    "title": "Text Processor",
    "description": "Efficient text processing MCP server with multi-language support.",
    "github_url": "https://github.com/example/text-processor",
    "similarity": 0.85
  }
]

For more examples, see EXAMPLES.md.

Troubleshooting

Common Issues

1. Connection Refused

   • Ensure the server is running on the specified port
   • Check firewall settings

2. No Results Returned

   • Try a more general query
   • Check network connection to registry APIs

3. Performance Issues

   • Consider adding more specific search terms
   • Check server resources (CPU/memory)

For more troubleshooting information, see TROUBLESHOOTING.md.

Search Providers

MCP Advisor supports multiple search providers that can be used simultaneously:

1. Compass Search Provider: Retrieves MCP server information using the Compass API
2. GetMCP Search Provider: Uses the GetMCP API and vector search for semantic matching
3. Meilisearch Search Provider: Uses Meilisearch for fast, fault-tolerant text search

For detailed information about search providers, see SEARCH_PROVIDERS.md.

Roadmap

MCP Advisor is evolving from a simple recommendation system to an intelligent agent orchestration platform. Our vision is to create a system that not only recommends the right MCP servers but also learns from interactions and helps agents dynamically plan and execute complex tasks.

gantt
    title MCP Advisor Evolution Roadmap
    dateFormat  YYYY-MM-DD
    axisFormat  %Y-%m
    
    section Foundation
    Enhanced Search & Recommendation ✓       :done, 2025-01-01, 90d
    Hybrid Search Engine ✓                   :done, 2025-01-01, 90d
    Provider Priority System ✓               :done, 2025-04-01, 60d
    
    section Intelligence Layer
    Feedback Collection System               :active, 2025-04-01, 90d
    Agent Interaction Analytics             :2025-07-01, 120d
    Usage Pattern Recognition               :2025-07-01, 90d
    
    section Learning Systems
    Reinforcement Learning Framework         :2025-10-01, 180d
    Contextual Bandit Implementation         :2025-10-01, 120d
    Multi-Agent Reward Modeling             :2026-01-01, 90d
    
    section Advanced Features
    Task Decomposition Engine               :2026-01-01, 120d
    Dynamic Planning System                 :2026-04-01, 150d
    Adaptive MCP Orchestration              :2026-04-01, 120d
    
    section Ecosystem
    Developer SDK & API                     :2026-07-01, 90d
    Custom MCP Training Tools               :2026-07-01, 120d
    Enterprise Integration Framework        :2026-10-01, 150d

Major Development Phases

1. Recommendation Capability Optimization (2025 Q2-Q3)
   • Accept user feedback
   • Refine recommendation effectiveness
   • Introduce more indices

For a detailed roadmap, see ROADMAP.md.

To Implement the above features, we need to:

• Support Full-Text Index Search
• Support MCP Resources to read log
• Utilize Professional Rerank Module like https://github.com/PrithivirajDamodaran/FlashRank or Qwen Rerank Model
• Support Cline marketplace: https://api.cline.bot/v1/mcp/marketplace

License

This project is licensed under the MIT License - see the LICENSE file for details.