1RB · webbrain-one · Jul 27, 2026 · coderabbitai · Jul 27, 2026 · coderabbitai
diff --git a/README.es-ES.md 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://<username>:<password>@<host>:<port>/<database>?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://<username>:<password>@<host>:<port>/<database>?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.