@andrebuzeli/git-mcp 13.7.0 → 14.0.0

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
   };
 }
-