mcp-sync

Sincroniza configuraciones del servidor MCP entre varias herramientas de codificación de IA.

GitHub
46
Prueba este MCPPatrocinado

Documentación

mcp-sync

Sincroniza las configuraciones de MCP (Model Context Protocol) entre herramientas de IA.

Resumen

mcp-sync es una herramienta de línea de comandos que te ayuda a gestionar y sincronizar configuraciones de servidores MCP en diferentes herramientas de codificación con IA como Claude Desktop, Claude Code, Cline, extensiones de VS Code, y más.

Características

  • Auto-descubrimiento: Encuentra automáticamente configuraciones de MCP en tu sistema
  • Registro manual: Añade ubicaciones de archivos de configuración personalizadas para prepararte para el futuro
  • Configuraciones globales y de proyecto: Soporta tanto servidores a nivel de usuario como específicos de proyecto
  • Resolución de conflictos: Fusión inteligente donde las configuraciones de proyecto tienen prioridad
  • Modo de prueba (dry-run): Previsualiza los cambios antes de aplicarlos
  • Multiplataforma: Funciona en macOS, Windows y Linux

Instalación

Uso rápido (Recomendado)

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

Instalación persistente

uv tool install mcp-sync
mcp-sync status

Instalación para desarrollo

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

Inicio rápido

  1. Escanea las configuraciones existentes:

    mcp-sync scan

  2. Comprueba el estado actual:

    mcp-sync status

  3. Añade un servidor a la configuración global:

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

  4. Previsualiza los cambios de sincronización:

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

  5. Sincroniza las configuraciones:

    mcp-sync sync

Comandos

Descubrimiento y estado

  • mcp-sync scan - Auto-descubre las configuraciones MCP conocidas
  • mcp-sync status - Muestra el estado de sincronización
  • mcp-sync diff - Muestra las diferencias de configuración

Gestión de ubicaciones de configuración

  • mcp-sync add-location <path> [--name <alias>] - Registra un archivo de configuración personalizado
  • mcp-sync remove-location <path> - Da de baja la ubicación de configuración
  • mcp-sync list-locations - Muestra todas las rutas de configuración registradas

Operaciones de sincronización

  • mcp-sync sync - Sincroniza todas las configuraciones registradas
  • mcp-sync sync --dry-run - Previsualiza los cambios sin aplicarlos
  • mcp-sync sync --global-only - Sincroniza solo las configuraciones globales
  • mcp-sync sync --project-only - Sincroniza solo las configuraciones de proyecto
  • mcp-sync sync --location <path> - Sincroniza solo una ubicación específica

Gestión de servidores

  • mcp-sync add-server <name> - Añade un servidor MCP a la sincronización (avisos interactivos)
  • mcp-sync add-server <name> --command <cmd> --args <args> --env <vars> --scope <global|project> - Añade un servidor con parámetros en línea
  • mcp-sync remove-server <name> - Elimina un servidor de la sincronización (avisos interactivos)
  • mcp-sync remove-server <name> --scope <global|project> - Elimina un servidor con ámbito en línea
  • mcp-sync list-servers - Muestra todos los servidores gestionados

Migración

  • mcp-sync vacuum - Importa servidores MCP desde configuraciones descubiertas
    • --auto-resolve <first|last> elegir automáticamente la resolución de conflictos
    • --skip-existing evitar sobrescribir servidores que ya están en la configuración global

Añadir servidores: Al añadir un servidor, necesitas proporcionar:

  • Comando: El ejecutable a ejecutar (por ejemplo, python, npx, node)
  • Argumentos: Argumentos de línea de comandos (separados por comas, opcional)
  • Variables de entorno: Variables de entorno como pares KEY=value (separados por comas, opcional)
  • Ámbito: Si se añade a la configuración global (sincronizada en todas partes) o a la configuración de proyecto (solo este proyecto)

Ejemplo interactivo:

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

Ejemplo automatizado:

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

Gestión de proyectos

  • mcp-sync init - Crea el proyecto .mcp.json
  • mcp-sync template - Muestra la configuración de plantilla

Gestión de clientes

  • mcp-sync list-clients - Muestra todos los clientes compatibles y su estado de detección
  • mcp-sync client-info [client-id] - Muestra información detallada del cliente y rutas
  • mcp-sync edit-client-definitions - Edita las definiciones de cliente del usuario para añadir clientes personalizados

Jerarquía de configuración

mcp-sync utiliza un sistema de configuración de tres niveles:

  1. Configuración global (~/.mcp-sync/global.json)

    • Servidores de desarrollo personales
    • Sincronizados en todas las herramientas

  2. Configuración de proyecto (.mcp.json en la raíz del proyecto)

    • Servidores específicos del proyecto
    • Controlado por versiones junto con tu proyecto
    • Tiene prioridad sobre la configuración global

  3. Configuraciones de herramientas (ubicaciones auto-descubiertas)

    • Claude Desktop, VS Code, Cline, etc.
    • Actualizadas mediante operaciones de sincronización

Herramientas compatibles

mcp-sync utiliza un enfoque impulsado por configuración para admitir herramientas y editores de IA. Las definiciones de clientes se gestionan mediante archivos de configuración JSON.

Soporte integrado de clientes:

  • Claude Desktop - Aplicación oficial de Claude Desktop
  • Claude Code - CLI de Claude para edición de código
  • Cline - Extensión de VS Code para asistencia de IA
  • Roo - Extensión de VS Code para asistencia de IA
  • VS Code User Settings - Configuración global de usuario de VS Code
  • Cursor - Editor de código con IA de Cursor
  • Continue - Extensión de VS Code de Continue

Ejecuta mcp-sync list-clients para ver qué clientes se detectan en tu sistema, o mcp-sync client-info <client-id> para obtener información detallada sobre clientes específicos.

Añadir clientes personalizados: Los usuarios pueden añadir sus propias definiciones de cliente ejecutando mcp-sync edit-client-definitions. Esto crea ~/.mcp-sync/client_definitions.json donde se pueden añadir configuraciones de clientes personalizadas. Las definiciones de usuario tienen prioridad sobre las integradas, lo que permite la personalización y la adición de soporte para nuevas herramientas sin modificar el código base.

Ejemplo de flujo de trabajo

# 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 del archivo de configuración

Configuración del 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"
      }
    }
  }
}

Desarrollo

Requisitos

  • Python 3.12+
  • Administrador de paquetes uv

Configuración

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

Calidad del código

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

Ejecutar pruebas

Las pruebas requieren que el paquete esté en PYTHONPATH. Ya sea instalarlo en modo editable:

uv pip install -e .
uv run pytest

o establecer PYTHONPATH manualmente al invocar pytest:

PYTHONPATH=$PWD uv run pytest

Licencia

[Detalles de licencia aquí]

Contribución

[Directrices de contribución aquí]