@andrebuzeli/git-mcp 6.0.1 → 6.2.0

package/dist/tools/gitBranches.d.ts

@@ -8,6 +8,7 @@ export declare class GitBranchesTool implements Tool {
         branches?: undefined;
         current?: undefined;
         deleted?: undefined;
+        currentBranch?: undefined;
         result?: undefined;
         baseBranch?: undefined;
         compareBranch?: undefined;
@@ -19,6 +20,7 @@ export declare class GitBranchesTool implements Tool {
         success?: undefined;
         branch?: undefined;
         deleted?: undefined;
+        currentBranch?: undefined;
         result?: undefined;
         baseBranch?: undefined;
         compareBranch?: undefined;
@@ -30,6 +32,7 @@ export declare class GitBranchesTool implements Tool {
         current: boolean;
         branches?: undefined;
         deleted?: undefined;
+        currentBranch?: undefined;
         result?: undefined;
         baseBranch?: undefined;
         compareBranch?: undefined;
@@ -38,6 +41,7 @@ export declare class GitBranchesTool implements Tool {
     } | {
         success: boolean;
         deleted: any;
+        currentBranch: string;
         branch?: undefined;
         branches?: undefined;
         current?: undefined;
@@ -53,6 +57,7 @@ export declare class GitBranchesTool implements Tool {
         branches?: undefined;
         current?: undefined;
         deleted?: undefined;
+        currentBranch?: undefined;
         baseBranch?: undefined;
         compareBranch?: undefined;
         commits?: undefined;
@@ -67,6 +72,7 @@ export declare class GitBranchesTool implements Tool {
         branches?: undefined;
         current?: undefined;
         deleted?: undefined;
+        currentBranch?: undefined;
         result?: undefined;
     }>;
 }

package/dist/tools/gitBranches.js

@@ -7,6 +7,7 @@ exports.GitBranchesTool = void 0;
 const simple_git_1 = __importDefault(require("simple-git"));
 const errors_1 = require("../utils/errors");
 const safetyController_1 = require("../utils/safetyController");
+const repoHelpers_1 = require("../utils/repoHelpers");
 class GitBranchesTool {
     constructor() {
         this.name = 'git-branches';
@@ -60,8 +61,17 @@ class GitBranchesTool {
                 const branchName = params.branchName;
                 if (!branchName)
                     throw new errors_1.MCPError('VALIDATION_ERROR', 'branchName is required');
+                // Safety check: prevent deleting the current active branch
+                const currentBranch = (0, repoHelpers_1.getCurrentBranch)(projectPath);
+                if (currentBranch && currentBranch === branchName) {
+                    throw new errors_1.MCPError('SAFETY_ERROR', `Cannot delete the currently active branch '${branchName}'.`, [
+                        'Switch to another branch first using git checkout',
+                        'Example: git checkout master',
+                        'Then retry the delete operation',
+                    ]);
+                }
                 await git.deleteLocalBranch(branchName, params.force);
-                return { success: true, deleted: branchName };
+                return { success: true, deleted: branchName, currentBranch };
             }
             case 'merge': {
                 const branchName = params.branchName;

package/dist/tools/gitIssues.js

@@ -43,7 +43,17 @@ class GitIssuesTool {
                         results.providers.github = { success: true, issue: result.data };
                     }
                     catch (err) {
-                        results.providers.github = { success: false, error: err.message };
+                        const mcpError = (0, errors_1.handleApiError)(err, {
+                            provider: 'github',
+                            operation: 'create issue',
+                            resource: `${githubOwner}/${repo}`,
+                        });
+                        results.providers.github = {
+                            success: false,
+                            error: mcpError.message,
+                            code: mcpError.code,
+                            suggestions: mcpError.suggestions,
+                        };
                     }
                 }
                 // Gitea
@@ -84,7 +94,17 @@ class GitIssuesTool {
                         results.providers.github = { success: true, issues: result.data };
                     }
                     catch (err) {
-                        results.providers.github = { success: false, error: err.message };
+                        const mcpError = (0, errors_1.handleApiError)(err, {
+                            provider: 'github',
+                            operation: 'list issues',
+                            resource: `${githubOwner}/${repo}`,
+                        });
+                        results.providers.github = {
+                            success: false,
+                            error: mcpError.message,
+                            code: mcpError.code,
+                            suggestions: mcpError.suggestions,
+                        };
                     }
                 }
                 // Gitea

package/dist/tools/gitSync.d.ts

@@ -6,6 +6,7 @@ export declare class GitSyncTool implements Tool {
         success: boolean;
         remote: any;
         branch: any;
+        automated: boolean;
         message: string;
         status?: undefined;
         remotes?: undefined;
@@ -20,6 +21,7 @@ export declare class GitSyncTool implements Tool {
         remotes: import("simple-git").RemoteWithRefs[];
         remote?: undefined;
         branch?: undefined;
+        automated?: undefined;
         message?: undefined;
     }>;
 }

package/dist/tools/gitSync.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.GitSyncTool = void 0;
 const simple_git_1 = __importDefault(require("simple-git"));
 const errors_1 = require("../utils/errors");
+const repoHelpers_1 = require("../utils/repoHelpers");
 class GitSyncTool {
     constructor() {
         this.name = 'git-sync';
@@ -21,13 +22,20 @@ class GitSyncTool {
         switch (action) {
             case 'sync': {
                 const remote = params.remote || 'origin';
-                const branch = params.branch;
+                // Auto-detect current branch if not provided
+                let branch = params.branch;
+                if (!branch) {
+                    branch = (0, repoHelpers_1.getCurrentBranch)(projectPath);
+                    if (!branch) {
+                        throw new errors_1.MCPError('VALIDATION_ERROR', 'Could not detect current branch. Please provide branch parameter.');
+                    }
+                }
                 if (branch) {
                     await git.checkout(branch);
                 }
                 await git.fetch(remote);
                 await git.pull(remote, branch);
-                return { success: true, remote, branch, message: 'Repository synced' };
+                return { success: true, remote, branch, automated: !params.branch, message: 'Repository synced' };
             }
             case 'status': {
                 const status = await git.status();

package/dist/tools/gitUpload.js

@@ -60,7 +60,14 @@ class GitUploadTool {
         const repoName = params.repoName || (0, repoHelpers_1.getRepoNameFromPath)(projectPath);
         const description = params.description || `Project uploaded via git-upload at ${new Date().toISOString()}`;
         const isPrivate = params.private !== undefined ? params.private : true;
-        const branch = params.branch || 'master';
+        // Auto-detect current branch if not provided
+        let branch = params.branch;
+        if (!branch) {
+            branch = (0, repoHelpers_1.getCurrentBranch)(projectPath);
+            if (!branch) {
+                branch = 'master'; // Ultimate fallback
+            }
+        }
         const git = (0, simple_git_1.default)({ baseDir: projectPath });
         // Resultado com rastreabilidade completa
         const results = {

package/dist/utils/errors.d.ts

@@ -11,3 +11,45 @@ export declare class MCPError extends Error {
     suggestions?: string[];
     constructor(code: string, message: string, suggestions?: string[]);
 }
+/**
+ * Transform GitHub/Gitea API errors into user-friendly messages
+ */
+export declare function handleApiError(error: any, context: {
+    provider: 'github' | 'gitea';
+    operation: string;
+    resource?: string;
+}): MCPError;
+/**
+ * Handle Git command errors with helpful context
+ */
+export declare function handleGitError(error: any, context: {
+    operation: string;
+    path: string;
+}): MCPError;
+/**
+ * Wrap API calls with error handling
+ */
+export declare function withApiErrorHandling<T>(fn: () => Promise<T>, context: {
+    provider: 'github' | 'gitea';
+    operation: string;
+    resource?: string;
+}): Promise<{
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: MCPError;
+}>;
+/**
+ * Wrap Git commands with error handling
+ */
+export declare function withGitErrorHandling<T>(fn: () => Promise<T>, context: {
+    operation: string;
+    path: string;
+}): Promise<{
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: MCPError;
+}>;

package/dist/utils/errors.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MCPError = void 0;
 exports.createErrorResponse = createErrorResponse;
+exports.handleApiError = handleApiError;
+exports.handleGitError = handleGitError;
+exports.withApiErrorHandling = withApiErrorHandling;
+exports.withGitErrorHandling = withGitErrorHandling;
 function createErrorResponse(code, message, suggestions) {
     return {
         success: false,
@@ -20,3 +24,199 @@ class MCPError extends Error {
     }
 }
 exports.MCPError = MCPError;
+/**
+ * Transform GitHub/Gitea API errors into user-friendly messages
+ */
+function handleApiError(error, context) {
+    const { provider, operation, resource } = context;
+    // Extract status code and message
+    const status = error.status || error.response?.status;
+    const message = error.message || error.response?.data?.message || 'Unknown error';
+    // Handle common HTTP errors with context-specific messages
+    switch (status) {
+        case 401:
+            return new MCPError('AUTHENTICATION_ERROR', `❌ Authentication failed for ${provider.toUpperCase()}`, [
+                `Check if ${provider === 'github' ? 'GITHUB_TOKEN' : 'GITEA_TOKEN'} is set correctly`,
+                'Verify token has not expired',
+                `Generate a new token at: ${provider === 'github' ? 'https://github.com/settings/tokens' : 'your Gitea instance settings'}`,
+                'Ensure token has required permissions',
+            ]);
+        case 403:
+            const rateLimitRemaining = error.response?.headers?.['x-ratelimit-remaining'];
+            if (rateLimitRemaining === '0') {
+                const resetTime = error.response?.headers?.['x-ratelimit-reset'];
+                const resetDate = resetTime ? new Date(parseInt(resetTime) * 1000).toLocaleString() : 'soon';
+                return new MCPError('RATE_LIMIT_EXCEEDED', `⏱️ ${provider.toUpperCase()} API rate limit exceeded`, [
+                    `Rate limit will reset at: ${resetDate}`,
+                    'Wait for the rate limit to reset',
+                    `Consider using a different ${provider === 'github' ? 'GitHub' : 'Gitea'} account or token`,
+                    'For GitHub: Upgrade to GitHub Pro for higher limits',
+                ]);
+            }
+            return new MCPError('PERMISSION_DENIED', `🔒 Insufficient permissions for ${operation} on ${provider.toUpperCase()}`, [
+                `Token does not have permission to ${operation}`,
+                resource ? `Verify you have access to ${resource}` : 'Verify repository access',
+                'Check if repository is private and token has appropriate scopes',
+                `Required scopes: ${getRequiredScopes(operation, provider)}`,
+            ]);
+        case 404:
+            return new MCPError('RESOURCE_NOT_FOUND', `🔍 ${resource || 'Resource'} not found on ${provider.toUpperCase()}`, [
+                resource ? `"${resource}" does not exist` : 'The requested resource does not exist',
+                'Check if the repository/issue/PR name is correct',
+                'Verify you have access to this resource',
+                provider === 'github' ? 'Check if owner (GITHUB_USERNAME) is correct' : 'Check if owner (GITEA_USERNAME) is correct',
+                'For private resources, ensure your token has access',
+            ]);
+        case 409:
+            return new MCPError('CONFLICT_ERROR', `⚠️ Conflict during ${operation} on ${provider.toUpperCase()}`, [
+                'Resource already exists or is in conflicting state',
+                operation.includes('create') ? 'Try a different name or delete the existing resource' : 'Resolve conflicts first',
+                'Check if there are merge conflicts',
+                'Pull latest changes before pushing',
+            ]);
+        case 422:
+            return new MCPError('VALIDATION_ERROR', `📋 Invalid data for ${operation} on ${provider.toUpperCase()}: ${message}`, [
+                'Check if all required fields are provided',
+                'Verify field formats (branch names, tags, etc.)',
+                'Branch names cannot contain spaces or special characters',
+                'Issue/PR titles must not be empty',
+            ]);
+        case 500:
+        case 502:
+        case 503:
+            return new MCPError('SERVER_ERROR', `🔥 ${provider.toUpperCase()} server error during ${operation}`, [
+                `${provider === 'github' ? 'GitHub' : 'Gitea'} is experiencing issues`,
+                'Check service status: ' + (provider === 'github' ? 'https://www.githubstatus.com/' : 'your Gitea instance status'),
+                'Wait a few minutes and try again',
+                'If issue persists, the problem is on the server side',
+            ]);
+        default:
+            return new MCPError('API_ERROR', `❌ ${provider.toUpperCase()} API error during ${operation}: ${message}`, [
+                `HTTP ${status || 'unknown'}: ${message}`,
+                'Check your internet connection',
+                `Verify ${provider === 'github' ? 'GITHUB_TOKEN' : 'GITEA_TOKEN'} is valid`,
+                'Check API endpoint availability',
+            ]);
+    }
+}
+/**
+ * Get required token scopes for an operation
+ */
+function getRequiredScopes(operation, provider) {
+    if (provider === 'gitea') {
+        return 'write:repository, write:issue, write:user';
+    }
+    // GitHub scopes
+    if (operation.includes('delete') || operation.includes('update')) {
+        return 'repo (full control)';
+    }
+    if (operation.includes('create')) {
+        return 'repo, user';
+    }
+    if (operation.includes('read') || operation.includes('list') || operation.includes('get')) {
+        return 'repo (or public_repo for public repos)';
+    }
+    return 'repo';
+}
+/**
+ * Handle Git command errors with helpful context
+ */
+function handleGitError(error, context) {
+    const message = error.message || String(error);
+    const { operation, path } = context;
+    // Not a git repository
+    if (message.includes('not a git repository') || message.includes('not found')) {
+        return new MCPError('NOT_A_GIT_REPOSITORY', `📁 "${path}" is not a Git repository`, [
+            'Initialize a git repository first: git init',
+            'Or provide a valid repository path',
+            'Check if .git directory exists',
+            'Verify you have permissions to access the directory',
+        ]);
+    }
+    // Authentication/permission errors
+    if (message.includes('Permission denied') || message.includes('authentication failed')) {
+        return new MCPError('GIT_AUTH_ERROR', `🔐 Git authentication failed during ${operation}`, [
+            'Check if SSH keys are configured correctly',
+            'For HTTPS: verify credentials are correct',
+            'For SSH: ensure ssh-agent is running',
+            'Test connection: git ls-remote <remote-url>',
+        ]);
+    }
+    // Remote errors
+    if (message.includes('remote') || message.includes('fetch') || message.includes('push')) {
+        if (message.includes('does not appear to be a git repository')) {
+            return new MCPError('INVALID_REMOTE', `🌐 Remote repository URL is invalid or inaccessible`, [
+                'Check if remote URL is correct',
+                'Verify repository exists on remote',
+                'For private repos: ensure authentication is configured',
+                'List remotes: git remote -v',
+            ]);
+        }
+        if (message.includes('rejected') || message.includes('non-fast-forward')) {
+            return new MCPError('PUSH_REJECTED', `⚠️ Push rejected - remote has changes you don't have`, [
+                'Pull latest changes first: git pull',
+                'Resolve any merge conflicts',
+                'Then try pushing again',
+                'Or force push (dangerous): use with caution',
+            ]);
+        }
+    }
+    // Merge conflicts
+    if (message.includes('conflict') || message.includes('CONFLICT')) {
+        return new MCPError('MERGE_CONFLICT', `⚔️ Merge conflict detected during ${operation}`, [
+            'Resolve conflicts in affected files',
+            'Stage resolved files: git add <file>',
+            'Complete merge: git commit',
+            'Or abort: git merge --abort',
+        ]);
+    }
+    // Nothing to commit
+    if (message.includes('nothing to commit') || message.includes('no changes')) {
+        return new MCPError('NOTHING_TO_COMMIT', `✅ No changes to commit - working tree is clean`, [
+            'All changes are already committed',
+            'Check status: git status',
+            'Make changes before committing',
+            'Or use --allow-empty to create empty commit',
+        ]);
+    }
+    // Branch errors
+    if (message.includes('branch') && (message.includes('not found') || message.includes('does not exist'))) {
+        return new MCPError('BRANCH_NOT_FOUND', `🌿 Branch not found during ${operation}`, [
+            'List available branches: git branch -a',
+            'Create the branch first if needed',
+            'Check for typos in branch name',
+            'Fetch from remote: git fetch',
+        ]);
+    }
+    // Generic git error
+    return new MCPError('GIT_ERROR', `❌ Git error during ${operation}: ${message}`, [
+        'Check git command output for details',
+        'Verify repository state is clean',
+        'Try: git status',
+        'For more info: git --help',
+    ]);
+}
+/**
+ * Wrap API calls with error handling
+ */
+async function withApiErrorHandling(fn, context) {
+    try {
+        const data = await fn();
+        return { success: true, data };
+    }
+    catch (error) {
+        return { success: false, error: handleApiError(error, context) };
+    }
+}
+/**
+ * Wrap Git commands with error handling
+ */
+async function withGitErrorHandling(fn, context) {
+    try {
+        const data = await fn();
+        return { success: true, data };
+    }
+    catch (error) {
+        return { success: false, error: handleGitError(error, context) };
+    }
+}

package/dist/utils/repoHelpers.d.ts

@@ -6,6 +6,16 @@
  * Normalizes: spaces to hyphens, lowercase, keeps alphanumeric and hyphens/underscores
  */
 export declare function getRepoNameFromPath(projectPath: string): string;
+/**
+ * Get current Git branch from project path
+ * Returns empty string if not in a Git repository
+ */
+export declare function getCurrentBranch(projectPath: string): string;
+/**
+ * Get default branch from Git repository (usually 'main' or 'master')
+ * Falls back to 'master' if unable to determine
+ */
+export declare function getDefaultBranch(projectPath: string): string;
 /**
  * Get GitHub owner from environment
  */

package/dist/utils/repoHelpers.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getRepoNameFromPath = getRepoNameFromPath;
+exports.getCurrentBranch = getCurrentBranch;
+exports.getDefaultBranch = getDefaultBranch;
 exports.getGitHubOwner = getGitHubOwner;
 exports.getGiteaOwner = getGiteaOwner;
 exports.getGiteaUrl = getGiteaUrl;
@@ -11,6 +13,7 @@ exports.buildGitHubUrl = buildGitHubUrl;
 exports.buildGiteaUrl = buildGiteaUrl;
 exports.getRepoInfo = getRepoInfo;
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
 /**
  * Helper functions to extract repository information automatically
  */
@@ -24,6 +27,55 @@ function getRepoNameFromPath(projectPath) {
         .replace(/\s+/g, '-')
         .replace(/[^a-z0-9-_]/g, '');
 }
+/**
+ * Get current Git branch from project path
+ * Returns empty string if not in a Git repository
+ */
+function getCurrentBranch(projectPath) {
+    try {
+        const branchName = (0, child_process_1.execSync)('git rev-parse --abbrev-ref HEAD', {
+            cwd: projectPath,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'], // Suppress stderr
+        });
+        return branchName.trim();
+    }
+    catch (error) {
+        return '';
+    }
+}
+/**
+ * Get default branch from Git repository (usually 'main' or 'master')
+ * Falls back to 'master' if unable to determine
+ */
+function getDefaultBranch(projectPath) {
+    try {
+        // Try to get default branch from remote
+        const defaultBranch = (0, child_process_1.execSync)('git symbolic-ref refs/remotes/origin/HEAD', {
+            cwd: projectPath,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        });
+        return defaultBranch.trim().replace('refs/remotes/origin/', '');
+    }
+    catch (error) {
+        // If that fails, try to detect main or master
+        try {
+            const branches = (0, child_process_1.execSync)('git branch -r', {
+                cwd: projectPath,
+                encoding: 'utf8',
+                stdio: ['pipe', 'pipe', 'ignore'],
+            });
+            if (branches.includes('origin/main'))
+                return 'main';
+            if (branches.includes('origin/master'))
+                return 'master';
+        }
+        catch { }
+        // Ultimate fallback
+        return 'master';
+    }
+}
 /**
  * Get GitHub owner from environment
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@andrebuzeli/git-mcp",
-  "version": "6.0.1",
-  "description": "Professional MCP server for Git operations - FULLY AUTONOMOUS: each provider uses own username from env, repo name auto-normalized from projectPath (spaces→hyphens, lowercase, keeps underscores), zero redundant parameters, automatic dual-provider execution (GitHub + Gitea)",
+  "version": "6.2.0",
+  "description": "Professional MCP server for Git operations - FULLY AUTONOMOUS with INTELLIGENT ERROR HANDLING: auto-detects branches, owner, repo. User-friendly error messages with actionable suggestions. Zero cryptic codes. Dual-provider execution (GitHub + Gitea)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {