@andre.buzeli/git-mcp 16.1.2 → 16.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andre.buzeli/git-mcp",
-  "version": "16.1.2",
+  "version": "16.1.4",
   "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

@@ -49,13 +49,64 @@ if (!hasGitHub && !hasGitea) {
 
 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: {}
-  } }
+  { name: "git-mcp", version: "16.1.3" },
+  {
+    capabilities: {
+      tools: { listChanged: true },
+      resources: { subscribe: true, listChanged: true },
+      prompts: {},
+      logging: {}
+    },
+    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 |
+| Estatísticas de diff | git-diff | stat | - |
+| Criar branch | git-branches | create | branch |
+| Trocar branch | git-branches | checkout | branch |
+| Listar branches | git-branches | list | - |
+| Merge de branch | git-merge | merge | branch |
+| Criar tag | git-tags | create | tag |
+| Clonar repo | git-clone | clone | url |
+| Criar issue | git-issues | create | title |
+| Criar PR | git-pulls | create | head, base |
+| Salvar stash | git-stash | save | - |
+| Restaurar stash | git-stash | pop | - |
+| Reset commits | git-reset | soft/mixed/hard | ref |
+| 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 | - |
+| Criar release | git-remote | release-create | tag |
+| Gerenciar worktrees | git-worktree | add/list/remove | branch (add) |
+| Ajuda sobre tools | git-help | - | query/listTools/showFlows |
+
+## 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.`
+  }
 );
 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,38 +55,38 @@ 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 |
 |--------|-----------|------------|
-| show | Ver mudanças locais | filepath="src/file.js" (opcional) |
-| compare | Comparar commits | fromRef="HEAD~1", toRef="HEAD" |
-| stat | Estatísticas | fromRef="HEAD~1", toRef="HEAD" |
+| show | Ver mudanças locais (working vs HEAD) | staged=true (opcional, para staged vs HEAD) |
+| compare | Comparar branches/commits | target="main" (obrigatório), source="HEAD" (opcional) |
+| stat | Estatísticas resumidas | target="HEAD~1" (opcional), source (opcional) |
 
 ---
 
-## 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-clone.js

@@ -67,6 +67,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-diff.js

@@ -4,6 +4,20 @@ 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",
@@ -30,6 +44,7 @@ export function createGitDiffTool(git) {
       },
       staged: {
         type: "boolean",
+        default: false,
         description: "Para action='show': comparar staged vs HEAD (em vez de working vs index). Default: false"
       }
     },
@@ -63,20 +78,24 @@ EXEMPLOS:
       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-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

@@ -19,10 +19,12 @@ export function createGitHistoryTool(git) {
       },
       ref: { 
         type: "string",
+        default: "HEAD",
         description: "Referência inicial para o log (branch, tag, SHA). Default: HEAD"
       },
       maxCount: { 
         type: "number",
+        default: 50,
         description: "Número máximo de commits a retornar. Default: 50"
       }
     },
@@ -62,7 +64,8 @@ EXEMPLOS:
     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: [], 
@@ -81,7 +84,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-merge.js

@@ -98,11 +98,13 @@ SQUASH:
         // Pre-merge check: working tree status
         const status = await git.status(projectPath);
         if (!status.isClean) {
-          // We could warn or fail. Standard git refuses merge if changes would be overwritten.
-          // Let's just warn in logs or return error if critical?
-          // Git will fail anyway if conflicts with local changes.
-          // Let's inform the user.
-          console.warn("[GitMerge] Working tree not clean. Merge might fail.");
+            return asToolError("DIRTY_WORKING_TREE",
+                "Working tree com alterações não commitadas. Faça commit ou stash antes de mergear.", {
+                modified: status.modified,
+                staged: status.staged,
+                notAdded: status.not_added,
+                suggestion: "Use git-workflow action='update' para commitar as mudanças, ou git-stash para guardá-las temporariamente"
+            });
         }
 
         const currentBranch = await git.getCurrentBranch(projectPath);

package/src/tools/git-remote.js

@@ -167,7 +167,11 @@ ARQUIVOS VIA API:
       },
       content: {
         type: "string",
-        description: "Conteúdo do arquivo para contents-create"
+        description: "Conteúdo do arquivo para contents-create (texto simples, será convertido para base64 automaticamente)"
+      },
+      message: {
+        type: "string",
+        description: "Mensagem do commit para contents-create. Default: 'Add {path}'"
       },
       branch: {
         type: "string",

package/src/tools/git-stash.js

@@ -34,6 +34,7 @@ export function createGitStashTool(git) {
       },
       includeUntracked: {
         type: "boolean",
+        default: false,
         description: "Incluir arquivos não rastreados no stash (action='save'). Default: false"
       }
     },