Code Sync MCP Server

Recarregue a quente aplicações Python containerizadas remotas diretamente da sua IDE.

Documentação

Code Sync MCP Server

Recarregue automaticamente seus aplicativos Python containerizados remotos diretamente da sua IDE usando MCP (Model Context Protocol).

A arquitetura do Code Sync MCP preenche a lacuna entre o desenvolvimento local e contêineres remotos para linguagens interpretadas — Python, Ruby ou outro código interpretado no seu editor local e veja as alterações refletidas instantaneamente em contêineres rodando em qualquer lugar (staging, clusters de desenvolvimento, ambientes de nuvem ou até produção). Nenhuma etapa de compilação é necessária — as alterações entram em vigor imediatamente.

O Que Ele Faz

Sincronização remota instantânea: Alterações no seu editor local aparecem imediatamente em contêineres rodando em qualquer lugar
Suporte a múltiplos ambientes: Cada desenvolvedor pode direcionar seu próprio ambiente remoto
Mudanças mínimas no contêiner: Basta envolver seu entrypoint existente — sem reescrever Dockerfiles
Integração com IDE: Funciona por meio de ferramentas MCP em editores como Cursor
Acesso remoto seguro: Autenticação por chave de API para conexões remotas seguras em produção

Demonstração

O docker-compose.yaml incluído executa tudo localmente com um aplicativo de demonstração.

Esta demonstração mostra a introdução de um bug em um health check, vendo-o quebrar imediatamente e depois corrigindo-o em tempo real.

Como Funciona

Quando você faz uma alteração de código no seu editor:

Chamada de ferramenta MCP é acionada a partir do seu editor (ex.: Cursor)
rsync local gera um patch das suas alterações
Proxy remoto (rodando no seu ambiente de nuvem/staging) recebe o patch e roteia para o deployment apropriado
Sidecar (rodando ao lado do contêiner do seu aplicativo) aplica as alterações a um volume compartilhado
Seu aplicativo remoto é reiniciado automaticamente com o novo código

Architecture diagram

Todos os componentes, exceto o servidor MCP, rodam no seu ambiente remoto

Guia de Configuração

Pré-requisitos

Ambiente remoto com Docker/contêineres (Kubernetes, Docker Swarm, instâncias de nuvem, etc.)
Editor local com suporte a MCP (como Cursor)
Uma chave de API para proteger conexões remotas

1. Implante o Proxy no seu ambiente remoto

O proxy é um servidor websocket central que roteia alterações de código para os contêineres corretos.

Implante code-sync-proxy com:

PROXY_API_KEY=your-secret-key-here

Você precisa apenas de um proxy por ambiente remoto para todos os seus aplicativos e desenvolvedores.

2. Configure Seu Aplicativo Remoto (Por App/Deployment)

Para cada deployment de aplicativo, você precisa de duas alterações:

A) Modifique o entrypoint do seu contêiner

Substitua seu entrypoint existente por este wrapper que aguarda o sistema de sincronização:

# 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'"

Ou use o modelo de script fornecido.

B) Adicione o contêiner sidecar ao seu deployment remoto

Implante o contêiner code-sync-sidecar junto com seu aplicativo com estas variáveis de ambiente:

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

Exemplos de deployment:

Kubernetes: Adicione como um contêiner sidecar na especificação do seu pod
Docker Compose: Adicione como um serviço adicional com volumes compartilhados
ECS: Adicione como um contêiner sidecar na definição da sua tarefa

C) [Se Necessário] Garanta que seu aplicativo tenha permissões para sincronizar (se não estiver rodando como root)

Adicione ao seu Dockerfile:

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

3. Configure Seu Editor

Para Cursor, adicione isto às suas configurações MCP locais apontando para o seu 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"
      }
    }
  }
}

Você verá estas ferramentas se tornarem disponíveis: Cursor MCP tools

Então você precisa adicionar um arquivo .bifrost.json à raiz do seu aplicativo:

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

Uso

Após a configuração, use a ferramenta push_changes no seu editor para sincronizar suas alterações de código locais para qualquer contêiner remoto. O sistema respeita seu arquivo .gitignore automaticamente.

Exemplo de fluxo de trabalho:

Edite um arquivo localmente no Cursor
Use a ferramenta MCP push_changes
Veja as alterações refletidas imediatamente no seu ambiente de staging remoto
Depure, itere e teste — tudo sem sair do seu editor local

Análise Aprofundada da Arquitetura

O sistema tem quatro componentes principais:

code-sync-mcp-server (Local)

Roda localmente no seu editor
Expõe a ferramenta MCP push_changes
Usa rsync para detectar e empacotar alterações com eficiência
Respeita as regras de .gitignore

code-sync-proxy (Remoto)

Servidor websocket central (baseado em FastAPI) rodando no seu ambiente remoto
Roteia lotes de alterações para as instâncias sidecar corretas
Lida com autenticação e gerenciamento de conexões
Uma instância atende todos os aplicativos e desenvolvedores

code-sync-sidecar (Remoto)

Roda ao lado de cada contêiner no seu ambiente remoto
Recebe lotes de alterações via websocket
Sincroniza arquivos para o volume compartilhado com o aplicativo principal
Envia SIGHUP para acionar o reinício do aplicativo

rsync-launcher.sh (Remoto)

Script wrapper para seu aplicativo remoto
Sincroniza arquivos do volume compartilhado para o diretório do aplicativo
Lida com reinícios graciosos em alterações de arquivos
Modificação mínima nos contêineres existentes

Principais Benefícios para Desenvolvimento Remoto

Elimine o ciclo de deploy-teste: Não espere mais por CI/CD para alterações simples
Desenvolvimento remoto verdadeiro: Trabalhe com bancos de dados, serviços e infraestrutura remotos
Múltiplos ambientes remotos: Cada desenvolvedor pode direcionar seu próprio staging remoto
Testes semelhantes à produção: Teste em ambientes que correspondem exatamente à produção

Demonstração Local (Para Testes)

Pré-requisitos

Antes de executar a demonstração local, certifique-se de ter o seguinte instalado:

Cliente MCP: Instale o Cursor para esta demonstração
Rsync (versão 3.4.1 ou mais recente):
- macOS: brew install rsync && rsync --version
- Outras plataformas: Verifique sua versão com rsync --version e atualize se necessário

Configuração e Definições

1. Clone e Inicie os Serviços

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

# Start the local environment
docker-compose up

2. Abra o Projeto no Cursor

cursor ./demo-app

3. Configure o Servidor MCP

Adicione a seguinte configuração às suas configurações MCP do 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"
      }
    }
  }
}

Testando a Demonstração

Faça uma alteração de código em demo-app/app.py (tente adicionar uma Exception ao health check)
Implante suas alterações digitando na janela de chat do Cursor:
```
deploy these changes
```
Exemplo:
Observe os resultados:
- Verifique os logs para atividade de deployment
- Visite http://localhost:8080/health para ver o serviço atualizado
- Observe quaisquer erros que possam ocorrer durante o deployment

Uso Real: Em um deployment real, os componentes proxy e sidecar rodariam na sua infraestrutura remota em vez de localmente. Esta demonstração simula esse ambiente na sua máquina local para fins de teste.