@andrebuzeli/git-mcp 10.0.8 → 11.0.0

package/README.md

@@ -1,441 +1,47 @@
-# GIT MCP Server
+# @andrebuzeli/git-mcp
 
-Professional MCP (Model Context Protocol) server for Git operations with multi-provider support, enhanced security, comprehensive safety features, and **universal IDE compatibility**.
+- Pacote MCP para manipulação Git com Gitea e GitHub em paralelo
+- Configuração via NPX gerando `mcp.json` com `GITEA_URL`, `GITEA_TOKEN`, `GITHUB_TOKEN`
+- Independente de Git instalado: usa `isomorphic-git` puro em Node
 
-## ✨ NEW in v7.4.0 - Universal IDE Compatibility
+## Instalação
 
-**🎉 Now works with ALL IDEs and AI agents without parameter errors!**
+- `npm i -g @andrebuzeli/git-mcp@11.0.0` ou use via npx
 
-- ✅ **VSCode** (all AI extensions)
-- ✅ **Cursor AI**
-- ✅ **Trae AI**
-- ✅ **Kiro.dev**
-- ✅ **Claude Desktop**
-- ✅ **Any MCP-compatible client**
+## Configuração
 
-### Problem Solved
-Previously, different IDEs sent parameters in different formats causing `Error: action is required`. Now Git-MCP **automatically normalizes** parameters from any source!
+- `npx @andrebuzeli/git-mcp@11.0.0 init --path .`
+- Edite `mcp.json` preenchendo os valores de ambiente
+- Garanta que o processo/IDE exporte as variáveis de ambiente
 
-```javascript
-// ALL these formats work now! ✅
-{ "command": "git status", "projectPath": "..." }  // IDE format
-{ "action": "status", "projectPath": "..." }        // Standard format
-{ "command": "status", "projectPath": "..." }       // Simple format
-{ "projectPath": "..." }                             // Auto-detect (defaults to status)
-```
+## Uso rápido
 
-## Features
+- Criar repositórios remotos em ambos provedores
+  - `npx @andrebuzeli/git-mcp@11.0.0 call --tool git-remote --action createRepo --projectPath "C:\\Projetos\\Meu Projeto"`
+- Inicializar e enviar para ambos remotos
+  - `npx @andrebuzeli/git-mcp@11.0.0 call --tool git-local --action init --projectPath "..."`
+  - `npx @andrebuzeli/git-mcp@11.0.0 call --tool git-remote --action ensureRemotes --projectPath "..."`
+  - `npx @andrebuzeli/git-mcp@11.0.0 call --tool git-local --action add --projectPath "..." --args '{"patterns":["."]}'`
+  - `npx @andrebuzeli/git-mcp@11.0.0 call --tool git-local --action commit --projectPath "..." --args '{"message":"Initial commit"}'`
+  - `npx @andrebuzeli/git-mcp@11.0.0 call --tool git-local --action push --projectPath "..." --args '{"remote":"origin-gitea","branch":"main"}'`
+  - `npx @andrebuzeli/git-mcp@11.0.0 call --tool git-local --action push --projectPath "..." --args '{"remote":"origin-github","branch":"main"}'`
 
-- 🌐 **NEW: Universal Parameter Normalization** - Accepts both 'action' and 'command' formats
-- 🚀 **23 Specialized Git Tools** - Complete Git workflow coverage with 170+ actions
-- 📚 **Self-Documenting Resources** - Complete documentation via MCP protocol
-- ⚡ **3 Powerful Tools with Full Traceability**
-  - **git-upload** - Upload complete projects to GitHub + Gitea automatically
-  - **git-update** - Complete update workflow (add + commit + push) with tracking
-  - **git-history** - Detailed history tracking with remote issues
-- 🔄 **Dual Provider Support** - GitHub and Gitea with automatic dual execution
-- 🔒 **Security-First Design** - Read-only file operations, no content modification via API
-- 🚨 **Safety Warnings** - Comprehensive warnings for destructive operations
-- 🛡️ **Enhanced Error Handling** - Detailed diagnostics with actionable solutions
-- 📋 **Comprehensive Validation** - Pre-execution validation with helpful guidance
-- 🔧 **IDE/Client Compatibility** - Works seamlessly with ANY IDE or AI agent
-- 📦 **NPM Distribution** - Easy installation via npx
-- 🤖 **AI Agent Integration** - Designed for AI agent workflows with safety controls
-- 📊 **Full Traceability** - Every operation tracked locally and remotely
+## Integração em IDEs
 
-## Resources System
+- VSCode/Cursor/Trae: apontar o executor MCP para `npx @andrebuzeli/git-mcp@11.0.0 start` e usar `mcp.json` para descoberta das tools
+- Todas as tools exigem `projectPath` e derivam o nome do projeto do último segmento, substituindo espaços por underscore
+ - Consulte `docs/TOOLS.md` para descrições, schema e exemplos de uso por tool/action
 
-Git-MCP v5.7.0 includes a comprehensive **Resources** system that provides detailed documentation directly through the MCP protocol:
+## Tools
 
-### Available Resources
+- `git-local`: status, init, add, commit, push, pull, branch, tag
+  - Implementado com `isomorphic-git` (sem binário git)
+- `git-remote`: createRepo, deleteRepo, ensureRemotes
+- `git-sync`: mirror (push simultâneo para Gitea e GitHub)
+- `git-issues`: create
+- `git-releases`: create
 
-#### Tools Guide Resource
-- **URI:** `git-mcp://tools/guide`
-- **Format:** Markdown
-- **Content:** Complete documentation for all 20 tools with 102 actions
-- **Size:** 35,000+ characters
+## Notas
 
-### Accessing Documentation
-
-```bash
-# List all available resources
-curl http://localhost:3210/resources
-
-# Get complete tools guide
-curl "http://localhost:3210/resources/git-mcp://tools/guide"
-```
-
-### What's Included
-
-- ✅ Quick start guide
-- ✅ All 20 tools documented with examples
-- ✅ 102 actions with parameters
-- ✅ Provider types explained (LOCAL/DUAL/HYBRID)
-- ✅ Best practices and workflows
-- ✅ Troubleshooting guide
-- ✅ Complete reference tables
-
-**See [RESOURCES.md](RESOURCES.md) for detailed documentation on the resources system.**
-
-## Provider Architecture
-
-This MCP server supports **2 providers** (for remote API operations only):
-- **`github`** - GitHub remote operations (issues, PRs, releases) via @octokit/rest
-- **`gitea`** - Gitea remote operations (issues, PRs, releases) via axios to nas-ubuntu:3000
-
-**Important**: Local Git operations (commit, branch, tag, stash, etc) use `isomorphic-git` directly and do **NOT** require a `provider` parameter. The `provider` parameter is only needed for remote API operations (issues, PRs, releases, etc). Gitea as a provider is only for remote API calls, not for local Git operations.
-
-## Quick Start
-
-### Installation & Usage
-
-```bash
-# Option 1: Install globally (RECOMMENDED - faster startup)
-npm install -g @andrebuzeli/git-mcp
-git-mcp
-
-# Option 2: Run with npx (slower first run, ~2-3min for dependency download)
-npx @andrebuzeli/git-mcp@latest
-```
-
-**⚡ Performance Note**: Global installation is **10x faster** on startup (~1s vs 2-3min). `npx` needs to download and install all dependencies on first run. For production use, install globally.
-
-### Configuration
-
-Configure the git-mcp server in your MCP client's configuration file (e.g., Cursor's mcp.json, Claude Desktop's config, etc.):
-
-```json
-{
-  "mcpServers": {
-    "git-mcp": {
-      "command": "npx",
-      "args": ["@andrebuzeli/git-mcp@latest"],
-      "env": {
-        "GITHUB_USERNAME": "your-github-username",
-        "GITHUB_TOKEN": "ghp_your_github_token_here",
-        "GITEA_USERNAME": "your-gitea-username", 
-        "GITEA_TOKEN": "your_gitea_token_here",
-        "GITEA_URL": "https://your-gitea-instance.com/",
-        "DEBUG": "false"
-      }
-    }
-  }
-}
-```
-
-**The MCP client automatically passes these environment variables to the git-mcp server - no additional configuration files needed!**
-
-#### Alternative: Direct Environment Variables
-If running the server directly (not through MCP client):
-
-```bash
-export GITHUB_TOKEN="your_github_token"
-export GITHUB_USERNAME="your_username"
-export GITEA_URL="https://your-gitea-instance.com"
-export GITEA_TOKEN="your_gitea_token"
-export GITEA_USERNAME="your_username"
-```
-
-#### PowerShell (Windows)
-```powershell
-$env:GITEA_URL = 'https://your-gitea-instance.com'
-$env:GITEA_TOKEN = 'your_gitea_token'
-$env:GITEA_USERNAME = 'your_username'
-$env:GITHUB_TOKEN = 'your_github_token'
-$env:GITHUB_USERNAME = 'your_username'
-```
-
-#### Multi-Provider Support
-You can configure both GitHub and Gitea simultaneously. Use `provider="github"` or `provider="gitea"` in tool calls to specify which provider to use for remote operations.
-
-## Available Tools
-
-| Tool | Description | Operations | Safety Features |
-|------|-------------|------------|-----------------|
-| `git-workflow` | Core Git operations | init, status, commit, sync, backup, create, list, get, update, delete, fork, search | Repository deletion warnings |
-| `git-files` | **Read-only** file operations | read, list, search, backup | File modification blocked |
-| `git-branches` | Branch management | create, list, get, delete, merge, compare | Branch deletion warnings |
-| `git-issues` | Issue management | create, list, get, update, close, comment, search | - |
-| `git-pulls` | Pull request management | create, list, get, update, merge, close, review, search | - |
-| `git-tags` | Tag management | create, list, get, delete, search | - |
-| `git-release` | Release management | create, list, get, update, delete, publish, download | - |
-| `git-remote` | Remote repository management | add, remove, rename, show, set-url, prune | - |
-| `git-reset` | **⚠️ Repository reset** | soft, mixed, hard, reset-to-commit, reset-branch | **Hard reset warnings** |
-| `git-stash` | Stash management | stash, pop, apply, list, show, drop, clear | - |
-| `git-config` | Git configuration | get, set, unset, list, edit, show | - |
-| `git-monitor` | Repository monitoring | status, changes, health | - |
-| `git-backup` | Repository backup | create, restore, list, verify | - |
-| `git-archive` | Repository archiving | create, extract, list, verify | - |
-| `git-sync` | Repository synchronization | sync, status | - |
-| `git-packages` | Package management | list, get, create, update, delete, publish, download | - |
-| `git-analytics` | Repository analytics | stats, insights, reports | - |
-
-## Security Features
-
-### 🔒 File Operations Restriction
-
-The `git-files` tool is **read-only only** for security reasons:
-
-**✅ Allowed Operations:**
-- `read` - Read file content
-- `list` - List directory contents  
-- `search` - Search file content
-- `backup` - Create local backups
-
-**❌ Blocked Operations:**
-- `create` - Create new files (blocked)
-- `update` - Modify existing files (blocked)
-- `delete` - Delete files (blocked)
-
-**Why?** File content modification should be done through your local development environment, not via remote API calls.
-
-### 🚨 Safety Warnings
-
-Destructive operations include comprehensive safety warnings:
-
-#### Git Reset Warnings
-```json
-{
-  "tool": "git-reset",
-  "params": {
-    "action": "hard",
-    "projectPath": "/path/to/project"
-  }
-}
-```
-
-**Result:** Detailed warning about data loss with alternatives:
-- `git reset --soft` (keeps changes staged)
-- `git reset --mixed` (keeps changes unstaged)  
-- `git stash` (saves changes temporarily)
-
-#### Branch Deletion Warnings
-```json
-{
-  "tool": "git-branches", 
-  "params": {
-    "action": "delete",
-    "branchName": "feature-branch"
-  }
-}
-```
-
-**Result:** Warning about permanent branch deletion with suggestions:
-- Ensure branch is merged first
-- Create backup branch before deletion
-- Check for unmerged commits
-
-### 🔍 Enhanced Error Handling
-
-All tools provide detailed error messages with actionable solutions:
-
-**Example Error Response:**
-```json
-{
-  "success": false,
-  "error": {
-    "code": "BRANCH_NOT_FOUND",
-    "message": "Branch not found",
-    "suggestions": [
-      "Check if the branch name is correct",
-      "Use git branch -a to see all available branches", 
-      "Ensure the branch exists on the remote repository"
-    ]
-  }
-}
-```
-
-## Usage Examples
-
-### Local Git Operations
-
-```json
-{
-  "tool": "git-workflow",
-  "params": {
-    "action": "status",
-    "projectPath": "/path/to/project"
-  }
-}
-```
-
-```json
-{
-  "tool": "git-workflow", 
-  "params": {
-    "action": "commit",
-    "projectPath": "/path/to/project",
-    "message": "Add new feature"
-  }
-}
-```
-
-### Remote Repository Operations (GitHub Example)
-
-```json
-{
-  "tool": "git-workflow",
-  "params": {
-    "action": "create",
-    "provider": "github",
-    "name": "my-new-repo",
-    "description": "My new repository",
-    "private": true
-  }
-}
-```
-
-### Remote Repository Operations (Gitea Example)
-
-```json
-{
-  "tool": "git-issues",
-  "params": {
-    "action": "create",
-    "provider": "gitea",
-    "owner": "your-username",
-    "repo": "your-repo",
-    "title": "Bug report",
-    "body": "Description of the issue"
-  }
-}
-```
-
-### Safe File Operations (Read-Only)
-
-```json
-{
-  "tool": "git-files",
-  "params": {
-    "action": "read",
-    "projectPath": "/path/to/project",
-    "filePath": "README.md"
-  }
-}
-```
-
-### Destructive Operations (With Warnings)
-
-```json
-{
-  "tool": "git-reset",
-  "params": {
-    "action": "hard",
-    "projectPath": "/path/to/project",
-    "confirmDestructive": true
-  }
-}
-```
-
-## Error Codes Reference
-
-### Common Error Codes
-
-| Code | Description | Solution |
-|------|-------------|----------|
-| `VALIDATION_ERROR` | Parameter validation failed | Check required parameters and format |
-| `NOT_A_GIT_REPOSITORY` | Directory is not a Git repository | Use `git init` first |
-| `NOTHING_TO_COMMIT` | No changes to commit | Make changes first |
-| `MERGE_CONFLICT` | Merge conflicts detected | Resolve conflicts before proceeding |
-| `PERMISSION_DENIED` | Permission denied | Check credentials and access rights |
-| `PROVIDER_NOT_CONFIGURED` | Provider not configured | Set up GitHub or Gitea credentials |
-| `NETWORK_ERROR` | Network connectivity issue | Check internet connection |
-| `OPERATION_RESTRICTED` | File modification blocked | Use read-only operations only |
-| `SAFETY_WARNING` | Destructive operation detected | Review warning and confirm if needed |
-
-### Git-Specific Error Codes
-
-| Code | Description | Solution |
-|------|-------------|----------|
-| `BRANCH_EXISTS` | Branch already exists | Use different name or delete existing |
-| `BRANCH_NOT_FOUND` | Branch not found | Check branch name and remote config |
-| `DIRTY_WORKING_TREE` | Uncommitted changes | Commit or stash changes first |
-| `DETACHED_HEAD` | Repository in detached HEAD state | Create branch or checkout existing |
-| `REF_LOCK_ERROR` | Cannot lock Git reference | Wait for other operations to complete |
-
-## Setup Instructions
-
-1. **Configure your MCP client** with the git-mcp server and your credentials (see Configuration section above)
-
-2. **Generate GitHub Token:**
-   - Go to GitHub Settings → Developer settings → Personal access tokens
-   - Create token with `repo` scope
-   - Add to your MCP client configuration
-
-3. **Generate Gitea Token:**
-   - Go to your Gitea instance → Settings → Applications
-   - Generate new token with appropriate permissions
-   - Add to your MCP client configuration
-
-4. **Test Configuration:**
-   - Restart your MCP client
-   - Try using git-mcp tools in your IDE
-
-## Troubleshooting
-
-### Common Issues
-
-**"Provider not configured" error:**
-- Check environment variables are set correctly
-- Verify token has required permissions
-- Test API connectivity manually
-
-**"Operation restricted" error:**
-- File modification operations are blocked for security
-- Use read-only operations: `read`, `list`, `search`, `backup`
-- Make file changes through your local development environment
-
-**"Safety warning" error:**
-- Review the detailed warning message
-- Consider safer alternatives suggested
-- Use `confirmDestructive: true` only if absolutely necessary
-
-**"Network error" errors:**
-- Check internet connectivity
-- Verify provider URLs are correct
-- Check firewall/proxy settings
-
-### Getting Help
-
-1. **Check error messages** - They include specific suggestions
-2. **Review safety warnings** - They explain risks and alternatives  
-3. **Validate credentials** - Server validates on startup
-4. **Use read-only operations** - Safe file operations are always available
-
-## Development
-
-### Building from Source
-
-```bash
-git clone https://github.com/your-repo/git-mcp.git
-cd git-mcp
-npm install
-npm run build
-```
-
-### Testing
-
-```bash
-npm test
-```
-
-## License
-
-MIT License - see LICENSE file for details.
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests for new functionality
-5. Submit a pull request
-
----
-
-**⚠️ Important Security Notes:**
-
-- File content modification is intentionally restricted for security
-- Always review safety warnings before destructive operations
-- Keep your API tokens secure and rotate them regularly
-- Use `confirmDestructive: true` only when absolutely necessary
+- Tokens nunca são persistidos, somente lidos de variáveis de ambiente
+- Operações remotas usam chamadas paralelas com relatório agregado

package/bin/git-mcp.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { initMcpJson, startServer, callOnce } from '../src/server.js'
+
+const argv = process.argv.slice(2)
+const cmd = argv[0] || 'start'
+
+function getFlag(name) {
+  const idx = argv.findIndex(a => a === `--${name}`)
+  if (idx >= 0) return argv[idx + 1]
+  return undefined
+}
+
+async function main() {
+  if (cmd === 'init') { const pathArg = getFlag('path'); const force = !!getFlag('force'); await initMcpJson(pathArg, force); return }
+  if (cmd === 'start') { await startServer(); return }
+  if (cmd === 'call') { const tool = getFlag('tool'); const action = getFlag('action'); const projectPath = getFlag('projectPath'); const argsStr = getFlag('args'); const args = argsStr ? JSON.parse(argsStr) : undefined; const res = await callOnce({ tool, action, projectPath, args }); console.log(JSON.stringify(res)); return }
+  console.error('Comando inválido')
+  process.exit(1)
+}
+
+main()

package/docs/TOOLS.md

@@ -0,0 +1,110 @@
+# Tools e Actions — @andrebuzeli/git-mcp
+
+Todas as tools operam com chamadas no formato padrão via stdio:
+
+Entrada:
+```
+{ "tool": "<nome>", "action": "<acao>", "projectPath": "<caminho>", "args": { ... } }
+```
+Saída:
+```
+{ "ok": true, "res": <resultado> }
+```
+
+## Parâmetros
+- `projectPath` (string): caminho completo do projeto no IDE
+- `action` (string): ação dentro da tool
+- `args` (objeto, opcional): parâmetros da ação
+- Nome do projeto é derivado do último segmento de `projectPath` com espaços substituídos por underline
+
+## Tools
+
+### git-local
+- Ações: `status`, `init`, `add`, `commit`, `push`, `pull`, `branch`, `tag`, `clone`
+- Observações:
+  - Independente de Git instalado (usa `isomorphic-git`)
+  - `branch`: subactions `list|create|switch` via `args.subaction`
+  - `push`/`pull`: aceita `args.remote` ou `args.url` e faz fallback por Contents API
+- Exemplos:
+```
+call --tool git-local --action init --projectPath "C:\Projetos\X"
+call --tool git-local --action add --projectPath "..." --args '{"patterns":["README.md"]}'
+call --tool git-local --action commit --projectPath "..." --args '{"message":"init"}'
+call --tool git-local --action push --projectPath "..." --args '{"branch":"master"}'
+```
+
+### git-remote
+- Ações: `createRepo`, `deleteRepo`, `ensureRemotes`
+- Cria/garante repositórios/remotes em Gitea e GitHub simultaneamente
+
+### git-sync
+- Ações: `mirror`
+- Sincroniza conteúdo para ambos provedores; tenta push e, se necessário, sobe todos arquivos via Contents API
+
+### git-repos
+- Ações: `get`, `patch`, `languages`, `tags`, `topics-get`, `topics-put`, `collaborators`, `subscribers`, `subscription-get`, `subscription-put`, `subscription-delete`, `stargazers`, `forks-get`, `forks-post`, `activities`, `hooks`, `keys`
+
+### git-contents
+- Ações: `list`, `create`, `get`
+- `create`: `args.path`, `args.content` (base64), `args.message`, opcional `args.branch`
+
+### git-commits
+- Ações: `branches`, `create-branch`, `branch-protections`, `commits`, `refs`
+
+### git-issues-prs
+- Ações: `issue-create`, `issue-comment`, `issue-labels`, `labels-list`, `labels-create`, `milestones-list`, `milestones-create`, `pr-create`, `pr-get`
+- Auto-correções: cria labels/branches quando necessário
+
+### git-releases
+- Ações: `create`
+- `args`: `tag`, `title`, `body`
+
+### git-actions (GitHub)
+- Ações: `workflows`, `runs`, `artifacts`, `runners`, `secrets`
+
+### git-activity
+- Ações: `notifications-get`, `notifications-put`, `events`, `feeds`, `starring-put`, `starring-get`, `starring-delete`, `subscription-put`, `subscription-delete`
+
+### git-search
+- Ações: `repos`, `users`, `issues`, `repos-gitea`
+
+### git-gitdata (GitHub)
+- Ações: `blob-create`, `blob-get`, `tree-create`, `refs-get`
+
+### git-checks (GitHub)
+- Ações: `status`
+- `args`: `sha`, `state`, `context`
+
+### git-deployments (GitHub)
+- Ações: `create`, `status`
+- `create` detecta automaticamente `ref` (`main`/`master`)
+
+### git-misc
+- Ações: `version`, `markdown`, `markdown-raw`, `licenses`, `gitignore-templates`, `label-templates`, `emojis`, `rate_limit`, `zen`
+
+### git-gists (GitHub)
+- Ações: `create`, `get`, `star`, `delete`
+
+### git-packages (Gitea)
+- Ações: `list`
+
+### git-raw (Gitea)
+- Ações: `get`
+
+## Integração IDE
+- Configure `mcp.json` com:
+```
+{
+  "git-mcp": {
+    "command": "npx",
+    "type": "stdio",
+    "args": ["@andrebuzeli/git-mcp@latest"],
+    "env": {
+      "GITEA_URL": "",
+      "GITEA_TOKEN": "",
+      "GITHUB_TOKEN": ""
+    }
+  }
+}
+```
+- IDEs (VSCode, Cursor, Trae) podem invocar via stdio enviando o JSON de chamada descrito acima

package/mcp.json.template

@@ -0,0 +1,12 @@
+{
+  "git-mcp": {
+    "command": "npx",
+    "type": "stdio",
+    "args": ["@andrebuzeli/git-mcp@latest"],
+    "env": {
+      "GITEA_URL": "",
+      "GITEA_TOKEN": "",
+      "GITHUB_TOKEN": ""
+    }
+  }
+}