sinapse-ai 5.0.8 → 6.0.1

package/docs/es/docker-mcp-setup.md

@@ -1,426 +0,0 @@
-# Guía de Configuración de Docker MCP
-
-> **ES**
-
----
-
-Guía para configurar servidores MCP (Model Context Protocol) basados en Docker con SINAPSE.
-
-**Versión:** 2.1.0
-**Última Actualización:** 2026-01-28
-
----
-
-## Requisitos Previos
-
-Antes de configurar Docker MCP, asegúrate de tener:
-
-- **Docker Desktop** instalado y en ejecución
-- **Node.js** 18+ instalado
-- Proyecto **SINAPSE** inicializado
-- Claves API para los servicios MCP deseados (EXA, Apify, etc.)
-
----
-
-## Instalación
-
-### Paso 1: Instalar Docker MCP Toolkit
-
-```bash
-# Instalar Docker MCP Toolkit
-docker mcp install
-
-# Verificar instalación
-docker mcp --version
-```
-
-### Paso 2: Inicializar Configuración MCP
-
-```bash
-# Crear estructura MCP global
-sinapse mcp setup
-```
-
-Esto crea:
-
-- `~/.sinapse/mcp/` - Directorio de configuración MCP
-- `~/.sinapse/mcp/global-config.json` - Archivo de configuración principal
-- `~/.sinapse/mcp/servers/` - Configuraciones de servidores individuales
-- `~/.sinapse/credentials/` - Almacenamiento seguro de credenciales
-
-### Paso 3: Agregar Servidores MCP
-
-```bash
-# Agregar servidores desde plantillas
-sinapse mcp add context7
-sinapse mcp add exa
-sinapse mcp add github
-```
-
----
-
-## Configuración
-
-### Arquitectura MCP
-
-SINAPSE usa Docker MCP Toolkit como infraestructura MCP principal:
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    Claude Code                           │
-│                         │                                │
-│    ┌────────────────────┼────────────────────┐          │
-│    │                    │                    │          │
-│    ▼                    ▼                    ▼          │
-│ playwright      docker-gateway           native tools   │
-│ (direct)        (container MCPs)         (Read, Write)  │
-│                         │                                │
-│              ┌──────────┼──────────┐                    │
-│              ▼          ▼          ▼                    │
-│            EXA     Context7     Apify                   │
-│         (search)   (docs)     (scraping)               │
-└─────────────────────────────────────────────────────────┘
-```
-
-### Directo en Claude Code (global ~/.claude.json)
-
-| MCP                   | Propósito                                        |
-| --------------------- | ------------------------------------------------ |
-| **playwright**        | Automatización de navegador, capturas, testing web |
-| **desktop-commander** | Operaciones de contenedores Docker vía docker-gateway |
-
-### Dentro de Docker Desktop (vía docker-gateway)
-
-| MCP          | Propósito                                            |
-| ------------ | ---------------------------------------------------- |
-| **EXA**      | Búsqueda web, investigación, análisis de empresas/competidores |
-| **Context7** | Búsqueda de documentación de librerías              |
-| **Apify**    | Web scraping, Actors, extracción de datos de redes sociales |
-
-### Archivos de Configuración
-
-**global-config.json:**
-
-```json
-{
-  "version": "1.0",
-  "servers": {
-    "context7": {
-      "type": "sse",
-      "url": "https://mcp.context7.com/sse",
-      "enabled": true
-    },
-    "exa": {
-      "command": "npx",
-      "args": ["-y", "exa-mcp-server"],
-      "env": {
-        "EXA_API_KEY": "${EXA_API_KEY}"
-      },
-      "enabled": true
-    }
-  },
-  "defaults": {
-    "timeout": 30000,
-    "retries": 3
-  }
-}
-```
-
----
-
-## MCPs Disponibles
-
-### Context7 (Búsqueda de Documentación)
-
-```bash
-# Agregar Context7
-sinapse mcp add context7
-
-# Uso
-mcp__context7__resolve-library-id
-mcp__context7__query-docs
-```
-
-**Usar para:**
-
-- Búsqueda de documentación de librerías
-- Referencia API para paquetes/frameworks
-- Obtener documentación actualizada de dependencias
-
-### EXA (Búsqueda Web)
-
-```bash
-# Agregar EXA
-sinapse mcp add exa
-
-# Configurar clave API
-export EXA_API_KEY="your-api-key"
-
-# Uso
-mcp__exa__web_search_exa
-mcp__exa__get_code_context_exa
-```
-
-**Usar para:**
-
-- Búsquedas web de información actual
-- Investigación y búsqueda de documentación
-- Investigación de empresas y competidores
-- Encontrar ejemplos de código en línea
-
-### Apify (Web Scraping)
-
-```bash
-# Agregar Apify
-sinapse mcp add apify
-
-# Configurar token API
-export APIFY_TOKEN="your-token"
-
-# Uso
-mcp__docker-gateway__search-actors
-mcp__docker-gateway__call-actor
-```
-
-**Usar para:**
-
-- Web scraping para redes sociales (Instagram, TikTok, LinkedIn)
-- Extraer datos de sitios de e-commerce
-- Recolección automatizada de datos de cualquier sitio web
-- Navegación web habilitada para RAG para contexto de IA
-
-### GitHub (Integración API)
-
-```bash
-# Agregar GitHub
-sinapse mcp add github
-
-# Configurar token
-export GITHUB_TOKEN="your-token"
-```
-
-**Usar para:**
-
-- Operaciones de API de GitHub
-- Gestión de repositorios
-- Manejo de PRs e issues
-
-### Playwright (Automatización de Navegador)
-
-```bash
-# Agregar Playwright
-sinapse mcp add puppeteer
-```
-
-**Usar para:**
-
-- Automatización de navegador
-- Capturar screenshots de páginas web
-- Interactuar con sitios web
-- Web scraping y testing
-
----
-
-## Comandos CLI
-
-### Comandos de Configuración
-
-```bash
-# Inicializar configuración MCP global
-sinapse mcp setup
-
-# Forzar recreación (respaldar existente)
-sinapse mcp setup --force
-```
-
-### Gestión de Servidores
-
-```bash
-# Agregar servidor desde plantilla
-sinapse mcp add <server-name>
-
-# Agregar con configuración personalizada
-sinapse mcp add custom-server --config='{"command":"npx","args":["-y","package"]}'
-
-# Eliminar servidor
-sinapse mcp remove <server-name>
-
-# Habilitar/deshabilitar servidores
-sinapse mcp enable <server-name>
-sinapse mcp disable <server-name>
-```
-
-### Estado y Listado
-
-```bash
-# Listar servidores configurados
-sinapse mcp list
-
-# Mostrar estado detallado
-sinapse mcp status
-
-# Sincronizar al proyecto
-sinapse mcp sync
-```
-
----
-
-## Variables de Entorno
-
-### Configurar Variables
-
-**macOS/Linux:**
-
-```bash
-export EXA_API_KEY="your-api-key"
-export GITHUB_TOKEN="your-github-token"
-export APIFY_TOKEN="your-apify-token"
-```
-
-**Windows (PowerShell):**
-
-```powershell
-$env:EXA_API_KEY = "your-api-key"
-$env:GITHUB_TOKEN = "your-github-token"
-$env:APIFY_TOKEN = "your-apify-token"
-```
-
-### Variables Persistentes
-
-Agregar a tu perfil de shell (`~/.bashrc`, `~/.zshrc`, o `~/.profile`):
-
-```bash
-export EXA_API_KEY="your-api-key"
-export GITHUB_TOKEN="your-github-token"
-export APIFY_TOKEN="your-apify-token"
-```
-
-### Almacenamiento Seguro de Credenciales
-
-```bash
-# Agregar credencial
-sinapse mcp credential set EXA_API_KEY "your-api-key"
-
-# Obtener credencial
-sinapse mcp credential get EXA_API_KEY
-
-# Listar credenciales (enmascaradas)
-sinapse mcp credential list
-```
-
----
-
-## Solución de Problemas
-
-### Problemas Comunes
-
-| Problema                       | Solución                                               |
-| ------------------------------ | ------------------------------------------------------ |
-| Permiso denegado               | Ejecutar terminal como Administrador (Windows) o usar sudo |
-| Servidor no inicia             | Verificar command y args, verificar paquete instalado  |
-| Variable de entorno no encontrada | Configurar variable o usar almacenamiento de credenciales |
-| Errores de timeout             | Aumentar timeout en configuración                      |
-| Conexión rechazada             | Verificar URL y acceso a red                           |
-
-### Bug de Secrets de Docker MCP (Dic 2025)
-
-**Problema:** El almacén de secrets de Docker MCP Toolkit (`docker mcp secret set`) y la interpolación de plantillas (`{{...}}`) NO funcionan correctamente. Las credenciales no se pasan a los contenedores.
-
-**Síntomas:**
-
-- `docker mcp tools ls` muestra "(N prompts)" en lugar de "(N tools)"
-- El servidor MCP inicia pero falla la autenticación
-- La salida verbose muestra `-e ENV_VAR` sin valores
-
-**Solución alternativa:** Editar `~/.docker/mcp/catalogs/docker-mcp.yaml` directamente:
-
-```yaml
-{ mcp-name }:
-  env:
-    - name: API_TOKEN
-      value: 'actual-token-value-here'
-```
-
-**Ejemplo - Apify:**
-
-```yaml
-apify-mcp-server:
-  env:
-    - name: TOOLS
-      value: 'actors,docs,apify/rag-web-browser'
-    - name: APIFY_TOKEN
-      value: 'apify_api_xxxxxxxxxxxxx'
-```
-
-**Nota:** Esto expone credenciales en un archivo local. Asegurar permisos de archivo y nunca hacer commit de este archivo.
-
-### Correcciones Comunes
-
-```bash
-# Resetear configuración global
-sinapse mcp setup --force
-
-# Limpiar caché
-rm -rf ~/.sinapse/mcp/cache/*
-
-# Verificar configuración
-sinapse mcp status --verbose
-
-# Probar servidor manualmente
-npx -y @modelcontextprotocol/server-github
-```
-
----
-
-## Gobernanza MCP
-
-**Importante:** Toda la gestión de infraestructura MCP es manejada exclusivamente por el **Agente DevOps (@devops / Felix)**.
-
-| Operación          | Agente | Comando             |
-| ------------------ | ------ | ------------------- |
-| Buscar catálogo MCP | DevOps | `*search-mcp`      |
-| Agregar servidor MCP | DevOps | `*add-mcp`        |
-| Listar MCPs habilitados | DevOps | `*list-mcps`   |
-| Eliminar servidor MCP | DevOps | `*remove-mcp`    |
-| Configurar Docker MCP | DevOps | `*setup-mcp-docker` |
-
-Otros agentes (Dev, Architect, etc.) son **consumidores** de MCP, no administradores. Si se necesita gestión de MCP, delegar a @devops.
-
----
-
-## Prioridad de Selección de Herramientas
-
-Siempre preferir herramientas nativas de Claude Code sobre servidores MCP:
-
-| Tarea            | USAR ESTO              | NO ESTO        |
-| ---------------- | ---------------------- | -------------- |
-| Leer archivos    | `Read` tool            | docker-gateway |
-| Escribir archivos | `Write` / `Edit` tools | docker-gateway |
-| Ejecutar comandos | `Bash` tool           | docker-gateway |
-| Buscar archivos  | `Glob` tool            | docker-gateway |
-| Buscar contenido | `Grep` tool            | docker-gateway |
-| Listar directorios | `Bash(ls)` o `Glob`  | docker-gateway |
-
-### Cuándo Usar docker-gateway
-
-Solo usar docker-gateway cuando:
-
-1. El usuario dice explícitamente "usa docker" o "usa contenedor"
-2. El usuario menciona explícitamente "Desktop Commander"
-3. La tarea específicamente requiere operaciones de contenedores Docker
-4. Accediendo MCPs ejecutándose dentro de Docker (EXA, Context7)
-5. El usuario pide ejecutar algo dentro de un contenedor Docker
-
----
-
-## Documentación Relacionada
-
-- [Tutorial Docker Gateway](./guides/mcp/docker-gateway-tutorial.md)
-- [Guía MCP Desktop Commander](./guides/mcp/desktop-commander.md)
-- [Guía de Configuración Global MCP](./guides/mcp-global-setup.md)
-- [Diagramas de Arquitectura MCP](./architecture/mcp-system-diagrams.md)
-- [Agente DevOps](../.sinapse-ai/development/agents/devops.md)
-
----
-
-_Guía de Configuración de Docker MCP de SINAPSE v4.0_

package/docs/es/framework/README.md

@@ -1,99 +0,0 @@
-<!--
-  Traducción: ES
-  Original: /docs/en/framework/README.md
-  Última sincronización: 2026-01-26
--->
-
-# Documentación del Framework SINAPSE
-
-> 🌐 [EN](../../framework/README.md) | [PT](../../pt/framework/README.md) | **ES**
-
----
-
-**Estado:** Estándares Oficiales del Framework
-**Creado:** 2025-01-16 (Story 6.1.2.6)
-**Objetivo de Migración:** Q2 2026 → repositorio `SinapseAI/sinapse-ai`
-
----
-
-## Descripción General
-
-Este directorio contiene la **documentación oficial del framework SINAPSE** que define estándares, patrones y estructuras aplicables a todos los proyectos SINAPSE (greenfield y brownfield).
-
-**Propósito**: Separar la documentación a nivel de framework de los detalles de implementación específicos del proyecto.
-
----
-
-## Inventario de Documentación
-
-| Documento                                      | Propósito                                                                                   | Audiencia                     |
-| ---------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------- |
-| [**coding-standards.md**](coding-standards.md) | Estándares JavaScript/TypeScript, convenciones de nomenclatura, reglas de calidad de código | Todos los desarrolladores     |
-| [**tech-stack.md**](tech-stack.md)             | Elecciones tecnológicas, frameworks, bibliotecas y estándares de herramientas               | Arquitectos, desarrolladores  |
-| [**source-tree.md**](source-tree.md)           | Estructura de directorios, organización de archivos y patrones de diseño del proyecto       | Todos los miembros del equipo |
-
----
-
-## Aviso de Migración
-
-**IMPORTANTE**: Estos documentos ahora están en el repositorio `SinapseAI/sinapse-ai`. La migración desde la antigua organización `sinapse/sinapse-ai` se completó en diciembre de 2024 como parte del OSR-9 (Rebranding).
-
-### Cronograma de Migración
-
-- **Fase 1 (Q1 2026 - Story 6.1.2.6):** Documentación del framework separada en `docs/framework/`
-- **Fase 2 (Q4 2024):** Repositorio migrado a `SinapseAI/sinapse-ai` (OSR-9)
-- **Fase 3 (Q3 2026):** Copias antiguas de `docs/architecture/` eliminadas del proyecto brownfield
-
-### Compatibilidad hacia Atrás
-
-Para compatibilidad hacia atrás, la documentación del framework permanece accesible en **ambas** ubicaciones hasta Q3 2026:
-
-- **Nueva ubicación** (preferida): `docs/framework/{nombre-doc}.md`
-- **Ubicación antigua** (obsoleta): `docs/architecture/{nombre-doc}.md`
-
-**Referencias**: Actualice los enlaces internos para usar `docs/framework/` para prepararse para la migración.
-
----
-
-## Documentación de Framework vs. Proyecto
-
-### Documentación del Framework (`docs/framework/`)
-
-- **Alcance**: Portable a través de todos los proyectos SINAPSE
-- **Ejemplos**: Estándares de codificación, stack tecnológico, estructura del árbol de código fuente
-- **Ciclo de vida**: Reside en el repositorio `SinapseAI/sinapse-ai`
-- **Cambios**: Requieren aprobación a nivel de framework
-
-### Documentación del Proyecto (`docs/architecture/project-decisions/`)
-
-- **Alcance**: Específico para la implementación brownfield
-- **Ejemplos**: Análisis de decisiones, revisiones arquitectónicas, decisiones de integración
-- **Ciclo de vida**: Reside permanentemente en el repositorio del proyecto
-- **Cambios**: Decididos por el equipo del proyecto
-
----
-
-## Guías de Uso
-
-### Para Desarrolladores
-
-1. **Lea la documentación del framework durante la incorporación** - Comprenda los estándares de SINAPSE
-2. **Consulte durante el desarrollo** - Asegure el cumplimiento con los patrones del framework
-3. **Proponga cambios mediante PRs** - Los estándares del framework evolucionan con aportes de la comunidad
-
-### Para Arquitectos
-
-1. **Mantenga la documentación del framework** - Mantenga los estándares actualizados y prácticos
-2. **Revise PRs para cumplimiento** - Asegure que el código siga los estándares documentados
-3. **Planifique la migración** - Prepárese para la separación del repositorio en Q2 2026
-
-### Para Mantenedores del Framework SINAPSE
-
-1. **Control de versiones** - Rastree cambios en los estándares del framework
-2. **Preparación para la migración** - Asegure que la documentación esté lista para la separación del repositorio
-3. **Consistencia entre proyectos** - Aplique los estándares de manera uniforme
-
----
-
-**Última Actualización**: 2025-12-14
-**Mantenedor**: Equipo del Framework SINAPSE