WTP - Worktree Plus

Permite que agentes gerenciem worktrees do Git via a CLI wtp.

Documentação

wtp-mcp-rs

Um servidor Model Context Protocol (MCP) para wtp (Worktree Plus), escrito em Rust. Ele permite que assistentes de IA gerenciem worktrees do Git via a CLI do wtp.

Para:

Usuários de Rust que desejam cargo install e uma CLI nativa.
Usuários de npm que desejam npm install -g com binários de plataforma pré-compilados.
Usuários de Git que desejam automação segura e scriptável de worktrees.

Funciona em qualquer repositório Git. O binário wtp é necessário e deve estar no PATH (ou definido via --wtp-path / config).

Destaques

Padrões de segurança: Hooks e exclusão de branch são desabilitados por padrão e devem ser explicitamente habilitados.
Recursos ricos: Consulte listas de worktrees, caminhos resolvidos, visualizações agrupadas e visão geral do repositório.

Instalação

Cargo (crates.io)

cargo install wtp-mcp-rs

Homebrew

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

GitHub Releases

Baixe um arquivo pré-compilado da página de GitHub Releases, extraia-o e coloque wtp-mcp-rs no seu PATH.

A partir do código-fonte

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

Início Rápido

Adicione esta configuração MCP. Exemplos para clientes MCP comuns (escolha um):

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

Execute o cliente MCP a partir da raiz do seu repositório (ou passe --repo-root / --config se quiser fixar um caminho diferente). Para Codex CLI, a configuração MCP é global; use codex --cd /path/to/repo se quiser definir a raiz de trabalho sem alterar diretórios.
Garanta que wtp esteja instalado e no PATH (ou defina --wtp-path / config).
Opcional: execute init-config uma vez para gerar .wtp.yml, depois edite defaults.base_dir e os hooks antes de usar add-worktree.

Uso

Configuração MCP

Adicione o trecho do Início Rápido à configuração do seu cliente MCP. O exemplo abaixo inclui todos os argumentos suportados (remova os que não precisar):

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

Se o seu cliente MCP inicia servidores a partir da raiz do repositório (escopo de projeto/workspace), você pode omitir --repo-root porque wtp-mcp-rs usa como padrão o diretório de trabalho atual.

Opções da CLI

Opção	Descrição	Padrão
`--repo-root <path>`	Diretório raiz do repositório	Diretório de trabalho atual
`--wtp-path <path>`	Caminho alternativo para o binário wtp	Detecção automática
`--config <path>`	Caminho para o arquivo de configuração TOML	Nenhum

Configuração de Worktree (.wtp.yml)

wtp controla o layout dos worktrees e os hooks via .wtp.yml na raiz do repositório.

init-config executa wtp init para gerar .wtp.yml. O modelo padrão geralmente define defaults.base_dir como ../worktrees e inclui exemplos de hooks.
Edite o arquivo para escolher o diretório base dos seus worktrees (por exemplo, .worktrees para worktrees dentro do repositório).
Hooks são ações opcionais pós-criação/remoção (copiar arquivos, criar symlinks de diretórios, executar comandos de configuração). Eles estão bloqueados por padrão neste servidor, a menos que security.allow_hooks = true.
Se .wtp.yml estiver ausente, add-worktree cria uma configuração mínima com defaults.base_dir = .worktrees e sem hooks.

Exemplo mínimo:

version: "1.0"
defaults:
  base_dir: .worktrees

Mesclando alterações de worktrees

Fluxo típico:

Cada worktree é um checkout de branch em seu próprio diretório.
Faça commit nesse worktree.
Mescle no seu branch de destino a partir de qualquer worktree (geralmente o "principal"):
- git merge feature/x
- ou abra um PR e mescle no GitHub.

Configuração de Exemplo (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

Padrões de segurança (por que ações destrutivas são bloqueadas)

Por padrão, operações potencialmente destrutivas estão desabilitadas:

Execução de hooks: Desabilitada por padrão. Hooks podem executar código arbitrário.
Exclusão de branch: Desabilitada por padrão. As flags --with-branch e --force-branch em remove-worktree exigem habilitação explícita.

Para habilitar esses recursos, adicione ao seu arquivo de configuração:

[security]
allow_hooks = true
allow_branch_delete = true

Ferramentas

list-worktrees - Lista todos os worktrees no repositório
add-worktree - Cria um novo worktree para um branch existente ou novo
remove-worktree - Remove um worktree (opcionalmente com seu branch)
merge-worktree - Retorna um comando git merge para um branch de worktree
init-config - Inicializa a configuração do wtp no repositório
get-worktree-path - Obtém o caminho absoluto para um worktree
shell-hook - Obtém script de hook de shell (bash/zsh/fish)
shell-init - Obtém script de inicialização de shell (bash/zsh/fish)

Recursos

O servidor expõe os seguintes recursos MCP:

URI	Descrição
`wtp://worktrees`	Lista de todos os worktrees (bruto)
`wtp://worktrees/resolved`	Lista de worktrees com caminhos absolutos resolvidos
`wtp://worktree/{name}`	Detalhes para um worktree específico
`wtp://overview`	Visão geral do repositório com worktrees e configurações de segurança
`wtp://worktrees/by-branch-prefix`	Worktrees agrupados por prefixo de branch (feature/, bugfix/, etc.)

Habilidade

skills/git-worktree-plus-with-mcp/SKILL.md: Use esta habilidade quando o usuário quiser gerenciar worktrees do Git através do servidor MCP wtp (listar, criar, remover, resolver caminhos, inicializar .wtp.yml ou preparar comandos de merge), especialmente quando os padrões de segurança em torno de hooks e exclusão de branch forem relevantes.

Desenvolvimento

Executando Testes

Testes unitários (sem necessidade de wtp):

cargo test --lib

Testes de integração (requer wtp instalado; os testes são ignorados se ausente):

cargo test --test integration

Licença

Licença MIT - veja LICENSE para detalhes.