@andrebuzeli/git-mcp 2.48.0 → 3.0.0

package/README.md

@@ -1,329 +1,356 @@
-# Git MCP - Servidor MCP Completo para Gitea e GitHub
-
-> Servidor MCP (Model Context Protocol) completo para integração com Gitea e GitHub - 100% AUTOSSUFICIENTE com 20 ferramentas DevOps completas
-
-[![npm version](https://badge.fury.io/js/@andrebuzeli/git-mcp.svg)](https://badge.fury.io/js/@andrebuzeli/git-mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## 🎯 Visão Geral
-
-Git MCP é um servidor MCP abrangente projetado para desenvolvedores que precisam de automação Git poderosa. Suporta dual providers (Gitea + GitHub) com backup automático, gerenciamento completo de repositórios e configuração zero.
-
-## ✨ Características Principais
-
-### 🔧 **Operações Git Completas**
-- **Gerenciamento de Repositórios**: Inicializar, clonar e gerenciar repositórios
-- **Operações de Arquivo**: Criar, atualizar, deletar arquivos e diretórios
-- **Workflow de Commit**: Add, commit, push com mensagens automatizadas
-- **Gerenciamento de Branches**: Criar, trocar, merge e deletar branches
-- **Histórico e Recuperação**: Rastreamento completo com rollback fácil
-
-### 💾 **Backup Dual Provider**
-- **Sincronização Automática**: Mantenha Gitea e GitHub perfeitamente sincronizados
-- **Backup Redundante**: Nunca perca seu código com armazenamento dual
-- **Recuperação Inteligente**: Restaure de qualquer provider ou ponto de backup
-- **Zero Configuração**: Usa variáveis de ambiente, sem configuração manual
-
-### 🚀 **Releases Profissionais**
-- **Versionamento Semântico**: Gerenciamento automatizado de versões
-- **Geração de Changelog**: Notas de release auto-geradas
-- **Gerenciamento de Assets**: Upload e gerenciamento de assets de release
-- **Publicação Multi-Provider**: Release simultâneo em ambas as plataformas
-
-### ⚙️ **Developer-Friendly**
-- **Zero Config**: Funciona imediatamente com variáveis de ambiente
-- **Templates Inteligentes**: .gitignore auto-gerado para qualquer tipo de projeto
-- **Workflows Automatizados**: Trata tarefas repetitivas automaticamente
-- **Foco Individual**: Sem complexidade enterprise, apenas o que você precisa
-
-## 🏗️ Arquitetura
-
-Git MCP consiste de 20 ferramentas especializadas organizadas em 4 categorias:
-
-### Core Git Tools (15)
-| Tool | Propósito | Ações Principais |
-|------|-----------|------------------|
-| **git-repositories** | Gerenciamento de repositórios | create, list, get, update, delete, fork, search, init, clone |
-| **git-commits** | Operações de commit | list, get, create, compare, search, push, pull |
-| **git-branches** | Gerenciamento de branches | create, list, get, delete, merge, compare |
-| **git-files** | Operações de arquivo | get, create, update, delete, list, search |
-| **git-issues** | Gerenciamento de issues | create, list, get, update, close, comment, search |
-| **git-pulls** | Pull requests | create, list, get, update, merge, close, review, search |
-| **git-releases** | Releases e tags | create, list, get, update, delete, publish |
-| **git-tags** | Gerenciamento de tags | create, list, get, delete, search |
-| **git-config** | Configurações Git | get, set, unset, list, edit, show |
-| **git-remote** | Operações remotas | add, remove, rename, show, set-url, prune |
-| **git-reset** | Reset de commits | soft, mixed, hard, reset-to-commit, reset-branch |
-| **git-revert** | Revert de mudanças | revert-commit, revert-merge, revert-range |
-| **git-stash** | Stash de mudanças | stash, pop, apply, list, show, drop, clear |
-| **git-archive** | Arquivos compactados | create, extract, list, verify |
-| **git-sync** | Sincronização | configure, status, one-shot |
-
-### Advanced Tools (5)
-| Tool | Propósito | Ações Principais |
-|------|-----------|------------------|
-| **git-update-project** | Atualização completa | init, update, status, diff, log, reset, stash, pull, sync |
-| **git-initialize** | Inicialização | init |
-| **git-packages** | Pacotes | list, get, create, update, delete, publish, download |
-| **git-projects** | Projetos | list, get, create, update, delete, addItem, updateItem, deleteItem, listItems |
-| **git-branch-protection** | Proteção de branches | create, list, get, update, delete |
-
-## 🚀 Início Rápido
-
-### Instalação
-
-```bash
-npm install -g @andrebuzeli/git-mcp
-```
-
-### Configuração de Ambiente
-
-Crie um arquivo `.env` ou defina variáveis de ambiente:
-
-```env
-# Configuração Gitea
-GITEA_URL=http://seu-servidor-gitea:3000
-GITEA_TOKEN=seu_token_acesso_gitea
-GITEA_USERNAME=seu_username
-
-# Configuração GitHub
-GITHUB_TOKEN=seu_token_pessoal_github
-```
-
-### Configuração do Cliente MCP
-
-Adicione à configuração do seu cliente MCP (ex: Claude Desktop, Cursor):
-
-```json
-{
-  "mcpServers": {
-    "git-mcp": {
-      "command": "git-mcp",
-      "env": {
-        "GITEA_URL": "http://seu-servidor-gitea:3000",
-        "GITEA_TOKEN": "seu_token_gitea",
-        "GITEA_USERNAME": "seu_username",
-        "GITHUB_TOKEN": "seu_token_github"
-      }
-    }
-  }
-}
-```
-
-## 📖 Exemplos de Uso
-
-### Inicializar um Novo Projeto
-
-```typescript
-// Inicializar projeto com setup dual provider
-{
-  "tool": "git-repositories",
-  "arguments": {
-    "action": "init",
-    "projectPath": "/caminho/do/projeto",
-    "repo": "meu-projeto-incrivel",
-    "provider": "gitea"
-  }
-}
-```
-
-### Commit e Sincronização de Mudanças
-
-```typescript
-// Commit das mudanças
-{
-  "tool": "git-commits",
-  "arguments": {
-    "action": "create",
-    "repo": "meu-projeto",
-    "message": "feat: adicionar nova funcionalidade",
-    "projectPath": "/caminho/do/projeto",
-    "provider": "gitea"
-  }
-}
-
-// Push para remoto
-{
-  "tool": "git-commits",
-  "arguments": {
-    "action": "push",
-    "repo": "meu-projeto",
-    "projectPath": "/caminho/do/projeto",
-    "provider": "gitea"
-  }
-}
-```
-
-### Criar um Release
-
-```typescript
-{
-  "tool": "git-releases",
-  "arguments": {
-    "action": "create",
-    "repo": "meu-projeto",
-    "tag_name": "v1.2.0",
-    "name": "Versão 1.2.0",
-    "body": "Atualização major com performance melhorada",
-    "provider": "gitea"
-  }
-}
-```
-
-### Upload Completo do Projeto
-
-```typescript
-{
-  "tool": "git-update-project",
-  "arguments": {
-    "action": "init",
-    "repo": "meu-projeto",
-    "projectPath": "/caminho/do/projeto",
-    "provider": "gitea",
-    "message": "Upload inicial do projeto"
-  }
-}
-```
-
-## 🔧 Configuração
-
-### Variáveis de Ambiente
-
-| Variável | Obrigatório | Descrição |
-|----------|-------------|-----------|
-| `GITEA_URL` | Sim | URL do seu servidor Gitea |
-| `GITEA_TOKEN` | Sim | Token de acesso Gitea |
-| `GITEA_USERNAME` | Sim | Seu username Gitea |
-| `GITHUB_TOKEN` | Não | Token pessoal GitHub |
-| `LOG_LEVEL` | Não | Nível de log (ERROR, WARN, INFO, DEBUG) |
-
-### Permissões dos Tokens
-
-**Token Gitea:**
-- Repository: Read, Write
-- Issues: Read, Write
-- Pull Requests: Read, Write
-
-**Token GitHub:**
-- `repo` - Acesso completo ao repositório
-- `workflow` - Atualizar workflows GitHub Actions
-- `write:packages` - Upload de pacotes
-
-## 🛠️ Desenvolvimento
-
-### Pré-requisitos
-
-- Node.js 18+
-- Git instalado e configurado
-- Acesso a instâncias Gitea e GitHub
-
-### Setup
-
-```bash
-# Clonar o repositório
-git clone https://github.com/andrebuzeli/gitea-mcp-v2.git
-cd gitea-mcp-v2
-
-# Instalar dependências
-npm install
-
-# Build do projeto
-npm run build
-
-# Executar em modo desenvolvimento
-npm run dev
-```
-
-### Testes
-
-```bash
-# Executar testes
-npm test
-
-# Executar linting
-npm run lint
-```
-
-## 📚 Referência da API
-
-### Visão Geral das Ferramentas
-
-#### git-repositories
-Gerenciamento completo de repositórios Git.
-
-**Ações:** `create`, `list`, `get`, `update`, `delete`, `fork`, `search`, `init`, `clone`
-
-#### git-commits
-Operações completas de commit e histórico.
-
-**Ações:** `list`, `get`, `create`, `compare`, `search`, `push`, `pull`
-
-#### git-branches
-Gerenciamento completo de branches.
-
-**Ações:** `create`, `list`, `get`, `delete`, `merge`, `compare`
-
-#### git-files
-Operações de arquivo e diretório.
-
-**Ações:** `get`, `create`, `update`, `delete`, `list`, `search`
-
-#### git-issues
-Sistema completo de gerenciamento de issues.
-
-**Ações:** `create`, `list`, `get`, `update`, `close`, `comment`, `search`
-
-#### git-pulls
-Gerenciamento completo de pull requests.
-
-**Ações:** `create`, `list`, `get`, `update`, `merge`, `close`, `review`, `search`
-
-#### git-releases
-Sistema profissional de releases e versionamento.
-
-**Ações:** `create`, `list`, `get`, `update`, `delete`, `publish`
-
-#### git-tags
-Gerenciamento de tags para versionamento.
-
-**Ações:** `create`, `list`, `get`, `delete`, `search`
-
-#### git-update-project
-Atualização completa e sincronização de projetos.
-
-**Ações:** `init`, `update`, `status`, `diff`, `log`, `reset`, `stash`, `pull`, `sync`
-
-## 🤝 Contribuição
-
-Contribuições são bem-vindas! Leia nosso [Guia de Contribuição](CONTRIBUTING.md) para detalhes sobre nosso código de conduta e o processo para submeter pull requests.
-
-### Workflow de Desenvolvimento
-
-1. Fork o repositório
-2. Crie uma branch de feature: `git checkout -b feature/recurso-incrivel`
-3. Faça suas mudanças e adicione testes
-4. Commit suas mudanças: `git commit -m 'feat: adicionar recurso incrivel'`
-5. Push para a branch: `git push origin feature/recurso-incrivel`
-6. Abra um Pull Request
-
-## 📄 Licença
-
-Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
-
-## 🙏 Agradecimentos
-
-- [Model Context Protocol](https://modelcontextprotocol.io/) pelo excelente framework MCP
-- A comunidade open-source por inspiração e suporte
-
-## 📞 Suporte
-
-- 📧 Email: andre@buzeli.com
-- 🐛 Issues: [GitHub Issues](https://github.com/andrebuzeli/gitea-mcp-v2/issues)
-- 💬 Discussões: [GitHub Discussions](https://github.com/andrebuzeli/gitea-mcp-v2/discussions)
-
----
-
-**Feito com ❤️ para desenvolvedores que querem automação Git poderosa sem complexidade.**
-
-
-
+# Git MCP - Servidor MCP Completo para Gitea e GitHub
+
+> Servidor MCP (Model Context Protocol) completo para integração com Gitea e GitHub - 100% AUTOSSUFICIENTE com 20 ferramentas DevOps completas
+
+[![npm version](https://badge.fury.io/js/@andrebuzeli/git-mcp.svg)](https://badge.fury.io/js/@andrebuzeli/git-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 🎯 Visão Geral
+
+Git MCP é um servidor MCP abrangente projetado para desenvolvedores que precisam de automação Git poderosa. Suporta dual providers (Gitea + GitHub) com backup automático, gerenciamento completo de repositórios e configuração zero.
+
+## ✨ Características Principais
+
+### 🔧 **Operações Git Completas**
+- **Gerenciamento de Repositórios**: Inicializar, clonar e gerenciar repositórios
+- **Operações de Arquivo**: Criar, atualizar, deletar arquivos e diretórios
+- **Workflow de Commit**: Add, commit, push com mensagens automatizadas
+- **Gerenciamento de Branches**: Criar, trocar, merge e deletar branches
+- **Histórico e Recuperação**: Rastreamento completo com rollback fácil
+
+### 💾 **Backup Dual Provider**
+- **Sincronização Automática**: Mantenha Gitea e GitHub perfeitamente sincronizados
+- **Backup Redundante**: Nunca perca seu código com armazenamento dual
+- **Recuperação Inteligente**: Restaure de qualquer provider ou ponto de backup
+- **Zero Configuração**: Usa variáveis de ambiente, sem configuração manual
+
+### 🚀 **Releases Profissionais**
+- **Versionamento Semântico**: Gerenciamento automatizado de versões
+- **Geração de Changelog**: Notas de release auto-geradas
+- **Gerenciamento de Assets**: Upload e gerenciamento de assets de release
+- **Publicação Multi-Provider**: Release simultâneo em ambas as plataformas
+
+### ⚙️ **Developer-Friendly**
+- **Zero Config**: Funciona imediatamente com variáveis de ambiente
+- **Templates Inteligentes**: .gitignore auto-gerado para qualquer tipo de projeto
+- **Workflows Automatizados**: Trata tarefas repetitivas automaticamente
+- **Foco Individual**: Sem complexidade enterprise, apenas o que você precisa
+
+## 🏗️ Arquitetura Reestruturada
+
+Git MCP v3.0.0 foi **completamente reestruturado** para programadores individuais, reduzindo de 20 para **6 ferramentas principais** com funcionalidades combinadas e error handling inteligente.
+
+### 🛠️ Core Tools (4) - Funcionalidades Unificadas
+| Tool | Propósito | Ações Principais | Substitui |
+|------|-----------|------------------|-----------|
+| **git-workflow** ⭐⭐⭐⭐⭐ | Workflow completo | init, commit, sync, status, diff, log, stash, reset, pull, push | git-update-project, git-commits, git-stash, git-reset |
+| **git-projects** ⭐⭐⭐⭐⭐ | Projetos & arquivos | create, list, clone, create-file, read-file, list-files | git-repositories, git-files, git-initialize |
+| **git-versioning** ⭐⭐⭐⭐⭐ | Branches & releases | create-branch, list-branches, create-release, create-tag, bump-version | git-branches, git-releases, git-tags |
+| **git-undo** ⭐⭐⭐⭐⭐ | Undo/Redo inteligente | stash-save, reset-soft/mixed/hard, revert, undo-last, redo-last | git-stash, git-reset, git-revert |
+
+### 🔧 Additional Tools (2) - Funcionalidades Específicas
+| Tool | Propósito | Ações Principais |
+|------|-----------|------------------|
+| **git-issues** ⭐⭐⭐⭐ | Issues pessoais | create, list, get, update, close, comment, search |
+| **git-config** ⭐⭐⭐ | Configurações Git | get, set, unset, list, edit, show |
+
+## ✨ Melhorias Implementadas
+
+### Error Handling Inteligente
+- **Sugestões automáticas** de correção para erros comuns
+- **Recovery guidance** com próximos passos recomendados
+- **Confirmações** para operações destrutivas
+- **Context-aware** error messages
+
+### Workflow Otimizado
+- **Funcionalidades combinadas** reduzindo complexidade
+- **Actions intuitivas** focadas em uso pessoal
+- **Auto-detecção** de providers e configurações
+- **Smart defaults** para programadores individuais
+
+### Segurança e Confiabilidade
+- **Validação rigorosa** de todos os inputs
+- **Safe operations** com preview e confirmação
+- **Atomic operations** quando possível
+- **Rollback support** para operações críticas
+
+## 🚀 Início Rápido
+
+### Instalação
+
+```bash
+npm install -g @andrebuzeli/git-mcp
+```
+
+### Configuração de Ambiente
+
+Crie um arquivo `.env` ou defina variáveis de ambiente:
+
+```env
+# Configuração Gitea
+GITEA_URL=http://seu-servidor-gitea:3000
+GITEA_TOKEN=seu_token_acesso_gitea
+GITEA_USERNAME=seu_username
+
+# Configuração GitHub
+GITHUB_TOKEN=seu_token_pessoal_github
+```
+
+### Configuração do Cliente MCP
+
+Adicione à configuração do seu cliente MCP (ex: Claude Desktop, Cursor):
+
+```json
+{
+  "mcpServers": {
+    "git-mcp": {
+      "command": "git-mcp",
+      "env": {
+        "GITEA_URL": "http://seu-servidor-gitea:3000",
+        "GITEA_TOKEN": "seu_token_gitea",
+        "GITEA_USERNAME": "seu_username",
+        "GITHUB_TOKEN": "seu_token_github"
+      }
+    }
+  }
+}
+```
+
+## 📖 Exemplos de Uso
+
+### Inicializar um Novo Projeto
+
+```typescript
+// Inicializar projeto com setup dual provider
+{
+  "tool": "git-repositories",
+  "arguments": {
+    "action": "init",
+    "projectPath": "/caminho/do/projeto",
+    "repo": "meu-projeto-incrivel",
+    "provider": "gitea"
+  }
+}
+```
+
+### Commit e Sincronização de Mudanças
+
+```typescript
+// Commit das mudanças
+{
+  "tool": "git-commits",
+  "arguments": {
+    "action": "create",
+    "repo": "meu-projeto",
+    "message": "feat: adicionar nova funcionalidade",
+    "projectPath": "/caminho/do/projeto",
+    "provider": "gitea"
+  }
+}
+
+// Push para remoto
+{
+  "tool": "git-commits",
+  "arguments": {
+    "action": "push",
+    "repo": "meu-projeto",
+    "projectPath": "/caminho/do/projeto",
+    "provider": "gitea"
+  }
+}
+```
+
+### Criar um Release
+
+```typescript
+{
+  "tool": "git-releases",
+  "arguments": {
+    "action": "create",
+    "repo": "meu-projeto",
+    "tag_name": "v1.2.0",
+    "name": "Versão 1.2.0",
+    "body": "Atualização major com performance melhorada",
+    "provider": "gitea"
+  }
+}
+```
+
+### Upload Completo do Projeto
+
+```typescript
+{
+  "tool": "git-update-project",
+  "arguments": {
+    "action": "init",
+    "repo": "meu-projeto",
+    "projectPath": "/caminho/do/projeto",
+    "provider": "gitea",
+    "message": "Upload inicial do projeto"
+  }
+}
+```
+
+## 🔧 Configuração
+
+### Variáveis de Ambiente
+
+| Variável | Obrigatório | Descrição |
+|----------|-------------|-----------|
+| `GITEA_URL` | Sim | URL do seu servidor Gitea |
+| `GITEA_TOKEN` | Sim | Token de acesso Gitea |
+| `GITEA_USERNAME` | Sim | Seu username Gitea |
+| `GITHUB_TOKEN` | Não | Token pessoal GitHub |
+| `LOG_LEVEL` | Não | Nível de log (ERROR, WARN, INFO, DEBUG) |
+
+### Permissões dos Tokens
+
+**Token Gitea:**
+- Repository: Read, Write
+- Issues: Read, Write
+- Pull Requests: Read, Write
+
+**Token GitHub:**
+- `repo` - Acesso completo ao repositório
+- `workflow` - Atualizar workflows GitHub Actions
+- `write:packages` - Upload de pacotes
+
+## 🛠️ Desenvolvimento
+
+### Pré-requisitos
+
+- Node.js 18+
+- Git instalado e configurado
+- Acesso a instâncias Gitea e GitHub
+
+### Setup
+
+```bash
+# Clonar o repositório
+git clone https://github.com/andrebuzeli/gitea-mcp-v2.git
+cd gitea-mcp-v2
+
+# Instalar dependências
+npm install
+
+# Build do projeto
+npm run build
+
+# Executar em modo desenvolvimento
+npm run dev
+```
+
+### Testes
+
+```bash
+# Executar testes
+npm test
+
+# Executar linting
+npm run lint
+```
+
+## 📚 Referência da API - v3.0.0
+
+### Core Tools - Reestruturadas
+
+#### git-workflow 🛠️
+**Workflow completo para desenvolvimento diário**
+
+**Ações:**
+- `init` - Inicializar projeto e fazer primeiro commit
+- `commit` - Commit automático com push opcional
+- `sync` - Pull + commit + push completo
+- `status` - Status detalhado do projeto
+- `diff` - Ver diferenças nos arquivos
+- `log` - Histórico de commits
+- `stash` - Salvar mudanças temporariamente
+- `stash-list` - Listar stashes salvos
+- `stash-apply` - Aplicar stash salvo
+- `reset` - Desfazer commits (soft/mixed/hard)
+- `pull` - Baixar mudanças do remoto
+- `push` - Enviar mudanças para remoto
+
+#### git-projects 📁
+**Gerenciamento de projetos e arquivos**
+
+**Ações:**
+- `create` - Criar repositório remoto
+- `list` - Listar repositórios
+- `clone` - Clonar repositório localmente
+- `create-file` - Criar arquivo local
+- `read-file` - Ler arquivo local
+- `list-files` - Listar arquivos/diretórios
+
+#### git-versioning 🏷️
+**Versionamento inteligente com branches e releases**
+
+**Ações:**
+- `create-branch` - Criar nova branch
+- `list-branches` - Listar branches
+- `switch-branch` - Trocar de branch
+- `delete-branch` - Remover branch
+- `create-release` - Criar release
+- `list-releases` - Listar releases
+- `create-tag` - Criar tag
+- `list-tags` - Listar tags
+- `bump-version` - Bump automático (patch/minor/major)
+
+#### git-undo ↩️
+**Undo/Redo inteligente e seguro**
+
+**Ações:**
+- `stash-save` - Salvar mudanças no stash
+- `stash-list` - Listar stashes
+- `stash-apply` - Aplicar stash
+- `stash-drop` - Remover stash
+- `stash-clear` - Limpar todos os stashes
+- `reset-soft/mixed/hard` - Reset com diferentes níveis
+- `revert-commit` - Reverter commit específico
+- `undo-last` - Desfazer última operação
+- `redo-last` - Refazer operação desfeita
+
+#### git-issues 📋
+**Issues pessoais e TODO tracking**
+
+**Ações:** `create`, `list`, `get`, `update`, `close`, `comment`, `search`
+
+#### git-config ⚙️
+**Configurações Git**
+
+**Ações:** `get`, `set`, `unset`, `list`, `edit`, `show`
+
+## 🤝 Contribuição
+
+Contribuições são bem-vindas! Leia nosso [Guia de Contribuição](CONTRIBUTING.md) para detalhes sobre nosso código de conduta e o processo para submeter pull requests.
+
+### Workflow de Desenvolvimento
+
+1. Fork o repositório
+2. Crie uma branch de feature: `git checkout -b feature/recurso-incrivel`
+3. Faça suas mudanças e adicione testes
+4. Commit suas mudanças: `git commit -m 'feat: adicionar recurso incrivel'`
+5. Push para a branch: `git push origin feature/recurso-incrivel`
+6. Abra um Pull Request
+
+## 📄 Licença
+
+Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
+
+## 🙏 Agradecimentos
+
+- [Model Context Protocol](https://modelcontextprotocol.io/) pelo excelente framework MCP
+- A comunidade open-source por inspiração e suporte
+
+## 📞 Suporte
+
+- 📧 Email: andre@buzeli.com
+- 🐛 Issues: [GitHub Issues](https://github.com/andrebuzeli/gitea-mcp-v2/issues)
+- 💬 Discussões: [GitHub Discussions](https://github.com/andrebuzeli/gitea-mcp-v2/discussions)
+
+---
+
+**Feito com ❤️ para desenvolvedores que querem automação Git poderosa sem complexidade.**
+
+
+