@andrebuzeli/git-mcp 5.5.1 → 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
 
@@ -44,8 +92,15 @@ export GITEA_TOKEN="your_gitea_token"
 export GITEA_USERNAME="your_username"
 ```
 
+PowerShell (Windows) example - session only:
+```powershell
+$env:GITEA_URL = 'https://your-gitea-instance.com'
+$env:GITEA_TOKEN = 'your_gitea_token'
+$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
 
@@ -169,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",
@@ -185,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
@@ -277,6 +347,24 @@ The server automatically validates credentials on startup:
    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>"
+  }
+}
+```
+
+Security note: do NOT commit `mcp.json` with real tokens. The repository's `.gitignore` includes `mcp.json` to help avoid leaks.
+
 ## Troubleshooting
 
 ### Common Issues

package/dist/config.d.ts

@@ -1,131 +1,5 @@
-/**
- * Configuration Management
- *
- * Handles environment variable configuration for GitHub and Gitea providers.
- * Provides validation and auto-detection utilities.
- */
-export type GitMCPMode = 'normal' | 'universal';
-export interface GitMCPConfig {
-    mode: GitMCPMode;
-    github?: {
-        token: string;
-        username: string;
-    };
-    gitea?: {
-        url: string;
-        token: string;
-        username: string;
-    };
-}
-export interface ProjectContext {
-    projectPath: string;
-    repositoryName: string;
-    isGitRepository: boolean;
-    remoteOrigin?: string;
-    currentBranch?: string;
-    detectedProvider?: string;
-}
-export interface ConfigValidationResult {
-    isValid: boolean;
-    errors: string[];
-    warnings: string[];
-    missingEnvVars: string[];
-    configurationGuide?: {
-        requiredEnvVars: string[];
-        exampleConfig: Record<string, string>;
-    };
-}
-export interface DetailedValidationResult {
-    isValid: boolean;
-    providerResults: {
-        github?: ProviderValidationResult;
-        gitea?: ProviderValidationResult;
-    };
-    summary: {
-        totalProviders: number;
-        validProviders: number;
-        errors: string[];
-        warnings: string[];
-    };
-}
-export interface ProviderValidationResult {
-    provider: 'github' | 'gitea';
-    isValid: boolean;
-    isConfigured: boolean;
-    credentialStatus: 'valid' | 'invalid' | 'missing' | 'network_error';
-    errorDetails?: string;
-    userInfo?: {
-        username: string;
-        displayName?: string;
-        email?: string;
-    };
-    permissions?: string[];
-    rateLimit?: {
-        limit: number;
-        remaining: number;
-        reset: Date;
-    };
-}
-export declare class ConfigManager {
-    private config;
-    constructor();
-    private loadConfiguration;
-    getConfig(): GitMCPConfig;
-    isGitHubConfigured(): boolean;
-    isGiteaConfigured(): boolean;
-    getConfigurationStatus(): Record<string, string>;
-    /**
-     * Gets the current operation mode
-     */
-    getMode(): GitMCPMode;
-    /**
-     * Checks if universal mode is enabled
-     */
-    isUniversalMode(): boolean;
-    /**
-     * Validates GitHub and Gitea credentials
-     */
-    validateCredentials(): ConfigValidationResult;
-    /**
-     * Auto-detects project context from projectPath
-     */
-    detectProjectContext(projectPath: string): ProjectContext;
-    /**
-     * Auto-detects username/owner from environment variables
-     */
-    autoDetectUsername(provider: 'github' | 'gitea'): string | undefined;
-    /**
-     * Gets provider configuration for a specific provider
-     */
-    getProviderConfig(provider: 'github' | 'gitea'): {
-        token: string;
-        username: string;
-    } | undefined;
-    /**
-     * Checks if a provider is supported for operations
-     */
-    isProviderSupported(provider: 'github' | 'gitea' | 'both'): boolean;
-    /**
-     * Validates credentials with detailed testing of API connectivity
-     */
-    validateCredentialsDetailed(): Promise<DetailedValidationResult>;
-    /**
-     * Validates GitHub credentials with API test
-     */
-    private validateGitHubCredentials;
-    /**
-     * Validates Gitea credentials with API test
-     */
-    private validateGiteaCredentials;
-    /**
-     * Gets configuration guidance for missing setup
-     */
-    getConfigurationGuidance(): {
-        requiredEnvVars: string[];
-        exampleConfig: Record<string, string>;
-        setupInstructions: string[];
-    };
-}
-export declare const configManager: ConfigManager;
-export declare function getProviderConfig(): GitMCPConfig;
-//# sourceMappingURL=config.d.ts.map
+export type MCPConfig = {
+    env?: Record<string, string>;
+    [k: string]: any;
+};
+export declare function loadMCPConfig(configPath?: string): MCPConfig | null;