@andre.buzeli/git-mcp 16.0.6 → 16.1.2

package/src/tools/git-clone.js

@@ -1,6 +1,7 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse, createError } from "../utils/errors.js";
-import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { validateProjectPath } from "../utils/repoHelpers.js";
+import { withRetry } from "../utils/retry.js";
 
 const ajv = new Ajv({ allErrors: true });
 
@@ -10,128 +11,90 @@ export function createGitCloneTool(git) {
     properties: {
       projectPath: { 
         type: "string",
-        description: "Caminho absoluto onde o repositório será clonado"
+        description: "Caminho absoluto do DIRETÓRIO PAI onde o repositório será clonado. O nome da pasta será o nome do repo, a menos que especificado."
       },
       action: { 
         type: "string", 
         enum: ["clone"],
-        description: "Ação a executar: clone - clona um repositório remoto"
+        description: "Ação a executar: clone"
       },
       url: { 
         type: "string",
-        description: "URL do repositório para clonar. Ex: 'https://github.com/user/repo.git'"
+        description: "URL do repositório Git (HTTPS ou SSH)"
+      },
+      name: { 
+        type: "string",
+        description: "Nome da pasta de destino (opcional). Se não informado, usa o nome do repo da URL"
       },
       branch: { 
         type: "string",
-        description: "Branch específica para clonar. Default: branch padrão do repo"
+        description: "Branch específica para clonar (opcional)"
       },
-      depth: {
+      depth: { 
         type: "number",
-        description: "Profundidade do clone (shallow clone). Ex: 1 para último commit apenas"
-      },
-      singleBranch: {
-        type: "boolean",
-        description: "Se true, clona apenas a branch especificada. Default: false"
+        description: "Profundidade do clone (shallow clone). Ex: 1 para apenas o último commit"
       }
     },
     required: ["projectPath", "action", "url"],
     additionalProperties: false
   };
 
-  const description = `Clonar repositórios remotos.
-
-QUANDO USAR:
-- Baixar um repositório existente do GitHub/Gitea
-- Iniciar trabalho em um projeto existente
-- Criar cópia local de um repositório
+  const description = `IMPORTANTE — projectPath:
+Informe o caminho absoluto do projeto aberto no IDE. O servidor MCP não tem acesso ao
+contexto do IDE e não consegue detectar automaticamente qual projeto está sendo trabalhado.
 
-EXEMPLOS:
-- Clone básico: action='clone' url='https://github.com/user/repo.git'
-- Clone shallow: action='clone' url='...' depth=1
-- Clone de branch: action='clone' url='...' branch='develop'
+Clonagem de repositórios Git.
 
-AUTENTICAÇÃO:
-- Repos públicos: Não precisa de token
-- Repos privados: Configure GITHUB_TOKEN ou GITEA_TOKEN
+QUANDO USAR:
+- Baixar um projeto existente do GitHub/Gitea
+- Iniciar trabalho em um novo repo
 
-NOTAS:
-- O diretório de destino será criado automaticamente
-- Se já existir arquivos, o clone falhará`;
+EXEMPLO:
+- Clonar repo: action='clone' url='https://github.com/user/repo.git'
+- Clonar em pasta específica: action='clone' url='...' name='minha-pasta'
+- Shallow clone (rápido): action='clone' url='...' depth=1`;
 
   async function handle(args) {
     const validate = ajv.compile(inputSchema);
     if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    
+    // projectPath aqui é o diretório PAI
     const { projectPath, action, url } = args;
     
     try {
-      // Validação de path
+      // Validar se diretório pai existe
+      // validateProjectPath verifica se existe.
       validateProjectPath(projectPath);
       
       if (action === "clone") {
-        if (!url) {
-          return asToolError("MISSING_PARAMETER", "url é obrigatório para clone", { 
-            parameter: "url",
-            example: "https://github.com/user/repo.git"
-          });
-        }
+        await withRetry(() => git.clone(projectPath, url, {
+          name: args.name,
+          branch: args.branch,
+          depth: args.depth
+        }), 3, "git-clone");
         
-        // Idempotency check
-        if (fs.existsSync(path.join(projectPath, ".git"))) {
-          try {
-            // Check if it's the same repo
-            // git.getRemoteUrl is not standard in adapter, use exec or listRemotes logic
-            // Assuming git.listRemotes or similar exists, or we catch the error
-            // Let's try to infer from config or just warn
-            
-            // We'll rely on git status to check if it's healthy
-            await git.status(projectPath);
-            
-            return asToolResult({
-              success: true,
-              url,
-              path: projectPath,
-              branch: args.branch || "current",
-              message: `Repositório já existe em '${projectPath}'. Clone ignorado (idempotente).`,
-              nextStep: "Use git-workflow status para ver o estado atual"
-            });
-          } catch (e) {
-            // If status fails, maybe it's broken
-            console.warn("Existing repo check failed:", e);
-          }
-        } else if (fs.existsSync(projectPath) && fs.readdirSync(projectPath).length > 0) {
-           return asToolError("DIR_NOT_EMPTY", `Diretório '${projectPath}' existe e não está vazio`, {
-             suggestion: "Use um diretório novo ou limpe o atual"
-           });
-        }
-
-        const result = await withRetry(
-          () => git.clone(url, projectPath, {
-            branch: args.branch,
-            depth: args.depth,
-            singleBranch: args.singleBranch
-          }),
-          3,
-          "clone"
-        );
+        const repoName = args.name || url.split("/").pop().replace(".git", "");
+        const finalPath = `${projectPath}/${repoName}`.replace("//", "/");
         
-        return asToolResult({
-          success: true,
-          url,
-          path: projectPath,
-          branch: result.branch || args.branch || "default",
-          ...result,
-          message: `Repositório clonado com sucesso em '${projectPath}'`,
-          nextStep: "Use git-workflow status para ver o estado do repositório"
+        return asToolResult({ 
+          success: true, 
+          message: `Repositório clonado com sucesso em '${finalPath}'`,
+          path: finalPath,
+          url
         });
       }
       
-      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { 
-        availableActions: ["clone"] 
-      });
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["clone"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-clone", description, inputSchema, handle };
+  return { 
+    name: "git-clone", 
+    description, 
+    inputSchema, 
+    handle,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
+  };
 }

package/src/tools/git-config.js

@@ -11,7 +11,7 @@ export function createGitConfigTool(git) {
     properties: {
       projectPath: {
         type: "string",
-        description: "Caminho absoluto do diretório do projeto"
+        description: "Caminho absoluto do diretório do projeto no IDE (ex: '/home/user/meu-projeto' ou 'C:/Users/user/meu-projeto'). IMPORTANTE: este valor não pode ser inferido automaticamente pelo servidor — o agente deve fornecer o path real do projeto sendo trabalhado, não o diretório home do usuário."
       },
       action: {
         type: "string",
@@ -40,7 +40,11 @@ export function createGitConfigTool(git) {
     additionalProperties: false
   };
 
-  const description = `Gerenciamento de configurações Git.
+  const description = `IMPORTANTE — projectPath:
+Informe o caminho absoluto do projeto aberto no IDE. O servidor MCP não tem acesso ao
+contexto do IDE e não consegue detectar automaticamente qual projeto está sendo trabalhado.
+
+Gerenciamento de configurações Git.
 
 CONFIGURAÇÕES COMUNS:
 - user.name: Nome do autor dos commits
@@ -90,5 +94,11 @@ EXEMPLOS:
     }
   }
 
-  return { name: "git-config", description, inputSchema, handle };
+  return { 
+    name: "git-config", 
+    description, 
+    inputSchema, 
+    handle,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
+  };
 }

package/src/tools/git-diff.js

@@ -1,137 +1,121 @@
-import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
-import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
-
-const ajv = new Ajv({ allErrors: true });
-
-export function createGitDiffTool(git) {
-  const inputSchema = {
-    type: "object",
-    properties: {
-      projectPath: {
-        type: "string",
-        description: "Caminho absoluto do diretório do projeto"
-      },
-      action: {
-        type: "string",
-        enum: ["show", "compare", "stat"],
-        description: `Ação a executar:
-- show: Mostra diff do working directory (arquivos não commitados)
-- compare: Compara dois commits/branches/tags
-- stat: Mostra estatísticas (arquivos alterados, linhas +/-)`
-      },
-      from: {
-        type: "string",
-        description: "Ref inicial para comparação (commit SHA, branch, tag). Default: HEAD"
-      },
-      fromRef: {
-        type: "string",
-        description: "Alias para 'from'. Ref inicial para comparação"
-      },
-      to: {
-        type: "string",
-        description: "Ref final para comparação. Se não fornecido, compara com working directory"
-      },
-      toRef: {
-        type: "string",
-        description: "Alias para 'to'. Ref final para comparação"
-      },
-      file: {
-        type: "string",
-        description: "Arquivo específico para ver diff. Se não fornecido, mostra todos"
-      },
-      filepath: {
-        type: "string",
-        description: "Alias para 'file'. Arquivo específico para ver diff"
-      },
-      context: {
-        type: "number",
-        description: "Número de linhas de contexto ao redor das mudanças. Default: 3"
-      }
-    },
-    required: ["projectPath", "action"],
-    additionalProperties: false
-  };
-
-  const description = `Ver diferenças entre commits, branches ou arquivos.
-
-QUANDO USAR:
-- Ver o que mudou antes de commitar (action='show')
-- Comparar branches antes de merge (action='compare')
-- Ver estatísticas de mudanças (action='stat')
-
-EXEMPLOS:
-- Ver mudanças não commitadas: action='show'
-- Ver mudanças de um arquivo: action='show' file='src/index.js'
-- Comparar com último commit: action='compare' from='HEAD~1'
-- Comparar branches: action='compare' from='main' to='feature/x'
-- Ver stats: action='stat' from='main' to='develop'`;
-
-  async function handle(args) {
-    const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
-    const { projectPath, action } = args;
-
-    // Support aliases: fromRef -> from, toRef -> to, filepath -> file
-    const fromParam = args.from || args.fromRef || "HEAD";
-    const toParam = args.to || args.toRef;
-    const fileParam = args.file || args.filepath;
-
-    try {
-      validateProjectPath(projectPath);
-      if (action === "show") {
-        const diff = await withRetry(() => git.diff(projectPath, {
-          file: fileParam,
-          context: args.context || 3
-        }), 3, "diff-show");
-
-        if (!diff || diff.length === 0) {
-          return asToolResult({
-            changes: [],
-            message: "Nenhuma mudança detectada no working directory"
-          });
-        }
-
-        return asToolResult({
-          changes: diff,
-          totalFiles: diff.length,
-          message: `${diff.length} arquivo(s) com mudanças`
-        });
-      }
-
-      if (action === "compare") {
-        const diff = await withRetry(() => git.diffCommits(projectPath, fromParam, toParam, {
-          file: fileParam,
-          context: args.context || 3
-        }), 3, "diff-compare");
-
-        return asToolResult({
-          from: fromParam,
-          to: toParam || "working directory",
-          changes: diff,
-          totalFiles: diff.length,
-          message: `Comparando ${fromParam} com ${toParam || 'working directory'}: ${diff.length} arquivo(s)`
-        });
-      }
-
-      if (action === "stat") {
-        const stats = await withRetry(() => git.diffStats(projectPath, fromParam, toParam), 3, "diff-stat");
-
-        return asToolResult({
-          from: fromParam,
-          to: toParam || "working directory",
-          ...stats,
-          message: `${stats.filesChanged} arquivo(s), +${stats.insertions} -${stats.deletions}`
-        });
-      }
-
-      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, {
-        availableActions: ["show", "compare", "stat"]
-      });
-    } catch (e) {
-      return errorToResponse(e);
-    }
-  }
-
-  return { name: "git-diff", description, inputSchema, handle };
-}
+import Ajv from "ajv";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { validateProjectPath } from "../utils/repoHelpers.js";
+
+const ajv = new Ajv({ allErrors: true });
+
+export function createGitDiffTool(git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto no IDE (ex: '/home/user/meu-projeto' ou 'C:/Users/user/meu-projeto'). IMPORTANTE: este valor não pode ser inferido automaticamente pelo servidor — o agente deve fornecer o path real do projeto sendo trabalhado, não o diretório home do usuário."
+      },
+      action: { 
+        type: "string", 
+        enum: ["show", "compare", "stat"],
+        description: `Ação a executar:
+- show: Mostra diferenças não commitadas (working tree vs index/HEAD)
+- compare: Compara duas referências (branch vs branch, commit vs commit)
+- stat: Mostra estatísticas resumidas (arquivos alterados, inserções, deleções)`
+      },
+      target: { 
+        type: "string",
+        description: "Alvo da comparação (para action='compare'). Ex: 'HEAD', 'main', 'develop', 'abc1234'"
+      },
+      source: { 
+        type: "string",
+        description: "Origem da comparação (para action='compare'). Default: HEAD atual"
+      },
+      staged: {
+        type: "boolean",
+        description: "Para action='show': comparar staged vs HEAD (em vez de working vs index). Default: false"
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `IMPORTANTE — projectPath:
+Informe o caminho absoluto do projeto aberto no IDE. O servidor MCP não tem acesso ao
+contexto do IDE e não consegue detectar automaticamente qual projeto está sendo trabalhado.
+
+Visualização de diferenças (diff) no Git.
+
+QUANDO USAR:
+- Revisar mudanças antes de commitar (action='show')
+- Comparar branches antes de merge (action='compare')
+- Ver o que mudou entre versões
+
+EXEMPLOS:
+- Ver mudanças não commitadas: action='show'
+- Ver mudanças staged: action='show' staged=true
+- Comparar branch atual com main: action='compare' target='main'
+- Estatísticas de mudança: action='stat' target='HEAD~1'`;
+
+  async function handle(args) {
+    const validate = ajv.compile(inputSchema);
+    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    const { projectPath, action } = args;
+    
+    try {
+      validateProjectPath(projectPath);
+      
+      if (action === "show") {
+        const diff = await git.diff(projectPath, { staged: args.staged });
+        return asToolResult({ 
+          diff: diff || "Nenhuma diferença encontrada",
+          staged: !!args.staged
+        });
+      }
+      
+      if (action === "compare") {
+        if (!args.target) return asToolError("MISSING_PARAMETER", "target é obrigatório para compare", { parameter: "target", example: "main" });
+        const diff = await git.diff(projectPath, { target: args.target, source: args.source });
+        return asToolResult({ 
+          diff: diff || "Nenhuma diferença encontrada",
+          target: args.target,
+          source: args.source || "HEAD"
+        });
+      }
+      
+      if (action === "stat") {
+        // Implementação simplificada de diff --stat via git log ou diff
+        // Se target fornecido, compara HEAD com target. Se não, compara working com HEAD
+        // gitAdapter.diff já retorna texto. Para stat, precisaríamos parsear ou usar flag.
+        // O adaptador atual talvez não suporte --stat diretamente.
+        // Vamos retornar o diff normal com uma nota, ou tentar implementar se suportado.
+        // Assumindo que git.diff suporta options string ou object.
+        
+        // Se o adaptador não suportar stat nativamente, retornamos o diff normal
+        const diff = await git.diff(projectPath, { target: args.target, source: args.source });
+        
+        // Tentar gerar estatísticas simples do diff text
+        const filesChanged = (diff.match(/^diff --git/gm) || []).length;
+        const insertions = (diff.match(/^\+/gm) || []).length;
+        const deletions = (diff.match(/^-/gm) || []).length;
+        
+        return asToolResult({ 
+          summary: `${filesChanged} arquivos alterados, ${insertions} inserções(+), ${deletions} deleções(-)`,
+          filesChanged,
+          insertions,
+          deletions,
+          target: args.target
+        });
+      }
+      
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["show", "compare", "stat"] });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { 
+    name: "git-diff", 
+    description, 
+    inputSchema, 
+    handle,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  };
+}

package/src/tools/git-files.js

@@ -10,7 +10,7 @@ export function createGitFilesTool(git) {
     properties: {
       projectPath: { 
         type: "string",
-        description: "Caminho absoluto do diretório do projeto"
+        description: "Caminho absoluto do diretório do projeto no IDE (ex: '/home/user/meu-projeto' ou 'C:/Users/user/meu-projeto'). IMPORTANTE: este valor não pode ser inferido automaticamente pelo servidor — o agente deve fornecer o path real do projeto sendo trabalhado, não o diretório home do usuário."
       },
       action: { 
         type: "string", 
@@ -32,7 +32,11 @@ export function createGitFilesTool(git) {
     additionalProperties: false
   };
 
-  const description = `Leitura de arquivos do repositório Git.
+  const description = `IMPORTANTE — projectPath:
+Informe o caminho absoluto do projeto aberto no IDE. O servidor MCP não tem acesso ao
+contexto do IDE e não consegue detectar automaticamente qual projeto está sendo trabalhado.
+
+Leitura de arquivos do repositório Git.
 
 QUANDO USAR:
 - Ver arquivos de um commit antigo
@@ -78,5 +82,11 @@ NOTA: Esta tool lê arquivos do histórico Git, não do sistema de arquivos.`;
     }
   }
 
-  return { name: "git-files", description, inputSchema, handle };
+  return { 
+    name: "git-files", 
+    description, 
+    inputSchema, 
+    handle,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  };
 }