@andrebuzeli/git-mcp 4.0.2 → 4.0.3

package/EXEMPLOS.md

@@ -0,0 +1,861 @@
+# 🚀 EXEMPLOS PRÁTICOS - MCP Git AI Unification Server
+
+## 📋 Casos de Uso Reais
+
+### 1. Inicialização de Projeto Novo
+
+```json
+// git-workflow init - Começar projeto do zero
+{
+  "action": "init",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Inicialização do projeto React com TypeScript"
+}
+```
+
+**Resultado esperado:**
+```json
+{
+  "success": true,
+  "action": "init",
+  "message": "Projeto inicializado com sucesso - repositório criado, remotes configurados",
+  "autoDetected": {
+    "repo": "meu-app",
+    "owner": "johndoe",
+    "providers": ["gitea"]
+  }
+}
+```
+
+### 2. Desenvolvimento Diário - Commit + Push
+
+```json
+// git-workflow commit - Após implementar uma feature
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Implementar autenticação JWT\n\n- Adicionar middleware de validação\n- Criar endpoints /login e /register\n- Implementar refresh token\n- Adicionar testes unitários"
+}
+```
+
+### 3. Sincronização Antes de Trabalhar
+
+```json
+// git-workflow sync - Atualizar com mudanças do time
+{
+  "action": "sync",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+```
+
+### 4. Verificar Status do Projeto
+
+```json
+// git-workflow status - Overview completo
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\meu-app",
+  "detailed": true
+}
+```
+
+**Output inclui:**
+- Status Git (modified, untracked, staged)
+- Branches locais/remotas
+- Últimos commits
+- Status de sincronização com providers
+
+### 5. Backup Estratégico
+
+```json
+// git-workflow backup - Antes de mudanças arriscadas
+{
+  "action": "backup",
+  "projectPath": "C:\\projetos\\meu-app",
+  "description": "Backup antes de refatoração da API"
+}
+```
+
+---
+
+## 📁 Gerenciamento de Arquivos
+
+### Criar Arquivo de Componente
+
+```json
+// git-files write - Novo componente React
+{
+  "action": "write",
+  "projectPath": "C:\\projetos\\meu-app",
+  "filePath": "src/components/LoginForm.tsx",
+  "content": "import React, { useState } from 'react';
+
+interface LoginFormProps {
+  onLogin: (credentials: {email: string, password: string}) => void;
+}
+
+export const LoginForm: React.FC<LoginFormProps> = ({ onLogin }) => {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    onLogin({ email, password });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type=\"email\"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder=\"Email\"
+        required
+      />
+      <input
+        type=\"password\"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder=\"Senha\"
+        required
+      />
+      <button type=\"submit\">Entrar</button>
+    </form>
+  );
+};"
+}
+```
+
+### Buscar Funções no Código
+
+```json
+// git-files search - Encontrar todas as funções de validação
+{
+  "action": "search",
+  "projectPath": "C:\\projetos\\meu-app",
+  "query": "function.*validate|const.*validate",
+  "path": "src",
+  "caseSensitive": false
+}
+```
+
+### Backup de Arquivos de Configuração
+
+```json
+// git-files backup-files - Salvar configs importantes
+{
+  "action": "backup-files",
+  "projectPath": "C:\\projetos\\meu-app",
+  "patterns": ["*.json", "*.config.*", ".env*"],
+  "description": "Backup de arquivos de configuração"
+}
+```
+
+---
+
+## 🚀 Gerenciamento de Releases
+
+### Release Patch (Correção de Bug)
+
+```json
+// git-release create - Release automático de correção
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "changelog": true,
+  "notes": "Correção crítica no sistema de login",
+  "assets": ["dist/app.js", "dist/styles.css"]
+}
+```
+
+**Output:**
+- Versão automaticamente incrementada (ex: v1.2.3)
+- Changelog gerado automaticamente
+- Publicação em todos os providers configurados
+
+### Bump de Versão Manual
+
+```json
+// git-release version - Preparar para release major
+{
+  "action": "version",
+  "projectPath": "C:\\projetos\\meu-app",
+  "type": "major"
+}
+```
+
+### Rollback de Emergência
+
+```json
+// git-release rollback - Reverter release problemático
+{
+  "action": "rollback",
+  "projectPath": "C:\\projetos\\meu-app",
+  "createBackup": true
+}
+```
+
+---
+
+## 📊 Monitoramento e Analytics
+
+### Status Completo do Projeto
+
+```json
+// git-monitor status - Dashboard completo
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\meu-app",
+  "includeMetrics": true,
+  "detailed": true
+}
+```
+
+**Métricas incluídas:**
+- Commits por dia/semana
+- Arquivos modificados
+- Branches ativas
+- Tamanho do repositório
+- Status de sincronização
+
+### Análise de Produtividade
+
+```json
+// git-monitor metrics - Métricas de desenvolvimento
+{
+  "action": "metrics",
+  "projectPath": "C:\\projetos\\meu-app",
+  "period": "30d",
+  "includeCharts": true
+}
+```
+
+### Check-up de Saúde
+
+```json
+// git-monitor health - Diagnóstico de problemas
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app",
+  "deep": true,
+  "suggestions": true
+}
+```
+
+---
+
+## 💾 Sistema de Backup
+
+### Backup Completo
+
+```json
+// git-backup create - Backup full do projeto
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "type": "full",
+  "name": "backup-semanal",
+  "compress": true,
+  "includeUntracked": true
+}
+```
+
+### Restauração Seletiva
+
+```json
+// git-backup restore - Restaurar versão específica
+{
+  "action": "restore",
+  "projectPath": "C:\\projetos\\meu-app",
+  "backupId": "backup-2025-09-25-full",
+  "preview": true,
+  "targetPath": "C:\\restauracao\\meu-app"
+}
+```
+
+### Backup Automático
+
+```json
+// git-backup auto - Configurar backup diário
+{
+  "action": "auto",
+  "projectPath": "C:\\projetos\\meu-app",
+  "enabled": true,
+  "schedule": "daily",
+  "retention": 30,
+  "maxBackups": 10
+}
+```
+
+---
+
+## 🌿 Gerenciamento de Branches
+
+### Feature Branch Completo
+
+```json
+// 1. Criar feature branch
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "feature/user-authentication"
+}
+
+// 2. Trabalhar na feature (usar outras tools)
+
+// 3. Comparar com main antes do merge
+{
+  "action": "compare",
+  "projectPath": "C:\\projetos\\meu-app",
+  "base": "main",
+  "head": "feature/user-authentication",
+  "detailed": true
+}
+
+// 4. Merge inteligente
+{
+  "action": "merge",
+  "projectPath": "C:\\projetos\\meu-app",
+  "branch": "feature/user-authentication",
+  "strategy": "squash"
+}
+
+// 5. Limpar branch
+{
+  "action": "delete",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "feature/user-authentication"
+}
+```
+
+### Hotfix Urgente
+
+```json
+// Criar hotfix branch
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "hotfix/critical-security-patch",
+  "from": "main"
+}
+
+// Implementar correção (usar git-files, git-workflow)
+
+// Merge direto na main
+{
+  "action": "switch",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "main"
+}
+
+{
+  "action": "merge",
+  "projectPath": "C:\\projetos\\meu-app",
+  "branch": "hotfix/critical-security-patch",
+  "strategy": "merge"
+}
+```
+
+---
+
+## 📝 Sistema de Issues Local
+
+### Criar Issue Estruturada
+
+```json
+// git-issues create - Nova feature
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "title": "Implementar sistema de notificações push",
+  "description": "Adicionar notificações em tempo real para ações do usuário",
+  "labels": ["feature", "frontend", "backend"],
+  "priority": "high",
+  "assignee": "johndoe",
+  "dueDate": "2025-10-15"
+}
+```
+
+### Auto-detecção de TODOs
+
+```json
+// git-issues scan - Converter TODOs em issues
+{
+  "action": "scan",
+  "projectPath": "C:\\projetos\\meu-app",
+  "createIssues": true,
+  "patterns": ["TODO", "FIXME", "HACK", "XXX"]
+}
+```
+
+**Converte automaticamente:**
+```javascript
+// TODO: Implementar validação de email
+// FIXME: Corrigir bug no login mobile
+```
+**Em issues estruturadas com:**
+- Título extraído do comentário
+- Prioridade baseada no tipo (TODO=medium, FIXME=high)
+- Localização do arquivo
+- Labels apropriadas
+
+### Gerenciamento de Sprint
+
+```json
+// Listar issues da sprint atual
+{
+  "action": "list",
+  "projectPath": "C:\\projetos\\meu-app",
+  "state": "open",
+  "sort": "priority",
+  "limit": 20
+}
+
+// Atualizar progresso
+{
+  "action": "update",
+  "projectPath": "C:\\projetos\\meu-app",
+  "id": "ISSUE-123",
+  "status": "in_progress"
+}
+
+// Fechar issue completa
+{
+  "action": "close",
+  "projectPath": "C:\\projetos\\meu-app",
+  "id": "ISSUE-123",
+  "comment": "Implementação concluída com testes unitários"
+}
+```
+
+---
+
+## 🏷️ Gerenciamento de Tags
+
+### Versionamento Semântico
+
+```json
+// Tag de release
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "v2.1.0",
+  "message": "Release v2.1.0 - Sistema de notificações\n\nFeatures:\n- Notificações push em tempo real\n- Configurações de preferências\n- Suporte a múltiplos idiomas\n\nBugfixes:\n- Correção de memory leak\n- Validação de formulários aprimorada",
+  "type": "annotated"
+}
+
+// Tag de pré-release
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "v2.1.0-beta.1",
+  "message": "Beta release para testes",
+  "type": "annotated"
+}
+```
+
+### Busca de Tags
+
+```json
+// Encontrar releases de produção
+{
+  "action": "search",
+  "projectPath": "C:\\projetos\\meu-app",
+  "query": "^v\\d+\\.\\d+\\.\\d+$",
+  "sort": "version"
+}
+```
+
+---
+
+## 💾 Gerenciamento de Stash
+
+### Work in Progress (WIP)
+
+```json
+// Salvar trabalho em andamento
+{
+  "action": "save",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "WIP: Refatoração da API de usuários",
+  "includeUntracked": true,
+  "keepIndex": true
+}
+
+// Ver stashes disponíveis
+{
+  "action": "list",
+  "projectPath": "C:\\projetos\\meu-app",
+  "detailed": true
+}
+
+// Aplicar stash específico
+{
+  "action": "apply",
+  "projectPath": "C:\\projetos\\meu-app",
+  "index": "1"
+}
+```
+
+### Context Switching
+
+```json
+// Salvar contexto atual
+{
+  "action": "save",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "Context: Implementação do dashboard"
+}
+
+// Mudar para hotfix urgente
+// ... trabalhar no hotfix ...
+
+// Retornar ao contexto anterior
+{
+  "action": "pop",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+```
+
+---
+
+## 🔧 Configuração e Remotos
+
+### Setup Inicial de Remotos
+
+```json
+// Adicionar remote do Gitea
+{
+  "action": "add",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "origin",
+  "url": "https://gitea.example.com/johndoe/meu-app.git",
+  "provider": "gitea"
+}
+
+// Adicionar backup no GitHub
+{
+  "action": "add",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "github",
+  "url": "https://github.com/johndoe/meu-app.git",
+  "provider": "github"
+}
+```
+
+### Sincronização Multi-Provider
+
+```json
+// Verificar status de todos os remotos
+{
+  "action": "show",
+  "projectPath": "C:\\projetos\\meu-app",
+  "detailed": true
+}
+
+// Limpar referências obsoletas
+{
+  "action": "prune",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+```
+
+---
+
+## 🚨 Tratamento de Erros e Recovery
+
+### Exemplo de Auto-Recovery
+
+```json
+// Request que pode falhar
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Nova funcionalidade"
+}
+```
+
+**Response com erro e sugestão:**
+```json
+{
+  "success": false,
+  "action": "commit",
+  "message": "Falha no commit",
+  "error": {
+    "code": "GIT_PUSH_FAILED",
+    "message": "Não foi possível fazer push para o remote",
+    "cause": "Remote 'origin' não encontrado ou sem permissão",
+    "suggestion": "Execute 'git remote add origin <url>' ou verifique as credenciais"
+  },
+  "autoDetected": {
+    "repo": "meu-app",
+    "owner": "johndoe",
+    "providers": []
+  }
+}
+```
+
+### Recovery Automático
+
+```json
+// Sistema tenta corrigir automaticamente
+{
+  "action": "sync",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+```
+
+**Output:**
+- Detecta problema
+- Tenta `git pull --rebase`
+- Se falhar, sugere resolução manual
+- Backup automático antes de operações arriscadas
+
+---
+
+## 🎯 Workflows Completos
+
+### Workflow de Desenvolvimento Diário
+
+```json
+// 1. Sincronizar com time
+{
+  "action": "sync",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+
+// 2. Ver status
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+
+// 3. Criar feature branch
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "feature/dark-mode"
+}
+
+// 4. Implementar (usar git-files, etc.)
+
+// 5. Commit progressivo
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Implementar tema dark\n\n- Adicionar variáveis CSS\n- Toggle component\n- Persistir preferência"
+}
+
+// 6. Verificar qualidade
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+
+// 7. Merge na main
+{
+  "action": "merge",
+  "projectPath": "C:\\projetos\\meu-app",
+  "branch": "feature/dark-mode"
+}
+```
+
+### Workflow de Release
+
+```json
+// 1. Verificar saúde pré-release
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app",
+  "deep": true
+}
+
+// 2. Backup estratégico
+{
+  "action": "backup",
+  "projectPath": "C:\\projetos\\meu-app",
+  "description": "Backup pré-release v2.0.0"
+}
+
+// 3. Bump versão
+{
+  "action": "version",
+  "projectPath": "C:\\projetos\\meu-app",
+  "type": "minor"
+}
+
+// 4. Release completo
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "changelog": true,
+  "notes": "Major release com redesign completo",
+  "assets": ["dist/bundle.js", "dist/styles.css"]
+}
+
+// 5. Tag de versão
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "v2.0.0",
+  "type": "annotated",
+  "message": "Release v2.0.0 - Redesign completo da interface"
+}
+```
+
+### Workflow de Troubleshooting
+
+```json
+// 1. Diagnosticar problema
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\meu-app",
+  "detailed": true
+}
+
+// 2. Verificar saúde
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app",
+  "suggestions": true
+}
+
+// 3. Backup antes de mudanças
+{
+  "action": "backup",
+  "projectPath": "C:\\projetos\\meu-app",
+  "description": "Backup antes de troubleshooting"
+}
+
+// 4. Reset se necessário
+{
+  "action": "reset-to-commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "commit": "HEAD~1",
+  "type": "mixed"
+}
+
+// 5. Limpar stashes se houver
+{
+  "action": "clear",
+  "projectPath": "C:\\projetos\\meu-app",
+  "confirm": true
+}
+```
+
+---
+
+## 🔧 Configurações Avançadas
+
+### Ambiente de Desenvolvimento
+
+```bash
+# .env file
+GITEA_USERNAME=developer
+GITEA_TOKEN=your_personal_token
+GITEA_URL=https://gitea.company.com
+
+GITHUB_USERNAME=developer
+GITHUB_TOKEN=your_github_token
+
+# Optional
+DEMO_MODE=false
+LOG_LEVEL=debug
+```
+
+### Configuração Multi-Projeto
+
+```json
+// Para projetos diferentes, apenas mude o projectPath
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\api-backend"
+}
+
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\web-frontend"
+}
+
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\mobile-app"
+}
+```
+
+---
+
+## 💡 Dicas e Boas Práticas
+
+### 1. Commits Atômicos
+```json
+// ❌ Ruim
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "Update"
+}
+
+// ✅ Bom
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Adicionar validação de formulário\n\n- Campo email obrigatório\n- Validação de formato\n- Mensagens de erro localizadas\n- Testes unitários incluídos"
+}
+```
+
+### 2. Branches por Feature
+```json
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "feature/user-profile-page"
+}
+
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "bugfix/login-validation"
+}
+
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "refactor/api-cleanup"
+}
+```
+
+### 3. Backups Estratégicos
+```json
+// Antes de mudanças arriscadas
+{
+  "action": "backup",
+  "projectPath": "C:\\projetos\\meu-app",
+  "description": "Antes de refatoração da arquitetura"
+}
+
+// Backups automáticos
+{
+  "action": "auto",
+  "projectPath": "C:\\projetos\\meu-app",
+  "enabled": true,
+  "schedule": "commit"
+}
+```
+
+### 4. Monitoramento Contínuo
+```json
+// Status diário
+{
+  "action": "metrics",
+  "projectPath": "C:\\projetos\\meu-app",
+  "period": "7d"
+}
+
+// Health checks
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app",
+  "suggestions": true
+}
+```

package/INSTRUCOES.md

@@ -0,0 +1,444 @@
+# 📖 INSTRUÇÕES DE USO - MCP Git AI Unification Server
+
+## 🎯 Visão Geral
+
+Sistema unificado de 18 ferramentas Git otimizadas para agentes de IA, com auto-detecção universal e zero-configuração.
+
+## 📋 Formato Universal de Request
+
+Todas as ferramentas seguem o mesmo padrão:
+
+```json
+{
+  "action": "nome_da_action",
+  "projectPath": "/caminho/absoluto/do/projeto"
+  // outros parâmetros específicos da action
+}
+```
+
+## 🛠️ Ferramentas Disponíveis
+
+### 1. git-workflow (Workflow Principal)
+**Responsável:** Operações essenciais de Git em workflow completo
+
+#### Actions Disponíveis:
+
+**`init`** - Inicialização completa do projeto
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `message` (mensagem inicial do commit)
+- **Funcionalidade:** Cria repositório, configura remotes, faz commit inicial
+
+**`commit`** - Commit com push automático
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `message`
+- **Funcionalidade:** Add automático + commit + push para todos os providers
+
+**`sync`** - Sincronização completa
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `message` (se houver mudanças locais)
+- **Funcionalidade:** Pull de todos + commit opcional + push para todos
+
+**`status`** - Status completo do projeto
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `detailed` (boolean, default: false)
+- **Funcionalidade:** Status Git + multi-provider + métricas
+
+**`backup`** - Backup completo do estado atual
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `description` (descrição do backup)
+- **Funcionalidade:** Commit + push para todos os providers
+
+### 2. git-files (Gerenciamento Inteligente de Arquivos)
+**Responsável:** Operações de arquivo com backup automático
+
+#### Actions Disponíveis:
+
+**`read`** - Leitura de arquivos
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `filePath`
+- **Funcionalidade:** Lê conteúdo, metadados e encoding
+
+**`write`** - Escrita com backup automático
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `filePath`, `content`
+- **Funcionalidade:** Escreve arquivo + commit automático + push
+
+**`search`** - Busca eficiente no código
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `query`
+- **Parâmetros opcionais:** `path` (diretório específico), `caseSensitive` (boolean), `patterns` (array de glob patterns)
+- **Funcionalidade:** Busca em arquivos .js, .ts, .json, .md
+
+**`update`** - Atualização com versionamento
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `filePath`, `content`
+- **Funcionalidade:** Atualiza arquivo + backup automático
+
+**`backup-files`** - Backup seletivo de arquivos
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `patterns` (array de padrões glob), `description`
+- **Funcionalidade:** Backup de arquivos específicos + commit
+
+### 3. git-release (Automação de Releases)
+**Responsável:** Versionamento semântico e publicação
+
+#### Actions Disponíveis:
+
+**`create`** - Release automático
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `version`, `changelog`, `draft`, `prerelease`, `assets`, `notes`
+- **Funcionalidade:** Auto-versioning + changelog + multi-provider publish
+
+**`version`** - Controle de versão
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `type` ("patch"/"minor"/"major")
+- **Funcionalidade:** Bump automático de versão semântica
+
+**`publish`** - Publicação de release
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `providers` (array específico)
+- **Funcionalidade:** Publicação em múltiplos providers
+
+**`history`** - Histórico de releases
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `limit`, `includeDrafts`
+- **Funcionalidade:** Lista completa de releases
+
+**`rollback`** - Rollback seguro
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `createBackup`
+- **Funcionalidade:** Reverte release com backup automático
+
+### 4. git-monitor (Monitoramento e Analytics)
+**Responsável:** Métricas e monitoramento de projeto
+
+#### Actions Disponíveis:
+
+**`status`** - Status detalhado
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `includeMetrics`, `detailed`
+- **Funcionalidade:** Status completo + métricas
+
+**`history`** - Histórico de atividades
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `since` (período), `limit`, `type`
+- **Funcionalidade:** Timeline de atividades
+
+**`metrics`** - Métricas de produtividade
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `period` ("1d"/"7d"/"30d"/"90d"), `includeCharts`
+- **Funcionalidade:** Estatísticas de desenvolvimento
+
+**`health`** - Análise de saúde
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `deep`, `suggestions`
+- **Funcionalidade:** Diagnóstico de problemas
+
+**`activity`** - Atividade recente
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `hours`, `includeRemote`
+- **Funcionalidade:** Atividade em tempo real
+
+### 5. git-backup (Sistema de Backup Completo)
+**Responsável:** Backups incrementais e restauração
+
+#### Actions Disponíveis:
+
+**`create`** - Criar backup
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `type` ("full"/"incremental"/"checkpoint"), `name`, `includeUntracked`, `compress`
+- **Funcionalidade:** Backup inteligente do estado atual
+
+**`restore`** - Restaurar backup
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `backupId`
+- **Parâmetros opcionais:** `preview`, `force`, `targetPath`
+- **Funcionalidade:** Restauração granular
+
+**`list`** - Listar backups
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `filter`, `limit`, `sortBy`
+- **Funcionalidade:** Gerenciamento de backups
+
+**`auto`** - Backup automático
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `enabled`, `schedule`, `retention`, `maxBackups`
+- **Funcionalidade:** Configuração de backup automático
+
+**`verify`** - Verificação de integridade
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `backupId`
+- **Parâmetros opcionais:** `deep`
+- **Funcionalidade:** Validação de backups
+
+### 6. git-branches (Gerenciamento de Branches)
+**Responsável:** Branches com sincronização multi-provider
+
+#### Actions Disponíveis:
+
+**`create`** - Criar branch
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `name`
+- **Parâmetros opcionais:** `from` (branch base)
+- **Funcionalidade:** Criação + push automático
+
+**`list`** - Listar branches
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `remote` (incluir remotas)
+- **Funcionalidade:** Local + remoto
+
+**`switch`** - Trocar branch
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `name`
+- **Parâmetros opcionais:** `create` (criar se não existir)
+- **Funcionalidade:** Troca segura
+
+**`delete`** - Remover branch
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `name`
+- **Parâmetros opcionais:** `force`
+- **Funcionalidade:** Local e remoto
+
+**`merge`** - Merge inteligente
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `branch`
+- **Parâmetros opcionais:** `strategy` ("merge"/"rebase"/"squash"), `noCommit`
+- **Funcionalidade:** Merge com resolução automática
+
+**`compare`** - Comparação entre branches
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `base`, `head`
+- **Parâmetros opcionais:** `detailed`
+- **Funcionalidade:** Diff detalhado
+
+### 7. git-remote (Gerenciamento de Remotos)
+**Responsável:** Configuração e gerenciamento de remotos
+
+#### Actions Disponíveis:
+
+**`add`** - Adicionar remote
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `name`, `url`
+- **Parâmetros opcionais:** `provider`
+- **Funcionalidade:** Auto-detecção de provider
+
+**`remove`** - Remover remote
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `name`
+- **Parâmetros opcionais:** `force`
+- **Funcionalidade:** Remoção segura
+
+**`rename`** - Renomear remote
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `oldName`, `newName`
+- **Funcionalidade:** Renomeação completa
+
+**`show`** - Mostrar informações
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `detailed`
+- **Funcionalidade:** Status detalhado
+
+**`set-url`** - Atualizar URL
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `name`, `url`
+- **Parâmetros opcionais:** `push`
+- **Funcionalidade:** URL específica para push
+
+**`prune`** - Limpeza de referências
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Funcionalidade:** Remove referências obsoletas
+
+### 8. git-stash (Gerenciamento de Stash)
+**Responsável:** Salvamento temporário de mudanças
+
+#### Actions Disponíveis:
+
+**`save`** - Salvar stash
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `message`, `includeUntracked`, `keepIndex`
+- **Funcionalidade:** Auto-naming inteligente
+
+**`pop`** - Aplicar e remover
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `index`
+- **Funcionalidade:** Aplicação + remoção
+
+**`apply`** - Aplicar sem remover
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `index`
+- **Funcionalidade:** Aplicação apenas
+
+**`list`** - Listar stashes
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `detailed`, `filter`
+- **Funcionalidade:** Gerenciamento completo
+
+**`show`** - Mostrar detalhes
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `index`
+- **Parâmetros opcionais:** `patch`
+- **Funcionalidade:** Conteúdo detalhado
+
+**`drop`** - Remover stash
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `index`
+- **Funcionalidade:** Remoção específica
+
+**`clear`** - Limpar todos
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `confirm`
+- **Funcionalidade:** Limpeza completa
+
+### 9. git-reset (Reset Seguro)
+**Responsável:** Operações de reset controladas
+
+#### Actions Disponíveis:
+
+**`soft`** - Reset soft
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `commit`
+- **Funcionalidade:** Mantém staging area
+
+**`mixed`** - Reset mixed
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `commit`
+- **Funcionalidade:** Limpa staging, preserva working
+
+**`hard`** - Reset hard
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `commit`
+- **Parâmetros opcionais:** `confirm`
+- **Funcionalidade:** Remove tudo
+
+**`reset-to-commit`** - Reset específico
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `commit`
+- **Parâmetros opcionais:** `type` ("soft"/"mixed"/"hard")
+- **Funcionalidade:** Reset para commit específico
+
+**`reset-branch`** - Reset de branch
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `branch`
+- **Parâmetros opcionais:** `target`, `type`
+- **Funcionalidade:** Reset de branch específica
+
+### 10. git-tags (Gerenciamento de Tags)
+**Responsável:** Versionamento com tags semânticas
+
+#### Actions Disponíveis:
+
+**`create`** - Criar tag
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `name`
+- **Parâmetros opcionais:** `message`, `target`, `type` ("lightweight"/"annotated")
+- **Funcionalidade:** Auto-detecção de tipo
+
+**`list`** - Listar tags
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `pattern`, `sort`, `limit`
+- **Funcionalidade:** Filtragem avançada
+
+**`get`** - Detalhes da tag
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `name`
+- **Parâmetros opcionais:** `detailed`
+- **Funcionalidade:** Informações completas
+
+**`delete`** - Remover tag
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `name`
+- **Parâmetros opcionais:** `remote`, `force`
+- **Funcionalidade:** Local e remoto
+
+**`search`** - Busca de tags
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `query`, `pattern`
+- **Funcionalidade:** Busca avançada
+
+### 11. git-issues (Sistema de Issues Local)
+**Responsável:** Gerenciamento de tarefas locais
+
+#### Actions Disponíveis:
+
+**`create`** - Criar issue
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `title`
+- **Parâmetros opcionais:** `description`, `labels`, `priority`, `assignee`, `dueDate`
+- **Funcionalidade:** Issue estruturada
+
+**`list`** - Listar issues
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `state`, `limit`, `sort`
+- **Funcionalidade:** Filtragem completa
+
+**`get`** - Detalhes da issue
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `id`
+- **Parâmetros opcionais:** `detailed`
+- **Funcionalidade:** Informações completas
+
+**`update`** - Atualizar issue
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `id`
+- **Parâmetros opcionais:** `title`, `description`, `status`, `priority`, etc.
+- **Funcionalidade:** Modificação completa
+
+**`close`** - Fechar issue
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `id`
+- **Parâmetros opcionais:** `comment`
+- **Funcionalidade:** Fechamento com comentário
+
+**`scan`** - Auto-detecção de TODOs
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Parâmetros opcionais:** `createIssues`, `patterns`
+- **Funcionalidade:** Converte TODO/FIXME em issues
+
+### 12. git-pulls (Pull Requests Locais)
+**Responsável:** Sistema básico de pull requests
+
+#### Actions Disponíveis:
+
+**`create`** - Criar PR
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `title`, `head`, `base`
+- **Funcionalidade:** PR local básico
+
+**`list`** - Listar PRs
+- **Parâmetros obrigatórios:** `action`, `projectPath`
+- **Funcionalidade:** PRs locais
+
+**`merge`** - Merge PR
+- **Parâmetros obrigatórios:** `action`, `projectPath`, `number`
+- **Funcionalidade:** Merge básico
+
+### 13-18. Ferramentas Especializadas (Placeholders)
+
+**git-analytics, git-archive, git-packages, git-sync, git-repos, git-config**
+- Status: Implementação básica disponível
+- Funcionalidade: Estrutura pronta para expansão
+- Parâmetros: Seguem padrão universal
+
+## ⚙️ Configuração de Ambiente
+
+### Variáveis Obrigatórias:
+```bash
+GITEA_USERNAME=seu_usuario
+GITEA_TOKEN=seu_token_gitea
+GITEA_URL=https://seu-gitea.com
+```
+
+### Variáveis Opcionais:
+```bash
+GITHUB_USERNAME=seu_usuario_github
+GITHUB_TOKEN=seu_token_github
+DEMO_MODE=true  # Para testes
+```
+
+## 📊 Formato de Response Universal
+
+Todas as ferramentas retornam:
+
+```json
+{
+  "success": true,
+  "action": "nome_da_action",
+  "message": "descrição do resultado",
+  "data": { /* dados específicos */ },
+  "error": { /* se houver erro */ },
+  "autoDetected": {
+    "repo": "nome_repo",
+    "owner": "dono_repo",
+    "providers": ["gitea", "github"],
+    "projectPath": "/caminho/projeto"
+  },
+  "metadata": {
+    "timestamp": "2025-09-30T22:26:04.378Z",
+    "operation": "nome_da_action",
+    "tool": "nome_da_tool"
+  }
+}
+```
+
+## 🚨 Tratamento de Erros
+
+- **Auto-recovery**: Tentativas automáticas de correção
+- **Sugestões**: Recomendações específicas para resolução
+- **Códigos padronizados**: Classificação consistente de erros
+
+## 🎯 Boas Práticas
+
+1. **Sempre use projectPath absoluto**
+2. **Configure providers antes do uso**
+3. **Verifique responses para autoDetected**
+4. **Use error.suggestion para recovery**
+5. **Prefira actions em lote quando possível**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andrebuzeli/git-mcp",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "MCP server for Gitea and GitHub integration - UNIFICADO: 18 ferramentas otimizadas para AI agents, auto-detecção universal, error handling inteligente, workflow completo - 100% COMPATÍVEL: git-workflow, git-files, git-release, git-monitor, git-backup, git-branches, git-remote, git-stash, git-reset, git-tags, git-issues, git-pulls + 6 ferramentas especializadas - ZERO CONFIG, FULLY IMPLEMENTED for AI agents",
   "main": "dist/index.js",
   "bin": {
@@ -13,9 +13,9 @@
     "test": "node tests/basic.test.js",
     "lint": "echo \"No linting configured\" && exit 0",
     "prepublishOnly": "npm run build",
-    "postpublish": "echo 'Git MCP v4.0.2 published successfully - UNIFICADO: 18 ferramentas otimizadas para AI agents, auto-detecção universal, error handling inteligente - git-workflow, git-files, git-release, git-monitor, git-backup, git-branches, git-remote, git-stash, git-reset, git-tags, git-issues, git-pulls + 6 ferramentas especializadas - ZERO CONFIGURAÇÃO, 100% COMPATÍVEL COM QUALQUER AI AGENT!'"
+    "postpublish": "echo 'Git MCP v4.0.3 published successfully - DOCUMENTADO: 18 ferramentas + documentação completa - INSTRUCOES.md com guia detalhado de todas as actions, EXEMPLOS.md com casos reais de uso, README.md atualizado - UNIFICADO para AI agents com auto-detecção universal, error handling inteligente e workflow completo!'"
 
-  },
+},
   "keywords": [
     "mcp",
     "gitea",
@@ -55,6 +55,8 @@
   "files": [
     "dist/**/*",
     "README.md",
+    "INSTRUCOES.md",
+    "EXEMPLOS.md",
     "LICENSE"
   ]
 }