MCP Advisor

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

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

• Quick Start Guide - Installation, configuration, and basic usage
• Technical Reference - Advanced features and search providers
• Contributing Guide - Development setup and contribution guidelines
• Architecture Documentation - System architecture details
• Troubleshooting - Common issues and solutions
• Roadmap - Future development plans

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 and detailed configuration, see the Quick Start Guide.

Optional: Local Meilisearch (improves recommendations)

To boost recommendation quality, you can run a local Meilisearch instance:

pnpm meilisearch:start

This starts Meilisearch at http://localhost:7700, bootstraps the mcp_servers index from local data, and persists environment variables to ~/.meilisearch/env. Load them in your current shell with:

source ~/.meilisearch/env

Or enable it automatically with a single flag when launching MCPAdvisor (no manual env needed):

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

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.

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 Quick Start Guide)

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 Technical Reference.

Testing

Run compr

---

README truncated. View full README on GitHub.