@andrebuzeli/git-mcp 10.0.2 → 10.0.4

package/README.md

@@ -102,26 +102,47 @@ npx @andrebuzeli/git-mcp@latest
 
 ### Configuration
 
-Set up your provider credentials via environment variables:
+Configure the git-mcp server in your MCP client's configuration file (e.g., Cursor's mcp.json, Claude Desktop's config, etc.):
 
-#### GitHub Configuration
-```bash
-export GITHUB_TOKEN="your_github_token"
-export GITHUB_USERNAME="your_username"
+```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"
+      }
+    }
+  }
+}
 ```
 
-#### Gitea Configuration
+**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) example - session only:
+#### 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
@@ -332,63 +353,23 @@ All tools provide detailed error messages with actionable solutions:
 | `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 |
 
-## Configuration Guide
-
-### Environment Variables
-
-**Required for GitHub:**
-- `GITHUB_TOKEN` - Personal access token with repo permissions
-- `GITHUB_USERNAME` - Your GitHub username
+## Setup Instructions
 
-**Required for Gitea:**
-- `GITEA_URL` - Your Gitea instance URL (e.g., `https://git.example.com`)
-- `GITEA_TOKEN` - Personal access token
-- `GITEA_USERNAME` - Your Gitea username
+1. **Configure your MCP client** with the git-mcp server and your credentials (see Configuration section above)
 
-### Credential Validation
-
-The server automatically validates credentials on startup:
-
-- ✅ **Valid credentials** - API connectivity confirmed
-- ❌ **Invalid token** - Authentication failed
-- 🌐 **Network error** - Cannot reach provider API
-- ⚠️ **Partial failure** - Some providers failed validation
-
-### Setup Instructions
-
-1. **Generate GitHub Token:**
+2. **Generate GitHub Token:**
    - Go to GitHub Settings → Developer settings → Personal access tokens
    - Create token with `repo` scope
-   - Copy token to `GITHUB_TOKEN` environment variable
+   - Add to your MCP client configuration
 
-2. **Generate Gitea Token:**
+3. **Generate Gitea Token:**
    - Go to your Gitea instance → Settings → Applications
    - Generate new token with appropriate permissions
-   - Copy token to `GITEA_TOKEN` environment variable
-
-3. **Test Configuration:**
-   ```bash
-   # Start the server to see validation results
-   npx @andrebuzeli/git-mcp@latest
-   ```
-
-Optional: use a local `mcp.json` (NOT committed) to keep credentials for local testing.
-
-1. Create `mcp.json` next to package.json with this shape (use the `.example` as a starting point):
-
-```json
-{
-  "env": {
-    "GITEA_URL": "http://nas-ubuntu:3000",
-    "GITEA_TOKEN": "<GITEA_TOKEN>",
-    "GITEA_USERNAME": "<GITEA_USERNAME>",
-    "GITHUB_TOKEN": "<GITHUB_TOKEN>",
-    "GITHUB_USERNAME": "<GITHUB_USERNAME>"
-  }
-}
-```
+   - Add to your MCP client configuration
 
-Security note: do NOT commit `mcp.json` with real tokens. The repository's `.gitignore` includes `mcp.json` to help avoid leaks.
+4. **Test Configuration:**
+   - Restart your MCP client
+   - Try using git-mcp tools in your IDE
 
 ## Troubleshooting
 

package/dist/index.js

@@ -3,7 +3,6 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { ProviderManager } from './providers/providerManager.js';
-import { loadMCPConfig } from './config.js';
 import { IsomorphicGitAdapter } from './utils/gitAdapter.js';
 import { GitFilesTool } from './tools/gitFiles.js';
 import { GitWorkflowTool } from './tools/gitWorkflow.js';
@@ -30,8 +29,6 @@ import { GitIgnoreTool } from './tools/gitIgnore.js';
 import { GIT_PROMPTS } from './prompts/gitPrompts.js';
 import TOOLS_GUIDE from './resources/toolsGuide.js';
 async function main() {
-    // Load optional mcp.json configuration (will populate process.env if values present)
-    loadMCPConfig();
     const providerManager = new ProviderManager();
     const gitAdapter = new IsomorphicGitAdapter(providerManager);
     // Skip validation on startup to prevent hanging (validation happens on first use)
@@ -82,7 +79,7 @@ async function main() {
             tools: tools.map(tool => ({
                 name: tool.name,
                 description: tool.description,
-                inputSchema: {
+                inputSchema: tool.inputSchema || {
                     type: 'object',
                     properties: {},
                     additionalProperties: true,

package/dist/tools/gitAnalytics.d.ts

@@ -8,6 +8,7 @@ export declare class GitAnalyticsTool implements Tool {
             projectPath: {
                 type: string;
                 description: string;
+                examples: string[];
             };
             action: {
                 type: string;

package/dist/tools/gitAnalytics.js

@@ -10,24 +10,25 @@ export class GitAnalyticsTool {
             properties: {
                 projectPath: {
                     type: "string",
-                    description: "Absolute path to the project/repository (REQUIRED)"
+                    description: "The absolute path to the Git repository directory on the local filesystem. This should be the root directory containing the .git folder. For example: '/home/user/my-project' on Linux/Mac or 'C:\\Users\\user\\my-project' on Windows.",
+                    examples: ["/home/user/my-repo", "C:\\Users\\user\\my-repo"]
                 },
                 action: {
                     type: "string",
                     enum: ["stats", "commits", "contributors"],
-                    description: "Action to perform: stats (get repo statistics), commits (get commit history), contributors (get contributor stats)"
+                    description: "The analytics operation to perform: 'stats' for repository statistics, 'commits' for commit history analysis, 'contributors' for contributor statistics."
                 },
                 limit: {
                     type: "number",
-                    description: "Maximum number of commits to return (optional for commits action, default: 100)"
+                    description: "Maximum number of commits to return (optional, default: 100, only used for 'commits' action)"
                 },
                 since: {
                     type: "string",
-                    description: "Start date for commits/contributors query (ISO 8601 format, optional)"
+                    description: "Start date for filtering commits/contributors in ISO 8601 format (optional, e.g., '2023-01-01T00:00:00Z')"
                 },
                 until: {
                     type: "string",
-                    description: "End date for commits/contributors query (ISO 8601 format, optional)"
+                    description: "End date for filtering commits/contributors in ISO 8601 format (optional, e.g., '2024-01-01T00:00:00Z')"
                 }
             },
             required: ["projectPath", "action"],

package/dist/tools/gitArchive.d.ts

@@ -14,10 +14,6 @@ export declare class GitArchiveTool implements Tool {
                 enum: string[];
                 description: string;
             };
-            archiveName: {
-                type: string;
-                description: string;
-            };
             outputPath: {
                 type: string;
                 description: string;
@@ -31,10 +27,6 @@ export declare class GitArchiveTool implements Tool {
                 type: string;
                 description: string;
             };
-            archivePath: {
-                type: string;
-                description: string;
-            };
         };
         required: string[];
         additionalProperties: boolean;

package/dist/tools/gitArchive.js

@@ -10,20 +10,16 @@ export class GitArchiveTool {
             properties: {
                 projectPath: {
                     type: "string",
-                    description: "Absolute path to the project/repository (REQUIRED)"
+                    description: "The absolute path to the Git repository directory on the local filesystem. This should be the root directory containing the .git folder. For example: '/home/user/my-project' on Linux/Mac or 'C:\\Users\\user\\my-project' on Windows."
                 },
                 action: {
                     type: "string",
-                    enum: ["create", "list", "verify", "extract"],
-                    description: "Action to perform: create (create archive), list (list archives), verify (verify archive), extract (extract archive)"
-                },
-                archiveName: {
-                    type: "string",
-                    description: "Name for the archive file (optional for create, default: timestamp-based)"
+                    enum: ["create", "extract"],
+                    description: "Archive operation to perform: create (create archive), extract (extract archive)"
                 },
                 outputPath: {
                     type: "string",
-                    description: "Output directory for archives (optional for create, default: .git-archives)"
+                    description: "Output archive file path (required for create)"
                 },
                 format: {
                     type: "string",
@@ -33,10 +29,6 @@ export class GitArchiveTool {
                 ref: {
                     type: "string",
                     description: "Git reference to archive (optional for create, default: HEAD)"
-                },
-                archivePath: {
-                    type: "string",
-                    description: "Path to archive file (required for verify/extract)"
                 }
             },
             required: ["projectPath", "action"],

package/dist/tools/gitBackup.js

@@ -11,28 +11,28 @@ export class GitBackupTool {
             properties: {
                 projectPath: {
                     type: "string",
-                    description: "Absolute path to the project/repository (REQUIRED)"
+                    description: "The absolute path to the Git repository directory on the local filesystem. This should be the root directory containing the .git folder. For example: '/home/user/my-project' on Linux/Mac or 'C:\\Users\\user\\my-project' on Windows."
                 },
                 action: {
                     type: "string",
-                    enum: ["backup", "list", "verify", "restore"],
-                    description: "Action to perform: backup (create backup), list (list backups), verify (verify backup), restore (restore from backup)"
+                    enum: ["create", "restore", "list", "delete"],
+                    description: "Backup operation to perform: create (create backup), restore (restore from backup), list (list backups), delete (delete backup)"
                 },
                 backupPath: {
                     type: "string",
-                    description: "Path to backup file (required for restore/verify)"
+                    description: "Path to backup file (required for create/restore/delete)"
                 },
                 compress: {
                     type: "boolean",
-                    description: "Compress backup (optional for backup, default: true)"
+                    description: "Compress backup (optional for create, default: true)"
                 },
                 confirm: {
                     type: "boolean",
-                    description: "Confirm destructive operations (optional for restore)"
+                    description: "Confirm destructive operations (optional for restore/delete)"
                 },
                 name: {
                     type: "string",
-                    description: "Backup name (optional for backup)"
+                    description: "Backup name (optional for create)"
                 }
             },
             required: ["projectPath", "action"],

package/dist/tools/gitFix.js

@@ -2,6 +2,7 @@ import simpleGit from 'simple-git';
 import path from 'path';
 import fs from 'fs/promises';
 import { existsSync } from 'fs';
+import { buildGitHubUrl, buildGiteaUrl } from '../utils/repoHelpers.js';
 export async function handleGitFix(args) {
     try {
         const { projectPath, githubRepo, giteaRepo, autoDetect = true } = args;
@@ -106,16 +107,15 @@ export async function handleGitFix(args) {
             }
         }
         // Adicionar novos remotes no padrão dual
-        const giteaUrl = process.env.GITEA_URL || 'http://nas-ubuntu:9999';
-        const githubUrl = `https://github.com/${finalGithubRepo}.git`;
-        const giteaRepoUrl = `${giteaUrl}/${finalGiteaRepo}.git`;
+        const githubUrl = buildGitHubUrl(finalGithubRepo.split('/')[0], finalGithubRepo.split('/')[1]);
+        const giteaUrlFull = buildGiteaUrl(finalGiteaRepo.split('/')[0], finalGiteaRepo.split('/')[1]);
         await git.addRemote('github', githubUrl);
-        result.fixed.push(`✅ Adicionado remote GitHub: ${githubUrl}`);
-        await git.addRemote('gitea', giteaRepoUrl);
-        result.fixed.push(`✅ Adicionado remote Gitea: ${giteaRepoUrl}`);
+        result.fixed.push(`✅ Adicionado remote GitHub: ${githubUrl.replace(/oauth2:[^@]+@/, 'oauth2:***@')}`);
+        await git.addRemote('gitea', giteaUrlFull);
+        result.fixed.push(`✅ Adicionado remote Gitea: ${giteaUrlFull.replace(/:[^:]+@/, ':***@')}`);
         // Configurar origin como push múltiplo
         await git.addRemote('origin', githubUrl);
-        await git.addConfig('remote.origin.pushurl', giteaRepoUrl, false, 'local');
+        await git.addConfig('remote.origin.pushurl', giteaUrlFull, false, 'local');
         result.fixed.push(`✅ Configurado origin para push dual (GitHub + Gitea)`);
         // Capturar remotes depois
         const remotesAfter = await git.getRemotes(true);

package/dist/tools/gitFix.tool.js

@@ -67,19 +67,19 @@ export class GitFixTool {
             properties: {
                 projectPath: {
                     type: "string",
-                    description: "Absolute path to the Git repository (REQUIRED)"
+                    description: "The absolute path to the Git repository directory on the local filesystem. This should be the root directory containing the .git folder. For example: '/home/user/my-project' on Linux/Mac or 'C:\\Users\\user\\my-project' on Windows."
                 },
                 githubRepo: {
                     type: "string",
-                    description: "GitHub repo in format 'owner/repo' (optional, auto-detected)"
+                    description: "GitHub repo in format \"owner/repo\" (auto-detected if not provided)"
                 },
                 giteaRepo: {
                     type: "string",
-                    description: "Gitea repo in format 'owner/repo' (optional, auto-detected)"
+                    description: "Gitea repo in format \"owner/repo\" (auto-detected if not provided)"
                 },
                 autoDetect: {
                     type: "boolean",
-                    description: "Auto-detect repos from existing remotes (optional, default: true)"
+                    description: "Auto-detect repos from existing remotes (default: true)"
                 }
             },
             required: ["projectPath"],

package/dist/tools/gitHistory.d.ts

@@ -10,36 +10,13 @@ export declare class GitHistoryTool implements Tool {
     inputSchema: {
         type: "object";
         properties: {
-            action: {
-                type: string;
-                enum: string[];
-                description: string;
-            };
             projectPath: {
                 type: string;
                 description: string;
             };
-            description: {
-                type: string;
-                description: string;
-            };
-            message: {
-                type: string;
-                description: string;
-            };
-            title: {
-                type: string;
-                description: string;
-            };
-            tags: {
-                type: string;
-                items: {
-                    type: string;
-                };
-                description: string;
-            };
-            category: {
+            action: {
                 type: string;
+                enum: string[];
                 description: string;
             };
             owner: {

package/dist/tools/gitHistory.js

@@ -16,35 +16,14 @@ export class GitHistoryTool {
         this.inputSchema = {
             type: "object",
             properties: {
-                action: {
-                    type: "string",
-                    enum: ["track", "list", "sync", "report"],
-                    description: "History operation to perform"
-                },
                 projectPath: {
                     type: "string",
-                    description: "Absolute path to the Git repository"
+                    description: "The absolute path to the Git repository directory on the local filesystem. This should be the root directory containing the .git folder. For example: '/home/user/my-project' on Linux/Mac or 'C:\\Users\\user\\my-project' on Windows."
                 },
-                description: {
-                    type: "string",
-                    description: "Description of the change being tracked - optional for track action"
-                },
-                message: {
-                    type: "string",
-                    description: "Alternative name for description - optional for track action"
-                },
-                title: {
-                    type: "string",
-                    description: "Custom title for the history issue - optional for track action"
-                },
-                tags: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Tags to categorize the change - optional for track action"
-                },
-                category: {
+                action: {
                     type: "string",
-                    description: "Category of the change (e.g., 'feature', 'bugfix', 'refactor') - optional for track action, default: 'general'"
+                    enum: ["track", "list", "sync", "report"],
+                    description: "History operation to perform: track (track changes), list (list history), sync (sync to remote), report (generate report)"
                 },
                 owner: {
                     type: "string",

package/dist/tools/gitIgnore.d.ts

@@ -9,17 +9,13 @@ export declare class GitIgnoreTool implements Tool {
     inputSchema: {
         type: "object";
         properties: {
-            action: {
-                type: string;
-                enum: string[];
-                description: string;
-            };
             projectPath: {
                 type: string;
                 description: string;
             };
-            template: {
+            action: {
                 type: string;
+                enum: string[];
                 description: string;
             };
             patterns: {
@@ -29,14 +25,6 @@ export declare class GitIgnoreTool implements Tool {
                 };
                 description: string;
             };
-            comment: {
-                type: string;
-                description: string;
-            };
-            content: {
-                type: string;
-                description: string;
-            };
         };
         required: string[];
         additionalProperties: boolean;

package/dist/tools/gitIgnore.js

@@ -12,31 +12,19 @@ export class GitIgnoreTool {
         this.inputSchema = {
             type: "object",
             properties: {
-                action: {
-                    type: "string",
-                    enum: ["read", "create", "ensure", "add", "remove", "update", "clear"],
-                    description: "Git ignore operation to perform"
-                },
                 projectPath: {
                     type: "string",
-                    description: "Absolute path to the Git repository"
+                    description: "The absolute path to the Git repository directory on the local filesystem. This should be the root directory containing the .git folder. For example: '/home/user/my-project' on Linux/Mac or 'C:\\Users\\user\\my-project' on Windows."
                 },
-                template: {
+                action: {
                     type: "string",
-                    description: "Template to use for creating .gitignore (e.g., 'default', 'node', 'python') - optional for create, ensure, clear"
+                    enum: ["create", "add", "remove", "read"],
+                    description: "Action: create, add, remove, read"
                 },
                 patterns: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Array of file patterns to add or remove - required for add and remove actions"
-                },
-                comment: {
-                    type: "string",
-                    description: "Comment to add before patterns - optional for add action"
-                },
-                content: {
-                    type: "string",
-                    description: "Complete .gitignore content to write - required for update action"
+                    description: "Patterns to add/remove"
                 }
             },
             required: ["projectPath", "action"],

package/dist/tools/gitIssues.d.ts

@@ -14,10 +14,6 @@ export declare class GitIssuesTool implements Tool {
                 enum: string[];
                 description: string;
             };
-            repo: {
-                type: string;
-                description: string;
-            };
             title: {
                 type: string;
                 description: string;

package/dist/tools/gitIssues.js

@@ -9,20 +9,16 @@ export class GitIssuesTool {
             properties: {
                 projectPath: {
                     type: "string",
-                    description: "Absolute path to the project/repository (optional, used to auto-detect repo name)"
+                    description: "The absolute path to the Git repository directory on the local filesystem. This should be the root directory containing the .git folder. For example: '/home/user/my-project' on Linux/Mac or 'C:\\Users\\user\\my-project' on Windows."
                 },
                 action: {
                     type: "string",
                     enum: ["create", "list", "get", "update", "close", "comment", "search"],
-                    description: "Action to perform: create (create issue), list (list issues), get (get issue), update (update issue), close (close issue), comment (add comment), search (search issues)"
-                },
-                repo: {
-                    type: "string",
-                    description: "Repository name (required if projectPath not provided)"
+                    description: "Issue operation to perform: create (create issue), list (list issues), get (get issue details), update (update issue), close (close issue), comment (add comment), search (search issues)"
                 },
                 title: {
                     type: "string",
-                    description: "Issue title (required for create)"
+                    description: "Issue title (required for create action)"
                 },
                 body: {
                     type: "string",
@@ -49,7 +45,7 @@ export class GitIssuesTool {
                 state: {
                     type: "string",
                     enum: ["open", "closed"],
-                    description: "Issue state (optional for update)"
+                    description: "Issue state: open, closed (optional for update)"
                 },
                 state_filter: {
                     type: "string",
@@ -75,24 +71,22 @@ export class GitIssuesTool {
                     description: "Search query (required for search action)"
                 }
             },
-            required: ["action"],
+            required: ["projectPath", "action"],
             additionalProperties: true
         };
     }
     async handle(params, ctx) {
         params = normalizeToolParams(params);
         const action = params.action;
+        const projectPath = params.projectPath;
         if (!action)
             throw new MCPError('VALIDATION_ERROR', 'action is required');
-        // Auto-extract repo info if projectPath is provided
-        let repo = params.repo;
-        if (!repo && params.projectPath) {
-            const repoInfo = getRepoInfo(params.projectPath);
-            repo = repoInfo.repoName;
-        }
-        // Each provider uses its own username from env
-        const githubOwner = process.env.GITHUB_USERNAME;
-        const giteaOwner = process.env.GITEA_USERNAME;
+        if (!projectPath)
+            throw new MCPError('VALIDATION_ERROR', 'projectPath is required');
+        const repoInfo = getRepoInfo(projectPath);
+        const repo = repoInfo.repoName;
+        const githubOwner = repoInfo.githubOwner || process.env.GITHUB_USERNAME;
+        const giteaOwner = repoInfo.giteaOwner || process.env.GITEA_USERNAME;
         switch (action) {
             case 'create': {
                 if (!params.title)

package/dist/tools/gitMonitor.js

@@ -11,7 +11,7 @@ export class GitMonitorTool {
             properties: {
                 projectPath: {
                     type: "string",
-                    description: "Absolute path to the project/repository (REQUIRED)"
+                    description: "The absolute path to the Git repository directory on the local filesystem. This should be the root directory containing the .git folder. For example: '/home/user/my-project' on Linux/Mac or 'C:\\Users\\user\\my-project' on Windows."
                 },
                 action: {
                     type: "string",

package/dist/tools/gitPackages.d.ts

@@ -2,6 +2,34 @@ import { Tool, MCPContext } from '../types.js';
 export declare class GitPackagesTool implements Tool {
     name: string;
     description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectPath: {
+                type: string;
+                description: string;
+            };
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
+            packageName: {
+                type: string;
+                description: string;
+            };
+            packageType: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
     handle(params: Record<string, any>, ctx: MCPContext): Promise<{
         success: boolean;
         name: any;