@andrebuzeli/git-mcp 13.6.0 → 14.0.0

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

package/src/tools/git-pulls.js

@@ -10,52 +10,101 @@ export function createGitPullsTool(pm) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["create", "list", "files"] },
-      title: { type: "string" },
-      head: { type: "string" },
-      base: { type: "string" },
-      number: { type: "number" }
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["create", "list", "files"],
+        description: `Ação a executar:
+- create: Cria Pull Request no GitHub E Gitea
+- list: Lista Pull Requests existentes
+- files: Lista arquivos modificados em um PR`
+      },
+      title: { 
+        type: "string",
+        description: "Título do PR. Ex: 'feat: adiciona autenticação OAuth'"
+      },
+      head: { 
+        type: "string",
+        description: "Branch de origem (com as mudanças). Ex: 'feature/oauth'"
+      },
+      base: { 
+        type: "string",
+        description: "Branch de destino (onde será mergeado). Ex: 'main', 'develop'"
+      },
+      number: { 
+        type: "number",
+        description: "Número do PR para action='files'"
+      },
+      body: {
+        type: "string",
+        description: "Descrição do PR com detalhes das mudanças"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Gerenciamento de Pull Requests no GitHub e Gitea.
+
+QUANDO USAR:
+- Propor mudanças de uma branch para outra
+- Code review antes de merge
+- Documentar mudanças significativas
+
+FLUXO TÍPICO:
+1. Cria branch: git-branches create branch='feature/nova'
+2. Faz mudanças e commits
+3. Push: git-workflow push
+4. Cria PR: git-pulls create head='feature/nova' base='main' title='Nova feature'
+
+AÇÕES:
+- create: Criar novo PR
+- list: Ver PRs existentes
+- files: Ver arquivos modificados em um PR
+
+NOTA: O PR é criado em AMBOS os providers simultaneamente.`;
+
   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") {
-        const head = args.head || "feature";
-        const base = args.base || "main";
+        if (!args.head) return asToolError("MISSING_PARAMETER", "head (branch de origem) é obrigatório", { parameter: "head", example: "feature/nova-funcionalidade" });
+        if (!args.base) return asToolError("MISSING_PARAMETER", "base (branch de destino) é obrigatório", { parameter: "base", example: "main" });
+        const head = args.head;
+        const base = args.base;
+        const title = args.title || `${head} -> ${base}`;
+        const body = args.body || "";
         const out = await runBoth(pm, {
-          github: async (owner) => { const r = await pm.github.rest.pulls.create({ owner, repo, title: args.title || `${head} -> ${base}`, head, base }); return { ok: true, number: r.data.number }; },
-          gitea: async (owner) => { const baseUrl = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.post(`${baseUrl}/api/v1/repos/${owner}/${repo}/pulls`, { title: args.title || `${head} -> ${base}`, head, base }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, number: r.data?.number }; }
+          github: async (owner) => { const r = await pm.github.rest.pulls.create({ owner, repo, title, head, base, body }); return { ok: true, number: r.data.number, url: r.data.html_url }; },
+          gitea: async (owner) => { const baseUrl = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.post(`${baseUrl}/api/v1/repos/${owner}/${repo}/pulls`, { title, head, base, 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, head, base, providers: out });
       }
       if (args.action === "list") {
         const out = await runBoth(pm, {
-          github: async (owner) => { const r = await pm.github.rest.pulls.list({ owner, repo, state: "all" }); return { ok: true, count: r.data.length }; },
-          gitea: async (owner) => { const baseUrl = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.get(`${baseUrl}/api/v1/repos/${owner}/${repo}/pulls`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, count: (r.data||[]).length }; }
+          github: async (owner) => { const r = await pm.github.rest.pulls.list({ owner, repo, state: "all", per_page: 30 }); return { ok: true, count: r.data.length, pulls: r.data.slice(0, 10).map(p => ({ number: p.number, title: p.title, state: p.state, head: p.head.ref, base: p.base.ref })) }; },
+          gitea: async (owner) => { const baseUrl = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.get(`${baseUrl}/api/v1/repos/${owner}/${repo}/pulls?state=all`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, count: (r.data||[]).length, pulls: (r.data||[]).slice(0, 10).map(p => ({ number: p.number, title: p.title, state: p.state, head: p.head?.ref, base: p.base?.ref })) }; }
         });
         return asToolResult({ providers: out });
       }
       if (args.action === "files") {
-        const num = args.number;
-        if (!num) return asToolError("VALIDATION_ERROR", "number é obrigatório");
+        if (!args.number) return asToolError("MISSING_PARAMETER", "number é obrigatório para ver arquivos do PR", { parameter: "number" });
         const out = await runBoth(pm, {
-          github: async (owner) => { const r = await pm.github.rest.pulls.listFiles({ owner, repo, pull_number: num }); return { ok: true, count: r.data.length }; },
-          gitea: async (owner) => { const baseUrl = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.get(`${baseUrl}/api/v1/repos/${owner}/${repo}/pulls/${num}/files`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, count: (r.data||[]).length }; }
+          github: async (owner) => { const r = await pm.github.rest.pulls.listFiles({ owner, repo, pull_number: args.number }); return { ok: true, count: r.data.length, files: r.data.map(f => ({ filename: f.filename, status: f.status, additions: f.additions, deletions: f.deletions })) }; },
+          gitea: async (owner) => { const baseUrl = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.get(`${baseUrl}/api/v1/repos/${owner}/${repo}/pulls/${args.number}/files`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, count: (r.data||[]).length, files: (r.data||[]).map(f => ({ filename: f.filename, status: f.status })) }; }
         });
-        return asToolResult({ providers: out });
+        return asToolResult({ prNumber: args.number, providers: out });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${args.action}`, { availableActions: ["create", "list", "files"] });
+      return asToolError("VALIDATION_ERROR", `Ação '${args.action}' não suportada`, { availableActions: ["create", "list", "files"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-pulls", description: "Pull Requests em paralelo (GitHub + Gitea)", inputSchema, handle };
+  return { name: "git-pulls", description, inputSchema, handle };
 }

package/src/tools/git-remote.js

@@ -10,37 +10,101 @@ export function createGitRemoteTool(pm, git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: [
-        "list",
-        "ensure",
-        "set-url",
-        "repo-delete",
-        "release-create",
-        "topics-set",
-        "milestone-create",
-        "label-create",
-        "fork-create",
-        "fork-list",
-        "star-set",
-        "star-unset",
-        "star-check",
-        "subscription-set",
-        "subscription-unset",
-        "contents-create"
-      ] },
-      tag: { type: "string" },
-      name: { type: "string" },
-      body: { type: "string" },
-      topics: { type: "array", items: { type: "string" } },
-      path: { type: "string" },
-      content: { type: "string" },
-      branch: { type: "string" }
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: [
+          "list", "ensure", "repo-delete",
+          "release-create", "topics-set", "milestone-create", "label-create",
+          "fork-create", "fork-list", "star-set", "star-unset",
+          "subscription-set", "subscription-unset", "contents-create"
+        ],
+        description: `Ação a executar:
+
+CONFIGURAÇÃO:
+- list: Lista remotes configurados (github, gitea, origin)
+- ensure: Cria repos no GitHub/Gitea e configura remotes (USE ESTE se push falhar)
+
+REPOSITÓRIO:
+- repo-delete: Deleta repositório no GitHub E Gitea (⚠️ PERIGOSO)
+- release-create: Cria release/versão no GitHub e Gitea
+- topics-set: Define tópicos/tags do repositório
+- milestone-create: Cria milestone para organização
+- label-create: Cria label para issues
+
+SOCIAL:
+- star-set: Adiciona estrela ao repo
+- star-unset: Remove estrela
+- fork-create: Cria fork do repositório
+- fork-list: Lista forks existentes
+
+NOTIFICAÇÕES:
+- subscription-set: Ativa notificações do repo
+- subscription-unset: Desativa notificações
+
+ARQUIVOS VIA API:
+- contents-create: Cria arquivo diretamente via API (sem git local)`
+      },
+      tag: { 
+        type: "string",
+        description: "Tag para release-create. Ex: 'v1.0.0'"
+      },
+      name: { 
+        type: "string",
+        description: "Nome da release, label, etc."
+      },
+      body: { 
+        type: "string",
+        description: "Descrição/corpo da release"
+      },
+      topics: { 
+        type: "array", 
+        items: { type: "string" },
+        description: "Lista de tópicos para topics-set. Ex: ['javascript', 'nodejs', 'mcp']"
+      },
+      path: { 
+        type: "string",
+        description: "Caminho do arquivo para contents-create"
+      },
+      content: { 
+        type: "string",
+        description: "Conteúdo do arquivo para contents-create"
+      },
+      branch: { 
+        type: "string",
+        description: "Branch alvo para contents-create. Default: main"
+      },
+      color: {
+        type: "string",
+        description: "Cor do label em hex (sem #). Ex: 'ff0000' para vermelho"
+      },
+      title: {
+        type: "string",
+        description: "Título do milestone"
+      }
     },
     required: ["projectPath", "action"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Operações em repositórios remotos GitHub e Gitea.
+
+AÇÕES MAIS USADAS:
+- ensure: Configurar remotes e criar repos (ESSENCIAL antes de push)
+- list: Ver remotes configurados
+- release-create: Publicar nova versão
+
+EXECUÇÃO PARALELA:
+Todas as operações são executadas em AMBOS os providers (GitHub + Gitea) simultaneamente.
+
+QUANDO USAR:
+- Se git-workflow push falhar: use action='ensure'
+- Para publicar release: use action='release-create'
+- Para configurar tópicos: use action='topics-set'`;
+
   async function handle(args) {
     const validate = ajv.compile(inputSchema);
     if (!validate(args || {})) return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
@@ -48,7 +112,13 @@ export function createGitRemoteTool(pm, git) {
     try {
       if (action === "list") {
         const remotes = await git.listRemotes(projectPath);
-        return asToolResult({ remotes });
+        return asToolResult({ 
+          remotes,
+          configured: remotes.length > 0,
+          hasGithub: remotes.some(r => r.remote === "github"),
+          hasGitea: remotes.some(r => r.remote === "gitea"),
+          message: remotes.length === 0 ? "Nenhum remote configurado. Use action='ensure' para configurar." : undefined
+        });
       }
       if (action === "ensure") {
         const repo = getRepoNameFromPath(projectPath);
@@ -60,11 +130,13 @@ export function createGitRemoteTool(pm, git) {
         const giteaUrl = geOwner && base ? `${base}/${geOwner}/${repo}.git` : "";
         await git.ensureRemotes(projectPath, { githubUrl, giteaUrl });
         const remotes = await git.listRemotes(projectPath);
-        return asToolResult({ success: true, ensured, remotes });
-      }
-      if (action === "set-url") {
-        // handled via ensure (auto)
-        return asToolResult({ success: true, message: "Use action=ensure para set-url automático" });
+        return asToolResult({ 
+          success: true, 
+          ensured, 
+          remotes,
+          urls: { github: githubUrl, gitea: giteaUrl },
+          message: "Remotes configurados. Agora pode usar git-workflow push."
+        });
       }
       if (action === "repo-delete") {
         const repo = getRepoNameFromPath(projectPath);
@@ -72,36 +144,38 @@ export function createGitRemoteTool(pm, git) {
           github: async (owner) => { await pm.github.rest.repos.delete({ owner, repo }); return { ok: true }; },
           gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.delete(`${base}/api/v1/repos/${owner}/${repo}`, { 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), deleted: repo, providers: out, warning: "Repositório deletado permanentemente!" });
       }
       if (action === "release-create") {
         const repo = getRepoNameFromPath(projectPath);
-        const tag = args.tag || "v1.0.0";
+        if (!args.tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório para criar release", { parameter: "tag", example: "v1.0.0" });
+        const tag = args.tag;
         const name = args.name || tag;
         const body = args.body || "";
         const out = await runBoth(pm, {
-          github: async (owner) => { const r = await pm.github.rest.repos.createRelease({ owner, repo, tag_name: tag, name, body, draft: false, prerelease: false }); return { ok: true, id: r.data.id }; },
+          github: async (owner) => { const r = await pm.github.rest.repos.createRelease({ owner, repo, tag_name: tag, name, body, draft: false, prerelease: false }); return { ok: true, id: r.data.id, url: r.data.html_url }; },
           gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.post(`${base}/api/v1/repos/${owner}/${repo}/releases`, { tag_name: tag, name, body }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, id: r.data?.id }; }
         });
-        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), providers: out });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), tag, name, providers: out });
       }
       if (action === "topics-set") {
         const repo = getRepoNameFromPath(projectPath);
         const topics = Array.isArray(args.topics) ? args.topics : [];
+        if (topics.length === 0) return asToolError("MISSING_PARAMETER", "topics é obrigatório", { parameter: "topics", example: ["javascript", "nodejs"] });
         const out = await runBoth(pm, {
           github: async (owner) => { await pm.github.request("PUT /repos/{owner}/{repo}/topics", { owner, repo, names: topics, headers: { accept: "application/vnd.github.mercy-preview+json" } }); return { ok: true }; },
           gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.put(`${base}/api/v1/repos/${owner}/${repo}/topics`, { topics }, { 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), topics, providers: out });
       }
       if (action === "milestone-create") {
         const repo = getRepoNameFromPath(projectPath);
-        const title = args.title || "v1.0";
+        const title = args.title || args.name || "v1.0";
         const out = await runBoth(pm, {
           github: async (owner) => { const r = await pm.github.request("POST /repos/{owner}/{repo}/milestones", { owner, repo, title }); return { ok: true, id: r.data?.id }; },
           gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.post(`${base}/api/v1/repos/${owner}/${repo}/milestones`, { title }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, id: r.data?.id }; }
         });
-        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), providers: out });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), title, providers: out });
       }
       if (action === "label-create") {
         const repo = getRepoNameFromPath(projectPath);
@@ -111,7 +185,7 @@ export function createGitRemoteTool(pm, git) {
           github: async (owner) => { await pm.github.request("POST /repos/{owner}/{repo}/labels", { owner, repo, name, color }); return { ok: true }; },
           gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.post(`${base}/api/v1/repos/${owner}/${repo}/labels`, { name, color }, { 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), label: { name, color }, providers: out });
       }
       if (action === "fork-create") {
         const repo = getRepoNameFromPath(projectPath);
@@ -129,22 +203,20 @@ export function createGitRemoteTool(pm, git) {
         });
         return asToolResult({ providers: out });
       }
-      if (action === "star-set" || action === "star-unset" || action === "star-check") {
+      if (action === "star-set" || action === "star-unset") {
         const repo = getRepoNameFromPath(projectPath);
         const out = await runBoth(pm, {
           github: async (owner) => {
             if (action === "star-set") { await pm.github.request("PUT /user/starred/{owner}/{repo}", { owner, repo }); return { ok: true }; }
-            if (action === "star-unset") { await pm.github.request("DELETE /user/starred/{owner}/{repo}", { owner, repo }); return { ok: true }; }
-            const r = await pm.github.request("GET /user/starred/{owner}/{repo}", { owner, repo }); return { ok: r.status === 204 || r.status === 200 };
+            await pm.github.request("DELETE /user/starred/{owner}/{repo}", { owner, repo }); return { ok: true };
           },
           gitea: async (owner) => {
             const base = pm.giteaUrl.replace(/\/$/, "");
             if (action === "star-set") { await axios.put(`${base}/api/v1/user/starred/${owner}/${repo}`, {}, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
-            if (action === "star-unset") { await axios.delete(`${base}/api/v1/user/starred/${owner}/${repo}`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
-            const r = await axios.get(`${base}/api/v1/user/starred/${owner}/${repo}`, { headers: { Authorization: `token ${pm.giteaToken}` }, validateStatus: () => true }); return { ok: r.status === 204 || r.status === 200 };
+            await axios.delete(`${base}/api/v1/user/starred/${owner}/${repo}`, { 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), action, providers: out });
       }
       if (action === "subscription-set" || action === "subscription-unset") {
         const repo = getRepoNameFromPath(projectPath);
@@ -152,33 +224,30 @@ export function createGitRemoteTool(pm, git) {
           github: async (owner) => { if (action === "subscription-set") { await pm.github.request("PUT /repos/{owner}/{repo}/subscription", { owner, repo, subscribed: true }); } else { await pm.github.request("DELETE /repos/{owner}/{repo}/subscription", { owner, repo }); } return { ok: true }; },
           gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); if (action === "subscription-set") { await axios.put(`${base}/api/v1/repos/${owner}/${repo}/subscription`, { subscribed: true }, { headers: { Authorization: `token ${pm.giteaToken}` } }); } else { await axios.delete(`${base}/api/v1/repos/${owner}/${repo}/subscription`, { 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), action, providers: out });
       }
       if (action === "contents-create") {
         const repo = getRepoNameFromPath(projectPath);
-        const filePath = args.path || "test.txt";
-        const message = args.message || "Add file";
-        const data = typeof args.content === "string" ? args.content : "";
+        if (!args.path) return asToolError("MISSING_PARAMETER", "path é obrigatório", { parameter: "path" });
+        if (!args.content) return asToolError("MISSING_PARAMETER", "content é obrigatório", { parameter: "content" });
+        const filePath = args.path;
+        const message = args.message || `Add ${filePath}`;
+        const data = args.content;
         const branch = args.branch || "main";
         const b64 = Buffer.from(data, "utf8").toString("base64");
         const out = await runBoth(pm, {
           github: async (owner) => { await pm.github.request("PUT /repos/{owner}/{repo}/contents/{path}", { owner, repo, path: filePath, message, content: b64, branch }); return { ok: true }; },
           gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.post(`${base}/api/v1/repos/${owner}/${repo}/contents/${encodeURIComponent(filePath)}`, { content: b64, message, branch }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
         });
-        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), path: filePath, providers: out });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), path: filePath, branch, providers: out });
       }
-      return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { 
-        availableActions: ["list", "ensure", "set-url", "repo-delete", "release-create", "topics-set", "milestone-create", "label-create", "fork-create", "fork-list", "star-set", "star-unset", "star-check", "subscription-set", "subscription-unset", "contents-create"] 
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { 
+        availableActions: ["list", "ensure", "repo-delete", "release-create", "topics-set", "milestone-create", "label-create", "fork-create", "fork-list", "star-set", "star-unset", "subscription-set", "subscription-unset", "contents-create"] 
       });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return {
-    name: "git-remote",
-    description: "Gerencia remotes e garante GitHub + Gitea",
-    inputSchema,
-    handle
-  };
+  return { name: "git-remote", description, inputSchema, handle };
 }

package/src/tools/git-reset.js

@@ -7,20 +7,52 @@ export function createGitResetTool(git) {
   const inputSchema = {
     type: "object",
     properties: {
-      projectPath: { type: "string" },
-      action: { type: "string", enum: ["soft", "mixed", "hard"] },
-      ref: { type: "string" }
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["soft", "mixed", "hard"],
+        description: `Tipo de reset a executar:
+- soft: Desfaz commits mas MANTÉM mudanças staged (pronto para re-commit)
+- mixed: Desfaz commits e unstage, mas MANTÉM mudanças no working directory
+- hard: Desfaz commits e DESCARTA todas as mudanças (PERIGOSO - dados perdidos)`
+      },
+      ref: { 
+        type: "string",
+        description: "Referência para reset. Ex: 'HEAD~1' (volta 1 commit), 'HEAD~2' (volta 2), ou SHA específico"
+      }
     },
     required: ["projectPath", "action", "ref"],
-    additionalProperties: true
+    additionalProperties: false
   };
 
+  const description = `Reset Git - desfaz commits e/ou mudanças.
+
+⚠️ CUIDADO: Reset pode causar perda de dados!
+
+TIPOS DE RESET:
+- soft: Seguro - mantém tudo, apenas move HEAD
+- mixed: Moderado - remove do staging mas mantém arquivos
+- hard: PERIGOSO - descarta todas as mudanças
+
+EXEMPLOS COMUNS:
+- Desfazer último commit (manter mudanças): action='soft' ref='HEAD~1'
+- Desfazer último commit (unstage): action='mixed' ref='HEAD~1'
+- Descartar tudo e voltar ao commit anterior: action='hard' ref='HEAD~1'
+
+REFERÊNCIAS:
+- HEAD~1: Um commit atrás
+- HEAD~2: Dois commits atrás
+- abc1234: SHA específico do commit`;
+
   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, ref } = args;
     try {
-      // Auto-verificação: checar se há commits suficientes para HEAD~N
+      // Verificar se há commits suficientes para HEAD~N
       if (ref.match(/HEAD~(\d+)/)) {
         const match = ref.match(/HEAD~(\d+)/);
         const steps = parseInt(match[1], 10);
@@ -35,16 +67,24 @@ export function createGitResetTool(git) {
         }
       }
       
-      if (action === "soft") await git.resetSoft(projectPath, ref);
-      else if (action === "mixed") await git.resetMixed(projectPath, ref);
-      else if (action === "hard") await git.resetHard(projectPath, ref);
-      else return asToolError("VALIDATION_ERROR", `Ação não suportada: ${action}`, { availableActions: ["soft", "mixed", "hard"] });
+      if (action === "soft") {
+        await git.resetSoft(projectPath, ref);
+        return asToolResult({ success: true, action: "soft", ref, message: "Commits desfeitos, mudanças mantidas staged" });
+      }
+      if (action === "mixed") {
+        await git.resetMixed(projectPath, ref);
+        return asToolResult({ success: true, action: "mixed", ref, message: "Commits desfeitos, mudanças mantidas no working directory" });
+      }
+      if (action === "hard") {
+        await git.resetHard(projectPath, ref);
+        return asToolResult({ success: true, action: "hard", ref, message: "⚠️ Reset hard executado - mudanças descartadas" });
+      }
       
-      return asToolResult({ success: true, action, ref, message: `Reset ${action} para ${ref} realizado` });
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["soft", "mixed", "hard"] });
     } catch (e) {
       return errorToResponse(e);
     }
   }
 
-  return { name: "git-reset", description: "Reset soft/mixed/hard", inputSchema, handle };
+  return { name: "git-reset", description, inputSchema, handle };
 }