Meilisearch MCP Server

• Ver la configuración de conexión actual
• Cambiar entre instancias de Meilisearch dinámicamente
• Actualizar claves API sobre la marcha

• Crear nuevos índices con claves primarias personalizadas
• Listar todos los índices con estadísticas
• Eliminar índices y sus datos
• Obtener métricas detalladas del índice

• Añadir o actualizar documentos
• Recuperar documentos con paginación
• Importar datos en lote

• Buscar con filtros, ordenación y facetas
• Búsqueda en múltiples índices
• Búsqueda semántica con vectores
• Búsqueda híbrida (palabras clave + semántica)

• Configurar reglas de clasificación
• Configurar facetado y filtrado
• Gestionar atributos buscables
• Personalizar la tolerancia a errores tipográficos

• Crear y gestionar claves API
• Establecer permisos granulares
• Monitorizar el uso de claves

⚠️ Nota: Aunque puedes añadir y actualizar hosts y claves API directamente en el chat por conveniencia, este enfoque está diseñado principalmente para casos de uso de desarrollo (como conectarse a múltiples instancias sobre la marcha). No sigue las mejores prácticas de seguridad de MCP y no debe usarse en entornos de producción sin las salvaguardas adecuadas.

• Verificaciones de salud
• Estadísticas del sistema
• Monitorización de tareas
• Información de versión

Herramientas Disponibles

Gestión de Conexiones

• get-connection-settings: Ver la URL de conexión actual de Meilisearch y el estado de la clave API
• update-connection-settings: Actualizar la URL y/o clave API para conectarse a una instancia diferente

Gestión de Índices

• create-index: Crear un nuevo índice con clave primaria opcional
• list-indexes: Listar todos los índices disponibles
• delete-index: Eliminar un índice existente y todos sus documentos
• get-index-metrics: Obtener métricas detalladas para un índice específico

Operaciones con Documentos

• get-documents: Recuperar documentos de un índice con paginación
• add-documents: Añadir o actualizar documentos en un índice

Búsqueda

• search: Búsqueda flexible en uno o varios índices con opciones de filtrado y ordenación

Gestión de Ajustes

• get-settings: Ver los ajustes actuales de un índice
• update-settings: Actualizar los ajustes del índice (clasificación, facetado, etc.)

Gestión de Claves API

• get-keys: Listar todas las claves API
• create-key: Crear una nueva clave API con permisos específicos
• delete-key: Eliminar una clave API existente

Gestión de Tareas

• get-task: Obtener información sobre una tarea específica
• get-tasks: Listar tareas con filtros opcionales
• cancel-tasks: Cancelar tareas pendientes o en cola
• delete-tasks: Eliminar tareas completadas

Monitorización del Sistema

• health-check: Verificación básica de salud
• get-health-status: Estado de salud completo
• get-version: Obtener información de la versión de Meilisearch
• get-stats: Obtener estadísticas de la base de datos
• get-system-info: Obtener información a nivel de sistema

Configuración de Desarrollo

Requisitos Previos

1. Inicia el servidor Meilisearch:

   # Using Docker (recommended for development)
   docker run -d -p 7700:7700 getmeili/meilisearch:v1.28
   
   # Or using brew (macOS)
   brew install meilisearch
   meilisearch
   
   # Or download from https://github.com/meilisearch/meilisearch/releases
   

2. Instala herramientas de desarrollo:

   # Install uv for Python package management
   pip install uv
   
   # Install Node.js for MCP Inspector testing
   # Visit https://nodejs.org/ or use your package manager
   

Ejecución de Pruebas

Este proyecto incluye pruebas de integración exhaustivas que verifican la funcionalidad de las herramientas MCP:

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_mcp_client.py -v

# Run tests with coverage report
python -m pytest --cov=src tests/

# Run tests in watch mode (requires pytest-watch)
pytest-watch tests/

Importante: Las pruebas requieren una instancia de Meilisearch en ejecución en http://localhost:7700.

Calidad del Código

# Format code with Black
black src/ tests/

# Run type checking (if mypy is configured)
mypy src/

# Lint code (if flake8 is configured)
flake8 src/ tests/

Guías de Contribución

1. Haz un fork y clona el repositorio
2. Configura el entorno de desarrollo siguiendo la sección de Configuración de Desarrollo anterior
3. Crea una rama de funcionalidad desde main
4. Escribe las pruebas primero si añades nueva funcionalidad (Desarrollo Guiado por Pruebas)
5. Ejecuta las pruebas localmente para asegurar que todas pasan antes de confirmar
6. Formatea el código con Black y asegura la calidad del código
7. Confirma los cambios con mensajes descriptivos
8. Sube a tu fork y crea una pull request

Flujo de Trabajo de Desarrollo

# Create feature branch
git checkout -b feature/your-feature-name

# Make your changes, write tests first
# Edit files...

# Run tests to ensure everything works
python -m pytest tests/ -v

# Format code
black src/ tests/

# Commit and push
git add .
git commit -m "Add feature description"
git push origin feature/your-feature-name

Directrices de Pruebas

• Todas las nuevas funcionalidades deben incluir pruebas
• Las pruebas deben pasar antes de enviar PRs
• Usa nombres de prueba descriptivos y afirmaciones claras
• Prueba tanto casos de éxito como de error
• Asegúrate de que Meilisearch esté en ejecución antes de lanzar las pruebas

Proceso de Publicación

Este proyecto utiliza versionado y publicación automatizados en PyPI. El proceso de publicación está diseñado para ser simple y automatizado.

Cómo Funcionan las Publicaciones

1. Publicación Automatizada: Cuando el número de versión en pyproject.toml cambia en la rama main, una GitHub Action automáticamente:

   • Construye el paquete Python
   • Lo publica en PyPI usando publicación confiable
   • Crea una nueva publicación en GitHub

2. Detección de Versión: El flujo de trabajo compara la versión actual en pyproject.toml con el commit anterior para detectar cambios

3. Publicación en PyPI: Usa la acción oficial de publicación de PyPA con publicación confiable (no se necesitan claves API manuales)

Crear una Nueva Publicación

Para crear una nueva publicación, sigue estos pasos:

1. Determinar el Número de Versión

Sigue el Versionado Semántico (MAYOR.MENOR.PARCHE):

• PARCHE (ej., 0.4.0 → 0.4.1): Corrección de errores, actualizaciones de documentación, mejoras menores
• MENOR (ej., 0.4.0 → 0.5.0): Nuevas funcionalidades, nuevas herramientas MCP, mejoras significativas
• MAYOR (ej., 0.5.0 → 1.0.0): Cambios disruptivos, cambios importantes en la API

2. Actualizar Versión y Crear PR

# 1. Create a branch from latest main
git checkout main
git pull origin main
git checkout -b release/v0.5.0

# 2. Update version in pyproject.toml
# Edit the version = "0.4.0" line to your new version

# 3. Commit and push
git add pyproject.toml
git commit -m "Bump version to 0.5.0"
git push origin release/v0.5.0

# 4. Create PR and get it reviewed/merged
gh pr create --title "Release v0.5.0" --body "Bump version for release"

3. Fusionar a Principal

Una vez que la PR sea aprobada y fusionada a main, la GitHub Action automáticamente:

1. Detectará el cambio de versión
2. Construirá el paquete
3. Publicará en PyPI en https://pypi.org/p/meilisearch-mcp
4. Hará disponible la nueva versión mediante pip install meilisearch-mcp

4. Verificar la Publicación

Después de fusionar, verifica la publicación:

# Check GitHub Action status
gh run list --workflow=publish.yml

# Verify on PyPI (may take a few minutes)
pip index versions meilisearch-mcp

# Test installation of new version
pip install --upgrade meilisearch-mcp

Archivo de Flujo de Trabajo de Publicación

La publicación automatizada es manejada por .github/workflows/publish.yml, que:

• Se activa en pushes a la rama main
• Verifica si la versión en pyproject.toml cambió
• Usa Python 3.10 y herramientas de construcción oficiales
• Publica usando publicación confiable (no se requieren claves API)
• Proporciona salida detallada para depuración

Solución de Problemas de Publicación

La publicación no se activó: Verifica que la versión en pyproject.toml realmente cambiara entre commits

La construcción falló: Revisa los registros de GitHub Actions para errores de construcción del paquete Python

La publicación en PyPI falló: Verifica el nombre del paquete y que la publicación confiable esté configurada correctamente

Conflictos de versión: Asegúrate de que el nuevo número de versión no se haya usado antes en PyPI

Versiones de Desarrollo vs Producción

• Desarrollo: Instalar desde el código fuente usando pip install -e .
• Producción: Instalar desde PyPI usando pip install meilisearch-mcp
• Versión específica: Instalar usando pip install meilisearch-mcp==0.5.0