@andre.buzeli/git-mcp 15.12.5

package/src/tools/git-branches.js

@@ -0,0 +1,126 @@
+import Ajv from "ajv";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { validateProjectPath } from "../utils/repoHelpers.js";
+
+const ajv = new Ajv({ allErrors: true });
+
+export function createGitBranchesTool(git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["list", "create", "delete", "rename", "checkout"],
+        description: `Ação a executar:
+- list: Lista todas as branches locais e remotas
+- create: Cria nova branch a partir do HEAD atual
+- delete: Remove uma branch (não pode ser a atual)
+- rename: Renomeia uma branch existente
+- checkout: Muda para outra branch`
+      },
+      branch: { 
+        type: "string",
+        description: "Nome da branch para create/delete/checkout. Ex: 'feature/nova-funcionalidade', 'bugfix/correcao'"
+      },
+      newBranch: { 
+        type: "string",
+        description: "Novo nome da branch (apenas para action='rename')"
+      },
+      force: { 
+        type: "boolean",
+        description: "Forçar delete mesmo se branch não está merged. Default: false"
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `Gerenciamento de branches Git.
+
+AÇÕES DISPONÍVEIS:
+- list: Ver branches existentes (locais e remotas)
+- create: Criar nova branch para desenvolvimento
+- checkout: Trocar de branch
+- delete: Remover branch após merge
+- rename: Renomear branch
+
+CONVENÇÕES DE NOMES:
+- feature/nome: Para novas funcionalidades
+- bugfix/nome: Para correções de bugs
+- hotfix/nome: Para correções urgentes
+- release/versao: Para releases`;
+
+  async function handle(args) {
+    const validate = ajv.compile(inputSchema);
+    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    const { projectPath, action } = args;
+    try {
+      validateProjectPath(projectPath);
+      if (action === "list") {
+        const local = await git.listBranches(projectPath, false);
+        const remote = await git.listBranches(projectPath, true).catch(() => []);
+        const current = await git.getCurrentBranch(projectPath);
+        return asToolResult({ current, local, remote });
+      }
+      if (action === "create") {
+        if (!args.branch) return asToolError("MISSING_PARAMETER", "branch é obrigatório para criar", { parameter: "branch" });
+        const existing = await git.listBranches(projectPath, false);
+        if (existing.includes(args.branch)) {
+          return asToolError("BRANCH_ALREADY_EXISTS", `Branch '${args.branch}' já existe`, { branch: args.branch, existingBranches: existing });
+        }
+        await git.createBranch(projectPath, args.branch);
+        return asToolResult({ success: true, branch: args.branch, message: `Branch '${args.branch}' criada. Use action='checkout' para mudar para ela.` });
+      }
+      if (action === "delete") {
+        if (!args.branch) return asToolError("MISSING_PARAMETER", "branch é obrigatório para deletar", { parameter: "branch" });
+        const existing = await git.listBranches(projectPath, false);
+        if (!existing.includes(args.branch)) {
+          return asToolError("BRANCH_NOT_FOUND", `Branch '${args.branch}' não encontrada`, { branch: args.branch, availableBranches: existing });
+        }
+        const current = await git.getCurrentBranch(projectPath);
+        if (args.branch === current) {
+          return asToolError("CANNOT_DELETE_CURRENT", `Não pode deletar branch atual '${args.branch}'`, { branch: args.branch, suggestion: "Faça checkout para outra branch primeiro" });
+        }
+        await git.deleteBranch(projectPath, args.branch, !!args.force);
+        return asToolResult({ success: true, branch: args.branch, deleted: true });
+      }
+      if (action === "rename") {
+        if (!args.branch || !args.newBranch) return asToolError("MISSING_PARAMETER", "branch e newBranch são obrigatórios", { parameters: ["branch", "newBranch"] });
+        await git.renameBranch(projectPath, args.branch, args.newBranch);
+        return asToolResult({ success: true, from: args.branch, to: args.newBranch });
+      }
+      if (action === "checkout") {
+        if (!args.branch) return asToolError("MISSING_PARAMETER", "branch é obrigatório para checkout", { parameter: "branch" });
+        
+        try {
+          await git.checkout(projectPath, args.branch);
+        } catch (e) {
+          const msg = e.message || "";
+          // Auto-fix: Create if not exists (common intent)
+          if (msg.includes("did not match any file") || msg.includes("pathspec") || msg.includes("not found")) {
+             // We can suggest or auto-create if configured. For now, let's suggest clearly or auto-create if it looks like a feature branch?
+             // Safer: Suggest. Or better: check if we should auto-create.
+             // Let's stick to safe behavior but enhanced error.
+             
+             // Check if user meant create
+             return asToolError("BRANCH_NOT_FOUND", `Branch '${args.branch}' não existe`, { 
+               suggestion: "Use action='create' para criar esta branch, ou verifique o nome." 
+             });
+          }
+          throw e;
+        }
+        
+        return asToolResult({ success: true, branch: args.branch, message: `Mudou para branch '${args.branch}'` });
+      }
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["list", "create", "delete", "rename", "checkout"] });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-branches", description, inputSchema, handle };
+}

package/src/tools/git-clone.js

@@ -0,0 +1,137 @@
+import Ajv from "ajv";
+import { asToolError, asToolResult, errorToResponse, createError } from "../utils/errors.js";
+import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
+
+const ajv = new Ajv({ allErrors: true });
+
+export function createGitCloneTool(git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto onde o repositório será clonado"
+      },
+      action: { 
+        type: "string", 
+        enum: ["clone"],
+        description: "Ação a executar: clone - clona um repositório remoto"
+      },
+      url: { 
+        type: "string",
+        description: "URL do repositório para clonar. Ex: 'https://github.com/user/repo.git'"
+      },
+      branch: { 
+        type: "string",
+        description: "Branch específica para clonar. Default: branch padrão do repo"
+      },
+      depth: {
+        type: "number",
+        description: "Profundidade do clone (shallow clone). Ex: 1 para último commit apenas"
+      },
+      singleBranch: {
+        type: "boolean",
+        description: "Se true, clona apenas a branch especificada. Default: false"
+      }
+    },
+    required: ["projectPath", "action", "url"],
+    additionalProperties: false
+  };
+
+  const description = `Clonar repositórios remotos.
+
+QUANDO USAR:
+- Baixar um repositório existente do GitHub/Gitea
+- Iniciar trabalho em um projeto existente
+- Criar cópia local de um repositório
+
+EXEMPLOS:
+- Clone básico: action='clone' url='https://github.com/user/repo.git'
+- Clone shallow: action='clone' url='...' depth=1
+- Clone de branch: action='clone' url='...' branch='develop'
+
+AUTENTICAÇÃO:
+- Repos públicos: Não precisa de token
+- Repos privados: Configure GITHUB_TOKEN ou GITEA_TOKEN
+
+NOTAS:
+- O diretório de destino será criado automaticamente
+- Se já existir arquivos, o clone falhará`;
+
+  async function handle(args) {
+    const validate = ajv.compile(inputSchema);
+    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    const { projectPath, action, url } = args;
+    
+    try {
+      // Validação de path
+      validateProjectPath(projectPath);
+      
+      if (action === "clone") {
+        if (!url) {
+          return asToolError("MISSING_PARAMETER", "url é obrigatório para clone", { 
+            parameter: "url",
+            example: "https://github.com/user/repo.git"
+          });
+        }
+        
+        // Idempotency check
+        if (fs.existsSync(path.join(projectPath, ".git"))) {
+          try {
+            // Check if it's the same repo
+            // git.getRemoteUrl is not standard in adapter, use exec or listRemotes logic
+            // Assuming git.listRemotes or similar exists, or we catch the error
+            // Let's try to infer from config or just warn
+            
+            // We'll rely on git status to check if it's healthy
+            await git.status(projectPath);
+            
+            return asToolResult({
+              success: true,
+              url,
+              path: projectPath,
+              branch: args.branch || "current",
+              message: `Repositório já existe em '${projectPath}'. Clone ignorado (idempotente).`,
+              nextStep: "Use git-workflow status para ver o estado atual"
+            });
+          } catch (e) {
+            // If status fails, maybe it's broken
+            console.warn("Existing repo check failed:", e);
+          }
+        } else if (fs.existsSync(projectPath) && fs.readdirSync(projectPath).length > 0) {
+           return asToolError("DIR_NOT_EMPTY", `Diretório '${projectPath}' existe e não está vazio`, {
+             suggestion: "Use um diretório novo ou limpe o atual"
+           });
+        }
+
+        const result = await withRetry(
+          () => git.clone(url, projectPath, {
+            branch: args.branch,
+            depth: args.depth,
+            singleBranch: args.singleBranch
+          }),
+          3,
+          "clone"
+        );
+        
+        return asToolResult({
+          success: true,
+          url,
+          path: projectPath,
+          branch: result.branch || args.branch || "default",
+          ...result,
+          message: `Repositório clonado com sucesso em '${projectPath}'`,
+          nextStep: "Use git-workflow status para ver o estado do repositório"
+        });
+      }
+      
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { 
+        availableActions: ["clone"] 
+      });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-clone", description, inputSchema, handle };
+}

package/src/tools/git-config.js

@@ -0,0 +1,94 @@
+import Ajv from "ajv";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { validateProjectPath } from "../utils/repoHelpers.js";
+import { withRetry } from "../utils/retry.js";
+
+const ajv = new Ajv({ allErrors: true });
+
+export function createGitConfigTool(git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: {
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: {
+        type: "string",
+        enum: ["get", "set", "unset", "list"],
+        description: `Ação a executar:
+- get: Obter valor de uma configuração específica
+- set: Definir valor de uma configuração
+- unset: Remover uma configuração
+- list: Listar todas as configurações do escopo`
+      },
+      key: {
+        type: "string",
+        description: "Chave da configuração. Ex: 'user.name', 'user.email', 'core.autocrlf'"
+      },
+      value: {
+        type: "string",
+        description: "Valor a definir (apenas para action='set')"
+      },
+      scope: {
+        type: "string",
+        enum: ["local", "global", "system"],
+        description: "Escopo da configuração. local: apenas este repo, global: todos os repos do usuário, system: todo o sistema"
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `Gerenciamento de configurações Git.
+
+CONFIGURAÇÕES COMUNS:
+- user.name: Nome do autor dos commits
+- user.email: Email do autor dos commits
+- core.autocrlf: Conversão de fim de linha (true/false/input)
+- core.editor: Editor padrão para commits
+
+ESCOPOS:
+- local: Apenas neste repositório (.git/config)
+- global: Todos os repos do usuário (~/.gitconfig)
+- system: Todo o sistema (/etc/gitconfig)
+
+EXEMPLOS:
+- Definir nome: action='set' key='user.name' value='Meu Nome'
+- Definir email: action='set' key='user.email' value='email@example.com'
+- Ver nome: action='get' key='user.name'`;
+
+  async function handle(args) {
+    const validate = ajv.compile(inputSchema);
+    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    const { projectPath, action } = args;
+    const scope = args.scope || "local";
+    try {
+      validateProjectPath(projectPath);
+      if (action === "get") {
+        if (!args.key) return asToolError("MISSING_PARAMETER", "key é obrigatório", { parameter: "key" });
+        const val = await withRetry(() => git.getConfig(projectPath, args.key, scope), 3, "get-config");
+        return asToolResult({ key: args.key, value: val, found: val !== undefined, scope });
+      }
+      if (action === "set") {
+        if (!args.key) return asToolError("MISSING_PARAMETER", "key é obrigatório", { parameter: "key" });
+        await withRetry(() => git.setConfig(projectPath, args.key, args.value ?? "", scope), 3, "set-config");
+        return asToolResult({ success: true, key: args.key, value: args.value ?? "", scope });
+      }
+      if (action === "unset") {
+        if (!args.key) return asToolError("MISSING_PARAMETER", "key é obrigatório", { parameter: "key" });
+        await withRetry(() => git.unsetConfig(projectPath, args.key, scope), 3, "unset-config");
+        return asToolResult({ success: true, key: args.key, removed: true, scope });
+      }
+      if (action === "list") {
+        const items = await withRetry(() => git.listConfig(projectPath, scope), 3, "list-config");
+        return asToolResult({ scope, configs: items, count: Object.keys(items).length });
+      }
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["get", "set", "unset", "list"] });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-config", description, inputSchema, handle };
+}

package/src/tools/git-diff.js

@@ -0,0 +1,137 @@
+import Ajv from "ajv";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
+
+const ajv = new Ajv({ allErrors: true });
+
+export function createGitDiffTool(git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: {
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: {
+        type: "string",
+        enum: ["show", "compare", "stat"],
+        description: `Ação a executar:
+- show: Mostra diff do working directory (arquivos não commitados)
+- compare: Compara dois commits/branches/tags
+- stat: Mostra estatísticas (arquivos alterados, linhas +/-)`
+      },
+      from: {
+        type: "string",
+        description: "Ref inicial para comparação (commit SHA, branch, tag). Default: HEAD"
+      },
+      fromRef: {
+        type: "string",
+        description: "Alias para 'from'. Ref inicial para comparação"
+      },
+      to: {
+        type: "string",
+        description: "Ref final para comparação. Se não fornecido, compara com working directory"
+      },
+      toRef: {
+        type: "string",
+        description: "Alias para 'to'. Ref final para comparação"
+      },
+      file: {
+        type: "string",
+        description: "Arquivo específico para ver diff. Se não fornecido, mostra todos"
+      },
+      filepath: {
+        type: "string",
+        description: "Alias para 'file'. Arquivo específico para ver diff"
+      },
+      context: {
+        type: "number",
+        description: "Número de linhas de contexto ao redor das mudanças. Default: 3"
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `Ver diferenças entre commits, branches ou arquivos.
+
+QUANDO USAR:
+- Ver o que mudou antes de commitar (action='show')
+- Comparar branches antes de merge (action='compare')
+- Ver estatísticas de mudanças (action='stat')
+
+EXEMPLOS:
+- Ver mudanças não commitadas: action='show'
+- Ver mudanças de um arquivo: action='show' file='src/index.js'
+- Comparar com último commit: action='compare' from='HEAD~1'
+- Comparar branches: action='compare' from='main' to='feature/x'
+- Ver stats: action='stat' from='main' to='develop'`;
+
+  async function handle(args) {
+    const validate = ajv.compile(inputSchema);
+    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    const { projectPath, action } = args;
+
+    // Support aliases: fromRef -> from, toRef -> to, filepath -> file
+    const fromParam = args.from || args.fromRef || "HEAD";
+    const toParam = args.to || args.toRef;
+    const fileParam = args.file || args.filepath;
+
+    try {
+      validateProjectPath(projectPath);
+      if (action === "show") {
+        const diff = await withRetry(() => git.diff(projectPath, {
+          file: fileParam,
+          context: args.context || 3
+        }), 3, "diff-show");
+
+        if (!diff || diff.length === 0) {
+          return asToolResult({
+            changes: [],
+            message: "Nenhuma mudança detectada no working directory"
+          });
+        }
+
+        return asToolResult({
+          changes: diff,
+          totalFiles: diff.length,
+          message: `${diff.length} arquivo(s) com mudanças`
+        });
+      }
+
+      if (action === "compare") {
+        const diff = await withRetry(() => git.diffCommits(projectPath, fromParam, toParam, {
+          file: fileParam,
+          context: args.context || 3
+        }), 3, "diff-compare");
+
+        return asToolResult({
+          from: fromParam,
+          to: toParam || "working directory",
+          changes: diff,
+          totalFiles: diff.length,
+          message: `Comparando ${fromParam} com ${toParam || 'working directory'}: ${diff.length} arquivo(s)`
+        });
+      }
+
+      if (action === "stat") {
+        const stats = await withRetry(() => git.diffStats(projectPath, fromParam, toParam), 3, "diff-stat");
+
+        return asToolResult({
+          from: fromParam,
+          to: toParam || "working directory",
+          ...stats,
+          message: `${stats.filesChanged} arquivo(s), +${stats.insertions} -${stats.deletions}`
+        });
+      }
+
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, {
+        availableActions: ["show", "compare", "stat"]
+      });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-diff", description, inputSchema, handle };
+}

package/src/tools/git-files.js

@@ -0,0 +1,82 @@
+import Ajv from "ajv";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
+
+const ajv = new Ajv({ allErrors: true });
+
+export function createGitFilesTool(git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["list", "read"],
+        description: `Ação a executar:
+- list: Lista todos os arquivos rastreados pelo Git em um commit/branch
+- read: Lê o conteúdo de um arquivo em um commit/branch específico`
+      },
+      filepath: { 
+        type: "string",
+        description: "Caminho do arquivo relativo à raiz do repo (action='read'). Ex: 'src/index.js', 'package.json'"
+      },
+      ref: { 
+        type: "string",
+        description: "Referência Git para ler (commit SHA, branch, tag). Default: HEAD (commit atual)"
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `Leitura de arquivos do repositório Git.
+
+QUANDO USAR:
+- Ver arquivos de um commit antigo
+- Comparar versões de arquivo entre commits
+- Listar arquivos rastreados pelo Git
+
+EXEMPLOS:
+- Listar arquivos: action='list'
+- Listar arquivos de tag: action='list' ref='v1.0.0'
+- Ler arquivo atual: action='read' filepath='package.json'
+- Ler arquivo de commit antigo: action='read' filepath='src/index.js' ref='abc1234'
+
+NOTA: Esta tool lê arquivos do histórico Git, não do sistema de arquivos.`;
+
+  async function handle(args) {
+    const validate = ajv.compile(inputSchema);
+    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    const { projectPath, action } = args;
+    try {
+      validateProjectPath(projectPath);
+      if (action === "list") {
+        const files = await git.listFiles(projectPath, args.ref || "HEAD");
+        return asToolResult({ files, count: files.length, ref: args.ref || "HEAD" });
+      }
+      if (action === "read") {
+        if (!args.filepath) return asToolError("MISSING_PARAMETER", "filepath é obrigatório", { parameter: "filepath" });
+        try {
+          const text = await git.readFile(projectPath, args.filepath, args.ref || "HEAD");
+          return { content: [{ type: "text", text }], isError: false };
+        } catch (e) {
+          const files = await git.listFiles(projectPath, args.ref || "HEAD").catch(() => []);
+          return asToolError("FILE_NOT_FOUND", `Arquivo '${args.filepath}' não encontrado`, { 
+            filepath: args.filepath, 
+            ref: args.ref || "HEAD",
+            similarFiles: files.filter(f => f.includes(args.filepath.split("/").pop())).slice(0, 10),
+            totalFiles: files.length
+          });
+        }
+      }
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["list", "read"] });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-files", description, inputSchema, handle };
+}