@andrebuzeli/git-mcp 10.0.3 → 10.0.5

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,7 @@ 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 { MCPError } from './utils/errors.js';
 import { IsomorphicGitAdapter } from './utils/gitAdapter.js';
 import { GitFilesTool } from './tools/gitFiles.js';
 import { GitWorkflowTool } from './tools/gitWorkflow.js';
@@ -29,11 +29,11 @@ import { GitFixTool } from './tools/gitFix.tool.js';
 import { GitIgnoreTool } from './tools/gitIgnore.js';
 import { GIT_PROMPTS } from './prompts/gitPrompts.js';
 import TOOLS_GUIDE from './resources/toolsGuide.js';
+import { Logger, logToolExecution, logSecurityEvent, logPerformanceMetric } from './utils/logger.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);
+    const logger = Logger.getInstance();
     // Skip validation on startup to prevent hanging (validation happens on first use)
     // Provider validation moved to lazy initialization
     // Register all 22 Git tools
@@ -67,17 +67,18 @@ async function main() {
     ];
     // Silent mode for MCP clients - only log to stderr in debug mode
     if (process.env.DEBUG) {
-        console.error(`Registered ${tools.length} Git tools`);
-        console.error(`Registered ${resources.length} resource(s)`);
-        console.error(`Registered ${GIT_PROMPTS.length} prompt(s)`);
+        logger.info(`Registered ${tools.length} Git tools`);
+        logger.info(`Registered ${resources.length} resource(s)`);
+        logger.info(`Registered ${GIT_PROMPTS.length} prompt(s)`);
     }
     // Create MCP Server with STDIO transport
     const server = new Server({
         name: '@andrebuzeli/git-mcp',
-        version: '10.0.1',
+        version: '10.0.4',
     });
     // Register tool list handler
     server.setRequestHandler(ListToolsRequestSchema, async () => {
+        logger.debug('Listing available tools');
         return {
             tools: tools.map(tool => ({
                 name: tool.name,
@@ -90,15 +91,42 @@ async function main() {
             })),
         };
     });
-    // Register tool execution handler
+    // Register tool execution handler with logging e segurança aprimorados
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const toolName = request.params.name;
         const tool = tools.find(t => t.name === toolName);
+        const startTime = Date.now();
         if (!tool) {
+            logSecurityEvent('TOOL_NOT_FOUND', { toolName });
             throw new Error(`Tool not found: ${toolName}`);
         }
         try {
-            const result = await tool.handle(request.params.arguments ?? {}, { providerManager, gitAdapter });
+            // Validar argumentos contra o schema da ferramenta
+            const args = request.params.arguments ?? {};
+            // Validação básica de segurança
+            if (typeof args !== 'object' || args === null) {
+                logSecurityEvent('INVALID_ARGUMENTS', { toolName, args });
+                throw new MCPError('VALIDATION_ERROR', 'Arguments must be an object');
+            }
+            // Validar projectPath se existir
+            if ('projectPath' in args) {
+                const projectPath = args.projectPath;
+                if (typeof projectPath !== 'string') {
+                    logSecurityEvent('INVALID_PROJECT_PATH_TYPE', { toolName, projectPath });
+                    throw new MCPError('VALIDATION_ERROR', 'projectPath must be a string');
+                }
+                if (!projectPath || projectPath.includes('..')) {
+                    logSecurityEvent('PATH_TRAVERSION_ATTEMPT', { toolName, projectPath });
+                    throw new MCPError('VALIDATION_ERROR', 'Invalid project path');
+                }
+            }
+            // Log da execução
+            logger.info(`Executing tool: ${toolName}`, { args }, toolName);
+            // Executar a ferramenta
+            const result = await tool.handle(args, { providerManager, gitAdapter });
+            const duration = Date.now() - startTime;
+            logPerformanceMetric(`tool_${toolName}`, duration, { success: true });
+            logToolExecution(toolName, args, result);
             return {
                 content: [
                     {
@@ -109,6 +137,9 @@ async function main() {
             };
         }
         catch (error) {
+            const duration = Date.now() - startTime;
+            logPerformanceMetric(`tool_${toolName}`, duration, { success: false, error: error.message });
+            logToolExecution(toolName, request.params.arguments ?? {}, undefined, error);
             return {
                 content: [
                     {
@@ -122,6 +153,7 @@ async function main() {
     });
     // Register resource list handler
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        logger.debug('Listing available resources');
         return {
             resources: resources.map(resource => ({
                 uri: resource.uri,
@@ -136,8 +168,10 @@ async function main() {
         const uri = request.params.uri;
         const resource = resources.find(r => r.uri === uri);
         if (!resource) {
+            logger.warn(`Resource not found: ${uri}`);
             throw new Error(`Resource not found: ${uri}`);
         }
+        logger.debug(`Reading resource: ${uri}`);
         return {
             contents: [
                 {
@@ -150,6 +184,7 @@ async function main() {
     });
     // Register prompt list handler
     server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        logger.debug('Listing available prompts');
         return {
             prompts: GIT_PROMPTS.map(prompt => ({
                 name: prompt.name,
@@ -163,8 +198,10 @@ async function main() {
         const promptName = request.params.name;
         const prompt = GIT_PROMPTS.find(p => p.name === promptName);
         if (!prompt) {
+            logger.warn(`Prompt not found: ${promptName}`);
             throw new Error(`Prompt not found: ${promptName}`);
         }
+        logger.debug(`Generating prompt: ${promptName}`);
         const result = await prompt.generate(request.params.arguments ?? {}, { providerManager, gitAdapter });
         return {
             description: result.description,
@@ -175,10 +212,10 @@ async function main() {
     await server.connect(transport);
     // Only log in debug mode
     if (process.env.DEBUG) {
-        console.error(`✅ git-mcp MCP server running via STDIO`);
-        console.error(`Tools: ${tools.length} registered`);
-        console.error(`Resources: ${resources.length} registered`);
-        console.error(`Prompts: ${GIT_PROMPTS.length} registered`);
+        logger.info(`✅ git-mcp MCP server running via STDIO`);
+        logger.info(`Tools: ${tools.length} registered`);
+        logger.info(`Resources: ${resources.length} registered`);
+        logger.info(`Prompts: ${GIT_PROMPTS.length} registered`);
     }
 }
 main().catch(err => {

package/dist/server-new.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server-new.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+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 { MCPError } from './utils/errors.js';
+import { IsomorphicGitAdapter } from './utils/gitAdapter.js';
+import { GitFilesTool } from './tools/gitFiles.js';
+import { GitWorkflowTool } from './tools/gitWorkflow.js';
+import { GitBranchesTool } from './tools/gitBranches.js';
+import { GitIssuesTool } from './tools/gitIssues.js';
+import { GitPullsTool } from './tools/gitPulls.js';
+import { GitTagsTool } from './tools/gitTags.js';
+import { GitReleaseTool } from './tools/gitRelease.js';
+import { GitRemoteTool } from './tools/gitRemote.js';
+import { GitResetTool } from './tools/gitReset.js';
+import { GitStashTool } from './tools/gitStash.js';
+import { GitConfigTool } from './tools/gitConfig.js';
+import { GitMonitorTool } from './tools/gitMonitor.js';
+import { GitBackupTool } from './tools/gitBackup.js';
+import { GitArchiveTool } from './tools/gitArchive.js';
+import { GitSyncTool } from './tools/gitSync.js';
+import { GitPackagesTool } from './tools/gitPackages.js';
+import { GitAnalyticsTool } from './tools/gitAnalytics.js';
+import { GitUploadTool } from './tools/gitUpload.js';
+import { GitUpdateTool } from './tools/gitUpdate.js';
+import { GitHistoryTool } from './tools/gitHistory.js';
+import { GitFixTool } from './tools/gitFix.tool.js';
+import { GitIgnoreTool } from './tools/gitIgnore.js';
+import { GIT_PROMPTS } from './prompts/gitPrompts.js';
+import TOOLS_GUIDE from './resources/toolsGuide.js';
+import { Logger, logToolExecution, logSecurityEvent, logPerformanceMetric } from './utils/logger.js';
+async function main() {
+    const providerManager = new ProviderManager();
+    const gitAdapter = new IsomorphicGitAdapter(providerManager);
+    const logger = Logger.getInstance();
+    // Skip validation on startup to prevent hanging (validation happens on first use)
+    // Provider validation moved to lazy initialization
+    // Register all 22 Git tools
+    const tools = [
+        new GitWorkflowTool(),
+        new GitFilesTool(),
+        new GitBranchesTool(),
+        new GitIssuesTool(),
+        new GitPullsTool(),
+        new GitTagsTool(),
+        new GitReleaseTool(),
+        new GitRemoteTool(),
+        new GitResetTool(),
+        new GitStashTool(),
+        new GitConfigTool(),
+        new GitMonitorTool(),
+        new GitBackupTool(),
+        new GitArchiveTool(),
+        new GitSyncTool(),
+        new GitPackagesTool(),
+        new GitAnalyticsTool(),
+        new GitUploadTool(),
+        new GitUpdateTool(),
+        new GitHistoryTool(),
+        new GitFixTool(),
+        new GitIgnoreTool(),
+    ];
+    // Register resources
+    const resources = [
+        TOOLS_GUIDE
+    ];
+    // Silent mode for MCP clients - only log to stderr in debug mode
+    if (process.env.DEBUG) {
+        logger.info(`Registered ${tools.length} Git tools`);
+        logger.info(`Registered ${resources.length} resource(s)`);
+        logger.info(`Registered ${GIT_PROMPTS.length} prompt(s)`);
+    }
+    // Create MCP Server with STDIO transport
+    const server = new Server({
+        name: '@andrebuzeli/git-mcp',
+        version: '10.0.4',
+    });
+    // Register tool list handler
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        logger.debug('Listing available tools');
+        return {
+            tools: tools.map(tool => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema || {
+                    type: 'object',
+                    properties: {},
+                    additionalProperties: true,
+                },
+            })),
+        };
+    });
+    // Register tool execution handler with logging e segurança aprimorados
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const toolName = request.params.name;
+        const tool = tools.find(t => t.name === toolName);
+        const startTime = Date.now();
+        if (!tool) {
+            logSecurityEvent('TOOL_NOT_FOUND', { toolName });
+            throw new Error(`Tool not found: ${toolName}`);
+        }
+        try {
+            // Validar argumentos contra o schema da ferramenta
+            const args = request.params.arguments ?? {};
+            // Validação básica de segurança
+            if (typeof args !== 'object' || args === null) {
+                logSecurityEvent('INVALID_ARGUMENTS', { toolName, args });
+                throw new MCPError('VALIDATION_ERROR', 'Arguments must be an object');
+            }
+            // Validar projectPath se existir
+            if ('projectPath' in args) {
+                const projectPath = args.projectPath;
+                if (typeof projectPath !== 'string') {
+                    logSecurityEvent('INVALID_PROJECT_PATH_TYPE', { toolName, projectPath });
+                    throw new MCPError('VALIDATION_ERROR', 'projectPath must be a string');
+                }
+                if (!projectPath || projectPath.includes('..')) {
+                    logSecurityEvent('PATH_TRAVERSION_ATTEMPT', { toolName, projectPath });
+                    throw new MCPError('VALIDATION_ERROR', 'Invalid project path');
+                }
+            }
+            // Log da execução
+            logger.info(`Executing tool: ${toolName}`, { args }, toolName);
+            // Executar a ferramenta
+            const result = await tool.handle(args, { providerManager, gitAdapter });
+            const duration = Date.now() - startTime;
+            logPerformanceMetric(`tool_${toolName}`, duration, { success: true });
+            logToolExecution(toolName, args, result);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            logPerformanceMetric(`tool_${toolName}`, duration, { success: false, error: error.message });
+            logToolExecution(toolName, request.params.arguments ?? {}, undefined, error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${error.message || String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Register resource list handler
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        logger.debug('Listing available resources');
+        return {
+            resources: resources.map(resource => ({
+                uri: resource.uri,
+                name: resource.name,
+                description: resource.description,
+                mimeType: resource.mimeType,
+            })),
+        };
+    });
+    // Register resource read handler
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        const resource = resources.find(r => r.uri === uri);
+        if (!resource) {
+            logger.warn(`Resource not found: ${uri}`);
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        logger.debug(`Reading resource: ${uri}`);
+        return {
+            contents: [
+                {
+                    uri: resource.uri,
+                    mimeType: resource.mimeType,
+                    text: resource.content,
+                },
+            ],
+        };
+    });
+    // Register prompt list handler
+    server.setRequestHandler(ListPromptsRequestSchema, async () => {
+        logger.debug('Listing available prompts');
+        return {
+            prompts: GIT_PROMPTS.map(prompt => ({
+                name: prompt.name,
+                description: prompt.description,
+                arguments: prompt.arguments,
+            })),
+        };
+    });
+    // Register prompt get handler
+    server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+        const promptName = request.params.name;
+        const prompt = GIT_PROMPTS.find(p => p.name === promptName);
+        if (!prompt) {
+            logger.warn(`Prompt not found: ${promptName}`);
+            throw new Error(`Prompt not found: ${promptName}`);
+        }
+        logger.debug(`Generating prompt: ${promptName}`);
+        const result = await prompt.generate(request.params.arguments ?? {}, { providerManager, gitAdapter });
+        return {
+            description: result.description,
+            messages: result.messages,
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Only log in debug mode
+    if (process.env.DEBUG) {
+        logger.info(`✅ git-mcp MCP server running via STDIO`);
+        logger.info(`Tools: ${tools.length} registered`);
+        logger.info(`Resources: ${resources.length} registered`);
+        logger.info(`Prompts: ${GIT_PROMPTS.length} registered`);
+    }
+}
+main().catch(err => {
+    console.error('❌ Failed to start git-mcp:', err);
+    process.exit(1);
+});

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"],