WTP - Worktree Plus

Permite que los agentes gestionen worktrees de Git a través de la CLI de wtp.

GitHubPrueba este MCPPatrocinado

Documentación

wtp-mcp-rs

Crates.io Version CI Crates.io Downloads License Discord Buymecoffee

Un servidor de Model Context Protocol (MCP) para wtp (Worktree Plus), escrito en Rust. Permite a los asistentes de IA gestionar worktrees de Git mediante la CLI de wtp.

Para:

  • Usuarios de Rust que quieran cargo install y una CLI nativa.
  • Usuarios de npm que quieran npm install -g con binarios de plataforma precompilados.
  • Usuarios de Git que quieran automatización de worktrees segura y scriptable.

Funciona en cualquier repositorio Git. El binario wtp es necesario y debe estar en PATH (o configurarse mediante --wtp-path / config).

Características destacadas

  • Valores seguros por defecto: Los hooks y la eliminación de ramas están deshabilitados por defecto y deben habilitarse explícitamente.
  • Recursos enriquecidos: Consulta listas de worktrees, rutas resueltas, vistas agrupadas y resumen del repositorio.

Instalación

Cargo (crates.io)

cargo install wtp-mcp-rs

Homebrew

brew install bnomei/wtp-mcp/wtp-mcp-rs

GitHub Releases

Descarga un archivo precompilado desde la página de GitHub Releases, extráelo y coloca wtp-mcp-rs en tu PATH.

Desde el código fuente

git clone https://github.com/bnomei/wtp-mcp.git
cd wtp-mcp
cargo build --release

Inicio rápido

  1. Añade esta configuración de MCP. Ejemplos para clientes MCP comunes (elige uno):
# Claude Code
claude mcp add --transport stdio --scope project wtp -- wtp-mcp-rs

# Codex CLI
codex mcp add wtp -- wtp-mcp-rs

# OpenCode (interactive)
opencode mcp add

# Amp (workspace)
amp mcp add --workspace wtp -- wtp-mcp-rs

{
  "mcpServers": {
    "wtp": {
      "command": "wtp-mcp-rs"
    }
  }
}
  1. Ejecuta el cliente MCP desde la raíz de tu repositorio (o pasa --repo-root / --config si quieres fijar una ruta diferente). Para Codex CLI, la configuración de MCP es global; usa codex --cd /path/to/repo si quieres establecer la raíz de trabajo sin cambiar de directorio.
  2. Asegúrate de que wtp esté instalado y en PATH (o configura --wtp-path / config).
  3. Opcional: ejecuta init-config una vez para generar .wtp.yml, luego edita defaults.base_dir y los hooks antes de usar add-worktree.

Uso

Configuración de MCP

Añade el fragmento de Inicio rápido a la configuración de tu cliente MCP. El ejemplo siguiente incluye todos los argumentos soportados (elimina los que no necesites):

{
  "mcpServers": {
    "wtp": {
      "command": "wtp-mcp-rs",
      "args": [
        "--wtp-path",
        "/usr/local/bin/wtp",
        "--config",
        "/path/to/config.toml"
      ]
    }
  }
}

Si tu cliente MCP lanza servidores desde la raíz del repositorio (ámbito de proyecto/espacio de trabajo), puedes omitir --repo-root porque wtp-mcp-rs usa por defecto el directorio de trabajo actual.

Opciones de CLI

OpciónDescripciónPor defecto
--repo-root <path>Directorio raíz del repositorioDirectorio de trabajo actual
--wtp-path <path>Ruta alternativa al binario wtpDetección automática
--config <path>Ruta al archivo de configuración TOMLNinguno

Configuración de Worktree (.wtp.yml)

wtp controla el diseño de worktrees y los hooks mediante .wtp.yml en la raíz del repositorio.

  • init-config ejecuta wtp init para generar .wtp.yml. La plantilla por defecto suele establecer defaults.base_dir a ../worktrees e incluye hooks de ejemplo.
  • Edita el archivo para elegir tu directorio base de worktrees (por ejemplo, .worktrees para worktrees dentro del repositorio).
  • Los hooks son acciones opcionales posteriores a la creación/eliminación (copiar archivos, enlazar directorios simbólicamente, ejecutar comandos de configuración). Están bloqueados por defecto en este servidor a menos que security.allow_hooks = true.
  • Si .wtp.yml falta, add-worktree crea una configuración mínima con defaults.base_dir = .worktrees y sin hooks.

Ejemplo mínimo:

version: "1.0"
defaults:
  base_dir: .worktrees

Fusionar cambios desde worktrees

Flujo típico:

  • Cada worktree es un checkout de una rama en su propio directorio.
  • Haz commit en ese worktree.
  • Fusiona en tu rama objetivo desde cualquier worktree (normalmente el "principal"):
    • git merge feature/x
    • o abre un PR y fusiona en GitHub.

Configuración de ejemplo (config.toml)

# Repository root (optional, defaults to cwd)
repo_root = "/path/to/repo"

[wtp]
# Path to wtp binary (optional, auto-detected from PATH)
path = "/usr/local/bin/wtp"

[security]
# Allow execution of wtp hooks (default: false)
allow_hooks = false
# Allow branch deletion with worktree removal (default: false)
allow_branch_delete = false

Valores seguros por defecto (por qué las acciones destructivas están bloqueadas)

Por defecto, las operaciones potencialmente destructivas están deshabilitadas:

  • Ejecución de hooks: Deshabilitada por defecto. Los hooks pueden ejecutar código arbitrario.
  • Eliminación de ramas: Deshabilitada por defecto. Las banderas --with-branch y --force-branch en remove-worktree requieren habilitación explícita.

Para habilitar estas características, añade a tu archivo de configuración:

[security]
allow_hooks = true
allow_branch_delete = true

Herramientas

  • list-worktrees - Lista todos los worktrees del repositorio
  • add-worktree - Crea un nuevo worktree para una rama existente o nueva
  • remove-worktree - Elimina un worktree (opcionalmente con su rama)
  • merge-worktree - Devuelve un comando git merge para una rama de worktree
  • init-config - Inicializa la configuración de wtp en el repositorio
  • get-worktree-path - Obtiene la ruta absoluta a un worktree
  • shell-hook - Obtiene el script de hook de shell (bash/zsh/fish)
  • shell-init - Obtiene el script de inicialización de shell (bash/zsh/fish)

Recursos

El servidor expone los siguientes recursos MCP:

URIDescripción
wtp://worktreesLista de todos los worktrees (cruda)
wtp://worktrees/resolvedLista de worktrees con rutas absolutas resueltas
wtp://worktree/{name}Detalles de un worktree específico
wtp://overviewResumen del repositorio con worktrees y ajustes de seguridad
wtp://worktrees/by-branch-prefixWorktrees agrupados por prefijo de rama (feature/, bugfix/, etc.)

Skill

skills/git-worktree-plus-with-mcp/SKILL.md: Usa este skill cuando el usuario quiera gestionar worktrees de Git a través del servidor MCP de wtp (listar, crear, eliminar, resolver rutas, inicializar .wtp.yml o preparar comandos de fusión), especialmente cuando los valores seguros por defecto en torno a hooks y eliminación de ramas sean relevantes.

Desarrollo

Ejecutar pruebas

Pruebas unitarias (no requieren wtp):

cargo test --lib

Pruebas de integración (requieren wtp instalado; las pruebas se omiten si falta):

cargo test --test integration

Licencia

Licencia MIT - consulta LICENSE para más detalles.