@andre.buzeli/git-mcp 16.0.8 → 16.1.2

package/package.json

@@ -1,29 +1,32 @@
-{
-  "name": "@andre.buzeli/git-mcp",
-  "version": "16.0.8",
-  "private": false,
-  "description": "MCP server para Git com operações locais e sincronização paralela GitHub/Gitea",
-  "license": "MIT",
-  "author": "andre.buzeli",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "src",
-    "README.md"
-  ],
-  "main": "src/index.js",
-  "bin": {
-    "git-mcp": "src/index.js",
-    "git-mcpv2": "src/index.js"
-  },
-  "scripts": {},
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.4.0",
-    "@octokit/rest": "^20.0.0",
-    "ajv": "^8.12.0",
-    "archiver": "^7.0.0",
-    "axios": "^1.7.7"
-  }
-}
+{
+  "name": "@andre.buzeli/git-mcp",
+  "version": "16.1.2",
+  "private": false,
+  "description": "MCP server para Git com operações locais e sincronização paralela GitHub/Gitea",
+  "license": "MIT",
+  "author": "andre.buzeli",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "main": "src/index.js",
+  "bin": {
+    "git-mcp": "src/index.js",
+    "git-mcpv2": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "@octokit/rest": "^20.0.0",
+    "ajv": "^8.12.0",
+    "archiver": "^7.0.0",
+    "axios": "^1.7.7",
+    "zod": "^3.23.0"
+  }
+}

package/src/index.js

@@ -1,147 +1,159 @@
-#!/usr/bin/env node
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import Ajv from "ajv";
-import { loadEnv } from "./utils/env.js";
-import { asToolError } from "./utils/errors.js";
-import { ProviderManager } from "./providers/providerManager.js";
-import { GitAdapter } from "./utils/gitAdapter.js";
-import { createGitWorkflowTool } from "./tools/git-workflow.js";
-import { createGitRemoteTool } from "./tools/git-remote.js";
-import { createGitBranchesTool } from "./tools/git-branches.js";
-import { createGitTagsTool } from "./tools/git-tags.js";
-import { createGitStashTool } from "./tools/git-stash.js";
-import { createGitResetTool } from "./tools/git-reset.js";
-import { createGitConfigTool } from "./tools/git-config.js";
-import { createGitIgnoreTool } from "./tools/git-ignore.js";
-import { createGitFilesTool } from "./tools/git-files.js";
-import { createGitHistoryTool } from "./tools/git-history.js";
-import { createGitSyncTool } from "./tools/git-sync.js";
-import { createGitIssuesTool } from "./tools/git-issues.js";
-import { createGitPullsTool } from "./tools/git-pulls.js";
-import { createGitMergeTool } from "./tools/git-merge.js";
-import { createGitDiffTool } from "./tools/git-diff.js";
-import { createGitCloneTool } from "./tools/git-clone.js";
-import { createGitHelpTool } from "./tools/git-help.js";
-import { getResources, readResource } from "./resources/index.js";
-import { createPromptsHandler, PROMPTS } from "./prompts/index.js";
-
-// Carrega variáveis de ambiente do arquivo .env (se existir)
-loadEnv();
-
-const pm = new ProviderManager();
-const git = new GitAdapter(pm);
-
-// Log de inicialização para stderr (não interfere com stdio do MCP)
-const hasGitHub = !!process.env.GITHUB_TOKEN;
-const hasGitea = !!process.env.GITEA_URL && !!process.env.GITEA_TOKEN;
-if (!hasGitHub && !hasGitea) {
-  console.error("[git-mcp] ⚠️ Nenhum provider configurado. Operações remotas não funcionarão.");
-  console.error("[git-mcp] Configure GITHUB_TOKEN e/ou GITEA_URL + GITEA_TOKEN");
-} else {
-  const providers = [];
-  if (hasGitHub) providers.push("GitHub");
-  if (hasGitea) providers.push("Gitea");
-  console.error(`[git-mcp] ✓ Providers ativos: ${providers.join(", ")}`);
-}
-
-const transport = new StdioServerTransport();
-const server = new Server(
-  { name: "git-mcp", version: "15.12.4" },
-  { capabilities: { tools: {}, resources: {}, prompts: {} } }
-);
-server.connect(transport);
-
-// Prompts handler
-const promptsHandler = createPromptsHandler(git, pm);
-
-// Ajv singleton para validação
-const ajv = new Ajv({ allErrors: true });
-
-const tools = [
-  createGitHelpTool(),  // Primeiro: AI pode pedir ajuda
-  createGitWorkflowTool(pm, git),
-  createGitRemoteTool(pm, git),
-  createGitBranchesTool(git),
-  createGitTagsTool(git),
-  createGitStashTool(git),
-  createGitResetTool(git),
-  createGitConfigTool(git),
-  createGitIgnoreTool(git),
-  createGitFilesTool(git),
-  createGitHistoryTool(git),
-  createGitSyncTool(git),
-  createGitIssuesTool(pm),
-  createGitPullsTool(pm),
-  createGitMergeTool(git),
-  createGitDiffTool(git),
-  createGitCloneTool(git),
-];
-
-// ============ TOOLS ============
-server.setRequestHandler(
-  (await import("@modelcontextprotocol/sdk/types.js")).ListToolsRequestSchema,
-  async () => ({
-    tools: tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
-  })
-);
-
-server.setRequestHandler(
-  (await import("@modelcontextprotocol/sdk/types.js")).CallToolRequestSchema,
-  async (req) => {
-    const name = req.params?.name || "";
-    const args = req.params?.arguments || {};
-    // Progress reporting removed to prevent timeouts/unknown token errors on slow networks
-    // const progressToken = req.params?._meta?.progressToken;
-
-    const tool = tools.find(t => t.name === name);
-    if (!tool) return { content: [{ type: "text", text: `Tool não encontrada: ${name}` }], isError: true };
-    try {
-      // if (progressToken) { await server.notification({ method: "notifications/progress", params: { progressToken, progress: 0 } }); }
-
-      const result = await tool.handle(args);
-
-      // if (progressToken) { await server.notification({ method: "notifications/progress", params: { progressToken, progress: 100 } }); }
-
-      return result;
-    } catch (e) {
-      return asToolError(e.code || "ERROR", e.message || String(e));
-    }
-  }
-);
-
-// ============ RESOURCES ============
-server.setRequestHandler(
-  (await import("@modelcontextprotocol/sdk/types.js")).ListResourcesRequestSchema,
-  async () => ({ resources: getResources() })
-);
-
-server.setRequestHandler(
-  (await import("@modelcontextprotocol/sdk/types.js")).ReadResourceRequestSchema,
-  async (req) => {
-    const uri = req.params?.uri || "";
-    const content = readResource(uri);
-    if (!content) {
-      return { contents: [{ uri, mimeType: "text/plain", text: `Resource não encontrado: ${uri}` }] };
-    }
-    return { contents: [{ uri, mimeType: "text/markdown", text: content }] };
-  }
-);
-
-// ============ PROMPTS ============
-server.setRequestHandler(
-  (await import("@modelcontextprotocol/sdk/types.js")).ListPromptsRequestSchema,
-  async () => ({ prompts: PROMPTS })
-);
-
-server.setRequestHandler(
-  (await import("@modelcontextprotocol/sdk/types.js")).GetPromptRequestSchema,
-  async (req) => {
-    const name = req.params?.name || "";
-    const args = req.params?.arguments || {};
-    return await promptsHandler.get(name, args);
-  }
-);
-
-// Keep process alive
-process.stdin.resume();
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import Ajv from "ajv";
+import { loadEnv } from "./utils/env.js";
+import { asToolError } from "./utils/errors.js";
+import { ProviderManager } from "./providers/providerManager.js";
+import { GitAdapter } from "./utils/gitAdapter.js";
+import { createGitWorkflowTool } from "./tools/git-workflow.js";
+import { createGitRemoteTool } from "./tools/git-remote.js";
+import { createGitBranchesTool } from "./tools/git-branches.js";
+import { createGitTagsTool } from "./tools/git-tags.js";
+import { createGitStashTool } from "./tools/git-stash.js";
+import { createGitResetTool } from "./tools/git-reset.js";
+import { createGitConfigTool } from "./tools/git-config.js";
+import { createGitIgnoreTool } from "./tools/git-ignore.js";
+import { createGitFilesTool } from "./tools/git-files.js";
+import { createGitHistoryTool } from "./tools/git-history.js";
+import { createGitSyncTool } from "./tools/git-sync.js";
+import { createGitIssuesTool } from "./tools/git-issues.js";
+import { createGitPullsTool } from "./tools/git-pulls.js";
+import { createGitMergeTool } from "./tools/git-merge.js";
+import { createGitDiffTool } from "./tools/git-diff.js";
+import { createGitCloneTool } from "./tools/git-clone.js";
+import { createGitWorktreeTool } from "./tools/git-worktree.js";
+import { createGitHelpTool } from "./tools/git-help.js";
+import { getResources, readResource } from "./resources/index.js";
+import { createPromptsHandler, PROMPTS } from "./prompts/index.js";
+import { sendProgress } from "./utils/mcpNotify.js";
+
+// Carrega variáveis de ambiente do arquivo .env (se existir)
+loadEnv();
+
+const pm = new ProviderManager();
+const git = new GitAdapter(pm);
+
+// Log de inicialização para stderr (não interfere com stdio do MCP)
+const hasGitHub = !!process.env.GITHUB_TOKEN;
+const hasGitea = !!process.env.GITEA_URL && !!process.env.GITEA_TOKEN;
+if (!hasGitHub && !hasGitea) {
+  console.error("[git-mcp] ⚠️ Nenhum provider configurado. Operações remotas não funcionarão.");
+  console.error("[git-mcp] Configure GITHUB_TOKEN e/ou GITEA_URL + GITEA_TOKEN");
+} else {
+  const providers = [];
+  if (hasGitHub) providers.push("GitHub");
+  if (hasGitea) providers.push("Gitea");
+  console.error(`[git-mcp] ✓ Providers ativos: ${providers.join(", ")}`);
+}
+
+const transport = new StdioServerTransport();
+const server = new Server(
+  { name: "git-mcp", version: "16.0.8" },
+  { capabilities: {
+    tools: { listChanged: true },
+    resources: { subscribe: true, listChanged: true },
+    prompts: {},
+    logging: {}
+  } }
+);
+server.connect(transport);
+
+// Prompts handler
+const promptsHandler = createPromptsHandler(git, pm);
+
+// Ajv singleton para validação
+const ajv = new Ajv({ allErrors: true });
+
+const tools = [
+  createGitHelpTool(),  // Primeiro: AI pode pedir ajuda
+  createGitWorkflowTool(pm, git, server),
+  createGitRemoteTool(pm, git, server),
+  createGitBranchesTool(git),
+  createGitTagsTool(git),
+  createGitStashTool(git),
+  createGitResetTool(git, server),
+  createGitConfigTool(git),
+  createGitIgnoreTool(git),
+  createGitFilesTool(git),
+  createGitHistoryTool(git),
+  createGitSyncTool(git),
+  createGitIssuesTool(pm),
+  createGitPullsTool(pm),
+  createGitMergeTool(git),
+  createGitDiffTool(git),
+  createGitCloneTool(git),
+  createGitWorktreeTool(git),
+];
+
+// ============ TOOLS ============
+server.setRequestHandler(
+  (await import("@modelcontextprotocol/sdk/types.js")).ListToolsRequestSchema,
+  async () => ({
+    tools: tools.map(t => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+      annotations: t.annotations
+    })),
+  })
+);
+
+server.setRequestHandler(
+  (await import("@modelcontextprotocol/sdk/types.js")).CallToolRequestSchema,
+  async (req) => {
+    const name = req.params?.name || "";
+    const args = req.params?.arguments || {};
+    const progressToken = req.params?._meta?.progressToken;
+
+    const tool = tools.find(t => t.name === name);
+    if (!tool) return { content: [{ type: "text", text: `Tool não encontrada: ${name}` }], isError: true };
+    try {
+      await sendProgress(server, progressToken, 0, 100, `Executando ${name}...`);
+
+      const result = await tool.handle(args);
+
+      await sendProgress(server, progressToken, 100, 100, `${name} concluído`);
+
+      return result;
+    } catch (e) {
+      return asToolError(e.code || "ERROR", e.message || String(e));
+    }
+  }
+);
+
+// ============ RESOURCES ============
+server.setRequestHandler(
+  (await import("@modelcontextprotocol/sdk/types.js")).ListResourcesRequestSchema,
+  async () => ({ resources: getResources() })
+);
+
+server.setRequestHandler(
+  (await import("@modelcontextprotocol/sdk/types.js")).ReadResourceRequestSchema,
+  async (req) => {
+    const uri = req.params?.uri || "";
+    const content = readResource(uri);
+    if (!content) {
+      return { contents: [{ uri, mimeType: "text/plain", text: `Resource não encontrado: ${uri}` }] };
+    }
+    return { contents: [{ uri, mimeType: "text/markdown", text: content }] };
+  }
+);
+
+// ============ PROMPTS ============
+server.setRequestHandler(
+  (await import("@modelcontextprotocol/sdk/types.js")).ListPromptsRequestSchema,
+  async () => ({ prompts: PROMPTS })
+);
+
+server.setRequestHandler(
+  (await import("@modelcontextprotocol/sdk/types.js")).GetPromptRequestSchema,
+  async (req) => {
+    const name = req.params?.name || "";
+    const args = req.params?.arguments || {};
+    return await promptsHandler.get(name, args);
+  }
+);
+
+// Keep process alive
+process.stdin.resume();

package/src/tools/git-branches.js

@@ -10,7 +10,7 @@ export function createGitBranchesTool(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", 
@@ -39,7 +39,11 @@ export function createGitBranchesTool(git) {
     additionalProperties: false
   };
 
-  const description = `Gerenciamento de branches 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 branches Git.
 
 AÇÕES DISPONÍVEIS:
 - list: Ver branches existentes (locais e remotas)
@@ -122,5 +126,11 @@ CONVENÇÕES DE NOMES:
     }
   }
 
-  return { name: "git-branches", description, inputSchema, handle };
+  return { 
+    name: "git-branches", 
+    description, 
+    inputSchema, 
+    handle,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
+  };
 }

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