@andrebuzeli/git-mcp 13.6.0 → 14.0.0

package/src/tools/git-stash.js

@@ -7,16 +7,58 @@ export function createGitStashTool(git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["list", "save", "apply", "pop", "drop", "clear"] },
-      message: { type: "string" },
-      ref: { type: "string" },
-      includeUntracked: { type: "boolean" }
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["list", "save", "apply", "pop", "drop", "clear"],
+        description: `Ação a executar:
+- list: Lista todos os stashes salvos
+- save: Salva mudanças atuais no stash (limpa working directory)
+- apply: Aplica stash sem removê-lo da lista
+- pop: Aplica stash E remove da lista (mais comum)
+- drop: Remove stash específico da lista
+- clear: Remove TODOS os stashes`
+      },
+      message: { 
+        type: "string",
+        description: "Mensagem descritiva para o stash (action='save'). Ex: 'WIP: implementando feature X'"
+      },
+      ref: { 
+        type: "string",
+        description: "Referência do stash para apply/pop/drop. Ex: 'stash@{0}' (mais recente), 'stash@{1}' (segundo)"
+      },
+      includeUntracked: { 
+        type: "boolean",
+        description: "Incluir arquivos não rastreados no stash (action='save'). Default: false"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Gerenciamento de stash Git - salva mudanças temporariamente.
+
+QUANDO USAR STASH:
+- Precisa trocar de branch mas tem mudanças não commitadas
+- Quer salvar trabalho em progresso sem commitar
+- Precisa aplicar hotfix urgente em outra branch
+
+FLUXO TÍPICO:
+1. git-stash save message='WIP: minha feature'  → salva mudanças
+2. (trabalha em outra coisa)
+3. git-stash pop  → restaura mudanças
+
+AÇÕES:
+- save: Salva e limpa working directory
+- pop: Restaura e remove do stash (use este na maioria dos casos)
+- apply: Restaura mas mantém no stash (para aplicar em múltiplas branches)
+- list: Ver stashes salvos
+- drop: Remover stash específico
+- clear: Remover todos os stashes`;
+
   async function handle(args) {
     const validate = ajv.compile(inputSchema);
     if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
@@ -25,54 +67,52 @@ export function createGitStashTool(git) {
       if (action === "list") {
         const items = await git.listStash(projectPath);
         return asToolResult({ 
-          items: items.map((s, i) => ({ index: i, ref: `stash@{${i}}`, message: s.message, timestamp: s.timestamp })),
-          count: items.length 
+          stashes: items.map((s, i) => ({ index: i, ref: `stash@{${i}}`, message: s.message, timestamp: s.timestamp })),
+          count: items.length,
+          message: items.length === 0 ? "Nenhum stash salvo" : undefined
         });
       }
       if (action === "save") {
-        // Auto-verificação: checar se há mudanças
         const status = await git.status(projectPath);
         if (status.isClean && !args.includeUntracked) {
           return asToolError("NOTHING_TO_STASH", "Working tree limpa, nada para stash", { status });
         }
         await git.saveStash(projectPath, args.message || "WIP", !!args.includeUntracked);
-        return asToolResult({ success: true, message: args.message || "WIP" });
+        return asToolResult({ success: true, message: args.message || "WIP", savedFiles: status.modified.length + status.created.length + status.not_added.length });
       }
       if (action === "apply") {
-        // Auto-verificação: checar se stash existe
         const items = await git.listStash(projectPath);
         if (items.length === 0) {
           return asToolError("STASH_NOT_FOUND", "Nenhum stash disponível", { availableStashes: [] });
         }
-        await git.applyStash(projectPath, args.ref);
-        return asToolResult({ success: true, ref: args.ref || "stash@{0}" });
+        await git.applyStash(projectPath, args.ref || "stash@{0}");
+        return asToolResult({ success: true, ref: args.ref || "stash@{0}", message: "Stash aplicado (ainda está na lista)" });
       }
       if (action === "pop") {
-        // Auto-verificação: checar se stash existe
         const items = await git.listStash(projectPath);
         if (items.length === 0) {
           return asToolError("STASH_NOT_FOUND", "Nenhum stash disponível", { availableStashes: [] });
         }
-        await git.popStash(projectPath, args.ref);
-        return asToolResult({ success: true, ref: args.ref || "stash@{0}" });
+        await git.popStash(projectPath, args.ref || "stash@{0}");
+        return asToolResult({ success: true, ref: args.ref || "stash@{0}", message: "Stash aplicado e removido da lista" });
       }
       if (action === "drop") {
         const items = await git.listStash(projectPath);
         if (items.length === 0) {
           return asToolError("STASH_NOT_FOUND", "Nenhum stash disponível", { availableStashes: [] });
         }
-        await git.dropStash(projectPath, args.ref);
-        return asToolResult({ success: true, ref: args.ref || "stash@{0}" });
+        await git.dropStash(projectPath, args.ref || "stash@{0}");
+        return asToolResult({ success: true, ref: args.ref || "stash@{0}", message: "Stash removido" });
       }
       if (action === "clear") {
         await git.clearStash(projectPath);
         return asToolResult({ success: true, message: "Todos os stashes removidos" });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "save", "apply", "pop", "drop", "clear"] });
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["list", "save", "apply", "pop", "drop", "clear"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-stash", description: "Gerencia stash", inputSchema, handle };
+  return { name: "git-stash", description, inputSchema, handle };
 }

package/src/tools/git-sync.js

@@ -7,15 +7,47 @@ export function createGitSyncTool(git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["pull", "fetch"] },
-      remote: { type: "string" },
-      branch: { type: "string" }
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["pull", "fetch"],
+        description: `Ação a executar:
+- fetch: Baixa commits do remote sem aplicar (seguro, apenas atualiza refs remotas)
+- pull: Baixa E aplica commits do remote (pode gerar conflitos)`
+      },
+      remote: { 
+        type: "string",
+        description: "Nome do remote específico (github, gitea, origin). Se não especificado, tenta todos"
+      },
+      branch: { 
+        type: "string",
+        description: "Branch para sincronizar. Default: branch atual"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Sincronização com repositórios remotos (GitHub/Gitea).
+
+DIFERENÇA FETCH vs PULL:
+- fetch: Seguro - apenas baixa, não modifica working directory
+- pull: Baixa E aplica - pode gerar conflitos se houver mudanças locais
+
+QUANDO USAR:
+- fetch: Para ver se há atualizações sem aplicar
+- pull: Para atualizar seu código local com as mudanças do remote
+
+FLUXO RECOMENDADO:
+1. git-workflow status → verificar se tem mudanças locais
+2. git-sync fetch → baixar atualizações
+3. git-sync pull → aplicar atualizações (se não tiver conflitos)
+
+NOTA: Se pull falhar com conflito, resolva manualmente e faça commit.`;
+
   async function handle(args) {
     const validate = ajv.compile(inputSchema);
     if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
@@ -33,7 +65,7 @@ export function createGitSyncTool(git) {
           branch, 
           fetched: successful.map(x => x.remote),
           failed: failed.map(x => ({ remote: x.remote, error: x.error })),
-          message: successful.length === 0 ? "Nenhum remote alcançado. Verifique conexão e configuração." : undefined
+          message: successful.length === 0 ? "Nenhum remote alcançado. Use git-remote ensure para configurar." : `Fetch de ${successful.length} remote(s) concluído`
         });
       }
       if (action === "pull") {
@@ -47,14 +79,14 @@ export function createGitSyncTool(git) {
           branch, 
           pulled: successful.map(x => x.remote),
           failed: failed.map(x => ({ remote: x.remote, error: x.error })),
-          message: successful.length === 0 ? "Nenhum remote alcançado. Verifique conexão e configuração." : undefined
+          message: successful.length === 0 ? "Nenhum remote alcançado. Use git-remote ensure para configurar." : `Pull de ${successful.length} remote(s) concluído`
         });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["pull", "fetch"] });
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["pull", "fetch"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-sync", description: "fetch/pull (opcionalmente múltiplos remotes)", inputSchema, handle };
+  return { name: "git-sync", description, inputSchema, handle };
 }

package/src/tools/git-tags.js

@@ -7,16 +7,54 @@ export function createGitTagsTool(git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["list", "create", "delete", "push"] },
-      tag: { type: "string" },
-      ref: { type: "string" },
-      message: { type: "string" }
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["list", "create", "delete", "push"],
+        description: `Ação a executar:
+- list: Lista todas as tags existentes
+- create: Cria nova tag no commit atual ou especificado
+- delete: Remove uma tag local
+- push: Envia tag para GitHub e Gitea`
+      },
+      tag: { 
+        type: "string",
+        description: "Nome da tag. Use versionamento semântico: v1.0.0, v1.1.0, v2.0.0"
+      },
+      ref: { 
+        type: "string",
+        description: "Commit/branch para criar tag (opcional, default: HEAD)"
+      },
+      message: { 
+        type: "string",
+        description: "Mensagem da tag anotada (opcional). Se fornecido, cria tag anotada"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Gerenciamento de tags Git para versionamento.
+
+AÇÕES DISPONÍVEIS:
+- list: Ver todas as tags existentes
+- create: Criar nova tag de versão
+- delete: Remover tag local
+- push: Enviar tag para GitHub e Gitea
+
+VERSIONAMENTO SEMÂNTICO:
+- v1.0.0: Versão inicial
+- v1.1.0: Nova funcionalidade (minor)
+- v1.0.1: Correção de bug (patch)
+- v2.0.0: Breaking change (major)
+
+FLUXO TÍPICO:
+1. git-tags create tag='v1.0.0' message='Release inicial'
+2. git-tags push tag='v1.0.0'`;
+
   async function handle(args) {
     const validate = ajv.compile(inputSchema);
     if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
@@ -27,38 +65,32 @@ export function createGitTagsTool(git) {
         return asToolResult({ tags, count: tags.length });
       }
       if (action === "create") {
-        const tag = args.tag;
-        if (!tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório", { parameter: "tag" });
-        // Auto-verificação: checar se já existe
+        if (!args.tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório", { parameter: "tag" });
         const existing = await git.listTags(projectPath);
-        if (existing.includes(tag)) {
-          return asToolError("TAG_ALREADY_EXISTS", `Tag '${tag}' já existe`, { tag, existingTags: existing });
+        if (existing.includes(args.tag)) {
+          return asToolError("TAG_ALREADY_EXISTS", `Tag '${args.tag}' já existe`, { tag: args.tag, existingTags: existing });
         }
-        await git.createTag(projectPath, tag, args.ref || "HEAD", args.message);
-        return asToolResult({ success: true, tag, ref: args.ref || "HEAD" });
+        await git.createTag(projectPath, args.tag, args.ref || "HEAD", args.message);
+        return asToolResult({ success: true, tag: args.tag, ref: args.ref || "HEAD", message: `Tag '${args.tag}' criada. Use action='push' para enviar ao GitHub/Gitea.` });
       }
       if (action === "delete") {
-        const tag = args.tag;
-        if (!tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório", { parameter: "tag" });
-        // Auto-verificação: checar se existe
+        if (!args.tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório", { parameter: "tag" });
         const existing = await git.listTags(projectPath);
-        if (!existing.includes(tag)) {
-          return asToolError("TAG_NOT_FOUND", `Tag '${tag}' não encontrada`, { tag, existingTags: existing });
+        if (!existing.includes(args.tag)) {
+          return asToolError("TAG_NOT_FOUND", `Tag '${args.tag}' não encontrada`, { tag: args.tag, existingTags: existing });
         }
-        await git.deleteTag(projectPath, tag);
-        return asToolResult({ success: true, tag });
+        await git.deleteTag(projectPath, args.tag);
+        return asToolResult({ success: true, tag: args.tag, deleted: true });
       }
       if (action === "push") {
-        const tag = args.tag;
-        if (!tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório", { parameter: "tag" });
-        // Auto-verificação: checar se existe
+        if (!args.tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório", { parameter: "tag" });
         const existing = await git.listTags(projectPath);
-        if (!existing.includes(tag)) {
-          return asToolError("TAG_NOT_FOUND", `Tag '${tag}' não existe localmente. Crie primeiro com action='create'`, { tag, existingTags: existing });
+        if (!existing.includes(args.tag)) {
+          return asToolError("TAG_NOT_FOUND", `Tag '${args.tag}' não existe localmente. Crie primeiro com action='create'`, { tag: args.tag, existingTags: existing });
         }
         const results = await Promise.allSettled([
-          git.pushTag(projectPath, "github", tag),
-          git.pushTag(projectPath, "gitea", tag)
+          git.pushTag(projectPath, "github", args.tag),
+          git.pushTag(projectPath, "gitea", args.tag)
         ]);
         const pushed = [];
         const failed = [];
@@ -67,13 +99,13 @@ export function createGitTagsTool(git) {
         if (results[1].status === "fulfilled") pushed.push("gitea");
         else failed.push({ remote: "gitea", error: results[1].reason?.message });
         
-        return asToolResult({ success: pushed.length > 0, tag, pushed, failed });
+        return asToolResult({ success: pushed.length > 0, tag: args.tag, pushed, failed });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "create", "delete", "push"] });
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["list", "create", "delete", "push"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-tags", description: "Gerencia tags e push paralelo", inputSchema, handle };
+  return { name: "git-tags", description, inputSchema, handle };
 }

package/src/tools/git-workflow.js

@@ -8,16 +8,56 @@ export function createGitWorkflowTool(pm, git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string", description: "Caminho absoluto do projeto" },
-      action: { type: "string", enum: ["init", "status", "add", "remove", "commit", "push", "pull", "sync", "ensure-remotes"], description: "Ação" },
-      files: { type: "array", items: { type: "string" } },
-      message: { type: "string" },
-      force: { type: "boolean", description: "Force push (para resolver divergências de histórico)" }
+      projectPath: { 
+        type: "string", 
+        description: "Caminho absoluto do diretório do projeto (ex: 'C:/Users/user/projeto' ou '/home/user/projeto')" 
+      },
+      action: { 
+        type: "string", 
+        enum: ["init", "status", "add", "remove", "commit", "push", "ensure-remotes"],
+        description: `Ação a executar:
+- init: Inicializa repositório git local E cria repos no GitHub/Gitea automaticamente
+- status: Retorna arquivos modificados, staged, untracked (use ANTES de commit para ver o que mudou)
+- add: Adiciona arquivos ao staging (use ANTES de commit)
+- remove: Remove arquivos do staging
+- commit: Cria commit com os arquivos staged (use DEPOIS de add)
+- push: Envia commits para GitHub E Gitea em paralelo (use DEPOIS de commit)
+- ensure-remotes: Configura remotes GitHub e Gitea (use se push falhar por falta de remote)`
+      },
+      files: { 
+        type: "array", 
+        items: { type: "string" },
+        description: "Lista de arquivos para add/remove. Use ['.'] para todos os arquivos. Ex: ['src/index.js', 'package.json']"
+      },
+      message: { 
+        type: "string",
+        description: "Mensagem do commit. Obrigatório para action='commit'. Ex: 'feat: adiciona nova funcionalidade'"
+      },
+      force: { 
+        type: "boolean", 
+        description: "Force push (use apenas se push normal falhar com erro de histórico divergente). Default: false"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Operações Git essenciais com sincronização automática GitHub + Gitea.
+
+FLUXO TÍPICO DE TRABALHO:
+1. git-workflow status → ver arquivos modificados
+2. git-workflow add → adicionar arquivos ao staging  
+3. git-workflow commit → criar commit
+4. git-workflow push → enviar para GitHub e Gitea
+
+QUANDO USAR CADA ACTION:
+- status: Para verificar estado atual do repositório
+- add: Quando há arquivos modificados para commitar
+- commit: Após add, para salvar as mudanças
+- push: Após commit, para sincronizar com remotes
+- init: Apenas uma vez, para novos projetos
+- ensure-remotes: Se push falhar por falta de configuração`;
+
   async function handle(args) {
     const validate = ajv.compile(inputSchema);
     if (!validate(args || {})) {
@@ -29,7 +69,7 @@ export function createGitWorkflowTool(pm, git) {
         await git.init(projectPath);
         const repo = getRepoNameFromPath(projectPath);
         const ensured = await pm.ensureRepos({ repoName: repo, createIfMissing: true });
-        return asToolResult({ success: true, ensured, message: "Repositório inicializado" });
+        return asToolResult({ success: true, ensured, message: "Repositório inicializado localmente e nos providers" });
       }
       if (action === "status") {
         const st = await git.status(projectPath);
@@ -38,7 +78,7 @@ export function createGitWorkflowTool(pm, git) {
       if (action === "add") {
         const files = Array.isArray(args.files) && args.files.length ? args.files : ["."];
         await git.add(projectPath, files);
-        return asToolResult({ success: true, files });
+        return asToolResult({ success: true, files, nextStep: "Use action='commit' com message para criar o commit" });
       }
       if (action === "remove") {
         const files = Array.isArray(args.files) ? args.files : [];
@@ -46,9 +86,11 @@ export function createGitWorkflowTool(pm, git) {
         return asToolResult({ success: true, files });
       }
       if (action === "commit") {
-        const msg = args.message || "update";
-        const sha = await git.commit(projectPath, msg);
-        return asToolResult({ success: true, sha, message: msg });
+        if (!args.message) {
+          return asToolError("MISSING_PARAMETER", "message é obrigatório para commit", { parameter: "message" });
+        }
+        const sha = await git.commit(projectPath, args.message);
+        return asToolResult({ success: true, sha, message: args.message, nextStep: "Use action='push' para enviar ao GitHub/Gitea" });
       }
       if (action === "ensure-remotes") {
         const repo = getRepoNameFromPath(projectPath);
@@ -59,20 +101,18 @@ export function createGitWorkflowTool(pm, git) {
         const base = pm.giteaUrl?.replace(/\/$/, "") || "";
         const giteaUrl = geOwner && base ? `${base}/${geOwner}/${repo}.git` : "";
         await git.ensureRemotes(projectPath, { githubUrl, giteaUrl });
-        return asToolResult({ success: true, ensured, remotes: { githubUrl, giteaUrl } });
+        const remotes = await git.listRemotes(projectPath);
+        return asToolResult({ success: true, ensured, remotes, nextStep: "Agora pode usar action='push'" });
       }
       if (action === "push") {
         const branch = await git.getCurrentBranch(projectPath);
         const force = !!args.force;
-        await git.pushParallel(projectPath, branch, force);
-        return asToolResult({ success: true, branch, remotes: ["github", "gitea"], force });
-      }
-      if (action === "sync" || action === "pull") {
-        // Basic implementation: fetch + status; full merge/pull can be added
-        return asToolResult({ success: true, message: "Operação de pull/sync não-op realizada" });
+        const result = await git.pushParallel(projectPath, branch, force);
+        return asToolResult({ success: true, branch, ...result });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { 
-        availableActions: ["init", "status", "add", "remove", "commit", "push", "pull", "sync", "ensure-remotes"] 
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { 
+        availableActions: ["init", "status", "add", "remove", "commit", "push", "ensure-remotes"],
+        suggestion: "Use uma das actions disponíveis"
       });
     } catch (e) {
       return errorToResponse(e);
@@ -81,9 +121,8 @@ export function createGitWorkflowTool(pm, git) {
 
   return {
     name: "git-workflow",
-    description: "Operações Git locais e remotas em paralelo (GitHub + Gitea)",
+    description,
     inputSchema,
     handle
   };
 }
-

package/src/utils/gitAdapter.js

@@ -6,6 +6,10 @@ import { MCPError, createError, mapExternalError } from "./errors.js";
 import { getProvidersEnv } from "./repoHelpers.js";
 import { withRetry } from "./retry.js";
 
+// #region agent log
+const debugLog = (loc, msg, data) => { fetch('http://127.0.0.1:8242/ingest/e5799a4a-1a0d-4201-a6ce-42835e6f6fc7',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:loc,message:msg,data,timestamp:Date.now(),sessionId:'debug-session'})}).catch(()=>{}); };
+// #endregion
+
 export class GitAdapter {
   constructor(providerManager) {
     this.pm = providerManager;
@@ -16,7 +20,14 @@ export class GitAdapter {
   }
 
   async status(dir) {
+    // #region agent log
+    const t0 = Date.now();
+    debugLog('gitAdapter.js:status', 'START statusMatrix', { dir, hypothesisId: 'A' });
+    // #endregion
     const matrix = await git.statusMatrix({ fs, dir });
+    // #region agent log
+    debugLog('gitAdapter.js:status', 'END statusMatrix', { duration: Date.now() - t0, fileCount: matrix.length, hypothesisId: 'A' });
+    // #endregion
     const FILE = 0, HEAD = 1, WORKDIR = 2, STAGE = 3;
     const modified = [], created = [], deleted = [], not_added = [], files = [];
     for (const row of matrix) {