npm - sinapse-ai - Versions diffs - 5.0.8 → 6.0.1 - Mend

sinapse-ai 5.0.8 → 6.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (660) hide show

package/docs/es/guides/mcp/docker-gateway-tutorial.md DELETED Viewed

@@ -1,336 +0,0 @@
-# Tutorial de Docker Gateway MCP
-> **ES** | [PT](../../pt/guides/mcp/docker-gateway-tutorial.md)
----
-Tutorial para configurar docker-gateway con servidores MCP ejecutándose dentro de contenedores Docker.
-**Versión:** 1.0.0
-**Última Actualización:** 2026-01-28
----
-## ¿Qué es Docker Gateway?
-Docker Gateway es un servidor MCP que actúa como un **puente** entre Claude Code y múltiples servidores MCP ejecutándose dentro de contenedores Docker.
-### Beneficio Clave: Sin Costo Extra de Tokens
-Cuando los MCPs se ejecutan dentro de docker-gateway, sus definiciones de herramientas están **encapsuladas** en el contenedor. Esto significa:
-| Configuración            | Costo de Tokens      | Definiciones de Herramientas en Contexto |
-| ------------------------ | -------------------- | ---------------------------------------- |
-| Directo en ~/.claude.json | Cada MCP suma tokens | Sí, todos los esquemas de herramientas visibles |
-| Dentro de docker-gateway | **Sin costo extra**  | Encapsuladas en el contenedor            |
-**¿Por qué?** Claude Code solo ve las herramientas de docker-gateway (`mcp-add`, `mcp-find`, etc.), no las herramientas individuales de cada MCP interno. Las herramientas reales se invocan a través del gateway.
----
-## Requisitos Previos
-- **Docker Desktop** 4.37+ instalado y ejecutándose
-- CLI de **Claude Code** instalado
-- Claves API para los servicios MCP deseados
----
-## Paso 1: Inicializar Docker MCP Toolkit
-```bash
-# Inicializar el sistema de catálogo
-docker mcp catalog init
-# Verificar inicialización
-docker mcp catalog ls
-```
-**Salida esperada:**
-```
-docker-mcp: Docker MCP Catalog
-```
-El catálogo contiene más de 313 servidores MCP disponibles para habilitar.
----
-## Paso 2: Explorar Servidores Disponibles
-```bash
-# Listar todos los servidores disponibles
-docker mcp catalog show docker-mcp
-# Buscar servidor específico
-docker mcp catalog show docker-mcp | grep -i apify
-docker mcp catalog show docker-mcp | grep -i exa
-```
----
-## Paso 3: Habilitar Servidores MCP
-```bash
-# Habilitar servidores que deseas usar
-docker mcp server enable apify-mcp-server
-docker mcp server enable exa
-docker mcp server enable context7
-# Listar servidores habilitados
-docker mcp server ls
-```
----
-## Paso 4: Configurar Claves API
-### Método 1: Usando Docker MCP Secrets (puede tener bugs)
-```bash
-# Establecer secrets
-docker mcp secret set APIFY_TOKEN "your-apify-token"
-docker mcp secret set EXA_API_KEY "your-exa-api-key"
-```
-### Método 2: Editar Archivo de Catálogo Directamente (solución recomendada)
-Debido a un bug conocido (Dic 2025), los secrets pueden no pasar correctamente a los contenedores.
-**Solución alternativa:** Editar `~/.docker/mcp/catalogs/docker-mcp.yaml` directamente:
-```yaml
-# Encuentra la entrada de tu MCP y agrega valores env
-apify-mcp-server:
-  env:
-    - name: APIFY_TOKEN
-      value: 'apify_api_xxxxxxxxxxxxx'
-    - name: TOOLS
-      value: 'actors,docs,apify/rag-web-browser'
-exa:
-  env:
-    - name: EXA_API_KEY
-      value: 'your-exa-api-key-here'
-```
-⚠️ **Nota de seguridad:** Esto expone credenciales en un archivo local. Establece permisos apropiados:
-```bash
-chmod 600 ~/.docker/mcp/catalogs/docker-mcp.yaml
-```
----
-## Paso 5: Configurar Claude Code
-Agregar docker-gateway a `~/.claude.json`:
-```json
-{
-  "mcpServers": {
-    "docker-gateway": {
-      "type": "stdio",
-      "command": "docker",
-      "args": ["mcp", "gateway", "run"]
-    }
-  }
-}
-```
-O usar el CLI de Claude:
-```bash
-claude mcp add docker-gateway -s user -- docker mcp gateway run
-```
----
-## Paso 6: Verificar Configuración
-```bash
-# Verificar herramientas disponibles a través del gateway
-docker mcp tools ls
-# La salida esperada muestra herramientas del gateway + herramientas de servidores habilitados
-# Ejemplo: 58 herramientas (7 del gateway + 51 de servidores habilitados)
-```
-En Claude Code:
-```bash
-# Listar estado de MCP
-claude mcp list
-# Debería mostrar:
-# docker-gateway: docker mcp gateway run - ✓ Connected
-```
----
-## Usando Docker Gateway
-### Herramientas del Gateway Disponibles
-| Herramienta          | Descripción                                |
-| -------------------- | ------------------------------------------ |
-| `mcp-add`            | Agregar servidor MCP a la sesión actual    |
-| `mcp-find`           | Buscar servidores en el catálogo           |
-| `mcp-remove`         | Eliminar servidor MCP de la sesión         |
-| `mcp-exec`           | Ejecutar herramienta de servidor habilitado |
-| `mcp-config-set`     | Configurar ajustes del servidor MCP        |
-| `code-mode`          | Crear herramientas JavaScript combinadas   |
-| `mcp-create-profile` | Guardar estado actual del gateway          |
-### Accediendo a Herramientas de Servidores Habilitados
-Una vez habilitados los servidores, sus herramientas están disponibles a través del gateway:
-```
-# Herramientas de Apify (vía docker-gateway)
-mcp__docker-gateway__search-actors
-mcp__docker-gateway__call-actor
-mcp__docker-gateway__apify-slash-rag-web-browser
-# Herramientas de EXA (vía docker-gateway)
-mcp__docker-gateway__web_search_exa
-mcp__docker-gateway__company_research
-# Herramientas de Context7 (vía docker-gateway)
-mcp__docker-gateway__resolve-library-id
-mcp__docker-gateway__query-docs
-```
----
-## Ejemplo de Configuración Completa
-### ~/.claude.json
-```json
-{
-  "mcpServers": {
-    "desktop-commander": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@wonderwhy-er/desktop-commander"]
-    },
-    "docker-gateway": {
-      "type": "stdio",
-      "command": "docker",
-      "args": ["mcp", "gateway", "run"]
-    },
-    "playwright": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@anthropic/mcp-playwright"]
-    }
-  }
-}
-```
-### Resultado
-```
-User MCPs (4 servers):
-├── desktop-commander  ✓ connected
-├── docker-gateway     ✓ connected  (58 tools inside)
-├── playwright         ✓ connected
-└── n8n-mcp           ✓ connected
-Inside docker-gateway:
-├── apify-mcp-server   (7 tools)
-├── exa                (8 tools)
-├── context7           (2 tools)
-└── + gateway tools    (7 tools)
-```
----
-## Resolución de Problemas
-### El Gateway No Inicia
-```bash
-# Verificar que Docker está ejecutándose
-docker info
-# Verificar logs del gateway
-docker mcp gateway run --verbose
-```
-### Las Herramientas Muestran "(N prompts)" en Lugar de "(N tools)"
-Esto indica fallo de autenticación. Usa la solución alternativa:
-```bash
-# Editar catálogo directamente con credenciales hardcoded
-nano ~/.docker/mcp/catalogs/docker-mcp.yaml
-```
-### Servidor No Encontrado
-```bash
-# Actualizar catálogo
-docker mcp catalog update
-# Verificar que el servidor existe
-docker mcp catalog show docker-mcp | grep -i "server-name"
-```
-### Reiniciar Todo
-```bash
-# Deshabilitar todos los servidores
-docker mcp server reset
-# Reiniciar catálogo
-docker mcp catalog reset
-# Re-inicializar
-docker mcp catalog init
-```
----
-## Mejores Prácticas
-### 1. Usar docker-gateway para MCPs basados en API
-Colocar estos dentro de docker-gateway (no necesitan acceso al host):
-- Apify (APIs de web scraping)
-- EXA (APIs de búsqueda)
-- Context7 (APIs de documentación)
-- Cualquier integración cloud/SaaS
-### 2. Mantener MCPs con acceso al host directos
-Mantener estos en ~/.claude.json directamente:
-- desktop-commander (necesita acceso a archivos/terminal del host)
-- playwright (necesita navegador del host)
-- MCPs de filesystem
-### 3. Asegurar tus credenciales
-```bash
-# Establecer permisos restrictivos
-chmod 600 ~/.docker/mcp/catalogs/docker-mcp.yaml
-chmod 700 ~/.docker/mcp/
-# Nunca hacer commit de estos archivos
-echo "~/.docker/mcp/" >> ~/.gitignore_global
-```
----
-## Documentación Relacionada
-- [Guía de Desktop Commander MCP](./desktop-commander.md)
-- [Guía de Configuración Global MCP](../mcp-global-setup.md)
-- [Configuración de Docker MCP](../../docker-mcp-setup.md)
----
-_Tutorial de Docker Gateway MCP v1.0.0 - SINAPSE Framework_