mcpadvisor

View on GitHub

MCP Advisor & Installation - Use the right MCP server for your needs

67 stars TypeScriptServers & Infrastructure Updated Oct 27, 2025

Documentation

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

2. Install & Configure MCP Servers

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:

code

Find MCP servers for insurance risk analysis

Or more specifically:

code

Search for MCP servers with natural language processing capabilities

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:

json

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

bash

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:

bash

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:

bash

source ~/.meilisearch/env

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

json

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

mermaid

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:

code

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

2. Search Providers

3. Hybrid Search Strategy

4. Transport Layer

For more detailed architecture documentation, see ARCHITECTURE.md.

Developer Quick Start

Development Environment Setup

1. Clone the repository

2. Install dependencies:

bash

pnpm install

3. Build the project:

bash

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 comprehensive tests:

bash

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

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

For detailed testing information, see Technical Reference.

Library Usage

typescript

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 Contributing Guide.

Contribution Guidelines

We welcome contributions to MCP Advisor!

Usage Examples

Example Queries

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

code

"Find MCP servers for natural language processing"
"Document summarization MCP servers"

Example Response

json

[
  {
    "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 and advanced usage, see Technical Reference.

Troubleshooting

Common Issues

1. Connection Refused

2. No Results Returned

3. Performance Issues

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

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.

mermaid

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)

For a detailed roadmap, see ROADMAP.md.

To Implement the above features, we need to:

[ ] Support Full-Text Index Search
[ ] Utilize Professional Rerank Module like https://github.com/PrithivirajDamodaran/FlashRank or Qwen Rerank Model
[ ] Support Cline marketplace: https://api.cline.bot/v1/mcp/marketplace