@andrebuzeli/git-mcp 13.5.0 → 13.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrebuzeli/git-mcp",
-  "version": "13.5.0",
+  "version": "13.7.0",
   "private": false,
   "description": "MCP server para Git com operações locais e sincronização paralela GitHub/Gitea",
   "license": "MIT",

package/src/index.js

@@ -19,6 +19,10 @@ import { createGitSyncTool } from "./tools/git-sync.js";
 import { createGitIssuesTool } from "./tools/git-issues.js";
 import { createGitPullsTool } from "./tools/git-pulls.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
+
 const transport = new StdioServerTransport();
 const server = new Server({ name: "git-mcpv2", version: "0.0.0" });
 server.connect(transport);
@@ -66,6 +70,10 @@ server.setRequestHandler(
     const tool = tools.find(t => t.name === name);
     if (!tool) return { content: [{ type: "text", text: `Tool não encontrada: ${name}` }], isError: true };
     try {
+      // #region agent log
+      const startTime = Date.now();
+      debugLog('index.js:call', `START ${name}`, { action: args.action, projectPath: args.projectPath, hypothesisId: 'A' });
+      // #endregion
       if (progressToken) {
         await server.notification({ method: "notifications/progress", params: { progressToken, progress: 0 } });
       }
@@ -73,6 +81,9 @@ server.setRequestHandler(
       if (progressToken) {
         await server.notification({ method: "notifications/progress", params: { progressToken, progress: 100 } });
       }
+      // #region agent log
+      debugLog('index.js:call', `END ${name}`, { duration: Date.now() - startTime, hypothesisId: 'A' });
+      // #endregion
       return result;
     } catch (e) {
       return asToolError(e.code || "ERROR", e.message || String(e));

package/src/providers/providerManager.js

@@ -2,6 +2,10 @@ import { Octokit } from "@octokit/rest";
 import axios from "axios";
 import { getProvidersEnv } from "../utils/repoHelpers.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 ProviderManager {
   constructor() {
     const { githubToken, giteaUrl, giteaToken } = getProvidersEnv();
@@ -18,12 +22,22 @@ export class ProviderManager {
     if (!this.github) return "";
     const now = Date.now();
     if (this._githubOwner && now - this._ownerFetchedAt < 5 * 60 * 1000) return this._githubOwner;
+    // #region agent log
+    const t0 = Date.now();
+    debugLog('providerManager.js:getGitHubOwner', 'START API call', { hypothesisId: 'B' });
+    // #endregion
     try {
       const me = await this.github.rest.users.getAuthenticated();
       this._githubOwner = me.data.login || "";
       this._ownerFetchedAt = now;
+      // #region agent log
+      debugLog('providerManager.js:getGitHubOwner', 'END API call', { duration: Date.now() - t0, owner: this._githubOwner, hypothesisId: 'B' });
+      // #endregion
       return this._githubOwner;
     } catch {
+      // #region agent log
+      debugLog('providerManager.js:getGitHubOwner', 'FAILED API call', { duration: Date.now() - t0, hypothesisId: 'B' });
+      // #endregion
       return "";
     }
   }
@@ -32,6 +46,10 @@ export class ProviderManager {
     if (!this.giteaUrl || !this.giteaToken) return "";
     const now = Date.now();
     if (this._giteaOwner && now - this._ownerFetchedAt < 5 * 60 * 1000) return this._giteaOwner;
+    // #region agent log
+    const t0 = Date.now();
+    debugLog('providerManager.js:getGiteaOwner', 'START API call', { hypothesisId: 'B' });
+    // #endregion
     try {
       const r = await axios.get(`${this.giteaUrl}/api/v1/user`, {
         headers: { Authorization: `token ${this.giteaToken}` },
@@ -40,8 +58,14 @@ export class ProviderManager {
       const d = r.data || {};
       this._giteaOwner = d.login || d.username || "";
       this._ownerFetchedAt = now;
+      // #region agent log
+      debugLog('providerManager.js:getGiteaOwner', 'END API call', { duration: Date.now() - t0, owner: this._giteaOwner, hypothesisId: 'B' });
+      // #endregion
       return this._giteaOwner;
     } catch {
+      // #region agent log
+      debugLog('providerManager.js:getGiteaOwner', 'FAILED API call', { duration: Date.now() - t0, hypothesisId: 'B' });
+      // #endregion
       return "";
     }
   }

package/src/tools/git-branches.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -29,32 +29,46 @@ export function createGitBranchesTool(git) {
       }
       if (action === "create") {
         const ref = args.branch;
-        if (!ref) return asToolError("VALIDATION_ERROR", "branch é obrigatório");
+        if (!ref) return asToolError("MISSING_PARAMETER", "branch é obrigatório", { parameter: "branch" });
+        // Auto-correção: verificar se já existe
+        const existing = await git.listBranches(projectPath, false);
+        if (existing.includes(ref)) {
+          return asToolError("BRANCH_ALREADY_EXISTS", `Branch '${ref}' já existe`, { branch: ref, existingBranches: existing });
+        }
         await git.createBranch(projectPath, ref);
         return asToolResult({ success: true, branch: ref });
       }
       if (action === "delete") {
         const ref = args.branch;
-        if (!ref) return asToolError("VALIDATION_ERROR", "branch é obrigatório");
+        if (!ref) return asToolError("MISSING_PARAMETER", "branch é obrigatório", { parameter: "branch" });
+        // Auto-correção: verificar se existe e não é a atual
+        const existing = await git.listBranches(projectPath, false);
+        if (!existing.includes(ref)) {
+          return asToolError("BRANCH_NOT_FOUND", `Branch '${ref}' não encontrada`, { branch: ref, availableBranches: existing });
+        }
+        const current = await git.getCurrentBranch(projectPath);
+        if (ref === current) {
+          return asToolError("CANNOT_DELETE_CURRENT", `Não pode deletar branch atual '${ref}'`, { branch: ref, suggestion: "Faça checkout para outra branch primeiro" });
+        }
         await git.deleteBranch(projectPath, ref, !!args.force);
         return asToolResult({ success: true, branch: ref });
       }
       if (action === "rename") {
         const oldName = args.branch;
         const newName = args.newBranch;
-        if (!oldName || !newName) return asToolError("VALIDATION_ERROR", "branch e newBranch são obrigatórios");
+        if (!oldName || !newName) return asToolError("MISSING_PARAMETER", "branch e newBranch são obrigatórios", { parameters: ["branch", "newBranch"] });
         await git.renameBranch(projectPath, oldName, newName);
         return asToolResult({ success: true, from: oldName, to: newName });
       }
       if (action === "checkout") {
         const ref = args.branch;
-        if (!ref) return asToolError("VALIDATION_ERROR", "branch é obrigatório");
+        if (!ref) return asToolError("MISSING_PARAMETER", "branch é obrigatório", { parameter: "branch" });
         await git.checkout(projectPath, ref);
         return asToolResult({ success: true, branch: ref });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "create", "delete", "rename", "checkout"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 

package/src/tools/git-config.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -24,30 +24,29 @@ export function createGitConfigTool(git) {
     const scope = args.scope || "local";
     try {
       if (action === "get") {
-        if (!args.key) return asToolError("VALIDATION_ERROR", "key é obrigatório");
+        if (!args.key) return asToolError("MISSING_PARAMETER", "key é obrigatório", { parameter: "key" });
         const val = await git.getConfig(projectPath, args.key, scope);
-        return asToolResult({ key: args.key, value: val });
+        return asToolResult({ key: args.key, value: val, found: val !== undefined });
       }
       if (action === "set") {
-        if (!args.key) return asToolError("VALIDATION_ERROR", "key é obrigatório");
+        if (!args.key) return asToolError("MISSING_PARAMETER", "key é obrigatório", { parameter: "key" });
         await git.setConfig(projectPath, args.key, args.value ?? "", scope);
         return asToolResult({ success: true, key: args.key, value: args.value ?? "" });
       }
       if (action === "unset") {
-        if (!args.key) return asToolError("VALIDATION_ERROR", "key é obrigatório");
+        if (!args.key) return asToolError("MISSING_PARAMETER", "key é obrigatório", { parameter: "key" });
         await git.unsetConfig(projectPath, args.key, scope);
         return asToolResult({ success: true, key: args.key });
       }
       if (action === "list") {
         const items = await git.listConfig(projectPath, scope);
-        return asToolResult({ scope, items });
+        return asToolResult({ scope, items, count: Object.keys(items).length });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["get", "set", "unset", "list"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 
   return { name: "git-config", description: "Gerencia configurações Git (local/global/system)", inputSchema, handle };
 }
-

package/src/tools/git-files.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -23,19 +23,29 @@ export function createGitFilesTool(git) {
     try {
       if (action === "list") {
         const files = await git.listFiles(projectPath, args.ref || "HEAD");
-        return asToolResult({ files });
+        return asToolResult({ files, count: files.length });
       }
       if (action === "read") {
-        if (!args.filepath) return asToolError("VALIDATION_ERROR", "filepath é obrigatório");
-        const text = await git.readFile(projectPath, args.filepath, args.ref || "HEAD");
-        return { content: [{ type: "text", text }], isError: false };
+        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) {
+          // Auto-diagnóstico: listar arquivos disponíveis se não encontrar
+          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",
+            availableFiles: files.slice(0, 20),
+            totalFiles: files.length
+          });
+        }
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "read"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 
   return { name: "git-files", description: "Lista e lê arquivos do repo", inputSchema, handle };
 }
-

package/src/tools/git-history.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -23,14 +23,31 @@ export function createGitHistoryTool(git) {
     try {
       if (action === "log") {
         const items = await git.log(projectPath, { ref: args.ref || "HEAD", maxCount: args.maxCount || 50 });
-        return asToolResult({ commits: items });
+        if (items.length === 0) {
+          return asToolResult({ 
+            commits: [], 
+            count: 0, 
+            message: "Nenhum commit encontrado. Use action='commit' para criar o primeiro commit." 
+          });
+        }
+        return asToolResult({ 
+          commits: items.map(c => ({
+            sha: c.sha,
+            shortSha: c.sha.substring(0, 7),
+            message: c.message.split("\n")[0],
+            fullMessage: c.message,
+            author: c.author.name,
+            email: c.author.email,
+            date: c.date
+          })), 
+          count: items.length 
+        });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["log"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 
   return { name: "git-history", description: "Histórico de commits", inputSchema, handle };
 }
-

package/src/tools/git-ignore.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -23,26 +23,37 @@ export function createGitIgnoreTool(git) {
     try {
       if (action === "list") {
         const items = await git.listGitignore(projectPath);
-        return asToolResult({ items });
+        return asToolResult({ items, count: items.length });
       }
       if (action === "create") {
+        if (patterns.length === 0) {
+          return asToolError("MISSING_PARAMETER", "patterns é obrigatório para criar .gitignore", { 
+            parameter: "patterns",
+            suggestion: "Forneça um array de padrões, ex: ['node_modules/', '*.log', '.env']"
+          });
+        }
         await git.createGitignore(projectPath, patterns);
-        return asToolResult({ success: true });
+        return asToolResult({ success: true, patterns });
       }
       if (action === "add") {
+        if (patterns.length === 0) {
+          return asToolError("MISSING_PARAMETER", "patterns é obrigatório para adicionar ao .gitignore", { parameter: "patterns" });
+        }
         await git.addToGitignore(projectPath, patterns);
-        return asToolResult({ success: true });
+        return asToolResult({ success: true, added: patterns });
       }
       if (action === "remove") {
+        if (patterns.length === 0) {
+          return asToolError("MISSING_PARAMETER", "patterns é obrigatório para remover do .gitignore", { parameter: "patterns" });
+        }
         await git.removeFromGitignore(projectPath, patterns);
-        return asToolResult({ success: true });
+        return asToolResult({ success: true, removed: patterns });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "create", "add", "remove"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 
   return { name: "git-ignore", description: "Gerencia .gitignore", inputSchema, handle };
 }
-

package/src/tools/git-issues.js

@@ -1,6 +1,6 @@
 import Ajv from "ajv";
 import axios from "axios";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 import { getRepoNameFromPath } from "../utils/repoHelpers.js";
 import { runBoth } from "../utils/providerExec.js";
 
@@ -48,9 +48,9 @@ export function createGitIssuesTool(pm) {
         });
         return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), providers: out });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${args.action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${args.action}`, { availableActions: ["create", "list", "comment"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 

package/src/tools/git-pulls.js

@@ -1,6 +1,6 @@
 import Ajv from "ajv";
 import axios from "axios";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 import { getRepoNameFromPath } from "../utils/repoHelpers.js";
 import { runBoth } from "../utils/providerExec.js";
 
@@ -51,9 +51,9 @@ export function createGitPullsTool(pm) {
         });
         return asToolResult({ providers: out });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${args.action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${args.action}`, { availableActions: ["create", "list", "files"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 

package/src/tools/git-remote.js

@@ -1,6 +1,6 @@
 import Ajv from "ajv";
 import axios from "axios";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, mapExternalError } from "../utils/errors.js";
 import { getRepoNameFromPath } from "../utils/repoHelpers.js";
 import { runBoth } from "../utils/providerExec.js";
 
@@ -167,9 +167,11 @@ export function createGitRemoteTool(pm, git) {
         });
         return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), path: filePath, providers: out });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { 
+        availableActions: ["list", "ensure", "set-url", "repo-delete", "release-create", "topics-set", "milestone-create", "label-create", "fork-create", "fork-list", "star-set", "star-unset", "star-check", "subscription-set", "subscription-unset", "contents-create"] 
+      });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 

package/src/tools/git-reset.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -20,16 +20,31 @@ export function createGitResetTool(git) {
     if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action, ref } = args;
     try {
+      // Auto-verificação: checar se há commits suficientes para HEAD~N
+      if (ref.match(/HEAD~(\d+)/)) {
+        const match = ref.match(/HEAD~(\d+)/);
+        const steps = parseInt(match[1], 10);
+        const log = await git.log(projectPath, { maxCount: steps + 2 });
+        if (log.length <= steps) {
+          return asToolError("INSUFFICIENT_HISTORY", `Histórico insuficiente para ${ref}`, {
+            requestedSteps: steps,
+            availableCommits: log.length,
+            suggestion: `Use HEAD~${log.length - 1} no máximo, ou um SHA específico`,
+            recentCommits: log.slice(0, 5).map(c => ({ sha: c.sha.substring(0, 7), message: c.message.split("\n")[0] }))
+          });
+        }
+      }
+      
       if (action === "soft") await git.resetSoft(projectPath, ref);
       else if (action === "mixed") await git.resetMixed(projectPath, ref);
       else if (action === "hard") await git.resetHard(projectPath, ref);
-      else return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
-      return asToolResult({ success: true, action, ref });
+      else return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["soft", "mixed", "hard"] });
+      
+      return asToolResult({ success: true, action, ref, message: `Reset ${action} para ${ref} realizado` });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 
   return { name: "git-reset", description: "Reset soft/mixed/hard", inputSchema, handle };
 }
-

package/src/tools/git-stash.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -24,34 +24,55 @@ export function createGitStashTool(git) {
     try {
       if (action === "list") {
         const items = await git.listStash(projectPath);
-        return asToolResult({ items });
+        return asToolResult({ 
+          items: items.map((s, i) => ({ index: i, ref: `stash@{${i}}`, message: s.message, timestamp: s.timestamp })),
+          count: items.length 
+        });
       }
       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 });
+        return asToolResult({ success: true, message: args.message || "WIP" });
       }
       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 });
+        return asToolResult({ success: true, ref: args.ref || "stash@{0}" });
       }
       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 });
+        return asToolResult({ success: true, ref: args.ref || "stash@{0}" });
       }
       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 });
+        return asToolResult({ success: true, ref: args.ref || "stash@{0}" });
       }
       if (action === "clear") {
         await git.clearStash(projectPath);
-        return asToolResult({ success: true });
+        return asToolResult({ success: true, message: "Todos os stashes removidos" });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "save", "apply", "pop", "drop", "clear"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 
   return { name: "git-stash", description: "Gerencia stash", inputSchema, handle };
 }
-

package/src/tools/git-sync.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -26,17 +26,33 @@ export function createGitSyncTool(git) {
         const remotes = args.remote ? [args.remote] : ["origin", "github", "gitea"];
         const promises = remotes.map(r => git.fetch(projectPath, r, branch).then(() => ({ remote: r, ok: true })).catch(e => ({ remote: r, ok: false, error: String(e?.message || e) })));
         const results = await Promise.all(promises);
-        return asToolResult({ success: results.some(x => x.ok), branch, results });
+        const successful = results.filter(x => x.ok);
+        const failed = results.filter(x => !x.ok);
+        return asToolResult({ 
+          success: successful.length > 0, 
+          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
+        });
       }
       if (action === "pull") {
         const remotes = args.remote ? [args.remote] : ["origin", "github", "gitea"];
         const promises = remotes.map(r => git.pull(projectPath, r, branch).then(() => ({ remote: r, ok: true })).catch(e => ({ remote: r, ok: false, error: String(e?.message || e) })));
         const results = await Promise.all(promises);
-        return asToolResult({ success: results.some(x => x.ok), branch, results });
+        const successful = results.filter(x => x.ok);
+        const failed = results.filter(x => !x.ok);
+        return asToolResult({ 
+          success: successful.length > 0, 
+          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
+        });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["pull", "fetch"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 

package/src/tools/git-tags.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -24,35 +24,56 @@ export function createGitTagsTool(git) {
     try {
       if (action === "list") {
         const tags = await git.listTags(projectPath);
-        return asToolResult({ tags });
+        return asToolResult({ tags, count: tags.length });
       }
       if (action === "create") {
         const tag = args.tag;
-        if (!tag) return asToolError("VALIDATION_ERROR", "tag é obrigatório");
+        if (!tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório", { parameter: "tag" });
+        // Auto-verificação: checar se já existe
+        const existing = await git.listTags(projectPath);
+        if (existing.includes(tag)) {
+          return asToolError("TAG_ALREADY_EXISTS", `Tag '${tag}' já existe`, { tag, existingTags: existing });
+        }
         await git.createTag(projectPath, tag, args.ref || "HEAD", args.message);
-        return asToolResult({ success: true, tag });
+        return asToolResult({ success: true, tag, ref: args.ref || "HEAD" });
       }
       if (action === "delete") {
         const tag = args.tag;
-        if (!tag) return asToolError("VALIDATION_ERROR", "tag é obrigatório");
+        if (!tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório", { parameter: "tag" });
+        // Auto-verificação: checar se existe
+        const existing = await git.listTags(projectPath);
+        if (!existing.includes(tag)) {
+          return asToolError("TAG_NOT_FOUND", `Tag '${tag}' não encontrada`, { tag, existingTags: existing });
+        }
         await git.deleteTag(projectPath, tag);
         return asToolResult({ success: true, tag });
       }
       if (action === "push") {
         const tag = args.tag;
-        if (!tag) return asToolError("VALIDATION_ERROR", "tag é obrigatório");
-        await Promise.all([
-          git.pushTag(projectPath, "github", tag).catch(() => {}),
-          git.pushTag(projectPath, "gitea", tag).catch(() => {})
+        if (!tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório", { parameter: "tag" });
+        // Auto-verificação: checar se existe
+        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 });
+        }
+        const results = await Promise.allSettled([
+          git.pushTag(projectPath, "github", tag),
+          git.pushTag(projectPath, "gitea", tag)
         ]);
-        return asToolResult({ success: true, tag, remotes: ["github", "gitea"] });
+        const pushed = [];
+        const failed = [];
+        if (results[0].status === "fulfilled") pushed.push("github");
+        else failed.push({ remote: "github", error: results[0].reason?.message });
+        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 asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "create", "delete", "push"] });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 
   return { name: "git-tags", description: "Gerencia tags e push paralelo", inputSchema, handle };
 }
-

package/src/tools/git-workflow.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { MCPError, asToolError, asToolResult } from "../utils/errors.js";
+import { MCPError, asToolError, asToolResult, errorToResponse, createError } from "../utils/errors.js";
 import { getRepoNameFromPath } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -71,9 +71,11 @@ export function createGitWorkflowTool(pm, git) {
         // Basic implementation: fetch + status; full merge/pull can be added
         return asToolResult({ success: true, message: "Operação de pull/sync não-op realizada" });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`);
+      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { 
+        availableActions: ["init", "status", "add", "remove", "commit", "push", "pull", "sync", "ensure-remotes"] 
+      });
     } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
+      return errorToResponse(e);
     }
   }
 

package/src/utils/errors.js

@@ -1,3 +1,5 @@
+// Sistema de Erros Melhorado para AI Agents
+
 export class MCPError extends Error {
   constructor(code, message, data) {
     super(message);
@@ -6,6 +8,262 @@ export class MCPError extends Error {
   }
 }
 
+// Códigos de erro padronizados com sugestões para AI
+export const ERROR_CODES = {
+  // Auth
+  AUTH_GITHUB_INVALID: {
+    code: "AUTH_GITHUB_INVALID",
+    suggestion: "Verifique se GITHUB_TOKEN está configurado e é válido. Gere um novo token em github.com/settings/tokens"
+  },
+  AUTH_GITEA_INVALID: {
+    code: "AUTH_GITEA_INVALID", 
+    suggestion: "Verifique se GITEA_TOKEN e GITEA_URL estão configurados corretamente"
+  },
+  AUTH_NO_PERMISSION: {
+    code: "AUTH_NO_PERMISSION",
+    suggestion: "Token não tem permissão para esta operação. Verifique os scopes do token"
+  },
+  
+  // Repo
+  REPO_NOT_FOUND: {
+    code: "REPO_NOT_FOUND",
+    suggestion: "Repositório não existe. Use action='init' com createIfMissing=true para criar"
+  },
+  REPO_NO_WRITE: {
+    code: "REPO_NO_WRITE",
+    suggestion: "Sem permissão de escrita. Verifique se você é owner ou colaborador do repositório"
+  },
+  REPO_ALREADY_EXISTS: {
+    code: "REPO_ALREADY_EXISTS",
+    suggestion: "Repositório já existe. Use action='ensure' para verificar ou escolha outro nome"
+  },
+  
+  // Git Local
+  NOT_A_GIT_REPO: {
+    code: "NOT_A_GIT_REPO",
+    suggestion: "Diretório não é um repositório git. Use action='init' primeiro para inicializar"
+  },
+  NO_COMMITS: {
+    code: "NO_COMMITS",
+    suggestion: "Repositório não tem commits. Use action='add' e depois action='commit' primeiro"
+  },
+  NOTHING_TO_COMMIT: {
+    code: "NOTHING_TO_COMMIT",
+    suggestion: "Working tree limpa, nada para commitar. Modifique arquivos primeiro"
+  },
+  NOTHING_TO_PUSH: {
+    code: "NOTHING_TO_PUSH",
+    suggestion: "Nenhuma mudança para push. Faça commits primeiro"
+  },
+  
+  // Branches
+  BRANCH_NOT_FOUND: {
+    code: "BRANCH_NOT_FOUND",
+    suggestion: "Branch não existe. Use action='list' para ver branches disponíveis"
+  },
+  BRANCH_ALREADY_EXISTS: {
+    code: "BRANCH_ALREADY_EXISTS",
+    suggestion: "Branch já existe. Use outro nome ou delete a existente primeiro"
+  },
+  CANNOT_DELETE_CURRENT: {
+    code: "CANNOT_DELETE_CURRENT",
+    suggestion: "Não pode deletar branch atual. Faça checkout para outra branch primeiro"
+  },
+  
+  // Tags
+  TAG_NOT_FOUND: {
+    code: "TAG_NOT_FOUND",
+    suggestion: "Tag não existe. Use action='list' para ver tags disponíveis"
+  },
+  TAG_ALREADY_EXISTS: {
+    code: "TAG_ALREADY_EXISTS",
+    suggestion: "Tag já existe. Use outro nome ou delete a existente primeiro"
+  },
+  
+  // Refs
+  REF_NOT_FOUND: {
+    code: "REF_NOT_FOUND",
+    suggestion: "Referência não encontrada. Verifique se o commit/branch/tag existe. Use action='log' para ver histórico"
+  },
+  INSUFFICIENT_HISTORY: {
+    code: "INSUFFICIENT_HISTORY",
+    suggestion: "Histórico insuficiente para HEAD~N. Use action='log' para verificar quantos commits existem"
+  },
+  
+  // Stash
+  NOTHING_TO_STASH: {
+    code: "NOTHING_TO_STASH",
+    suggestion: "Working tree limpa, nada para stash. Modifique arquivos primeiro"
+  },
+  STASH_NOT_FOUND: {
+    code: "STASH_NOT_FOUND",
+    suggestion: "Stash não encontrado. Use action='list' para ver stashes disponíveis"
+  },
+  
+  // Remote
+  REMOTE_NOT_FOUND: {
+    code: "REMOTE_NOT_FOUND",
+    suggestion: "Remote não configurado. Use action='ensure-remotes' para configurar"
+  },
+  PUSH_REJECTED: {
+    code: "PUSH_REJECTED",
+    suggestion: "Push rejeitado (histórico divergente). Use force=true para forçar, ou faça pull primeiro"
+  },
+  MERGE_CONFLICT: {
+    code: "MERGE_CONFLICT",
+    suggestion: "Conflito de merge. Resolva conflitos manualmente e faça novo commit"
+  },
+  
+  // Network
+  NETWORK_TIMEOUT: {
+    code: "NETWORK_TIMEOUT",
+    suggestion: "Timeout de conexão. Verifique sua internet e tente novamente"
+  },
+  RATE_LIMIT: {
+    code: "RATE_LIMIT",
+    suggestion: "Rate limit excedido. Aguarde alguns minutos antes de tentar novamente"
+  },
+  
+  // Validation
+  VALIDATION_ERROR: {
+    code: "VALIDATION_ERROR",
+    suggestion: "Parâmetros inválidos. Verifique os parâmetros obrigatórios da action"
+  },
+  MISSING_PARAMETER: {
+    code: "MISSING_PARAMETER",
+    suggestion: "Parâmetro obrigatório faltando"
+  },
+  
+  // Files
+  FILE_NOT_FOUND: {
+    code: "FILE_NOT_FOUND",
+    suggestion: "Arquivo não encontrado no repositório. Use action='list' para ver arquivos disponíveis"
+  },
+  
+  // Issues/PRs
+  ISSUE_NOT_FOUND: {
+    code: "ISSUE_NOT_FOUND",
+    suggestion: "Issue não encontrada. Use action='list' para ver issues disponíveis"
+  },
+  PR_NOT_FOUND: {
+    code: "PR_NOT_FOUND",
+    suggestion: "Pull Request não encontrado. Use action='list' para ver PRs disponíveis"
+  },
+  
+  // Generic
+  UNKNOWN_ERROR: {
+    code: "UNKNOWN_ERROR",
+    suggestion: "Erro desconhecido. Verifique os logs para mais detalhes"
+  }
+};
+
+// Função para criar erro com sugestão
+export function createError(errorCode, details = {}) {
+  const errorInfo = ERROR_CODES[errorCode] || ERROR_CODES.UNKNOWN_ERROR;
+  return new MCPError(errorInfo.code, details.message || errorInfo.code, {
+    suggestion: errorInfo.suggestion,
+    ...details
+  });
+}
+
+// Função para mapear erros externos para códigos internos
+export function mapExternalError(error, context = {}) {
+  const msg = error?.message?.toLowerCase() || String(error).toLowerCase();
+  
+  // GitHub/Gitea API errors
+  if (msg.includes("bad credentials") || msg.includes("401")) {
+    return context.provider === "gitea" 
+      ? createError("AUTH_GITEA_INVALID", { originalError: msg })
+      : createError("AUTH_GITHUB_INVALID", { originalError: msg });
+  }
+  
+  if (msg.includes("not found") || msg.includes("404")) {
+    if (context.type === "repo") return createError("REPO_NOT_FOUND", { repo: context.repo, originalError: msg });
+    if (context.type === "branch") return createError("BRANCH_NOT_FOUND", { branch: context.branch, originalError: msg });
+    if (context.type === "tag") return createError("TAG_NOT_FOUND", { tag: context.tag, originalError: msg });
+    if (context.type === "file") return createError("FILE_NOT_FOUND", { file: context.file, originalError: msg });
+    if (context.type === "issue") return createError("ISSUE_NOT_FOUND", { number: context.number, originalError: msg });
+    if (context.type === "pr") return createError("PR_NOT_FOUND", { number: context.number, originalError: msg });
+    return createError("REF_NOT_FOUND", { ref: context.ref, originalError: msg });
+  }
+  
+  if (msg.includes("permission") || msg.includes("403") || msg.includes("forbidden")) {
+    return createError("AUTH_NO_PERMISSION", { originalError: msg });
+  }
+  
+  if (msg.includes("rate limit") || msg.includes("429")) {
+    return createError("RATE_LIMIT", { originalError: msg });
+  }
+  
+  if (msg.includes("timeout") || msg.includes("etimedout") || msg.includes("econnrefused")) {
+    return createError("NETWORK_TIMEOUT", { originalError: msg });
+  }
+  
+  if (msg.includes("push rejected") || msg.includes("non-fast-forward")) {
+    return createError("PUSH_REJECTED", { originalError: msg });
+  }
+  
+  if (msg.includes("conflict")) {
+    return createError("MERGE_CONFLICT", { originalError: msg });
+  }
+  
+  if (msg.includes("already exists")) {
+    if (context.type === "repo") return createError("REPO_ALREADY_EXISTS", { repo: context.repo, originalError: msg });
+    if (context.type === "branch") return createError("BRANCH_ALREADY_EXISTS", { branch: context.branch, originalError: msg });
+    if (context.type === "tag") return createError("TAG_ALREADY_EXISTS", { tag: context.tag, originalError: msg });
+    return createError("BRANCH_ALREADY_EXISTS", { originalError: msg });
+  }
+  
+  // isomorphic-git specific errors
+  if (msg.includes("could not find") && msg.includes("head~")) {
+    return createError("INSUFFICIENT_HISTORY", { originalError: msg });
+  }
+  
+  if (msg.includes("is not a git repository") || msg.includes("could not find .git")) {
+    return createError("NOT_A_GIT_REPO", { path: context.path, originalError: msg });
+  }
+  
+  if (msg.includes("nothing to commit") || msg.includes("working tree clean")) {
+    return createError("NOTHING_TO_COMMIT", { originalError: msg });
+  }
+  
+  if (msg.includes("could not resolve ref") || msg.includes("invalid reference")) {
+    return createError("REF_NOT_FOUND", { originalError: msg });
+  }
+  
+  if (msg.includes("branch") && (msg.includes("does not exist") || msg.includes("not found"))) {
+    return createError("BRANCH_NOT_FOUND", { originalError: msg });
+  }
+  
+  if (msg.includes("tag") && (msg.includes("does not exist") || msg.includes("not found"))) {
+    return createError("TAG_NOT_FOUND", { originalError: msg });
+  }
+  
+  if (msg.includes("no commits") || msg.includes("unknown revision")) {
+    return createError("NO_COMMITS", { originalError: msg });
+  }
+  
+  if (msg.includes("nada para stash") || msg.includes("nothing to stash") || msg.includes("no local changes")) {
+    return createError("NOTHING_TO_STASH", { originalError: msg });
+  }
+  
+  if (msg.includes("stash") && (msg.includes("not found") || msg.includes("não encontrado"))) {
+    return createError("STASH_NOT_FOUND", { originalError: msg });
+  }
+  
+  if (msg.includes("author") || msg.includes("committer")) {
+    return createError("VALIDATION_ERROR", { 
+      message: "Configure user.name e user.email", 
+      suggestion: "Use git-config para configurar ou forneça tokens de provider",
+      originalError: msg 
+    });
+  }
+  
+  // Generic fallback
+  return createError("UNKNOWN_ERROR", { originalError: msg, context });
+}
+
+// Resultado de sucesso
 export function asToolResult(result) {
   return {
     content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -13,10 +271,27 @@ export function asToolResult(result) {
   };
 }
 
+// Resultado de erro (formato melhorado para AI agents)
 export function asToolError(code, message, data) {
+  const errorInfo = ERROR_CODES[code] || {};
+  const response = {
+    error: true,
+    code: code,
+    message: message,
+    suggestion: errorInfo.suggestion || "Verifique os parâmetros e tente novamente",
+    ...data
+  };
   return {
-    content: [{ type: "text", text: JSON.stringify({ code, message, data }) }],
+    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
     isError: true,
   };
 }
 
+// Helper para converter MCPError em resposta
+export function errorToResponse(error) {
+  if (error instanceof MCPError) {
+    return asToolError(error.code, error.message, error.data);
+  }
+  const mapped = mapExternalError(error);
+  return asToolError(mapped.code, mapped.message, mapped.data);
+}

package/src/utils/gitAdapter.js

@@ -2,8 +2,13 @@ import * as git from "isomorphic-git";
 import fs from "node:fs";
 import path from "node:path";
 import http from "isomorphic-git/http/node";
-import { MCPError } from "./errors.js";
+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) {
@@ -15,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) {
@@ -90,27 +102,58 @@ export class GitAdapter {
   getAuth(remoteUrl) {
     const { githubToken, giteaToken } = getProvidersEnv();
     if (remoteUrl.includes("github.com")) {
-      if (!githubToken) throw new MCPError("AUTH", "GITHUB_TOKEN ausente");
+      if (!githubToken) throw createError("AUTH_GITHUB_INVALID", { message: "GITHUB_TOKEN não configurado" });
       return () => ({ username: githubToken, password: "x-oauth-basic" });
     }
     if (giteaToken) return () => ({ username: "git", password: giteaToken });
-    throw new MCPError("AUTH", "GITEA_TOKEN ausente");
+    throw createError("AUTH_GITEA_INVALID", { message: "GITEA_TOKEN não configurado" });
   }
 
   async pushOne(dir, remote, branch, force = false) {
     const remotes = await git.listRemotes({ fs, dir });
     const info = remotes.find(r => r.remote === remote);
-    if (!info) throw new MCPError("REMOTE", `Remote '${remote}' não encontrado`);
+    if (!info) {
+      const available = remotes.map(r => r.remote).join(", ");
+      throw createError("REMOTE_NOT_FOUND", { 
+        message: `Remote '${remote}' não encontrado`, 
+        remote, 
+        availableRemotes: available || "nenhum" 
+      });
+    }
     const onAuth = this.getAuth(info.url);
     const ref = branch.startsWith("refs/") ? branch : `refs/heads/${branch}`;
-    await git.push({ fs, http, dir, remote, ref, remoteRef: ref, onAuth, force });
+    try {
+      await withRetry(() => git.push({ fs, http, dir, remote, ref, remoteRef: ref, onAuth, force }));
+    } catch (e) {
+      if (e.message?.includes("non-fast-forward") || e.message?.includes("rejected")) {
+        throw createError("PUSH_REJECTED", { message: e.message, remote, branch });
+      }
+      throw mapExternalError(e, { type: "push", remote, branch });
+    }
   }
 
   async pushParallel(dir, branch, force = false) {
     const remotes = await git.listRemotes({ fs, dir });
     const targets = remotes.filter(r => ["github", "gitea"].includes(r.remote));
-    if (targets.length === 0) throw new MCPError("REMOTE", "Nenhum remote github/gitea configurado");
-    await Promise.all(targets.map(t => this.pushOne(dir, t.remote, branch, force)));
+    if (targets.length === 0) {
+      throw createError("REMOTE_NOT_FOUND", { 
+        message: "Nenhum remote github/gitea configurado",
+        availableRemotes: remotes.map(r => r.remote).join(", ") || "nenhum",
+        suggestion: "Use action='ensure-remotes' para configurar os remotes"
+      });
+    }
+    const results = await Promise.allSettled(targets.map(t => this.pushOne(dir, t.remote, branch, force)));
+    const errors = results.filter(r => r.status === "rejected");
+    if (errors.length === targets.length) {
+      throw createError("PUSH_REJECTED", { 
+        message: "Push falhou para todos os remotes",
+        errors: errors.map(e => e.reason?.message || String(e.reason))
+      });
+    }
+    return { 
+      pushed: targets.filter((t, i) => results[i].status === "fulfilled").map(t => t.remote),
+      failed: errors.map((e, i) => ({ remote: targets[i]?.remote, error: e.reason?.message }))
+    };
   }
 
   // ============ BRANCHES ============
@@ -188,7 +231,12 @@ export class GitAdapter {
 
   async saveStash(dir, message = "WIP", includeUntracked = false) {
     const st = await this.status(dir);
-    if (st.isClean && !includeUntracked) throw new MCPError("STASH", "Nada para stash");
+    if (st.isClean && !includeUntracked) {
+      throw createError("NOTHING_TO_STASH", { 
+        message: "Working tree limpa, nada para stash",
+        status: st
+      });
+    }
     
     // Salva arquivos modificados/adicionados
     const filesToSave = [...st.not_added, ...st.modified, ...st.created];
@@ -223,7 +271,14 @@ export class GitAdapter {
     const stashes = await this.listStash(dir);
     const idx = Number(ref.match(/\{(\d+)\}/)?.[1] || 0);
     const stash = stashes[idx];
-    if (!stash) throw new MCPError("STASH", "Stash não encontrado");
+    if (!stash) {
+      throw createError("STASH_NOT_FOUND", { 
+        message: `Stash '${ref}' não encontrado`,
+        requestedIndex: idx,
+        availableStashes: stashes.length,
+        stashList: stashes.map((s, i) => `stash@{${i}}: ${s.message}`).slice(0, 5)
+      });
+    }
     
     // Restaura arquivos do stash
     for (const [file, content] of Object.entries(stash.files)) {
@@ -330,17 +385,39 @@ export class GitAdapter {
   async fetch(dir, remote, branch) {
     const remotes = await git.listRemotes({ fs, dir });
     const info = remotes.find(r => r.remote === remote);
-    if (!info) throw new MCPError("REMOTE", `Remote '${remote}' não encontrado`);
+    if (!info) {
+      throw createError("REMOTE_NOT_FOUND", { 
+        message: `Remote '${remote}' não encontrado`,
+        availableRemotes: remotes.map(r => r.remote)
+      });
+    }
     const onAuth = this.getAuth(info.url);
-    await git.fetch({ fs, http, dir, remote, ref: branch, singleBranch: true, onAuth });
+    try {
+      await withRetry(() => git.fetch({ fs, http, dir, remote, ref: branch, singleBranch: true, onAuth }));
+    } catch (e) {
+      throw mapExternalError(e, { type: "fetch", remote, branch, provider: info.url.includes("github") ? "github" : "gitea" });
+    }
   }
 
   async pull(dir, remote, branch) {
     const remotes = await git.listRemotes({ fs, dir });
     const info = remotes.find(r => r.remote === remote);
-    if (!info) throw new MCPError("REMOTE", `Remote '${remote}' não encontrado`);
+    if (!info) {
+      throw createError("REMOTE_NOT_FOUND", { 
+        message: `Remote '${remote}' não encontrado`,
+        availableRemotes: remotes.map(r => r.remote)
+      });
+    }
     const onAuth = this.getAuth(info.url);
-    await git.pull({ fs, http, dir, remote, ref: branch, singleBranch: true, onAuth, author: await this.getAuthor(dir) });
+    const author = await this.getAuthor(dir);
+    try {
+      await withRetry(async () => git.pull({ fs, http, dir, remote, ref: branch, singleBranch: true, onAuth, author }));
+    } catch (e) {
+      if (e.message?.includes("conflict")) {
+        throw createError("MERGE_CONFLICT", { message: e.message, remote, branch });
+      }
+      throw mapExternalError(e, { type: "pull", remote, branch, provider: info.url.includes("github") ? "github" : "gitea" });
+    }
   }
 
   // ============ RESET ============
@@ -352,10 +429,26 @@ export class GitAdapter {
       const steps = parseInt(match[2], 10);
       const commits = await git.log({ fs, dir, ref: baseRef, depth: steps + 1 });
       if (commits.length > steps) return commits[steps].oid;
-      throw new MCPError("REF", `Não foi possível resolver ${ref}`);
+      throw createError("INSUFFICIENT_HISTORY", { 
+        message: `Não foi possível resolver ${ref}`,
+        requestedSteps: steps,
+        availableCommits: commits.length,
+        suggestion: `Histórico tem apenas ${commits.length} commits. Use HEAD~${commits.length - 1} no máximo.`
+      });
     }
     // Refs normais
-    return await git.resolveRef({ fs, dir, ref });
+    try {
+      return await git.resolveRef({ fs, dir, ref });
+    } catch (e) {
+      const branches = await git.listBranches({ fs, dir }).catch(() => []);
+      const tags = await git.listTags({ fs, dir }).catch(() => []);
+      throw createError("REF_NOT_FOUND", { 
+        message: `Ref '${ref}' não encontrada`,
+        ref,
+        availableBranches: branches.slice(0, 10),
+        availableTags: tags.slice(0, 10)
+      });
+    }
   }
 
   async resetSoft(dir, ref) {

package/src/utils/retry.js

@@ -1,12 +1,61 @@
-export async function withRetry(fn, { retries = 3, baseDelayMs = 300 } = {}) {
-  let attempt = 0;
-  let lastErr;
-  while (attempt < retries) {
-    try { return await fn(); } catch (e) { lastErr = e; }
-    const delay = baseDelayMs * Math.pow(2, attempt);
-    await new Promise(r => setTimeout(r, delay));
-    attempt++;
+// Sistema de Retry com Backoff Exponencial
+
+const DEFAULT_OPTIONS = {
+  maxRetries: 3,
+  initialDelay: 1000,
+  maxDelay: 10000,
+  backoffFactor: 2,
+  retryableErrors: ["ETIMEDOUT", "ECONNRESET", "ENOTFOUND", "ECONNREFUSED", "timeout", "rate limit", "429", "503", "502"]
+};
+
+function shouldRetry(error, options) {
+  const msg = (error?.message || String(error)).toLowerCase();
+  const code = error?.code?.toLowerCase() || "";
+  
+  return options.retryableErrors.some(e => 
+    msg.includes(e.toLowerCase()) || code.includes(e.toLowerCase())
+  );
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function withRetry(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  let lastError;
+  let delay = opts.initialDelay;
+  
+  for (let attempt = 1; attempt <= opts.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      
+      if (attempt === opts.maxRetries || !shouldRetry(error, opts)) {
+        throw error;
+      }
+      
+      // Log retry (silencioso)
+      console.error(`[Retry] Attempt ${attempt}/${opts.maxRetries} failed, retrying in ${delay}ms...`);
+      
+      await sleep(delay);
+      delay = Math.min(delay * opts.backoffFactor, opts.maxDelay);
+    }
   }
-  throw lastErr;
+  
+  throw lastError;
+}
+
+// Wrapper para axios com retry
+export async function axiosWithRetry(axiosInstance, config, options = {}) {
+  return withRetry(() => axiosInstance(config), options);
 }
 
+// Wrapper para operações git com retry
+export async function gitWithRetry(fn, options = {}) {
+  return withRetry(fn, {
+    ...options,
+    retryableErrors: [...DEFAULT_OPTIONS.retryableErrors, "ENOENT", "lock"]
+  });
+}