MCP Advisor

Um serviço de descoberta e recomendação para explorar servidores MCP usando consultas em linguagem natural.

Documentação

MCP Advisor

Introdução

O MCP Advisor é um serviço de descoberta e recomendação que ajuda assistentes de IA a explorar servidores Model Context Protocol (MCP) usando consultas em linguagem natural. Ele facilita para os usuários encontrar e aproveitar ferramentas MCP adequadas para tarefas específicas.

Histórias de Usuário

Descobrir e Recomendar Servidores MCP
- Como desenvolvedor de agentes de IA, quero encontrar rapidamente os servidores MCP certos para uma tarefa específica usando consultas em linguagem natural.
- Exemplo de prompt: "Find MCP servers for insurance risk analysis"
Instalar e Configurar Servidores MCP
- Como usuário comum que descobre um servidor MCP útil, quero instalá-lo e começar a usá-lo o mais rápido possível.
- Exemplo de prompt: "Install this MCP: https://github.com/Deepractice/PromptX"

Demonstração

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

Uso

Uma vez configurado, o provedor Nacos será habilitado automaticamente e usado ao pesquisar por servidores MCP. Você pode consultá-lo usando linguagem natural, por exemplo:

Find MCP servers for insurance risk analysis

Ou mais especificamente:

Search for MCP servers with natural language processing capabilities

Navegação da Documentação

Guia de Início Rápido - Instalação, configuração e uso básico
Referência Técnica - Recursos avançados e provedores de busca
Guia de Contribuição - Configuração de desenvolvimento e diretrizes de contribuição
Documentação de Arquitetura - Detalhes da arquitetura do sistema
Solução de Problemas - Problemas comuns e soluções
Roteiro - Planos de desenvolvimento futuros

Início Rápido

Instalação

A maneira mais rápida é integrar o MCP Advisor através da configuração do MCP:

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

Adicione esta configuração ao arquivo de configurações MCP do seu assistente de IA:

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

Instalando via Smithery

Para instalar o Advisor para Claude Desktop automaticamente via Smithery:

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

Para mais métodos de instalação e configuração detalhada, consulte o Guia de Início Rápido.

Opcional: Meilisearch Local (melhora as recomendações)

Para aumentar a qualidade das recomendações, você pode executar uma instância local do Meilisearch:

pnpm meilisearch:start

Isso inicia o Meilisearch em http://localhost:7700,, inicializa o índice mcp_servers a partir de dados locais e persiste variáveis de ambiente em ~/.meilisearch/env. Carregue-as no seu shell atual com:

source ~/.meilisearch/env

Ou habilite-o automaticamente com uma única flag ao iniciar o MCPAdvisor (sem necessidade de env manual):

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

Guia do Desenvolvedor

Visão Geral da Arquitetura

O MCP Advisor adota uma arquitetura modular com separação clara de responsabilidades e princípios de programação funcional. O código foi recentemente refatorado (2025) para melhorar a manutenibilidade e escalabilidade:

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

Estrutura do Projeto

O código segue princípios de arquitetura limpa com uma estrutura de diretórios organizada:

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

Componentes Principais

Camada de Serviço de Busca
- Interface de busca unificada e agregação de provedores
- Suporte a múltiplos provedores de busca executando em paralelo
- Opções de busca configuráveis (limite, similaridade mínima)
Provedores de Busca
- Provedor Meilisearch: Busca vetorial usando Meilisearch
- Provedor GetMCP: Busca via API do registro GetMCP
- Provedor Compass: Busca via API do registro Compass
- Provedor Nacos: Integração com descoberta de serviços
- Provedor Offline: Busca híbrida combinando texto e vetores
Estratégia de Busca Híbrida
- Combinação inteligente de correspondência de texto e busca vetorial
- Balanceamento de pesos configurável
- Mecanismos inteligentes de filtragem adaptativa
Camada de Transporte
- Stdio (padrão CLI)
- SSE (integração web)
- Endpoints REST API

Para documentação de arquitetura mais detalhada, consulte ARCHITECTURE.md.

Início Rápido do Desenvolvedor

Configuração do Ambiente de Desenvolvimento

Clone o repositório
Instale as dependências:
```
pnpm install
```
Compile o projeto:
```
pnpm run build
```
Configure as variáveis de ambiente (veja o Guia de Início Rápido)

Testes

O MCP Advisor inclui suítes de testes abrangentes para garantir qualidade e funcionalidade do código. Para informações detalhadas sobre testes, incluindo testes unitários, testes de integração, testes ponta a ponta e procedimentos de teste manual, consulte a Referência Técnica.

Testes

Execute testes abrangentes:

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

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

Para informações detalhadas sobre testes, consulte a Referência Técnica.

Uso como Biblioteca

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

Opções de Transporte

O MCP Advisor suporta múltiplos métodos de transporte:

Transporte Stdio (padrão) - Adequado para ferramentas de linha de comando
Transporte SSE - Adequado para integração web
Transporte REST - Fornece endpoints REST API

Para mais detalhes de desenvolvimento, consulte o Guia de Contribuição.

Diretrizes de Contribuição

Aceitamos contribuições para o MCP Advisor!

Exemplos de Uso

Consultas de Exemplo

Aqui estão alguns exemplos de consultas que você pode usar com o MCP Advisor:

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

Resposta de Exemplo

[
  {
    "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
  }
]

Para mais exemplos e uso avançado, consulte a Referência Técnica.

Solução de Problemas

Problemas Comuns

Conexão Recusada
- Certifique-se de que o servidor está rodando na porta especificada
- Verifique as configurações do firewall
Nenhum Resultado Retornado
- Tente uma consulta mais geral
- Verifique a conexão de rede com as APIs do registro
Problemas de Desempenho
- Considere adicionar termos de busca mais específicos
- Verifique os recursos do servidor (CPU/memória)

Para mais informações sobre solução de problemas, consulte TROUBLESHOOTING.md.

Provedores de Busca

O MCP Advisor suporta múltiplos provedores de busca que podem ser usados simultaneamente:

Provedor de Busca Compass: Recupera informações de servidores MCP usando a API Compass
Provedor de Busca GetMCP: Usa a API GetMCP e busca vetorial para correspondência semântica
Provedor de Busca Meilisearch: Usa Meilisearch para busca de texto rápida e tolerante a falhas

Para informações detalhadas sobre provedores de busca, consulte a Referência Técnica.

Roteiro

O MCP Advisor está evoluindo de um sistema simples de recomendação para uma plataforma de orquestração de agentes inteligentes. Nossa visão é criar um sistema que não apenas recomende os servidores MCP certos, mas também aprenda com as interações e ajude os agentes a planejar e executar tarefas complexas dinamicamente.

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

Principais Fases de Desenvolvimento

Otimização da Capacidade de Recomendação (2025 Q2-Q3)
- Aceitar feedback do usuário
- Refinar a eficácia das recomendações
- Introduzir mais índices

Para um roteiro detalhado, consulte ROADMAP.md.

Para implementar os recursos acima, precisamos:

Suportar busca por índice de texto completo
Utilizar módulo profissional de reordenação como https://github.com/PrithivirajDamodaran/FlashRank ou Qwen Rerank Model
Suportar o marketplace Cline: https://api.cline.bot/v1/mcp/marketplace

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.