@andrebuzeli/git-mcp 13.7.0 → 14.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrebuzeli/git-mcp",
-  "version": "13.7.0",
+  "version": "14.0.0",
   "private": false,
   "description": "MCP server para Git com operações locais e sincronização paralela GitHub/Gitea",
   "license": "MIT",

package/src/tools/git-branches.js

@@ -7,16 +7,52 @@ export function createGitBranchesTool(git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["list", "create", "delete", "rename", "checkout"] },
-      branch: { type: "string" },
-      newBranch: { type: "string" },
-      force: { type: "boolean" }
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["list", "create", "delete", "rename", "checkout"],
+        description: `Ação a executar:
+- list: Lista todas as branches locais e remotas
+- create: Cria nova branch a partir do HEAD atual
+- delete: Remove uma branch (não pode ser a atual)
+- rename: Renomeia uma branch existente
+- checkout: Muda para outra branch`
+      },
+      branch: { 
+        type: "string",
+        description: "Nome da branch para create/delete/checkout. Ex: 'feature/nova-funcionalidade', 'bugfix/correcao'"
+      },
+      newBranch: { 
+        type: "string",
+        description: "Novo nome da branch (apenas para action='rename')"
+      },
+      force: { 
+        type: "boolean",
+        description: "Forçar delete mesmo se branch não está merged. Default: false"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Gerenciamento de branches Git.
+
+AÇÕES DISPONÍVEIS:
+- list: Ver branches existentes (locais e remotas)
+- create: Criar nova branch para desenvolvimento
+- checkout: Trocar de branch
+- delete: Remover branch após merge
+- rename: Renomear branch
+
+CONVENÇÕES DE NOMES:
+- feature/nome: Para novas funcionalidades
+- bugfix/nome: Para correções de bugs
+- hotfix/nome: Para correções urgentes
+- release/versao: Para releases`;
+
   async function handle(args) {
     const validate = ajv.compile(inputSchema);
     if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
@@ -25,53 +61,46 @@ export function createGitBranchesTool(git) {
       if (action === "list") {
         const local = await git.listBranches(projectPath, false);
         const remote = await git.listBranches(projectPath, true).catch(() => []);
-        return asToolResult({ local, remote });
+        const current = await git.getCurrentBranch(projectPath);
+        return asToolResult({ current, local, remote });
       }
       if (action === "create") {
-        const ref = args.branch;
-        if (!ref) return asToolError("MISSING_PARAMETER", "branch é obrigatório", { parameter: "branch" });
-        // Auto-correção: verificar se já existe
+        if (!args.branch) return asToolError("MISSING_PARAMETER", "branch é obrigatório para criar", { parameter: "branch" });
         const existing = await git.listBranches(projectPath, false);
-        if (existing.includes(ref)) {
-          return asToolError("BRANCH_ALREADY_EXISTS", `Branch '${ref}' já existe`, { branch: ref, existingBranches: existing });
+        if (existing.includes(args.branch)) {
+          return asToolError("BRANCH_ALREADY_EXISTS", `Branch '${args.branch}' já existe`, { branch: args.branch, existingBranches: existing });
         }
-        await git.createBranch(projectPath, ref);
-        return asToolResult({ success: true, branch: ref });
+        await git.createBranch(projectPath, args.branch);
+        return asToolResult({ success: true, branch: args.branch, message: `Branch '${args.branch}' criada. Use action='checkout' para mudar para ela.` });
       }
       if (action === "delete") {
-        const ref = args.branch;
-        if (!ref) return asToolError("MISSING_PARAMETER", "branch é obrigatório", { parameter: "branch" });
-        // Auto-correção: verificar se existe e não é a atual
+        if (!args.branch) return asToolError("MISSING_PARAMETER", "branch é obrigatório para deletar", { parameter: "branch" });
         const existing = await git.listBranches(projectPath, false);
-        if (!existing.includes(ref)) {
-          return asToolError("BRANCH_NOT_FOUND", `Branch '${ref}' não encontrada`, { branch: ref, availableBranches: existing });
+        if (!existing.includes(args.branch)) {
+          return asToolError("BRANCH_NOT_FOUND", `Branch '${args.branch}' não encontrada`, { branch: args.branch, availableBranches: existing });
         }
         const current = await git.getCurrentBranch(projectPath);
-        if (ref === current) {
-          return asToolError("CANNOT_DELETE_CURRENT", `Não pode deletar branch atual '${ref}'`, { branch: ref, suggestion: "Faça checkout para outra branch primeiro" });
+        if (args.branch === current) {
+          return asToolError("CANNOT_DELETE_CURRENT", `Não pode deletar branch atual '${args.branch}'`, { branch: args.branch, suggestion: "Faça checkout para outra branch primeiro" });
         }
-        await git.deleteBranch(projectPath, ref, !!args.force);
-        return asToolResult({ success: true, branch: ref });
+        await git.deleteBranch(projectPath, args.branch, !!args.force);
+        return asToolResult({ success: true, branch: args.branch, deleted: true });
       }
       if (action === "rename") {
-        const oldName = args.branch;
-        const newName = args.newBranch;
-        if (!oldName || !newName) return asToolError("MISSING_PARAMETER", "branch e newBranch são obrigatórios", { parameters: ["branch", "newBranch"] });
-        await git.renameBranch(projectPath, oldName, newName);
-        return asToolResult({ success: true, from: oldName, to: newName });
+        if (!args.branch || !args.newBranch) return asToolError("MISSING_PARAMETER", "branch e newBranch são obrigatórios", { parameters: ["branch", "newBranch"] });
+        await git.renameBranch(projectPath, args.branch, args.newBranch);
+        return asToolResult({ success: true, from: args.branch, to: args.newBranch });
       }
       if (action === "checkout") {
-        const ref = args.branch;
-        if (!ref) return asToolError("MISSING_PARAMETER", "branch é obrigatório", { parameter: "branch" });
-        await git.checkout(projectPath, ref);
-        return asToolResult({ success: true, branch: ref });
+        if (!args.branch) return asToolError("MISSING_PARAMETER", "branch é obrigatório para checkout", { parameter: "branch" });
+        await git.checkout(projectPath, args.branch);
+        return asToolResult({ success: true, branch: args.branch, message: `Mudou para branch '${args.branch}'` });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "create", "delete", "rename", "checkout"] });
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["list", "create", "delete", "rename", "checkout"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-branches", description: "Gerencia branches", inputSchema, handle };
+  return { name: "git-branches", description, inputSchema, handle };
 }
-

package/src/tools/git-config.js

@@ -7,16 +7,55 @@ export function createGitConfigTool(git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["get", "set", "unset", "list"] },
-      key: { type: "string" },
-      value: { type: "string" },
-      scope: { type: "string", enum: ["local", "global", "system"], default: "local" }
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["get", "set", "unset", "list"],
+        description: `Ação a executar:
+- get: Obter valor de uma configuração específica
+- set: Definir valor de uma configuração
+- unset: Remover uma configuração
+- list: Listar todas as configurações do escopo`
+      },
+      key: { 
+        type: "string",
+        description: "Chave da configuração. Ex: 'user.name', 'user.email', 'core.autocrlf'"
+      },
+      value: { 
+        type: "string",
+        description: "Valor a definir (apenas para action='set')"
+      },
+      scope: { 
+        type: "string", 
+        enum: ["local", "global", "system"],
+        description: "Escopo da configuração. local: apenas este repo, global: todos os repos do usuário, system: todo o sistema"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Gerenciamento de configurações Git.
+
+CONFIGURAÇÕES COMUNS:
+- user.name: Nome do autor dos commits
+- user.email: Email do autor dos commits
+- core.autocrlf: Conversão de fim de linha (true/false/input)
+- core.editor: Editor padrão para commits
+
+ESCOPOS:
+- local: Apenas neste repositório (.git/config)
+- global: Todos os repos do usuário (~/.gitconfig)
+- system: Todo o sistema (/etc/gitconfig)
+
+EXEMPLOS:
+- Definir nome: action='set' key='user.name' value='Meu Nome'
+- Definir email: action='set' key='user.email' value='email@example.com'
+- Ver nome: action='get' key='user.name'`;
+
   async function handle(args) {
     const validate = ajv.compile(inputSchema);
     if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
@@ -26,27 +65,27 @@ export function createGitConfigTool(git) {
       if (action === "get") {
         if (!args.key) return asToolError("MISSING_PARAMETER", "key é obrigatório", { parameter: "key" });
         const val = await git.getConfig(projectPath, args.key, scope);
-        return asToolResult({ key: args.key, value: val, found: val !== undefined });
+        return asToolResult({ key: args.key, value: val, found: val !== undefined, scope });
       }
       if (action === "set") {
         if (!args.key) return asToolError("MISSING_PARAMETER", "key é obrigatório", { parameter: "key" });
         await git.setConfig(projectPath, args.key, args.value ?? "", scope);
-        return asToolResult({ success: true, key: args.key, value: args.value ?? "" });
+        return asToolResult({ success: true, key: args.key, value: args.value ?? "", scope });
       }
       if (action === "unset") {
         if (!args.key) return asToolError("MISSING_PARAMETER", "key é obrigatório", { parameter: "key" });
         await git.unsetConfig(projectPath, args.key, scope);
-        return asToolResult({ success: true, key: args.key });
+        return asToolResult({ success: true, key: args.key, removed: true, scope });
       }
       if (action === "list") {
         const items = await git.listConfig(projectPath, scope);
-        return asToolResult({ scope, items, count: Object.keys(items).length });
+        return asToolResult({ scope, configs: items, count: Object.keys(items).length });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["get", "set", "unset", "list"] });
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["get", "set", "unset", "list"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-config", description: "Gerencia configurações Git (local/global/system)", inputSchema, handle };
+  return { name: "git-config", description, inputSchema, handle };
 }

package/src/tools/git-files.js

@@ -7,15 +7,45 @@ export function createGitFilesTool(git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["list", "read"] },
-      filepath: { type: "string" },
-      ref: { type: "string" }
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["list", "read"],
+        description: `Ação a executar:
+- list: Lista todos os arquivos rastreados pelo Git em um commit/branch
+- read: Lê o conteúdo de um arquivo em um commit/branch específico`
+      },
+      filepath: { 
+        type: "string",
+        description: "Caminho do arquivo relativo à raiz do repo (action='read'). Ex: 'src/index.js', 'package.json'"
+      },
+      ref: { 
+        type: "string",
+        description: "Referência Git para ler (commit SHA, branch, tag). Default: HEAD (commit atual)"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Leitura de arquivos do repositório Git.
+
+QUANDO USAR:
+- Ver arquivos de um commit antigo
+- Comparar versões de arquivo entre commits
+- Listar arquivos rastreados pelo Git
+
+EXEMPLOS:
+- Listar arquivos: action='list'
+- Listar arquivos de tag: action='list' ref='v1.0.0'
+- Ler arquivo atual: action='read' filepath='package.json'
+- Ler arquivo de commit antigo: action='read' filepath='src/index.js' ref='abc1234'
+
+NOTA: Esta tool lê arquivos do histórico Git, não do sistema de arquivos.`;
+
   async function handle(args) {
     const validate = ajv.compile(inputSchema);
     if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
@@ -23,7 +53,7 @@ export function createGitFilesTool(git) {
     try {
       if (action === "list") {
         const files = await git.listFiles(projectPath, args.ref || "HEAD");
-        return asToolResult({ files, count: files.length });
+        return asToolResult({ files, count: files.length, ref: args.ref || "HEAD" });
       }
       if (action === "read") {
         if (!args.filepath) return asToolError("MISSING_PARAMETER", "filepath é obrigatório", { parameter: "filepath" });
@@ -31,21 +61,20 @@ export function createGitFilesTool(git) {
           const text = await git.readFile(projectPath, args.filepath, args.ref || "HEAD");
           return { content: [{ type: "text", text }], isError: false };
         } catch (e) {
-          // Auto-diagnóstico: listar arquivos disponíveis se não encontrar
           const files = await git.listFiles(projectPath, args.ref || "HEAD").catch(() => []);
           return asToolError("FILE_NOT_FOUND", `Arquivo '${args.filepath}' não encontrado`, { 
             filepath: args.filepath, 
             ref: args.ref || "HEAD",
-            availableFiles: files.slice(0, 20),
+            similarFiles: files.filter(f => f.includes(args.filepath.split("/").pop())).slice(0, 10),
             totalFiles: files.length
           });
         }
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "read"] });
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["list", "read"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-files", description: "Lista e lê arquivos do repo", inputSchema, handle };
+  return { name: "git-files", description, inputSchema, handle };
 }

package/src/tools/git-history.js

@@ -7,15 +7,49 @@ export function createGitHistoryTool(git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["log"] },
-      ref: { type: "string" },
-      maxCount: { type: "number" }
+      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: true
+    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);
@@ -27,7 +61,7 @@ export function createGitHistoryTool(git) {
           return asToolResult({ 
             commits: [], 
             count: 0, 
-            message: "Nenhum commit encontrado. Use action='commit' para criar o primeiro commit." 
+            message: "Nenhum commit encontrado. Use git-workflow action='commit' para criar o primeiro commit." 
           });
         }
         return asToolResult({ 
@@ -40,14 +74,15 @@ export function createGitHistoryTool(git) {
             email: c.author.email,
             date: c.date
           })), 
-          count: items.length 
+          count: items.length,
+          ref: args.ref || "HEAD"
         });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["log"] });
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["log"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-history", description: "Histórico de commits", inputSchema, handle };
+  return { name: "git-history", description, inputSchema, handle };
 }

package/src/tools/git-ignore.js

@@ -7,14 +7,51 @@ export function createGitIgnoreTool(git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["list", "create", "add", "remove"] },
-      patterns: { type: "array", items: { type: "string" } }
+      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: true
+    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);
@@ -23,37 +60,37 @@ export function createGitIgnoreTool(git) {
     try {
       if (action === "list") {
         const items = await git.listGitignore(projectPath);
-        return asToolResult({ items, count: items.length });
+        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']"
+            suggestion: "Forneça um array de padrões. Ex: ['node_modules/', '*.log', '.env']"
           });
         }
         await git.createGitignore(projectPath, patterns);
-        return asToolResult({ success: true, patterns });
+        return asToolResult({ success: true, patterns, message: ".gitignore criado" });
       }
       if (action === "add") {
         if (patterns.length === 0) {
-          return asToolError("MISSING_PARAMETER", "patterns é obrigatório para adicionar ao .gitignore", { parameter: "patterns" });
+          return asToolError("MISSING_PARAMETER", "patterns é obrigatório", { parameter: "patterns" });
         }
         await git.addToGitignore(projectPath, patterns);
         return asToolResult({ success: true, added: patterns });
       }
       if (action === "remove") {
         if (patterns.length === 0) {
-          return asToolError("MISSING_PARAMETER", "patterns é obrigatório para remover do .gitignore", { parameter: "patterns" });
+          return asToolError("MISSING_PARAMETER", "patterns é obrigatório", { parameter: "patterns" });
         }
         await git.removeFromGitignore(projectPath, patterns);
         return asToolResult({ success: true, removed: patterns });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["list", "create", "add", "remove"] });
+      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: "Gerencia .gitignore", inputSchema, handle };
+  return { name: "git-ignore", description, inputSchema, handle };
 }

package/src/tools/git-issues.js

@@ -10,49 +10,87 @@ export function createGitIssuesTool(pm) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["create", "list", "comment"] },
-      title: { type: "string" },
-      body: { type: "string" },
-      number: { type: "number" }
+      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')"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    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);
     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 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 }; },
-          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 }; }
+          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 }; }
         });
-        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), providers: out });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), title: args.title, providers: out });
       }
       if (args.action === "list") {
         const out = await runBoth(pm, {
-          github: async (owner) => { const r = await pm.github.rest.issues.listForRepo({ owner, repo, state: "all" }); return { ok: true, count: r.data.length }; },
-          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.get(`${base}/api/v1/repos/${owner}/${repo}/issues`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, count: (r.data||[]).length }; }
+          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 })) }; }
         });
         return asToolResult({ providers: out });
       }
       if (args.action === "comment") {
-        const num = args.number;
-        if (!num) return asToolError("VALIDATION_ERROR", "number é obrigatório");
+        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 runBoth(pm, {
-          github: async (owner) => { await pm.github.rest.issues.createComment({ owner, repo, issue_number: num, body: args.body || "" }); return { ok: true }; },
-          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.post(`${base}/api/v1/repos/${owner}/${repo}/issues/${num}/comments`, { body: args.body || "" }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
+          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 }; }
         });
-        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), providers: out });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), issueNumber: args.number, providers: out });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${args.action}`, { availableActions: ["create", "list", "comment"] });
+      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: "Issues em paralelo (GitHub + Gitea)", inputSchema, handle };
+  return { name: "git-issues", description, inputSchema, handle };
 }