diff --git a/README.es-ES.md b/README.es-ES.md new file mode 100644 index 0000000..fb0a732 --- /dev/null +++ b/README.es-ES.md @@ -0,0 +1,308 @@ +# 🗄️ Servidor MCP de MongoDB para LLMs + +[![Node.js 18+](https://img.shields.io/badge/node-18%2B-blue.svg)](https://nodejs.org/en/) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![npm version](https://badge.fury.io/js/%40coderay%2Fmongo-mcp-server.svg)](https://www.npmjs.com/package/@coderay/mongo-mcp-server) +[![smithery badge](https://smithery.ai/badge/mongo-mcp)](https://smithery.ai/server/mongo-mcp) + +Un servidor del Model Context Protocol (MCP) que permite a los LLMs interactuar directamente con bases de datos MongoDB. Consulta colecciones, inspecciona esquemas y gestiona datos a través de lenguaje natural de forma fluida. + +## 📚 ¿Qué es el Model Context Protocol (MCP)? + +El Model Context Protocol (MCP) es un estándar abierto desarrollado por Anthropic que crea una forma universal para que los sistemas de IA se conecten con fuentes de datos y herramientas externas. MCP establece un canal de comunicación estandarizado entre: + +- **Clientes MCP**: Asistentes de IA como Claude que consumen datos (por ejemplo, Claude Desktop, Cursor.ai) +- **Servidores MCP**: Servicios que exponen datos y funcionalidad (como este servidor de MongoDB) + +Beneficios clave de MCP: +- **Acceso Universal**: Proporciona un único protocolo para que los asistentes de IA consulten datos de diversas fuentes. +- **Conexiones Estandarizadas**: Gestiona la autenticación, las políticas de uso y los formatos de datos de manera consistente. +- **Ecosistema Sostenible**: Promueve conectores reutilizables que funcionan en múltiples clientes de LLM. + +## ✨ Características + +- 🔍 Inspección del esquema de colecciones +- 📊 Consulta y filtrado de documentos +- 📈 Gestión de índices +- 📝 Operaciones de documentos (insertar, actualizar, eliminar) +- 🔒 Acceso seguro a la base de datos mediante cadenas de conexión +- 📋 Manejo de errores y validación exhaustiva + +## 📋 Prerrequisitos + +Antes de comenzar, asegúrate de tener: + +- [Node.js](https://nodejs.org/) (v18 o superior) +- Una instancia de [MongoDB](https://www.mongodb.com/) (local o remota) +- Un cliente MCP como [Claude Desktop](https://claude.ai/download) o [Cursor.ai](https://cursor.sh/) + +Puedes verificar tu instalación de Node.js ejecutando: +```bash +node --version # Debería mostrar v18.0.0 o superior +``` + +## 🚀 Inicio Rápido + +Para comenzar, busca la URL de conexión de tu MongoDB y añade esta configuración al archivo de configuración de Claude Desktop: + +**MacOS**: `~/Library/Application\ Support/Claude/claude_desktop_config.json` +**Windows**: `%APPDATA%/Claude/claude_desktop_config.json` + +```json +{ + "mcpServers": { + "mongodb": { + "command": "npx", + "args": [ + "mongo-mcp", + "mongodb://:@:/?authSource=admin" + ] + } + } +} +``` + +### Instalación vía Smithery + +[Smithery.ai](https://smithery.ai) es una plataforma de registro para servidores MCP que simplifica el descubrimiento y la instalación. Para instalar el Servidor MCP de MongoDB para Claude Desktop automáticamente vía Smithery: + +```bash +npx -y @smithery/cli install mongo-mcp --client claude +``` + +### Integración con Cursor.ai + +Para usar MongoDB MCP con Cursor.ai: + +1. Abre Cursor.ai y navega a Settings > Features +2. Busca "MCP Servers" en el panel de características +3. Añade un nuevo servidor MCP con la siguiente configuración: + - **Name**: `mongodb` + - **Command**: `npx` + - **Args**: `mongo-mcp mongodb://:@:/?authSource=admin` + +*Nota: Actualmente, Cursor solo soporta herramientas MCP en la función Agent in Composer.* + +### Configuración del Sandbox de Pruebas + +Si no tienes un servidor MongoDB para conectar y quieres crear un sandbox de muestra, sigue estos pasos: + +1. Inicia MongoDB usando Docker Compose: + +```bash +docker-compose up -d +``` + +2. Alimenta la base de datos con datos de prueba: + +```bash +npm run seed +``` + +### Configurar Claude Desktop + +Añade esta configuración al archivo de configuración de Claude Desktop: + +**MacOS**: `~/Library/Application\ Support/Claude/claude_desktop_config.json` +**Windows**: `%APPDATA%/Claude/claude_desktop_config.json` + +#### Modo de Desarrollo Local: + +```json +{ + "mcpServers": { + "mongodb": { + "command": "node", + "args": [ + "dist/index.js", + "mongodb://root:example@localhost:27017/test?authSource=admin" + ] + } + } +} +``` + +### Estructura de Datos del Sandbox de Pruebas + +El script de seed crea tres colecciones con datos de muestra: + +#### Usuarios (Users) + +- Información personal (nombre, email, edad) +- Dirección anidada con coordenadas +- Arrays de intereses +- Fechas de membresía + +#### Productos (Products) + +- Detalles del producto (nombre, SKU, categoría) +- Especificaciones anidadas +- Información de precio e inventario +- Etiquetas y calificaciones + +#### Pedidos (Orders) + +- Detalles del pedido con artículos +- Referencias de usuario +- Información de envío y pago +- Seguimiento de estado + +## 🎯 Prompts de Ejemplo + +Prueba estos prompts con Claude para explorar la funcionalidad: + +### Operaciones Básicas + +``` +"¿Qué colecciones están disponibles en la base de datos?" +"Muéstrame el esquema de la colección de usuarios" +"Busca todos los usuarios en San Francisco" +``` + +### Consultas Avanzadas + +``` +"Busca todos los productos electrónicos que estén en stock y cuesten menos de $1000" +"Muéstrame todos los pedidos del usuario john@example.com" +"Lista los productos con calificaciones superiores a 4.5" +``` + +### Gestión de Índices + +``` +"¿Qué índices existen en la colección de usuarios?" +"Crea un índice en la colección de productos para el campo 'category'" +"Lista todos los índices de todas las colecciones" +``` + +### Operaciones de Documentos + +``` +"Inserta un nuevo producto con nombre 'Gaming Laptop' en la colección de productos" +"Actualiza el estado del pedido con ID X a 'shipped'" +"Busca y elimina todos los productos que no tengan stock" +``` + +## 📝 Herramientas Disponibles + +El servidor proporciona estas herramientas para la interacción con la base de datos: + +### Herramientas de Consulta + +- `listCollections`: Lista las colecciones disponibles en la base de datos +- `find`: Consulta documentos con filtrado y proyección +- `insertOne`: Inserta un solo documento en una colección +- `updateOne`: Actualiza un solo documento en una colección +- `deleteOne`: Elimina un solo documento de una colección + +### Herramientas de Índices + +- `createIndex`: Crea un nuevo índice en una colección +- `dropIndex`: Elimina un índice de una colección +- `indexes`: Lista los índices de una colección + +## 🛠️ Desarrollo + +Este proyecto está construido con: + +- TypeScript para un desarrollo con seguridad de tipos +- Controlador de MongoDB para Node.js para las operaciones de base de datos +- Zod para la validación de esquemas +- SDK de Model Context Protocol para la implementación del servidor + +Para configurar el entorno de desarrollo: + +```bash +# Instalar dependencias +npm install + +# Construir el proyecto +npm run build + +# Ejecutar en modo de desarrollo +npm run dev + +# Ejecutar pruebas +npm test +``` + +## 🔒 Consideraciones de Seguridad + +Al utilizar este servidor MCP con tu base de datos MongoDB: + +1. **Crea un usuario de MongoDB dedicado** con los permisos mínimos necesarios para tu caso de uso. +2. **Nunca uses credenciales de administrador** en entornos de producción. +3. **Habilita el registro de acceso (logging)** para fines de auditoría. +4. **Establece permisos de lectura/escritura adecuados** en las colecciones. +5. **Usa parámetros de la cadena de conexión** para restringir el acceso (por ejemplo, `readPreference=secondary`). +6. **Considera la lista blanca de IPs** para restringir el acceso a la base de datos. + +⚠️ **IMPORTANTE**: Sigue siempre el principio de privilegio mínimo al configurar el acceso a la base de datos. + +## 🌐 Cómo Funciona + +El servidor MongoDB MCP: + +1. Se conecta a tu base de datos MongoDB usando la cadena de conexión proporcionada. +2. Expone las operaciones de MongoDB como herramientas que siguen la especificación MCP. +3. Valida las entradas usando Zod para seguridad y tipado. +4. Ejecuta las consultas y devuelve datos estructurados al cliente LLM. +5. Gestiona el pool de conexiones y el manejo adecuado de errores. + +Todas las operaciones se ejecutan con la validación correspondiente para prevenir problemas de seguridad, como ataques de inyección. + +## 📦 Despliegue + +Puedes desplegar este servidor MCP de varias maneras: + +- Localmente vía npx (como se muestra en el Inicio Rápido) +- Como un paquete global de npm: `npm install -g @coderay/mongo-mcp-server` +- En un contenedor Docker (ver Dockerfile en el repositorio) +- Como un servicio en plataformas como Heroku, Vercel o AWS + +## ❓ Solución de Problemas + +### Problemas Comunes + +1. **Errores de Conexión** + - Verifica que la cadena de conexión de MongoDB sea correcta. + - Comprueba que tu servidor MongoDB esté en ejecución y sea accesible. + - Asegúrate de que los permisos de red permitan la conexión. + +2. **Problemas de Autenticación** + - Confirma que el usuario y la contraseña sean correctos. + - Verifica que se haya especificado la base de datos de autenticación (generalmente `authSource=admin`). + - Comprueba si MongoDB requiere conexiones TLS/SSL. + +3. **Problemas de Ejecución de Herramientas** + - Reinicia Claude Desktop o Cursor.ai completamente. + - Revisa los logs para obtener mensajes de error detallados: + ```bash + # macOS + tail -n 20 -f ~/Library/Logs/Claude/mcp*.log + ``` + +4. **Problemas de Rendimiento** + - Considera añadir índices adecuados a los campos consultados frecuentemente. + - Usa la proyección para limitar los datos devueltos en las consultas. + - Usa los parámetros `limit` y `skip` para la paginación. + +### Obtener Ayuda + +Si encuentras problemas: +- Revisa la [Documentación de MCP](https://modelcontextprotocol.io) +- Envía un issue en nuestro [repositorio de GitHub](https://github.com/1rb/mongo-mcp/issues) + +## 🤝 Contribución + +¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar un Pull Request. + +1. Haz un fork del repositorio +2. Crea tu rama de funcionalidad (`git checkout -b feature/amazing-feature`) +3. Realiza tus cambios (`git commit -m 'Add some amazing feature'`) +4. Haz push a la rama (`git push origin feature/amazing-feature`) +5. Abre un Pull Request + +## 📜 Licencia + +Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo [LICENSE](LICENSE) para más detalles.