@andrebuzeli/git-mcp 5.5.2 → 5.8.0

package/README.md

@@ -1,11 +1,16 @@
 # GIT MCP Server
 
-Professional MCP (Model Context Protocol) server for Git operations with multi-provider support, enhanced security, and comprehensive safety features.
+Professional MCP (Model Context Protocol) server for Git operations with multi-provider support, enhanced security, comprehensive safety features, and **self-documenting resources**.
 
 ## Features
 
-- 🚀 **17 Specialized Git Tools** - Complete Git workflow coverage with safety warnings
-- 🔄 **Multi-Provider Support** - GitHub and Gitea simultaneously with credential validation
+- 🚀 **20 Specialized Git Tools** - Complete Git workflow coverage with safety warnings
+- 📚 **NEW: 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
@@ -13,6 +18,49 @@ Professional MCP (Model Context Protocol) server for Git operations with multi-p
 - 🔧 **IDE/Client Compatibility** - Universal aliases for different MCP client expectations
 - 📦 **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
+
+## Resources System
+
+Git-MCP v5.7.0 includes a comprehensive **Resources** system that provides detailed documentation directly through the MCP protocol:
+
+### Available Resources
+
+#### Tools Guide Resource
+- **URI:** `git-mcp://tools/guide`
+- **Format:** Markdown
+- **Content:** Complete documentation for all 20 tools with 102 actions
+- **Size:** 35,000+ characters
+
+### 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 `simple-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
 
@@ -52,7 +100,7 @@ $env:GITEA_USERNAME = 'your_username'
 ```
 
 #### Multi-Provider Support
-Configure both GitHub and Gitea to use `provider="both"` in tool calls.
+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
 
@@ -176,14 +224,13 @@ All tools provide detailed error messages with actionable solutions:
 }
 ```
 
-### Remote Repository Operations
+### Remote Repository Operations (GitHub Example)
 
 ```json
 {
   "tool": "git-workflow",
   "params": {
     "action": "create",
-    "projectPath": "/path/to/project", 
     "provider": "github",
     "name": "my-new-repo",
     "description": "My new repository",
@@ -192,6 +239,22 @@ All tools provide detailed error messages with actionable solutions:
 }
 ```
 
+### 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

package/dist/index.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const server_1 = require("./server");
 const providerManager_1 = require("./providers/providerManager");
@@ -21,14 +24,21 @@ const gitArchive_1 = require("./tools/gitArchive");
 const gitSync_1 = require("./tools/gitSync");
 const gitPackages_1 = require("./tools/gitPackages");
 const gitAnalytics_1 = require("./tools/gitAnalytics");
+const gitUpload_1 = require("./tools/gitUpload");
+const gitUpdate_1 = require("./tools/gitUpdate");
+const gitHistory_1 = require("./tools/gitHistory");
+const toolsGuide_1 = __importDefault(require("./resources/toolsGuide"));
 async function main() {
     // Load optional mcp.json configuration (will populate process.env if values present)
     (0, config_1.loadMCPConfig)();
     const providerManager = new providerManager_1.ProviderManager();
     // Register providers (validation happens inside manager)
     const validation = await providerManager.validateConfiguredProviders();
-    console.log('Provider validation results:', JSON.stringify(validation, null, 2));
-    // Register all 17 Git tools
+    // Only log validation in debug mode (prevents JSON parsing errors in MCP clients)
+    if (process.env.DEBUG) {
+        console.error('Provider validation:', JSON.stringify(validation, null, 2));
+    }
+    // Register all 20 Git tools
     const tools = [
         new gitWorkflow_1.GitWorkflowTool(),
         new gitFiles_1.GitFilesTool(),
@@ -47,14 +57,60 @@ async function main() {
         new gitSync_1.GitSyncTool(),
         new gitPackages_1.GitPackagesTool(),
         new gitAnalytics_1.GitAnalyticsTool(),
+        new gitUpload_1.GitUploadTool(),
+        new gitUpdate_1.GitUpdateTool(),
+        new gitHistory_1.GitHistoryTool(),
     ];
-    console.log(`Registered ${tools.length} Git tools`);
-    const app = (0, server_1.createServer)({ tools, providerManager });
-    const port = process.env.PORT ?? 3210;
-    const server = app.listen(port, () => {
-        console.log(`✅ git-mcp server ready on http://localhost:${port}`);
-        console.log(`Tools available: ${tools.map(t => t.name).join(', ')}`);
-    });
+    // Register resources
+    const resources = [
+        toolsGuide_1.default
+    ];
+    // 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)`);
+    }
+    const app = (0, server_1.createServer)({ tools, providerManager, resources });
+    // Try default port, then find available port if occupied
+    let port = parseInt(process.env.PORT || '3210');
+    const startServer = (attemptPort) => {
+        return new Promise((resolve, reject) => {
+            const server = app.listen(attemptPort, () => {
+                // Send success message to stderr (MCP clients expect JSON on stdout)
+                if (process.env.DEBUG) {
+                    console.error(`✅ git-mcp server ready on http://localhost:${attemptPort}`);
+                    console.error(`Tools: ${tools.map(t => t.name).join(', ')}`);
+                    console.error(`Resources: ${resources.map(r => r.uri).join(', ')}`);
+                }
+                resolve(server);
+            });
+            server.on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    // Port in use, try next port
+                    server.close();
+                    resolve(null);
+                }
+                else {
+                    reject(err);
+                }
+            });
+        });
+    };
+    // Try to start server on available port
+    let server = null;
+    const maxAttempts = 10;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const tryPort = port + attempt;
+        server = await startServer(tryPort);
+        if (server) {
+            port = tryPort;
+            break;
+        }
+    }
+    if (!server) {
+        console.error(`❌ Failed to find available port after ${maxAttempts} attempts`);
+        process.exit(1);
+    }
     server.on('error', (err) => {
         console.error('❌ Server error:', err);
         process.exit(1);

package/dist/resources/toolsGuide.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Git-MCP Tools Guide Resource
+ * Comprehensive documentation for all 20 Git tools available in the MCP server
+ */
+export declare const TOOLS_GUIDE: {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+    content: string;
+};
+export default TOOLS_GUIDE;