@andre.buzeli/git-mcp 16.1.3 → 16.1.6

package/README.md

@@ -17,10 +17,11 @@ Servidor MCP (Model Context Protocol) para operações Git locais sem git instal
       }
     }
   }
-}
+} 
 ```
 
-## Tools
+## Tools  
+
 
 - git-workflow: init, status, add, remove, commit, ensure-remotes, push
 - git-update: status -> add -> commit -> push (all-in-one)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andre.buzeli/git-mcp",
-  "version": "16.1.3",
+  "version": "16.1.6",
   "private": false,
   "description": "MCP server para Git com operações locais e sincronização paralela GitHub/Gitea",
   "license": "MIT",
@@ -19,14 +19,25 @@
     "git-mcpv2": "src/index.js"
   },
   "scripts": {
-    "start": "node src/index.js"
+    "start": "node src/index.js",
+    "test": "vitest run",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run --config tests/integration/vitest.config.js",
+    "test:e2e": "vitest run tests/e2e",
+    "test:property": "vitest run tests/property",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.11.0",
     "@octokit/rest": "^20.0.0",
-    "ajv": "^8.12.0",
+    "ajv": "^8.18.0",
     "archiver": "^7.0.0",
     "axios": "^1.7.7",
     "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "fast-check": "^4.6.0",
+    "vitest": "^4.1.0"
   }
 }

package/src/index.js

@@ -59,48 +59,44 @@ const server = new Server(
     },
     instructions: `# git-mcp — Instruções para AI Agents
 
-## REGRA #1: projectPath é OBRIGATÓRIO
-Toda tool (exceto git-help) exige "projectPath" com o caminho absoluto do projeto aberto no IDE.
-O servidor NÃO consegue detectar o projeto automaticamente.
-Exemplo: "projectPath": "C:/Users/user/meu-projeto" ou "/home/user/meu-projeto"
-
-## REGRA #2: action é OBRIGATÓRIO
-Toda tool usa o padrão { "projectPath": "...", "action": "nome-da-action", ...params }.
-Consulte o enum de cada tool para saber as actions disponíveis.
-
-## Guia Rápido de Tools
-
-| Necessidade | Tool | Action | Params obrigatórios |
-|-------------|------|--------|---------------------|
-| Atualizar projeto completo | git-workflow | update | message |
-| Ver status do repo | git-workflow | status | - |
-| Inicializar repo novo | git-workflow | init | - |
-| Ver diferenças locais | git-diff | show | - |
-| Comparar branches/commits | git-diff | compare | target |
-| Criar branch | git-branches | create | branch |
-| Trocar branch | git-branches | checkout | branch |
-| Listar branches | git-branches | list | - |
-| Merge de branch | git-merge | merge | sourceBranch |
-| Criar tag | git-tags | create | tag |
-| Clonar repo | git-clone | clone | url |
-| Criar issue | git-issues | create | title |
-| Criar PR | git-pulls | create | head, title |
-| Salvar stash | git-stash | save | - |
-| Reset commits | git-reset | soft/mixed/hard | - |
-| Configurar git | git-config | get/set | key |
-| Gerenciar .gitignore | git-ignore | add/list | patterns |
-| Ler arquivo do git | git-files | read | filepath |
-| Ver histórico | git-history | log | - |
-| Fetch/Pull remoto | git-sync | fetch/pull | - |
-| Gerenciar remotes | git-remote | list/ensure | - |
-
-## Exemplo Completo (ação mais comum)
-\`\`\`json
-{ "projectPath": "/caminho/do/projeto", "action": "update", "message": "feat: descrição das mudanças" }
-\`\`\`
-
-## Dica
-Use git-help action="listTools" para ver todas as tools e actions disponíveis em tempo real.`
+ATENÇÃO: NUNCA chame uma tool sem os parâmetros obrigatórios. Toda call incompleta retorna erro.
+
+## Parâmetros obrigatórios em TODAS as tools (exceto git-help)
+- "projectPath": caminho absoluto do projeto no sistema de arquivos do usuário. O servidor NÃO detecta automaticamente.
+- "action": string com o nome da action a executar (ver enum no schema de cada tool)
+
+## Exemplos prontos para uso — copie e substitua os valores
+
+git-workflow (update):  {"projectPath":"<PATH>","action":"update","message":"feat: descrição"}
+git-workflow (status):  {"projectPath":"<PATH>","action":"status"}
+git-workflow (init):    {"projectPath":"<PATH>","action":"init"}
+git-workflow (push):    {"projectPath":"<PATH>","action":"push"}
+git-diff (show):        {"projectPath":"<PATH>","action":"show"}
+git-diff (compare):     {"projectPath":"<PATH>","action":"compare","target":"main"}
+git-branches (list):    {"projectPath":"<PATH>","action":"list"}
+git-branches (create):  {"projectPath":"<PATH>","action":"create","branch":"feature/x"}
+git-branches (checkout):{"projectPath":"<PATH>","action":"checkout","branch":"main"}
+git-merge (merge):      {"projectPath":"<PATH>","action":"merge","branch":"feature/x"}
+git-tags (create):      {"projectPath":"<PATH>","action":"create","tag":"v1.0.0"}
+git-tags (push):        {"projectPath":"<PATH>","action":"push","tag":"v1.0.0"}
+git-stash (save):       {"projectPath":"<PATH>","action":"save"}
+git-stash (pop):        {"projectPath":"<PATH>","action":"pop"}
+git-reset (soft):       {"projectPath":"<PATH>","action":"soft","ref":"HEAD~1"}
+git-reset (hard):       {"projectPath":"<PATH>","action":"hard","ref":"HEAD~1"}
+git-history (log):      {"projectPath":"<PATH>","action":"log"}
+git-remote (ensure):    {"projectPath":"<PATH>","action":"ensure"}
+git-remote (list):      {"projectPath":"<PATH>","action":"list"}
+git-remote (release-create): {"projectPath":"<PATH>","action":"release-create","tag":"v1.0.0","name":"Release v1.0.0"}
+git-worktree (list):    {"projectPath":"<PATH>","action":"list"}
+git-worktree (add):     {"projectPath":"<PATH>","action":"add","branch":"feature/x"}
+git-sync (pull):        {"projectPath":"<PATH>","action":"pull"}
+git-config (get):       {"projectPath":"<PATH>","action":"get","key":"user.name"}
+git-ignore (add):       {"projectPath":"<PATH>","action":"add","patterns":["node_modules/"]}
+git-files (read):       {"projectPath":"<PATH>","action":"read","filepath":"package.json"}
+git-issues (create):    {"projectPath":"<PATH>","action":"create","title":"Bug: descrição"}
+git-pulls (create):     {"projectPath":"<PATH>","action":"create","head":"feature/x","base":"main","title":"feat: x"}
+git-clone (clone):      {"projectPath":"<PARENT_DIR>","action":"clone","url":"https://github.com/user/repo.git"}
+git-help:               {"listTools":true}  ← única tool sem projectPath/action obrigatórios`
   }
 );
 server.connect(transport);

package/src/resources/index.js

@@ -22,17 +22,21 @@ Operações Git essenciais.
 
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
-| **update** | **⭐ RECOMENDADO - Fluxo completo automatizado** | **message, files=["."], gitignore=["pattern"], force, skipIfClean, organization** |
-| status | Ver arquivos modificados/staged | - |
+| **update** | **⭐ RECOMENDADO - Fluxo completo automatizado** | **message (obrigatório), files=["."], gitignore=["pattern"], force, skipIfClean, channel, syncBranches, organization, isPublic, dryRun** |
+| status | Ver arquivos modificados/staged | dryRun |
 | add | Adicionar ao staging | files=["."] ou ["arquivo.js"] |
-| commit | Criar commit | message="descrição" (obrigatório) |
-| push | Enviar para GitHub+Gitea | force=true se histórico divergir |
-| init | Inicializar repo + criar remotes | createGitignore=true, organization |
-| ensure-remotes | Configurar remotes | organization |
-| clean | Remover arquivos não rastreados | - |
+| remove | Remover do staging | files=["arquivo.js"] |
+| commit | Criar commit | message="descrição" (obrigatório), dryRun |
+| push | Enviar para GitHub+Gitea | force=true se histórico divergir, organization |
+| init | Inicializar repo + criar remotes | createGitignore=true, isPublic, organization, dryRun |
+| ensure-remotes | Configurar remotes | organization, isPublic, dryRun |
+| clean | Remover arquivos não rastreados | dryRun |
+| init-branch | Criar worktree/branch atalho | branch (obrigatório), channel |
 
 **Exemplo update:** \`{ "projectPath": "/path", "action": "update", "message": "feat: nova func", "gitignore": ["*.log"] }\`
 **Com organização:** \`{ "projectPath": "/path", "action": "init", "organization": "automacao-casa" }\`
+**Com channel:** \`{ "projectPath": "/path", "action": "update", "message": "fix: patch", "channel": "beta" }\`
+**Sync worktrees:** \`{ "projectPath": "/path", "action": "update", "message": "sync", "syncBranches": true }\`
 
 ---
 
@@ -51,20 +55,20 @@ Gerenciar branches.
 
 ---
 
-## git-merge (NOVO)
+## git-merge
 Mesclar branches.
 
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
-| merge | Mesclar branch | sourceBranch="feature/x", targetBranch="main" |
-| status | Verificar conflitos | - |
-| abort | Abortar merge | - |
+| merge | Mesclar branch na branch atual | branch="feature/x" (obrigatório), message="opcional", squash=true |
+| status | Verificar se há merge em andamento | - |
+| abort | Abortar merge com conflitos | - |
 
-**Opções:** fastForwardOnly=true (só FF), squash=true (um commit)
+**Nota:** Faça checkout para a branch destino antes de executar merge. squash=true combina todos os commits em um.
 
 ---
 
-## git-diff (NOVO)
+## git-diff
 Visualizar diferenças.
 
 | Action | Descrição | Parâmetros |
@@ -75,14 +79,14 @@ Visualizar diferenças.
 
 ---
 
-## git-clone (NOVO)
+## git-clone
 Clonar repositórios.
 
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
-| clone | Clonar repo | url="https://...", targetPath="./pasta" |
+| clone | Clonar repo | url="https://..." (obrigatório), name="pasta-destino" (opcional) |
 
-**Opções:** branch="main", depth=1 (shallow clone)
+**Opções:** branch="main", depth=1 (shallow clone). projectPath é o diretório PAI onde o repo será clonado.
 
 ---
 
@@ -92,9 +96,9 @@ Versionamento semântico.
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
 | list | Listar tags | - |
-| create | Criar tag | tag="v1.0.0", message="opcional" |
-| delete | Deletar tag | tag="v1.0.0" |
-| push | Enviar para remotes | tag="v1.0.0" |
+| create | Criar tag | tag="v1.0.0" (obrigatório), ref="HEAD" (opcional), message="opcional" (cria tag anotada) |
+| delete | Deletar tag local | tag="v1.0.0" (obrigatório) |
+| push | Enviar para remotes | tag="v1.0.0" (obrigatório) |
 
 **Versões:** v1.0.0 (inicial), v1.1.0 (feature), v1.0.1 (bugfix), v2.0.0 (breaking)
 
@@ -106,10 +110,10 @@ Salvar mudanças temporariamente.
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
 | list | Ver stashes salvos | - |
-| save | Salvar mudanças | message="WIP", includeUntracked=true |
-| pop | Restaurar e remover | ref="stash@{0}" |
-| apply | Restaurar sem remover | ref="stash@{0}" |
-| drop | Remover sem restaurar | ref="stash@{0}" |
+| save | Salvar mudanças | message="WIP" (opcional), includeUntracked=true (opcional) |
+| pop | Restaurar e remover | ref="stash@{0}" (opcional, default: mais recente) |
+| apply | Restaurar sem remover | ref="stash@{0}" (opcional, default: mais recente) |
+| drop | Remover sem restaurar | ref="stash@{0}" (opcional, default: mais recente) |
 | clear | Remover todos | - |
 
 ---
@@ -119,12 +123,13 @@ Desfazer commits. ⚠️ CUIDADO
 
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
-| soft | Mantém mudanças staged | ref="HEAD~1" |
-| mixed | Mantém arquivos, remove staging | ref="HEAD~1" |
-| hard | ⚠️ DESCARTA tudo | ref="HEAD~1" |
-| hard-clean | ⚠️⚠️ DESCARTA + remove untracked | ref="HEAD" |
+| soft | Mantém mudanças staged | ref="HEAD~1" (obrigatório) |
+| mixed | Mantém arquivos, remove staging | ref="HEAD~1" (obrigatório) |
+| hard | ⚠️ DESCARTA tudo | ref="HEAD~1" (obrigatório) |
+| hard-clean | ⚠️⚠️ DESCARTA + remove untracked | ref="HEAD" (obrigatório) |
 
-**Refs:** HEAD~1 (1 commit), HEAD~2 (2 commits), SHA específico
+**Refs:** HEAD~1 (1 commit atrás), HEAD~2 (2 commits), SHA específico do commit
+**Nota:** hard e hard-clean pedem confirmação antes de executar.
 
 ---
 
@@ -146,6 +151,8 @@ Operações em repos remotos GitHub/Gitea.
 | fork-list | Listar forks | organization |
 | star-set | Dar estrela | - |
 | star-unset | Remover estrela | - |
+| subscription-set | Ativar notificações | - |
+| subscription-unset | Desativar notificações | - |
 | contents-create | Criar arquivo via API | path="", content="", branch="", organization |
 
 **Exemplo com organização:** \`{ "projectPath": "/path", "action": "ensure", "organization": "minha-org" }\`
@@ -171,9 +178,9 @@ Gerenciar issues.
 
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
-| create | Criar issue | title="Bug: ...", body="Descrição" |
-| list | Listar issues | - |
-| comment | Comentar | number=1, body="Comentário" |
+| create | Criar issue | title="Bug: ..." (obrigatório), body="Descrição", organization |
+| list | Listar issues | organization |
+| comment | Comentar | number=1 (obrigatório), body="Comentário" (obrigatório), organization |
 
 ---
 
@@ -182,9 +189,9 @@ Gerenciar Pull Requests.
 
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
-| create | Criar PR | head="feature/x", base="main", title="" |
-| list | Listar PRs | - |
-| files | Ver arquivos do PR | number=1 |
+| create | Criar PR | head="feature/x" (obrigatório), base="main" (obrigatório), title="", body="", organization |
+| list | Listar PRs | organization |
+| files | Ver arquivos do PR | number=1 (obrigatório), organization |
 
 ---
 
@@ -203,12 +210,13 @@ Configurações Git.
 
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
-| get | Obter valor | key="user.name" |
-| set | Definir valor | key="user.name", value="Nome" |
-| unset | Remover | key="user.name" |
+| get | Obter valor | key="user.name" (obrigatório), scope="local" |
+| set | Definir valor | key="user.name" (obrigatório), value="Nome", scope="local" |
+| unset | Remover | key="user.name" (obrigatório), scope="local" |
 | list | Listar todas | scope="local" |
 
-**Keys:** user.name, user.email, core.autocrlf
+**Keys comuns:** user.name, user.email, core.autocrlf, core.editor
+**Scopes:** local (só este repo), global (todos os repos), system (todo o sistema). Default: local
 
 ---
 
@@ -237,9 +245,39 @@ Gerenciar .gitignore.
 | Action | Descrição | Parâmetros |
 |--------|-----------|------------|
 | list | Ver padrões | - |
-| create | Criar .gitignore | patterns=["node_modules/","*.log"] |
-| add | Adicionar padrões | patterns=["dist/"] |
-| remove | Remover padrões | patterns=["*.log"] |
+| create | Criar .gitignore | patterns=["node_modules/","*.log"] (obrigatório) |
+| add | Adicionar padrões | patterns=["dist/"] (obrigatório) |
+| remove | Remover padrões | patterns=["*.log"] (obrigatório) |
+
+---
+
+## git-worktree
+Gerenciar múltiplos diretórios de trabalho (worktrees).
+
+| Action | Descrição | Parâmetros |
+|--------|-----------|------------|
+| list | Listar worktrees ativos | - |
+| add | Criar novo worktree | branch="nome" (obrigatório), path="caminho" (opcional), channel="production/beta/alpha", force |
+| remove | Remover worktree | branch="nome" ou path="caminho" (um obrigatório), force |
+| prune | Limpar worktrees deletados manualmente | - |
+| setup | Configurar estrutura recomendada | - |
+| set-channel | Definir canal de deploy da branch | branch="nome" (obrigatório), channel="production/beta/alpha" (obrigatório) |
+
+**Channels:** production (branch normal), beta (push para branch-beta), alpha (push para branch-alpha)
+**Nota:** path em add é relativo ao projectPath. Default: ../branch-name
+
+---
+
+## git-help
+Orientação sobre qual tool usar.
+
+| Parâmetro | Descrição |
+|-----------|-----------|
+| query="o que fazer" | Recomenda a tool certa para a intenção |
+| listTools=true | Lista todas as tools com descrição e actions |
+| showFlows=true | Mostra fluxos de trabalho comuns passo a passo |
+
+**Nota:** Única tool que não exige projectPath.
 
 ---
 

package/src/tools/git-branches.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -59,8 +59,11 @@ CONVENÇÕES DE NOMES:
 - release/versao: Para releases`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-branches", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-clone.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 import { withRetry } from "../utils/retry.js";
 
@@ -55,8 +55,11 @@ EXEMPLO:
 - Shallow clone (rápido): action='clone' url='...' depth=1`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-clone", { projectPath: "/path/to/parent", action: "clone", url: "https://github.com/user/repo.git" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     
     // projectPath aqui é o diretório PAI
     const { projectPath, action, url } = args;
@@ -67,6 +70,14 @@ EXEMPLO:
       validateProjectPath(projectPath);
       
       if (action === "clone") {
+        const validation = git.validateRemoteUrl(url);
+        if (!validation.valid) {
+            return asToolError("INVALID_URL", validation.error, {
+                url,
+                suggestion: validation.suggestion
+            });
+        }
+
         await withRetry(() => git.clone(projectPath, url, {
           name: args.name,
           branch: args.branch,

package/src/tools/git-config.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 import { withRetry } from "../utils/retry.js";
 
@@ -63,8 +63,11 @@ EXEMPLOS:
 - Ver nome: action='get' key='user.name'`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-config", { projectPath: "/path/to/project", action: "get", key: "user.name" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     const scope = args.scope || "local";
     try {

package/src/tools/git-diff.js

@@ -1,9 +1,23 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
 
+const DIFF_MAX_CHARS = 100_000;
+
+function applyDiffLimit(diff) {
+    if (!diff || diff.length <= DIFF_MAX_CHARS) {
+        return { diff: diff || "", truncated: false };
+    }
+    return {
+        diff: diff.substring(0, DIFF_MAX_CHARS),
+        truncated: true,
+        truncatedAt: DIFF_MAX_CHARS,
+        originalSize: diff.length
+    };
+}
+
 export function createGitDiffTool(git) {
   const inputSchema = {
     type: "object",
@@ -56,28 +70,35 @@ EXEMPLOS:
 - Estatísticas de mudança: action='stat' target='HEAD~1'`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-diff", { projectPath: "/path/to/project", action: "show" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    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 });
+        const raw = await git.diff(projectPath, { staged: args.staged });
+        const { diff, ...truncInfo } = applyDiffLimit(raw);
         return asToolResult({ 
           diff: diff || "Nenhuma diferença encontrada",
-          staged: !!args.staged
+          staged: !!args.staged,
+          ...truncInfo
         });
       }
       
       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 });
+        const raw = await git.diff(projectPath, { target: args.target, source: args.source });
+        const { diff, ...truncInfo } = applyDiffLimit(raw);
         return asToolResult({ 
           diff: diff || "Nenhuma diferença encontrada",
           target: args.target,
-          source: args.source || "HEAD"
+          source: args.source || "HEAD",
+          ...truncInfo
         });
       }
       

package/src/tools/git-files.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -52,8 +52,11 @@ EXEMPLOS:
 NOTA: Esta tool lê arquivos do histórico Git, não do sistema de arquivos.`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-files", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     const { projectPath, action } = args;
     try {
       validateProjectPath(projectPath);

package/src/tools/git-help.js

@@ -31,7 +31,7 @@ export function createGitHelpTool() {
     },
     "git-worktree": {
       purpose: "Gerenciar worktrees (multibranch)",
-      actions: ["add", "list", "remove", "setup", "set-channel"],
+      actions: ["add", "list", "remove", "prune", "setup", "set-channel"],
       useWhen: "Trabalhar em múltiplas branches/plataformas simultaneamente no mesmo repo"
     },
     "git-branches": {
@@ -76,8 +76,8 @@ export function createGitHelpTool() {
     },
     "git-remote": {
       purpose: "Operações em GitHub/Gitea",
-      actions: ["list", "ensure", "release-create", "topics-set", "label-create"],
-      useWhen: "Criar release, configurar repositório remoto"
+      actions: ["list", "list-all", "list-orgs", "ensure", "release-create", "topics-set", "label-create", "milestone-create", "fork-create", "fork-list", "star-set", "star-unset", "subscription-set", "subscription-unset", "contents-create", "repo-delete"],
+      useWhen: "Criar release, configurar repositório remoto, gerenciar repos remotos"
     },
     "git-sync": {
       purpose: "Sincronizar com remotes",
@@ -108,6 +108,11 @@ export function createGitHelpTool() {
       purpose: "Gerenciar Pull Requests",
       actions: ["create", "list", "files"],
       useWhen: "Propor mudanças para review"
+    },
+    "git-help": {
+      purpose: "Orientação sobre qual tool usar e fluxos de trabalho",
+      actions: ["query", "listTools", "showFlows"],
+      useWhen: "Não sabe qual tool usar, quer ver lista de tools ou fluxos comuns. Única tool sem projectPath obrigatório."
     }
   };
 

package/src/tools/git-history.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 
 const ajv = new Ajv({ allErrors: true });
@@ -58,13 +58,17 @@ EXEMPLOS:
 - Ver histórico de tag: action='log' ref='v1.0.0'`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-history", { projectPath: "/path/to/project", action: "log" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    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");
+        const maxCount = args.maxCount || 50;
+        const items = await withRetry(() => git.log(projectPath, { ref: args.ref || "HEAD", maxCount }), 3, "history-log");
         if (items.length === 0) {
           return asToolResult({ 
             commits: [], 
@@ -83,7 +87,8 @@ EXEMPLOS:
             date: c.date
           })), 
           count: items.length,
-          ref: args.ref || "HEAD"
+          ref: args.ref || "HEAD",
+          hasMore: items.length === maxCount
         });
       }
       return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["log"] });

package/src/tools/git-ignore.js

@@ -1,5 +1,5 @@
 import Ajv from "ajv";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { validateProjectPath } from "../utils/repoHelpers.js";
 import { withRetry } from "../utils/retry.js";
 
@@ -59,8 +59,11 @@ EXEMPLOS:
 - Adicionar padrão: action='add' patterns=['*.tmp']`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-ignore", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    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 {

package/src/tools/git-issues.js

@@ -1,6 +1,6 @@
 import Ajv from "ajv";
 import axios from "axios";
-import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { asToolError, asToolResult, errorToResponse, handleEmptyCall } from "../utils/errors.js";
 import { getRepoNameFromPath, validateProjectPath, withRetry } from "../utils/repoHelpers.js";
 import { runBoth } from "../utils/providerExec.js";
 
@@ -66,8 +66,11 @@ BOAS PRÁTICAS:
 - Use labels para categorizar (via git-remote label-create)`;
 
   async function handle(args) {
+    const emptyHelp = handleEmptyCall(args, inputSchema, "git-issues", { projectPath: "/path/to/project", action: "list" });
+    if (emptyHelp) return emptyHelp;
+
     const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    if (!validate(args)) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
     validateProjectPath(args.projectPath);
     const repo = getRepoNameFromPath(args.projectPath);
     try {