MCP Advisor

Un servicio de descubrimiento y recomendación para explorar servidores MCP mediante consultas en lenguaje natural.

Documentación

MCP Advisor

Introducción

MCP Advisor es un servicio de descubrimiento y recomendación que ayuda a los asistentes de IA a explorar servidores de Model Context Protocol (MCP) mediante consultas en lenguaje natural. Facilita a los usuarios encontrar y aprovechar herramientas MCP adecuadas para tareas específicas.

Historias de Usuario

Descubrir y Recomendar Servidores MCP
- Como desarrollador de agentes de IA, quiero encontrar rápidamente los servidores MCP adecuados para una tarea específica mediante consultas en lenguaje natural.
- Ejemplo de prompt: "Find MCP servers for insurance risk analysis"
Instalar y Configurar Servidores MCP
- Como usuario habitual que descubre un servidor MCP útil, quiero instalarlo y empezar a usarlo lo antes posible.
- Ejemplo de prompt: "Install this MCP: https://github.com/Deepractice/PromptX"

Demo

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

Uso

Una vez configurado, el proveedor Nacos se habilitará automáticamente y se utilizará al buscar servidores MCP. Puedes consultarlo usando lenguaje natural, por ejemplo:

Find MCP servers for insurance risk analysis

O de forma más específica:

Search for MCP servers with natural language processing capabilities

Navegación de Documentación

Guía de Inicio Rápido - Instalación, configuración y uso básico
Referencia Técnica - Funciones avanzadas y proveedores de búsqueda
Guía de Contribución - Configuración de desarrollo y pautas de contribución
Documentación de Arquitectura - Detalles de la arquitectura del sistema
Solución de Problemas - Problemas comunes y soluciones
Hoja de Ruta - Planes de desarrollo futuros

Inicio Rápido

Instalación

La forma más rápida es integrar MCP Advisor mediante la configuración de MCP:

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

Añade esta configuración al archivo de configuración MCP de tu asistente de IA:

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

Instalación mediante Smithery

Para instalar Advisor para Claude Desktop automáticamente a través de Smithery:

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

Para más métodos de instalación y configuración detallada, consulta la Guía de Inicio Rápido.

Opcional: Meilisearch local (mejora las recomendaciones)

Para mejorar la calidad de las recomendaciones, puedes ejecutar una instancia local de Meilisearch:

pnpm meilisearch:start

Esto inicia Meilisearch en http://localhost:7700,, inicializa el índice mcp_servers a partir de datos locales y persiste las variables de entorno en ~/.meilisearch/env. Cárgalas en tu shell actual con:

source ~/.meilisearch/env

O actívalo automáticamente con una sola bandera al lanzar MCPAdvisor (sin necesidad de variables de entorno manuales):

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

Guía para Desarrolladores

Resumen de Arquitectura

MCP Advisor adopta una arquitectura modular con una clara separación de responsabilidades y principios de programación funcional. El código ha sido recientemente refactorizado (2025) para mejorar el mantenimiento y la escalabilidad:

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

Estructura del Proyecto

El código sigue principios de arquitectura limpia con una estructura de directorios 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 Principales

Capa de Servicio de Búsqueda
- Interfaz de búsqueda unificada y agregación de proveedores
- Soporte para múltiples proveedores de búsqueda ejecutándose en paralelo
- Opciones de búsqueda configurables (límite, similitud mínima)
Proveedores de Búsqueda
- Proveedor Meilisearch: Búsqueda vectorial mediante Meilisearch
- Proveedor GetMCP: Búsqueda API desde el registro GetMCP
- Proveedor Compass: Búsqueda API desde el registro Compass
- Proveedor Nacos: Integración de descubrimiento de servicios
- Proveedor Offline: Búsqueda híbrida que combina texto y vectores
Estrategia de Búsqueda Híbrida
- Combinación inteligente de coincidencia de texto y búsqueda vectorial
- Equilibrio de pesos configurable
- Mecanismos inteligentes de filtrado adaptativo
Capa de Transporte
- Stdio (predeterminado para CLI)
- SSE (integración web)
- Endpoints de API REST

Para documentación de arquitectura más detallada, consulta ARCHITECTURE.md.

Inicio Rápido para Desarrolladores

Configuración del Entorno de Desarrollo

Clona el repositorio
Instala las dependencias:
```
pnpm install
```
Compila el proyecto:
```
pnpm run build
```
Configura las variables de entorno (consulta la Guía de Inicio Rápido)

Pruebas

MCP Advisor incluye conjuntos de pruebas exhaustivos para garantizar la calidad y funcionalidad del código. Para información detallada sobre pruebas, incluyendo pruebas unitarias, de integración, de extremo a extremo y procedimientos de prueba manual, consulta la Referencia Técnica.

Pruebas

Ejecuta las pruebas completas:

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

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

Para información detallada sobre pruebas, consulta la Referencia 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);

Opciones de Transporte

MCP Advisor admite múltiples métodos de transporte:

Transporte Stdio (predeterminado) - Adecuado para herramientas de línea de comandos
Transporte SSE - Adecuado para integración web
Transporte REST - Proporciona endpoints de API REST

Para más detalles de desarrollo, consulta la Guía de Contribución.

Pautas de Contribución

¡Damos la bienvenida a las contribuciones a MCP Advisor!

Ejemplos de Uso

Consultas de Ejemplo

Aquí tienes algunas consultas de ejemplo que puedes usar con MCP Advisor:

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

Respuesta de Ejemplo

[
  {
    "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 más ejemplos y uso avanzado, consulta la Referencia Técnica.

Solución de Problemas

Problemas Comunes

Conexión Rechazada
- Asegúrate de que el servidor esté ejecutándose en el puerto especificado
- Comprueba la configuración del firewall
No se Devuelven Resultados
- Prueba con una consulta más general
- Comprueba la conexión de red con las APIs del registro
Problemas de Rendimiento
- Considera añadir términos de búsqueda más específicos
- Comprueba los recursos del servidor (CPU/memoria)

Para más información sobre solución de problemas, consulta TROUBLESHOOTING.md.

Proveedores de Búsqueda

MCP Advisor admite múltiples proveedores de búsqueda que pueden utilizarse simultáneamente:

Proveedor de Búsqueda Compass: Recupera información de servidores MCP mediante la API de Compass
Proveedor de Búsqueda GetMCP: Utiliza la API de GetMCP y búsqueda vectorial para coincidencias semánticas
Proveedor de Búsqueda Meilisearch: Utiliza Meilisearch para búsqueda de texto rápida y tolerante a fallos

Para información detallada sobre los proveedores de búsqueda, consulta la Referencia Técnica.

Hoja de Ruta

MCP Advisor está evolucionando de un sistema simple de recomendación a una plataforma inteligente de orquestación de agentes. Nuestra visión es crear un sistema que no solo recomiende los servidores MCP adecuados, sino que también aprenda de las interacciones y ayude a los agentes a planificar y ejecutar tareas complejas de forma dinámica.

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

Principales Fases de Desarrollo

Optimización de la Capacidad de Recomendación (2025 Q2-Q3)
- Aceptar comentarios de los usuarios
- Refinar la efectividad de las recomendaciones
- Introducir más índices

Para una hoja de ruta detallada, consulta ROADMAP.md.

Para implementar las funciones anteriores, necesitamos:

Soporte de búsqueda por índice de texto completo
Utilizar un módulo de reordenamiento profesional como https://github.com/PrithivirajDamodaran/FlashRank o el modelo Qwen Rerank
Soporte del marketplace de Cline: https://api.cline.bot/v1/mcp/marketplace

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.