Code Sync MCP Server

Recarga en caliente aplicaciones Python contenerizadas remotas directamente desde tu IDE.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Code Sync MCP Server

Recarga en caliente tus aplicaciones Python contenerizadas remotas directamente desde tu IDE usando MCP (Model Context Protocol).

La arquitectura de Code Sync MCP cierra la brecha entre el desarrollo local y los contenedores remotos para lenguajes interpretados: Python, Ruby u otro código interpretado en tu editor local, y verás los cambios reflejados al instante en contenedores que se ejecutan en cualquier lugar (staging, clústeres de desarrollo, entornos en la nube o incluso producción). No se necesita paso de compilación: los cambios surten efecto de inmediato.

Qué Hace

  • Sincronización remota instantánea: Los cambios en tu editor local aparecen inmediatamente en contenedores que se ejecutan en cualquier lugar
  • Soporte multi-entorno: Cada desarrollador puede apuntar a su propio entorno remoto
  • Cambios mínimos en el contenedor: Solo envuelve tu entrypoint existente; no se necesitan reescrituras de Dockerfile
  • Integración con IDE: Funciona a través de herramientas MCP en editores como Cursor
  • Acceso remoto seguro: Autenticación con clave API para conexiones remotas seguras en producción

Demostración

El docker-compose.yaml incluido ejecuta todo localmente con una aplicación de demostración.

Esta demostración muestra cómo introducir un error en un health check, verlo fallar inmediatamente y luego corregirlo en tiempo real.

Cómo Funciona

Cuando haces un cambio de código en tu editor:

  1. Llamada a herramienta MCP se dispara desde tu editor (por ejemplo, Cursor)
  2. rsync local genera un parche de tus cambios
  3. Proxy remoto (que se ejecuta en tu entorno de nube/staging) recibe el parche y lo enruta al despliegue adecuado
  4. Sidecar (que se ejecuta junto al contenedor de tu aplicación) aplica los cambios a un volumen compartido
  5. Tu aplicación remota se reinicia automáticamente con el nuevo código

Architecture diagram

Todos los componentes excepto el servidor MCP se ejecutan en tu entorno remoto

Guía de Configuración

Requisitos Previos

  • Entorno remoto de Docker/contenedores (Kubernetes, Docker Swarm, instancias en la nube, etc.)
  • Editor local con soporte MCP (como Cursor)
  • Una clave API para asegurar conexiones remotas

1. Despliega el Proxy en tu entorno remoto

El proxy es un servidor websocket central que enruta los cambios de código a los contenedores correctos.

Despliega code-sync-proxy con:

PROXY_API_KEY=your-secret-key-here

Solo necesitas un proxy por entorno remoto para todas tus aplicaciones y desarrolladores.

2. Configura tu Aplicación Remota (Por App/Despliegue)

Para cada despliegue de aplicación, necesitas dos cambios:

A) Modifica el entrypoint de tu contenedor

Reemplaza tu entrypoint existente con este wrapper que espera al sistema de sincronización:

# Simple one-liner approach (recommended)
sh -c "while [ ! -f /app-files/.sidecar/rsync-launcher.sh ]; do echo 'Waiting for sync...'; sleep 1; done && /app-files/.sidecar/rsync-launcher.sh 'YOUR_ORIGINAL_COMMAND_HERE'"

O usa la plantilla de script proporcionada.

B) Añade el contenedor sidecar a tu despliegue remoto

Despliega el contenedor code-sync-sidecar junto a tu aplicación con estas variables de entorno:

BIFROST_API_URL=http://your-proxy-url
BIFROST_API_KEY=your-secret-key-here   # Same as proxy
BIFROST_APP_ID=my-app                  # Unique app identifier
BIFROST_DEPLOYMENT_ID=dev-john         # Unique deployment name

Ejemplos de despliegue:

  • Kubernetes: Añádelo como contenedor sidecar en tu spec de pod
  • Docker Compose: Añádelo como un servicio adicional con volúmenes compartidos
  • ECS: Añádelo como contenedor sidecar en tu definición de tarea

C) [Si es necesario] Asegúrate de que tu aplicación tenga permisos para sincronizar (si no se ejecuta como root)

Añade a tu Dockerfile:

RUN useradd -m appuser
RUN chown -R appuser:appuser /app
USER appuser

3. Configura tu Editor

Para Cursor, añade esto a tu configuración MCP local apuntando a tu proxy remoto:

{
  "mcpServers": {
    "code-sync": {
      "command": "uvx code-sync-mcp",
      "env": {
        "BIFROST_API_KEY": "your-secret-key-here",
        "BIFROST_WS_API_URL": "ws://your-proxy-url",
        "BIFROST_API_URL": "http://your-proxy-url"
      }
    }
  }
}

Verás que estas herramientas están disponibles: Cursor MCP tools

Luego necesitas añadir un archivo .bifrost.json a la raíz de tu aplicación:

{
    "app_id": "my-app",
    "deployment_id": "dev-john",
    "app_root": "absolute/path/to/code/root"
}

Uso

Una vez configurado, usa la herramienta push_changes en tu editor para sincronizar tus cambios de código locales con cualquier contenedor remoto. El sistema respeta tu archivo .gitignore automáticamente.

Flujo de trabajo de ejemplo:

  • Edita un archivo localmente en Cursor
  • Usa la herramienta MCP push_changes
  • Ve los cambios reflejados inmediatamente en tu entorno de staging remoto
  • Depura, itera y prueba, todo sin salir de tu editor local

Análisis Profundo de la Arquitectura

El sistema tiene cuatro componentes principales:

code-sync-mcp-server (Local)

  • Se ejecuta localmente en tu editor
  • Expone la herramienta MCP push_changes
  • Usa rsync para detectar y empaquetar cambios de manera eficiente
  • Respeta las reglas de .gitignore

code-sync-proxy (Remoto)

  • Servidor websocket central (basado en FastAPI) que se ejecuta en tu entorno remoto
  • Enruta lotes de cambios a las instancias sidecar correctas
  • Maneja la autenticación y la gestión de conexiones
  • Una instancia sirve a todas las aplicaciones y desarrolladores

code-sync-sidecar (Remoto)

  • Se ejecuta junto a cada contenedor en tu entorno remoto
  • Recibe lotes de cambios a través de websocket
  • Sincroniza archivos al volumen compartido con la aplicación principal
  • Envía SIGHUP para activar el reinicio de la aplicación

rsync-launcher.sh (Remoto)

  • Script wrapper para tu aplicación remota
  • Sincroniza archivos desde el volumen compartido al directorio de la aplicación
  • Maneja reinicios elegantes ante cambios de archivos
  • Modificación mínima de los contenedores existentes

Beneficios Clave para el Desarrollo Remoto

  • Elimina el ciclo de despliegue-prueba: No más esperas por CI/CD para cambios simples
  • Desarrollo remoto real: Trabaja con bases de datos, servicios e infraestructura remotos
  • Múltiples entornos remotos: Cada desarrollador puede apuntar a su propio staging remoto
  • Pruebas similares a producción: Prueba en entornos que coinciden exactamente con producción

Demo Local (Para Pruebas)

Requisitos Previos

Antes de ejecutar la demo local, asegúrate de tener instalado lo siguiente:

  • Cliente MCP: Instala Cursor para esta demo
  • Rsync (versión 3.4.1 o superior):
    • macOS: brew install rsync && rsync --version
    • Otras plataformas: Verifica tu versión con rsync --version y actualiza si es necesario

Configuración y Ajustes

1. Clona e Inicia los Servicios

# Clone the repository
git clone https://github.com/bifrostinc/code-sync-mcp.git

# Start the local environment
docker-compose up

2. Abre el Proyecto en Cursor

cursor ./demo-app

3. Configura el Servidor MCP

Añade la siguiente configuración a tu configuración MCP de Cursor:

{
  "mcpServers": {
    "code-sync": {
      "command": "uvx code-sync-mcp",
      "env": {
        "UV_PYTHON": "3.13",
        "BIFROST_API_KEY": "test-secret-key",
        "BIFROST_WS_API_URL": "ws://localhost:8000",
        "BIFROST_API_URL": "http://localhost:8000"
      }
    }
  }
}

Probando la Demo

  1. Haz un cambio de código en demo-app/app.py (intenta añadir una Excepción al health check)

  2. Despliega tus cambios escribiendo en la ventana de chat de Cursor:

    deploy these changes

    Ejemplo:

    Cursor Demo Screenshot

  3. Observa los resultados:

    • Revisa los registros para ver la actividad de despliegue
    • Visita http://localhost:8080/health para ver el servicio actualizado
    • Anota cualquier error que pueda ocurrir durante el despliegue

Uso real: En un despliegue real, los componentes proxy y sidecar se ejecutarían en tu infraestructura remota en lugar de localmente. Esta demo simula ese entorno en tu máquina local con fines de prueba.