@andre.buzeli/git-mcp 15.12.5

package/src/tools/git-help.js

@@ -0,0 +1,284 @@
+import { asToolResult } from "../utils/errors.js";
+
+/**
+ * Tool de ajuda para AI Agents - fornece orientação sobre qual tool usar
+ */
+export function createGitHelpTool() {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "O que você quer fazer? Ex: 'criar repositório', 'fazer commit', 'criar branch'"
+      },
+      listTools: {
+        type: "boolean",
+        description: "Se true, lista todas as tools disponíveis com descrição resumida"
+      },
+      showFlows: {
+        type: "boolean",
+        description: "Se true, mostra fluxos de trabalho comuns"
+      }
+    },
+    additionalProperties: false
+  };
+
+  const TOOLS_SUMMARY = {
+    "git-workflow": {
+      purpose: "Operações básicas do dia-a-dia: init, status, add, commit, push, update (⭐ RECOMENDADO)",
+      actions: ["init", "status", "add", "remove", "commit", "push", "ensure-remotes", "clean", "update"],
+      useWhen: "Salvar e enviar mudanças. Use action='update' para fluxo automatizado completo (status → add → commit → push)"
+    },
+    "git-branches": {
+      purpose: "Gerenciar branches: criar, listar, trocar, deletar",
+      actions: ["list", "create", "checkout", "delete", "rename"],
+      useWhen: "Trabalhar em features isoladas, organizar desenvolvimento"
+    },
+    "git-merge": {
+      purpose: "Juntar branches após desenvolvimento",
+      actions: ["merge", "abort", "status"],
+      useWhen: "Integrar feature branch na main/develop"
+    },
+    "git-stash": {
+      purpose: "Salvar mudanças temporariamente sem commit",
+      actions: ["list", "save", "apply", "pop", "drop", "clear"],
+      useWhen: "Trocar de branch com mudanças não commitadas"
+    },
+    "git-tags": {
+      purpose: "Marcar versões/releases",
+      actions: ["list", "create", "delete", "push"],
+      useWhen: "Publicar versão (v1.0.0, v2.0.0)"
+    },
+    "git-history": {
+      purpose: "Ver histórico de commits",
+      actions: ["log"],
+      useWhen: "Encontrar commit específico, ver quem alterou o quê"
+    },
+    "git-diff": {
+      purpose: "Ver diferenças entre versões",
+      actions: ["show", "compare", "stat"],
+      useWhen: "Revisar mudanças antes de commit, comparar branches"
+    },
+    "git-reset": {
+      purpose: "Desfazer commits ou mudanças",
+      actions: ["soft", "mixed", "hard", "hard-clean"],
+      useWhen: "Desfazer último commit, limpar working directory"
+    },
+    "git-config": {
+      purpose: "Configurar Git (nome, email, etc)",
+      actions: ["get", "set", "unset", "list"],
+      useWhen: "Configurar autor dos commits"
+    },
+    "git-remote": {
+      purpose: "Operações em GitHub/Gitea",
+      actions: ["list", "ensure", "release-create", "topics-set", "label-create"],
+      useWhen: "Criar release, configurar repositório remoto"
+    },
+    "git-sync": {
+      purpose: "Sincronizar com remotes",
+      actions: ["fetch", "pull"],
+      useWhen: "Baixar mudanças de outros desenvolvedores"
+    },
+    "git-clone": {
+      purpose: "Clonar repositório existente",
+      actions: ["clone"],
+      useWhen: "Baixar projeto existente do GitHub/Gitea"
+    },
+    "git-ignore": {
+      purpose: "Gerenciar .gitignore",
+      actions: ["list", "create", "add", "remove"],
+      useWhen: "Ignorar arquivos (node_modules, .env, etc)"
+    },
+    "git-files": {
+      purpose: "Ler arquivos do histórico Git",
+      actions: ["list", "read"],
+      useWhen: "Ver arquivo em versão antiga"
+    },
+    "git-issues": {
+      purpose: "Gerenciar issues no GitHub/Gitea",
+      actions: ["create", "list", "comment"],
+      useWhen: "Reportar bugs, criar tarefas"
+    },
+    "git-pulls": {
+      purpose: "Gerenciar Pull Requests",
+      actions: ["create", "list", "files"],
+      useWhen: "Propor mudanças para review"
+    }
+  };
+
+  const COMMON_FLOWS = {
+    "novo-projeto": {
+      description: "Criar repositório do zero",
+      steps: [
+        { tool: "git-workflow", action: "init", note: "Inicializa git e cria repos no GitHub/Gitea" },
+        { tool: "git-workflow", action: "add", params: { files: ["."] } },
+        { tool: "git-workflow", action: "commit", params: { message: "Initial commit" } },
+        { tool: "git-workflow", action: "push" }
+      ]
+    },
+    "salvar-mudancas": {
+      description: "Salvar e enviar mudanças (fluxo automatizado)",
+      steps: [
+        { tool: "git-workflow", action: "update", params: { message: "sua mensagem" }, note: "⭐ Executa status, add, commit e push automaticamente" }
+      ]
+    },
+    "nova-feature": {
+      description: "Desenvolver feature em branch separada",
+      steps: [
+        { tool: "git-branches", action: "create", params: { branch: "feature/nome" } },
+        { tool: "git-branches", action: "checkout", params: { branch: "feature/nome" } },
+        { note: "... fazer mudanças ..." },
+        { tool: "git-workflow", action: "add" },
+        { tool: "git-workflow", action: "commit" },
+        { tool: "git-branches", action: "checkout", params: { branch: "main" } },
+        { tool: "git-merge", action: "merge", params: { branch: "feature/nome" } },
+        { tool: "git-workflow", action: "push" }
+      ]
+    },
+    "criar-release": {
+      description: "Publicar nova versão",
+      steps: [
+        { tool: "git-tags", action: "create", params: { tag: "v1.0.0", message: "Release v1.0.0" } },
+        { tool: "git-tags", action: "push", params: { tag: "v1.0.0" } },
+        { tool: "git-remote", action: "release-create", params: { tag: "v1.0.0", name: "v1.0.0" } }
+      ]
+    },
+    "desfazer-commit": {
+      description: "Desfazer último commit mantendo mudanças",
+      steps: [
+        { tool: "git-reset", action: "soft", params: { ref: "HEAD~1" } }
+      ]
+    },
+    "trocar-branch-com-mudancas": {
+      description: "Salvar mudanças e trocar de branch",
+      steps: [
+        { tool: "git-stash", action: "save", params: { message: "WIP" } },
+        { tool: "git-branches", action: "checkout", params: { branch: "outra-branch" } },
+        { note: "... fazer o que precisar ..." },
+        { tool: "git-branches", action: "checkout", params: { branch: "branch-original" } },
+        { tool: "git-stash", action: "pop" }
+      ]
+    }
+  };
+
+  // Mapeamento de intenções para tools
+  const INTENT_MAP = {
+    // Palavras-chave -> tool recomendada
+    "criar reposit": "git-workflow (action=init)",
+    "iniciar projeto": "git-workflow (action=init)",
+    "novo projeto": "git-workflow (action=init)",
+    "commit": "git-workflow (action=commit)",
+    "salvar": "git-workflow (action=update) - ⭐ fluxo completo automatizado",
+    "atualizar": "git-workflow (action=update) - ⭐ fluxo completo automatizado",
+    "update": "git-workflow (action=update) - ⭐ fluxo completo automatizado",
+    "push": "git-workflow (action=push)",
+    "enviar": "git-workflow (action=push)",
+    "branch": "git-branches",
+    "criar branch": "git-branches (action=create)",
+    "trocar branch": "git-branches (action=checkout)",
+    "merge": "git-merge",
+    "juntar": "git-merge",
+    "stash": "git-stash",
+    "guardar": "git-stash (action=save)",
+    "tag": "git-tags",
+    "versão": "git-tags",
+    "release": "git-remote (action=release-create)",
+    "histórico": "git-history",
+    "log": "git-history",
+    "diff": "git-diff",
+    "diferença": "git-diff",
+    "desfazer": "git-reset",
+    "reset": "git-reset",
+    "clone": "git-clone",
+    "clonar": "git-clone",
+    "baixar projeto": "git-clone",
+    "issue": "git-issues",
+    "bug": "git-issues (action=create)",
+    "pull request": "git-pulls",
+    "pr": "git-pulls",
+    "ignorar": "git-ignore",
+    "gitignore": "git-ignore",
+    "config": "git-config",
+    "configurar": "git-config",
+    "status": "git-workflow (action=status)",
+    "ver mudanças": "git-workflow (action=status)"
+  };
+
+  const description = `Ajuda para AI Agents - descobre qual tool usar para cada situação.
+
+USE ESTA TOOL QUANDO:
+- Não sabe qual git-* tool usar
+- Precisa ver fluxos de trabalho comuns
+- Quer lista de todas as tools disponíveis
+
+EXEMPLOS:
+• { "query": "como criar um repositório?" }
+• { "listTools": true }
+• { "showFlows": true }`;
+
+  async function handle(args) {
+    const { query, listTools, showFlows } = args || {};
+
+    // Listar todas as tools
+    if (listTools) {
+      return asToolResult({
+        tools: TOOLS_SUMMARY,
+        tip: "Use query='o que você quer fazer' para recomendação específica"
+      });
+    }
+
+    // Mostrar fluxos comuns
+    if (showFlows) {
+      return asToolResult({
+        flows: COMMON_FLOWS,
+        tip: "Siga os steps em ordem para cada fluxo"
+      });
+    }
+
+    // Buscar por query
+    if (query) {
+      const q = query.toLowerCase();
+      const matches = [];
+
+      for (const [intent, tool] of Object.entries(INTENT_MAP)) {
+        if (q.includes(intent) || intent.includes(q)) {
+          matches.push({ intent, recommendation: tool });
+        }
+      }
+
+      if (matches.length > 0) {
+        return asToolResult({
+          query,
+          recommendations: matches,
+          tip: "Use a tool recomendada com os parâmetros indicados"
+        });
+      }
+
+      return asToolResult({
+        query,
+        message: "Não encontrei recomendação específica. Veja todas as tools:",
+        tools: Object.keys(TOOLS_SUMMARY),
+        tip: "Use listTools=true para ver detalhes de cada tool"
+      });
+    }
+
+    // Sem parâmetros - retornar overview
+    return asToolResult({
+      message: "Git MCP - Tools para AI Agents",
+      availableTools: Object.keys(TOOLS_SUMMARY).length,
+      usage: {
+        "Recomendação": "{ query: 'o que você quer fazer' }",
+        "Listar tools": "{ listTools: true }",
+        "Ver fluxos": "{ showFlows: true }"
+      },
+      quickStart: "Para começar um projeto: git-workflow com action='init'"
+    });
+  }
+
+  return {
+    name: "git-help",
+    description,
+    inputSchema,
+    handle
+  };
+}

package/src/tools/git-history.js

@@ -0,0 +1,90 @@
+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 createGitHistoryTool(git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["log"],
+        description: "Ação a executar: log - exibe histórico de commits"
+      },
+      ref: { 
+        type: "string",
+        description: "Referência inicial para o log (branch, tag, SHA). Default: HEAD"
+      },
+      maxCount: { 
+        type: "number",
+        description: "Número máximo de commits a retornar. Default: 50"
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `Histórico de commits do repositório Git.
+
+QUANDO USAR:
+- Ver commits recentes
+- Encontrar SHA de commit específico para reset/checkout
+- Verificar quem fez qual alteração
+- Ver histórico de uma branch
+
+INFORMAÇÕES RETORNADAS:
+- sha: Hash completo do commit
+- shortSha: Hash curto (7 caracteres)
+- message: Mensagem do commit
+- author: Nome do autor
+- email: Email do autor
+- date: Data do commit
+
+EXEMPLOS:
+- Ver últimos 10 commits: action='log' maxCount=10
+- Ver histórico de branch: action='log' ref='develop'
+- Ver histórico de tag: action='log' ref='v1.0.0'`;
+
+  async function handle(args) {
+    const validate = ajv.compile(inputSchema);
+    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    const { projectPath, action } = args;
+    try {
+      validateProjectPath(projectPath);
+      if (action === "log") {
+        const items = await withRetry(() => git.log(projectPath, { ref: args.ref || "HEAD", maxCount: args.maxCount || 50 }), 3, "history-log");
+        if (items.length === 0) {
+          return asToolResult({ 
+            commits: [], 
+            count: 0, 
+            message: "Nenhum commit encontrado. Use git-workflow 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,
+          ref: args.ref || "HEAD"
+        });
+      }
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["log"] });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-history", description, inputSchema, handle };
+}

package/src/tools/git-ignore.js

@@ -0,0 +1,98 @@
+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 createGitIgnoreTool(git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["list", "create", "add", "remove"],
+        description: `Ação a executar:
+- list: Lista padrões atuais do .gitignore
+- create: Cria novo .gitignore (sobrescreve existente)
+- add: Adiciona padrões ao .gitignore existente
+- remove: Remove padrões do .gitignore`
+      },
+      patterns: { 
+        type: "array", 
+        items: { type: "string" },
+        description: "Padrões para ignorar. Ex: ['node_modules/', '*.log', '.env', 'dist/', '*.tmp']"
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `Gerenciamento do arquivo .gitignore.
+
+PADRÕES COMUNS:
+- node_modules/: Dependências Node.js
+- *.log: Arquivos de log
+- .env: Variáveis de ambiente (segredos)
+- dist/, build/: Arquivos compilados
+- .DS_Store: Arquivos do macOS
+- Thumbs.db: Arquivos do Windows
+- *.tmp, *.bak: Arquivos temporários
+- .idea/, .vscode/: Configurações de IDE
+
+SINTAXE:
+- pasta/: Ignora diretório
+- *.ext: Ignora por extensão
+- !arquivo: Exceção (não ignorar)
+- **/pasta: Ignora em qualquer nível
+
+EXEMPLOS:
+- Criar para Node.js: action='create' patterns=['node_modules/', '*.log', '.env', 'dist/']
+- Adicionar padrão: action='add' patterns=['*.tmp']`;
+
+  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;
+    const patterns = Array.isArray(args.patterns) ? args.patterns : [];
+    try {
+      validateProjectPath(projectPath);
+      if (action === "list") {
+        const items = await withRetry(() => git.listGitignore(projectPath), 3, "ignore-list");
+        return asToolResult({ patterns: items, count: items.length, hasGitignore: items.length > 0 || true });
+      }
+      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 withRetry(() => git.createGitignore(projectPath, patterns), 3, "ignore-create");
+        return asToolResult({ success: true, patterns, message: ".gitignore criado" });
+      }
+      if (action === "add") {
+        if (patterns.length === 0) {
+          return asToolError("MISSING_PARAMETER", "patterns é obrigatório", { parameter: "patterns" });
+        }
+        await withRetry(() => git.addToGitignore(projectPath, patterns), 3, "ignore-add");
+        return asToolResult({ success: true, added: patterns });
+      }
+      if (action === "remove") {
+        if (patterns.length === 0) {
+          return asToolError("MISSING_PARAMETER", "patterns é obrigatório", { parameter: "patterns" });
+        }
+        await withRetry(() => git.removeFromGitignore(projectPath, patterns), 3, "ignore-remove");
+        return asToolResult({ success: true, removed: patterns });
+      }
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["list", "create", "add", "remove"] });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-ignore", description, inputSchema, handle };
+}

package/src/tools/git-issues.js

@@ -0,0 +1,101 @@
+import Ajv from "ajv";
+import axios from "axios";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { getRepoNameFromPath, validateProjectPath, withRetry } from "../utils/repoHelpers.js";
+import { runBoth } from "../utils/providerExec.js";
+
+const ajv = new Ajv({ allErrors: true });
+
+export function createGitIssuesTool(pm) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: {
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: {
+        type: "string",
+        enum: ["create", "list", "comment"],
+        description: `Ação a executar:
+- create: Cria nova issue no GitHub E Gitea
+- list: Lista issues existentes
+- comment: Adiciona comentário a uma issue existente`
+      },
+      title: {
+        type: "string",
+        description: "Título da issue (obrigatório para action='create'). Ex: 'Bug: aplicação crasha ao clicar em salvar'"
+      },
+      body: {
+        type: "string",
+        description: "Descrição detalhada da issue ou texto do comentário"
+      },
+      number: {
+        type: "number",
+        description: "Número da issue para comentar (obrigatório para action='comment')"
+      },
+      organization: {
+        type: "string",
+        description: "Opcional. Nome da organização no GitHub/Gitea. Se informado, operações são feitas na org em vez da conta pessoal."
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `Gerenciamento de Issues no GitHub e Gitea.
+
+QUANDO USAR:
+- Reportar bugs encontrados
+- Sugerir novas funcionalidades
+- Documentar tarefas a fazer
+- Acompanhar progresso do projeto
+
+AÇÕES:
+- create: Criar nova issue (executa em AMBOS os providers)
+- list: Ver issues existentes
+- comment: Comentar em issue existente
+
+BOAS PRÁTICAS:
+- Use títulos descritivos
+- Inclua passos para reproduzir bugs
+- Use labels para categorizar (via git-remote label-create)`;
+
+  async function handle(args) {
+    const validate = ajv.compile(inputSchema);
+    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    validateProjectPath(args.projectPath);
+    const repo = getRepoNameFromPath(args.projectPath);
+    try {
+      if (args.action === "create") {
+        if (!args.title) return asToolError("MISSING_PARAMETER", "title é obrigatório para criar issue", { parameter: "title" });
+        const out = await withRetry(() => runBoth(pm, {
+          github: async (owner) => { const r = await pm.github.rest.issues.create({ owner, repo, title: args.title, body: args.body || "" }); return { ok: true, number: r.data.number, url: r.data.html_url }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.post(`${base}/api/v1/repos/${owner}/${repo}/issues`, { title: args.title, body: args.body || "" }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, number: r.data?.number }; }
+        }, { organization: args.organization }), 3, "issues-create");
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), title: args.title, providers: out });
+      }
+      if (args.action === "list") {
+        const out = await withRetry(() => runBoth(pm, {
+          github: async (owner) => { const r = await pm.github.rest.issues.listForRepo({ owner, repo, state: "all", per_page: 30 }); return { ok: true, count: r.data.length, issues: r.data.slice(0, 10).map(i => ({ number: i.number, title: i.title, state: i.state })) }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.get(`${base}/api/v1/repos/${owner}/${repo}/issues?state=all`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, count: (r.data || []).length, issues: (r.data || []).slice(0, 10).map(i => ({ number: i.number, title: i.title, state: i.state })) }; }
+        }, { organization: args.organization }), 3, "issues-list");
+        return asToolResult({ providers: out });
+      }
+      if (args.action === "comment") {
+        if (!args.number) return asToolError("MISSING_PARAMETER", "number é obrigatório para comentar", { parameter: "number" });
+        if (!args.body) return asToolError("MISSING_PARAMETER", "body é obrigatório para comentar", { parameter: "body" });
+        const out = await withRetry(() => runBoth(pm, {
+          github: async (owner) => { await pm.github.rest.issues.createComment({ owner, repo, issue_number: args.number, body: args.body }); return { ok: true }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.post(`${base}/api/v1/repos/${owner}/${repo}/issues/${args.number}/comments`, { body: args.body }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
+        }, { organization: args.organization }), 3, "issues-comment");
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), issueNumber: args.number, providers: out });
+      }
+      return asToolError("VALIDATION_ERROR", `Ação '${args.action}' não suportada`, { availableActions: ["create", "list", "comment"] });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-issues", description, inputSchema, handle };
+}