mcp-sync

Sincroniza configurações do servidor MCP entre várias ferramentas de codificação de IA.

GitHub
45
Experimente este MCPPatrocinado

Documentação

mcp-sync

Sincronize configurações do MCP (Model Context Protocol) entre ferramentas de IA.

Visão Geral

mcp-sync é uma ferramenta de linha de comando que ajuda você a gerenciar e sincronizar configurações de servidores MCP entre diferentes ferramentas de codificação com IA, como Claude Desktop, Claude Code, Cline, extensões do VS Code e outras.

Recursos

  • Descoberta automática: Encontra automaticamente configurações do MCP no seu sistema
  • Registro manual: Adicione locais personalizados de arquivos de configuração para preparação futura
  • Configurações globais e de projeto: Suporta servidores tanto para o usuário em geral quanto específicos de projetos
  • Resolução de conflitos: Mesclagem inteligente com prioridade para configurações de projeto
  • Modo de simulação: Visualize as alterações antes de aplicá-las
  • Multiplataforma: Funciona em macOS, Windows e Linux

Instalação

Uso Rápido (Recomendado)

uvx mcp-sync status
uvx mcp-sync sync --dry-run

Instalação Persistente

uv tool install mcp-sync
mcp-sync status

Instalação para Desenvolvimento

git clone <repo-url>
cd mcp-sync
./scripts/setup.sh    # Installs dependencies and git hooks automatically

Início Rápido

  1. Verifique se há configurações existentes:

    mcp-sync scan

  2. Verifique o status atual:

    mcp-sync status

  3. Adicione um servidor à configuração global:

    mcp-sync add-server filesystem
# Follow prompts to configure

  4. Visualize as alterações de sincronização:

    mcp-sync diff
mcp-sync sync --dry-run

  5. Sincronize as configurações:

    mcp-sync sync

Comandos

Descoberta e Status

  • mcp-sync scan - Descubra automaticamente configurações MCP conhecidas
  • mcp-sync status - Mostre o status da sincronização
  • mcp-sync diff - Mostre as diferenças de configuração

Gerenciamento de Localização de Configurações

  • mcp-sync add-location <path> [--name <alias>] - Registre um arquivo de configuração personalizado
  • mcp-sync remove-location <path> - Cancele o registro de uma localização de configuração
  • mcp-sync list-locations - Mostre todos os caminhos de configuração registrados

Operações de Sincronização

  • mcp-sync sync - Sincronize todas as configurações registradas
  • mcp-sync sync --dry-run - Visualize as alterações sem aplicá-las
  • mcp-sync sync --global-only - Sincronize apenas as configurações globais
  • mcp-sync sync --project-only - Sincronize apenas as configurações de projeto
  • mcp-sync sync --location <path> - Sincronize apenas uma localização específica

Gerenciamento de Servidores

  • mcp-sync add-server <name> - Adicione um servidor MCP à sincronização (prompts interativos)
  • mcp-sync add-server <name> --command <cmd> --args <args> --env <vars> --scope <global|project> - Adicione um servidor com parâmetros inline
  • mcp-sync remove-server <name> - Remova um servidor da sincronização (prompts interativos)
  • mcp-sync remove-server <name> --scope <global|project> - Remova um servidor com escopo inline
  • mcp-sync list-servers - Mostre todos os servidores gerenciados

Migração

  • mcp-sync vacuum - Importe servidores MCP de configurações descobertas
    • --auto-resolve <first|last> escolha a resolução de conflitos automaticamente
    • --skip-existing evite sobrescrever servidores já presentes na configuração global

Adicionando Servidores: Ao adicionar um servidor, você precisa fornecer:

  • Comando: O executável a ser executado (por exemplo, python, npx, node)
  • Argumentos: Argumentos de linha de comando (separados por vírgula, opcional)
  • Variáveis de ambiente: Variáveis de ambiente como pares KEY=value (separados por vírgula, opcional)
  • Escopo: Se deve adicionar à configuração global (sincronizada em todos os lugares) ou à configuração do projeto (apenas neste projeto)

Exemplo interativo:

mcp-sync add-server filesystem
# Prompts for: scope, command, args, env vars

Exemplo automatizado:

mcp-sync add-server filesystem --command npx --args "-y,@modelcontextprotocol/server-filesystem,/home/user/docs" --scope global

Gerenciamento de Projetos

  • mcp-sync init - Crie o projeto .mcp.json
  • mcp-sync template - Mostre a configuração de modelo

Gerenciamento de Clientes

  • mcp-sync list-clients - Mostre todos os clientes suportados e seu status de detecção
  • mcp-sync client-info [client-id] - Mostre informações detalhadas do cliente e caminhos
  • mcp-sync edit-client-definitions - Edite as definições de cliente do usuário para adicionar clientes personalizados

Hierarquia de Configuração

mcp-sync usa um sistema de configuração em três níveis:

  1. Configuração Global (~/.mcp-sync/global.json)

    • Servidores de desenvolvimento pessoal
    • Sincronizada em todas as ferramentas

  2. Configuração do Projeto (.mcp.json na raiz do projeto)

    • Servidores específicos do projeto
    • Versionada junto com seu projeto
    • Tem prioridade sobre a configuração global

  3. Configurações das Ferramentas (Locais descobertos automaticamente)

    • Claude Desktop, VS Code, Cline, etc.
    • Atualizadas pelas operações de sincronização

Ferramentas Suportadas

mcp-sync usa uma abordagem orientada por configuração para suportar ferramentas e editores de IA. As definições de clientes são gerenciadas por meio de arquivos de configuração JSON.

Suporte integrado a clientes:

  • Claude Desktop - Aplicativo oficial do Claude Desktop
  • Claude Code - CLI do Claude para edição de código
  • Cline - Extensão do VS Code para assistência de IA
  • Roo - Extensão Roo do VS Code para assistência de IA
  • Configurações de Usuário do VS Code - Configurações globais de usuário do VS Code
  • Cursor - Editor de código com IA Cursor
  • Continue - Extensão Continue do VS Code

Execute mcp-sync list-clients para ver quais clientes são detectados no seu sistema, ou mcp-sync client-info <client-id> para informações detalhadas sobre clientes específicos.

Adicionando clientes personalizados: Os usuários podem adicionar suas próprias definições de clientes executando mcp-sync edit-client-definitions. Isso cria ~/.mcp-sync/client_definitions.json onde configurações personalizadas de clientes podem ser adicionadas. As definições do usuário têm precedência sobre as integradas, permitindo personalização e adição de suporte para novas ferramentas sem modificar o código-fonte.

Exemplo de Fluxo de Trabalho

# 1. Initialize project config
mcp-sync init

# 2. Add project-specific server
mcp-sync add-server database
# Choose "2. Project config"
# Command: python
# Args: /path/to/db-server.py
# Env: DB_URL=postgresql://...

# 3. Add global development server
mcp-sync add-server filesystem
# Choose "1. Global config"
# Command: npx
# Args: -y, @modelcontextprotocol/server-filesystem, /home/user

# 4. Sync to all tools
mcp-sync sync

# 5. Check status
mcp-sync status

Formato do Arquivo de Configuração

Configuração do Servidor MCP

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/directory"
      ]
    },
    "custom-server": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Desenvolvimento

Requisitos

  • Python 3.12+
  • Gerenciador de pacotes uv

Configuração

git clone <repo-url>
cd mcp-sync
uv sync
uv pip install -e .

Qualidade do Código

uv run ruff check .     # Linting
uv run ruff format .    # Formatting
uv run pytest          # Tests (when available)

Executando Testes

Os testes exigem que o pacote esteja em PYTHONPATH. Instale-o em modo editável:

uv pip install -e .
uv run pytest

ou defina PYTHONPATH manualmente ao invocar o pytest:

PYTHONPATH=$PWD uv run pytest

Licença

[Detalhes da licença aqui]

Contribuição

[Diretrizes de contribuição aqui]