Document Search MCP

🚀 Servidor MCP de Búsqueda en Documentación

Un servidor avanzado del Model Context Protocol (MCP) que proporciona capacidades de búsqueda semántica en documentación vectorizada utilizando ChromaDB y SentenceTransformers.

✨ Características Principales

• 🔍 Búsqueda semántica avanzada con similitud de embeddings
• 📊 Gestión completa de documentos (añadir, buscar, actualizar, eliminar)
• 🏗️ Arquitectura modular altamente escalable y mantenible
• 📝 Sistema de logging avanzado con rotación y formateo personalizado
• ⚙️ Configuración flexible vía variables de entorno o archivos
• 🏥 Monitoreo de salud del sistema completo
• 🚀 Rendimiento optimizado con caché y procesamiento por lotes

🏗️ Arquitectura Modular

El servidor está organizado en módulos independientes para máxima escalabilidad:

📁 Proyecto MCP
├── 📄 main.py              # Punto de entrada simplificado
├── 📄 config.py            # Configuración centralizada
├── 📄 logging_config.py    # Sistema de logging avanzado
├── 📄 database.py          # Gestión de ChromaDB
├── 📄 embeddings.py        # Modelo de embeddings con caché
├── 📄 tools.py             # Herramientas MCP disponibles
├── 📄 utils.py             # Utilidades comunes
├── 📄 server.py            # Coordinación del servidor
├── 📁 chroma_db/           # Base de datos vectorial
└── 📁 logs/                # Archivos de log rotativos

Descripción de Módulos

🛠️ Instalación y Configuración

Requisitos Previos

pip install mcp chromadb sentence-transformers

Configuración Básica

El servidor puede configurarse de dos maneras:

1. Variables de Entorno (Recomendado)

# Configuración básica
export MCP_COLLECTION_NAME="documentation"
export MCP_PERSIST_DIR="./chroma_db"
export MCP_EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2"

# Configuración de logging
export MCP_LOG_LEVEL="INFO"
export MCP_LOG_DIR="./logs"
export MCP_FILE_LOGGING="true"

# Configuración del servidor
export MCP_SERVER_NAME="documentation-search"
export MCP_SERVER_VERSION="0.2.0"

2. Configuración Programática

from config import MCPConfig

# Crear configuración personalizada
config = MCPConfig()
config.database.collection_name = "mi_documentacion"
config.logging.level = "DEBUG"
config.server.max_search_results = 20

🚀 Uso

Inicio Rápido

# Ejecutar servidor con configuración por defecto
python main.py

# Ejecutar con configuración personalizada
ENVIRONMENT=production python main.py

Herramientas Disponibles

El servidor proporciona las siguientes herramientas MCP:

🔍 search_documentation

Busca información usando similitud semántica.

{
  "query": "¿Cómo funciona la autenticación?",
  "n_results": 5,
  "metadata_filter": {
    "categoria": "seguridad"
  }
}

➕ add_document

Añade un nuevo documento a la base de datos.

{
  "content": "Contenido del documento...",
  "metadata": {
    "titulo": "Guía de Autenticación",
    "categoria": "seguridad",
    "fecha": "2024-01-01"
  },
  "custom_id": "doc_001"
}

📊 get_collection_stats

Obtiene estadísticas de la colección.

{
  "include_health": true
}

🗑️ delete_document

Elimina un documento por su ID.

{
  "document_id": "doc_001"
}

✏️ update_document

Actualiza contenido o metadatos de un documento.

{
  "document_id": "doc_001",
  "content": "Nuevo contenido...",
  "metadata": {
    "categoria": "seguridad_actualizada"
  }
}

🏥 health_check

Verifica el estado de salud del sistema.

{
  "detailed": true
}

📝 Sistema de Logging

Características del Logging

• 🔄 Rotación automática de archivos de log
• 📊 Múltiples niveles (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• 🎨 Formateo avanzado con información contextual
• 📁 Logs separados para errores críticos
• 🗂️ Organización por módulos

Configuración de Logging

from logging_config import LoggingConfig

# Configuración personalizada
logging_config = LoggingConfig(
    level="DEBUG",
    log_file="servidor_detailed.log",
    max_file_size_mb=50,
    backup_count=10,
    enable_console=True,
    enable_file=True
)

Niveles de Log por Módulo

• mcp-server.server: Información del servidor principal
• mcp-server.database: Operaciones de base de datos
• mcp-server.embeddings: Procesamiento de embeddings
• mcp-server.tools: Ejecución de herramientas

⚙️ Configuración Avanzada

Variables de Entorno Disponibles

Configuración de Producción

export ENVIRONMENT=production
export MCP_LOG_LEVEL=WARNING
export MCP_CONSOLE_LOGGING=false
export MCP_FILE_LOGGING=true
export MCP_LOG_DIR=/var/log/mcp-server

🔧 Desarrollo

Estructura del Proyecto

📁 Tu Proyecto MCP/
├── 📄 main.py              # Entry point
├── 📄 config.py            # Configuración
├── 📄 logging_config.py    # Logging avanzado
├── 📄 database.py          # ChromaDB manager
├── 📄 embeddings.py        # SentenceTransformers manager
├── 📄 tools.py             # MCP tools
├── 📄 utils.py             # Utilidades
├── 📄 server.py            # Server coordinator
├── 📄 requirements.txt     # Dependencias
├── 📄 pyproject.toml       # Configuración Python
└── 📄 README.md            # Esta documentación

Agregar Nuevas Herramientas

1. Definir la herramienta en tools.py:

def get_available_tools(self) -> List[types.Tool]:
    return [
        # ... herramientas existentes ...
        types.Tool(
            name="nueva_herramienta",
            description="Descripción de la nueva herramienta",
            inputSchema={
                "type": "object",
                "properties": {
                    "parametro": {"type": "string"}
                },
                "required": ["parametro"]
            }
        )
    ]

1. Implementar el handler:

async def handle_nueva_herramienta(self, parametro: str) -> List[types.TextContent]:
    # Lógica de la herramienta
    return [types.TextContent(type="text", text="Resultado")]

1. Registrar en el servidor en server.py:

elif name == "nueva_herramienta":
    result = await self.tools_manager.handle_nueva_herramienta(
        parametro=arguments.get("parametro", "")
    )

🧪 Testing

Pruebas Básicas

# 1. Iniciar el servidor
python main.py

# 2. En otra terminal, probar con curl
curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "add_document",
      "arguments": {
        "content": "Este es un documento de prueba"
      }
    }
  }'

Health Check

curl -X POST http://localhost:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "health_check",
      "arguments": {
        "detailed": true
      }
    }
  }'

🚨 Solución de Problemas

Problemas Comunes

1. Error de conexión a ChromaDB

   # Verificar permisos del directorio
   chmod 755 ./chroma_db

1. Modelo de embeddings no encontrado

   # Descargar modelo manualmente
   python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"

1. Logs no aparecen

   # Verificar configuración de logging
   export MCP_LOG_LEVEL=DEBUG
   export MCP_CONSOLE_LOGGING=true

Logs de Depuración

# Habilitar logging detallado
export MCP_LOG_LEVEL=DEBUG
export PYTHONUNBUFFERED=1

# Ver logs en tiempo real
tail -f logs/mcp_server.log

📈 Rendimiento

Optimizaciones Implementadas

• Caché de modelos: Evita recargar el modelo de embeddings
• Procesamiento por lotes: Para operaciones masivas
• Warmup automático: Prepara el modelo para mejor rendimiento
• Compresión de embeddings: Reduce uso de memoria
• Rotación de logs: Mantiene el tamaño de archivos manejable

Métricas de Rendimiento

• Tiempo de inicio: ~5-10 segundos (dependiendo del modelo)
• Búsqueda típica: 100-500ms
• Adición de documentos: 50-200ms por documento
• Uso de memoria: ~500MB - 2GB (dependiendo del modelo)

🤝 Contribución

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

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

🙏 Agradecimientos

• ChromaDB por la base de datos vectorial
• SentenceTransformers por los modelos de embeddings
• MCP por el protocolo estándar

⭐ Si encuentras útil este proyecto, ¡dale una estrella!