@andrebuzeli/git-mcp 9.2.0 → 10.0.0

package/README.md

@@ -1,328 +1,460 @@
-# 🚀 Git MCP - 100% Native JavaScript Git Implementation
-
-[![npm version](https://badge.fury.io/js/@andrebuzeli%2Fgit-mcp.svg)](https://www.npmjs.com/package/@andrebuzeli/git-mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
-
-**Model Context Protocol (MCP) server for Git operations with ZERO dependencies on installed Git!**
-
-🌍 **Universal IDE Support:** Claude Desktop • Cursor AI • VSCode • Windsurf • Trae AI • Kiro.dev • Any MCP-compatible IDE
-
-📖 **[Complete Setup Guide for All IDEs →](./UNIVERSAL-IDE-SETUP.md)**
-
-## ✨ Key Features
-
-### 🎯 **100% Git Independent**
-- **No Git installation required** - Pure JavaScript implementation using [isomorphic-git](https://isomorphic-git.org/)
-- **Works anywhere** - Browser, Node.js, Electron, VS Code, or any JavaScript runtime
-- **Cross-platform** - Windows, macOS, Linux with identical behavior
-- **Portable** - Bundle everything in your app, no external dependencies
-
-### 🔄 **Dual-Provider Support**
-- **GitHub + Gitea** - Automatic dual-push to both platforms
-- **Unified API** - Single command pushes to both providers
-- **Fallback support** - Works with either provider independently
-- **Environment-based auth** - Uses `GITHUB_TOKEN` and `GITEA_TOKEN`
-
-### 🧠 **Smart Commit Authors**
-- **Automatic detection** - Extracts username from GitHub/Gitea APIs
-- **Provider-aware** - Uses authenticated provider username
-- **Fallback chain** - Provider → Local .git/config → Default "MCP User"
-
-### 📊 **Complete Traceability**
-- **Full history tracking** - Every change logged with timestamps
-- **Issue integration** - Links commits to GitHub/Gitea issues
-- **Detailed metadata** - Files changed, authors, providers, and more
-
-### 🛠️ **22 Comprehensive Tools**
-
-#### Core Operations
-- `git-workflow` - Initialize, status, commit, sync, backup
-- `git-update` - Complete update workflow (add + commit + push)
-- `git-upload` - Upload entire project to GitHub/Gitea
-- `git-fix` - Auto-configure dual-provider system
-
-#### Branch Management
-- `git-branches` - List, create, delete, checkout, merge branches
-
-#### Remote Operations
-- `git-remote` - Manage remotes (add, remove, list)
-- `git-sync` - Fetch, pull, push operations
-
-#### Version Control
-- `git-tags` - Create, list, delete tags
-- `git-stash` - Save, list, apply, pop, drop stash (standard Git format)
-- `git-reset` - Soft, mixed, hard reset operations
-
-#### Configuration
-- `git-config` - Local, global, and system Git configuration
-- `git-ignore` - Manage .gitignore patterns
-
-#### Collaboration
-- `git-issues` - Create, list, update GitHub/Gitea issues
-- `git-pulls` - Create, list, merge pull requests
-- `git-release` - Create and manage releases
-
-#### Advanced
-- `git-history` - Complete change history with remote tracking
-- `git-monitor` - Repository monitoring and analytics
-- `git-analytics` - Detailed repository statistics
-- `git-backup` - Backup and restore operations
-- `git-archive` - Archive repository state
-- `git-packages` - Package management
-
-## 🏗️ Architecture
-
-### GitAdapter Pattern
-```typescript
-interface GitAdapter {
-  // Core operations
-  init(projectPath: string): Promise<void>;
-  status(projectPath: string): Promise<StatusResult>;
-  add(projectPath: string, files: string[]): Promise<void>;
-  commit(projectPath: string, message: string): Promise<string>;
-  
-  // Remote operations (HTTP-based, no SSH)
-  push(projectPath: string, remote: string, branch: string): Promise<void>;
-  pull(projectPath: string, remote: string, branch: string): Promise<void>;
-  fetch(projectPath: string, remote: string): Promise<void>;
-  
-  // Advanced operations
-  merge(projectPath: string, branch: string): Promise<void>;
-  log(projectPath: string, options?: any): Promise<LogEntry[]>;
-  diff(projectPath: string, ref1?: string, ref2?: string): Promise<DiffResult>;
-  reset(projectPath: string, ref: string, mode: 'soft'|'mixed'|'hard'): Promise<void>;
-  
-  // Hybrid implementations
-  stashSave/List/Apply/Pop/Drop/Clear() // Uses refs/stash + reflog
-  getConfig/setConfig/listConfig() // isomorphic-git + fs for global/system
-}
-```
-
-### IsomorphicGitAdapter Implementation
-- **100% isomorphic-git** - No simple-git dependency
-- **HTTP authentication** - Token-based via `onAuth` callbacks
-- **Standard Git formats** - Compatible with native Git
-- **Hybrid features** - Combines isomorphic-git with Node.js fs for full functionality
-
-## 📦 Installation
-
-```bash
-npm install @andrebuzeli/git-mcp
-```
-
-### Environment Variables
-```bash
-# GitHub authentication
-GITHUB_TOKEN=ghp_xxxxxxxxxxxx
-GITHUB_USERNAME=your-username
-
-# Gitea authentication
-GITEA_TOKEN=xxxxxxxxxx
-GITEA_USERNAME=your-username
-GITEA_URL=https://gitea.example.com  # or http://localhost:3000
-```
-
-### 🌍 Universal IDE Configuration
-
-**Works in:** Claude Desktop, Cursor AI, VSCode, Windsurf, Trae AI, Kiro.dev, and any MCP-compatible IDE!
-
-#### Quick Setup (Recommended)
-
-```json
-{
-  "mcpServers": {
-    "git-mcp": {
-      "command": "npx",
-      "args": ["-y", "@andrebuzeli/git-mcp"],
-      "env": {
-        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx",
-        "GITHUB_USERNAME": "your-username",
-        "GITEA_TOKEN": "xxxxxxxxxx",
-        "GITEA_USERNAME": "your-username",
-        "GITEA_URL": "https://gitea.example.com"
-      }
-    }
-  }
-}
-```
-
-#### Configuration Locations
-
-- **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
-- **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Cursor AI:** `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
-- **VSCode:** Via MCP extension settings or `settings.json`
-
-📖 **[Complete Universal Setup Guide](./UNIVERSAL-IDE-SETUP.md)** - Detailed instructions for all IDEs
-
-## 🚀 Quick Start
-
-### 1. Fix Existing Repository
-```typescript
-{
-  "projectPath": "/path/to/repo",
-  "autoDetect": true  // Auto-detects GitHub/Gitea from existing remotes
-}
-```
-
-### 2. Initialize New Repository
-```typescript
-{
-  "action": "init",
-  "projectPath": "/path/to/new-project"
-}
-```
-
-### 3. Complete Update Workflow
-```typescript
-{
-  "projectPath": "/path/to/project",
-  "commitMessage": "feat: add new feature",
-  "repoName": "my-project",
-  "description": "My awesome project",
-  "private": true
-}
-```
-
-## 🔧 How It Works
-
-### No Git Installation Needed
-
-Traditional Git tools require Git CLI to be installed:
-```bash
-# ❌ OLD WAY - Requires Git installation
-git add .
-git commit -m "message"
-git push origin main
-```
-
-**Git MCP uses isomorphic-git - pure JavaScript:**
-```typescript
-// ✅ NEW WAY - No Git installation required
-await git.add(projectPath, '.');
-await git.commit(projectPath, 'message');
-await git.push(projectPath, 'origin', 'main');
-```
-
-### HTTP-Based Authentication
-
-**No SSH keys needed** - Uses HTTP tokens:
-
-```typescript
-// Automatic authentication via environment tokens
-const auth = {
-  username: process.env.GITHUB_USERNAME,
-  password: process.env.GITHUB_TOKEN
-};
-
-await git.push({
-  fs,
-  http,
-  dir: projectPath,
-  remote: 'github',
-  ref: 'main',
-  onAuth: () => auth
-});
-```
-
-### Hybrid Implementations
-
-Some Git features not natively supported by isomorphic-git are implemented using hybrid approaches:
-
-#### Stash (refs/stash + reflog)
-```typescript
-// Creates standard Git stash using commits + refs/stash
-await git.stashSave(projectPath, 'WIP: feature');
-
-// Reflog stored in .git/logs/refs/stash
-// Compatible with native Git stash commands
-```
-
-#### Global Config (fs + isomorphic-git)
-```typescript
-// Local config via isomorphic-git
-await git.setConfig(projectPath, 'user.name', 'John', 'local');
-
-// Global config via direct fs access to ~/.gitconfig
-await git.setConfig(projectPath, 'user.email', 'john@example.com', 'global');
-```
-
-## 🎯 Use Cases
-
-### ✅ Perfect For:
-- **CI/CD pipelines** - No Git installation needed
-- **Electron apps** - Embedded Git functionality
-- **VS Code extensions** - Native Git operations
-- **Web applications** - Git in the browser
-- **Docker containers** - Smaller images without Git
-- **Cross-platform tools** - Consistent behavior everywhere
-
-### ⚠️ Limitations:
-- **SSH not supported** - Use HTTPS with tokens
-- **Large repos** - May be slower than native Git
-- **Complex operations** - Some advanced features limited
-
-## 📊 Performance
-
-- **Startup time**: ~100ms (no Git CLI spawning)
-- **Small repos (<100MB)**: Comparable to native Git
-- **Large repos (>1GB)**: 2-3x slower than native Git
-- **Memory usage**: Higher than native Git (pure JavaScript)
-
-## 🔒 Security
-
-- **Token-based auth** - No passwords or SSH keys stored
-- **Environment variables** - Credentials from secure sources
-- **No shell execution** - Pure JavaScript, no command injection
-- **Sandboxed operations** - All operations in Node.js runtime
-
-## 🛠️ Development
-
-### Build
-```bash
-npm run build
-```
-
-### Test
-```bash
-npm test
-```
-
-### Lint
-```bash
-npm run lint
-```
-
-## 📚 Documentation
-
-- [isomorphic-git Documentation](https://isomorphic-git.org/)
-- [Model Context Protocol](https://modelcontextprotocol.io/)
-- [API Reference](./docs/api.md) *(coming soon)*
-
-## 🤝 Contributing
-
-Contributions welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
-## 📄 License
-
-MIT License - see [LICENSE](./LICENSE) for details.
-
-## 🙏 Credits
-
-Built with:
-- [isomorphic-git](https://isomorphic-git.org/) - Pure JavaScript Git implementation
-- [@modelcontextprotocol/sdk](https://modelcontextprotocol.io/) - MCP protocol
-- [@octokit/rest](https://octokit.github.io/rest.js/) - GitHub API client
-- [axios](https://axios-http.com/) - HTTP client for Gitea API
-
-## 📞 Support
-
-- **Issues**: [GitHub Issues](https://github.com/Andre-Buzeli/git-mcp/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/Andre-Buzeli/git-mcp/discussions)
-
----
-
-**Made with ❤️ by Andre Buzeli**
-
-*Git operations without Git - powered by isomorphic-git and MCP*
+# GIT MCP Server
+
+Professional MCP (Model Context Protocol) server for Git operations with multi-provider support, enhanced security, comprehensive safety features, and **universal IDE compatibility**.
+
+## ✨ NEW in v7.4.0 - Universal IDE Compatibility
+
+**🎉 Now works with ALL IDEs and AI agents without parameter errors!**
+
+- ✅ **VSCode** (all AI extensions)
+- ✅ **Cursor AI**
+- ✅ **Trae AI**
+- ✅ **Kiro.dev**
+- ✅ **Claude Desktop**
+- ✅ **Any MCP-compatible client**
+
+### Problem Solved
+Previously, different IDEs sent parameters in different formats causing `Error: action is required`. Now Git-MCP **automatically normalizes** parameters from any source!
+
+```javascript
+// ALL these formats work now! ✅
+{ "command": "git status", "projectPath": "..." }  // IDE format
+{ "action": "status", "projectPath": "..." }        // Standard format
+{ "command": "status", "projectPath": "..." }       // Simple format
+{ "projectPath": "..." }                             // Auto-detect (defaults to status)
+```
+
+## Features
+
+- 🌐 **NEW: Universal Parameter Normalization** - Accepts both 'action' and 'command' formats
+- 🚀 **23 Specialized Git Tools** - Complete Git workflow coverage with 170+ actions
+- 📚 **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
+- 📋 **Comprehensive Validation** - Pre-execution validation with helpful guidance
+- 🔧 **IDE/Client Compatibility** - Works seamlessly with ANY IDE or AI agent
+- 📦 **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
+
+### Installation & Usage
+
+```bash
+# Option 1: Install globally (RECOMMENDED - faster startup)
+npm install -g @andrebuzeli/git-mcp
+git-mcp
+
+# Option 2: Run with npx (slower first run, ~2-3min for dependency download)
+npx @andrebuzeli/git-mcp@latest
+```
+
+**⚡ Performance Note**: Global installation is **10x faster** on startup (~1s vs 2-3min). `npx` needs to download and install all dependencies on first run. For production use, install globally.
+
+### Configuration
+
+Set up your provider credentials via environment variables:
+
+#### GitHub Configuration
+```bash
+export GITHUB_TOKEN="your_github_token"
+export GITHUB_USERNAME="your_username"
+```
+
+#### Gitea Configuration
+```bash
+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
+$env:GITEA_URL = 'https://your-gitea-instance.com'
+$env:GITEA_TOKEN = 'your_gitea_token'
+$env:GITEA_USERNAME = 'your_username'
+```
+
+#### Multi-Provider Support
+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
+
+| Tool | Description | Operations | Safety Features |
+|------|-------------|------------|-----------------|
+| `git-workflow` | Core Git operations | init, status, commit, sync, backup, create, list, get, update, delete, fork, search | Repository deletion warnings |
+| `git-files` | **Read-only** file operations | read, list, search, backup | File modification blocked |
+| `git-branches` | Branch management | create, list, get, delete, merge, compare | Branch deletion warnings |
+| `git-issues` | Issue management | create, list, get, update, close, comment, search | - |
+| `git-pulls` | Pull request management | create, list, get, update, merge, close, review, search | - |
+| `git-tags` | Tag management | create, list, get, delete, search | - |
+| `git-release` | Release management | create, list, get, update, delete, publish, download | - |
+| `git-remote` | Remote repository management | add, remove, rename, show, set-url, prune | - |
+| `git-reset` | **⚠️ Repository reset** | soft, mixed, hard, reset-to-commit, reset-branch | **Hard reset warnings** |
+| `git-stash` | Stash management | stash, pop, apply, list, show, drop, clear | - |
+| `git-config` | Git configuration | get, set, unset, list, edit, show | - |
+| `git-monitor` | Repository monitoring | status, changes, health | - |
+| `git-backup` | Repository backup | create, restore, list, verify | - |
+| `git-archive` | Repository archiving | create, extract, list, verify | - |
+| `git-sync` | Repository synchronization | sync, status | - |
+| `git-packages` | Package management | list, get, create, update, delete, publish, download | - |
+| `git-analytics` | Repository analytics | stats, insights, reports | - |
+
+## Security Features
+
+### 🔒 File Operations Restriction
+
+The `git-files` tool is **read-only only** for security reasons:
+
+**✅ Allowed Operations:**
+- `read` - Read file content
+- `list` - List directory contents  
+- `search` - Search file content
+- `backup` - Create local backups
+
+**❌ Blocked Operations:**
+- `create` - Create new files (blocked)
+- `update` - Modify existing files (blocked)
+- `delete` - Delete files (blocked)
+
+**Why?** File content modification should be done through your local development environment, not via remote API calls.
+
+### 🚨 Safety Warnings
+
+Destructive operations include comprehensive safety warnings:
+
+#### Git Reset Warnings
+```json
+{
+  "tool": "git-reset",
+  "params": {
+    "action": "hard",
+    "projectPath": "/path/to/project"
+  }
+}
+```
+
+**Result:** Detailed warning about data loss with alternatives:
+- `git reset --soft` (keeps changes staged)
+- `git reset --mixed` (keeps changes unstaged)  
+- `git stash` (saves changes temporarily)
+
+#### Branch Deletion Warnings
+```json
+{
+  "tool": "git-branches", 
+  "params": {
+    "action": "delete",
+    "branchName": "feature-branch"
+  }
+}
+```
+
+**Result:** Warning about permanent branch deletion with suggestions:
+- Ensure branch is merged first
+- Create backup branch before deletion
+- Check for unmerged commits
+
+### 🔍 Enhanced Error Handling
+
+All tools provide detailed error messages with actionable solutions:
+
+**Example Error Response:**
+```json
+{
+  "success": false,
+  "error": {
+    "code": "BRANCH_NOT_FOUND",
+    "message": "Branch not found",
+    "suggestions": [
+      "Check if the branch name is correct",
+      "Use git branch -a to see all available branches", 
+      "Ensure the branch exists on the remote repository"
+    ]
+  }
+}
+```
+
+## Usage Examples
+
+### Local Git Operations
+
+```json
+{
+  "tool": "git-workflow",
+  "params": {
+    "action": "status",
+    "projectPath": "/path/to/project"
+  }
+}
+```
+
+```json
+{
+  "tool": "git-workflow", 
+  "params": {
+    "action": "commit",
+    "projectPath": "/path/to/project",
+    "message": "Add new feature"
+  }
+}
+```
+
+### Remote Repository Operations (GitHub Example)
+
+```json
+{
+  "tool": "git-workflow",
+  "params": {
+    "action": "create",
+    "provider": "github",
+    "name": "my-new-repo",
+    "description": "My new repository",
+    "private": true
+  }
+}
+```
+
+### 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
+{
+  "tool": "git-files",
+  "params": {
+    "action": "read",
+    "projectPath": "/path/to/project",
+    "filePath": "README.md"
+  }
+}
+```
+
+### Destructive Operations (With Warnings)
+
+```json
+{
+  "tool": "git-reset",
+  "params": {
+    "action": "hard",
+    "projectPath": "/path/to/project",
+    "confirmDestructive": true
+  }
+}
+```
+
+## Error Codes Reference
+
+### Common Error Codes
+
+| Code | Description | Solution |
+|------|-------------|----------|
+| `VALIDATION_ERROR` | Parameter validation failed | Check required parameters and format |
+| `NOT_A_GIT_REPOSITORY` | Directory is not a Git repository | Use `git init` first |
+| `NOTHING_TO_COMMIT` | No changes to commit | Make changes first |
+| `MERGE_CONFLICT` | Merge conflicts detected | Resolve conflicts before proceeding |
+| `PERMISSION_DENIED` | Permission denied | Check credentials and access rights |
+| `PROVIDER_NOT_CONFIGURED` | Provider not configured | Set up GitHub or Gitea credentials |
+| `NETWORK_ERROR` | Network connectivity issue | Check internet connection |
+| `OPERATION_RESTRICTED` | File modification blocked | Use read-only operations only |
+| `SAFETY_WARNING` | Destructive operation detected | Review warning and confirm if needed |
+
+### Git-Specific Error Codes
+
+| Code | Description | Solution |
+|------|-------------|----------|
+| `BRANCH_EXISTS` | Branch already exists | Use different name or delete existing |
+| `BRANCH_NOT_FOUND` | Branch not found | Check branch name and remote config |
+| `DIRTY_WORKING_TREE` | Uncommitted changes | Commit or stash changes first |
+| `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
+
+**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
+
+### 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:**
+   - Go to GitHub Settings → Developer settings → Personal access tokens
+   - Create token with `repo` scope
+   - Copy token to `GITHUB_TOKEN` environment variable
+
+2. **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>"
+  }
+}
+```
+
+Security note: do NOT commit `mcp.json` with real tokens. The repository's `.gitignore` includes `mcp.json` to help avoid leaks.
+
+## Troubleshooting
+
+### Common Issues
+
+**"Provider not configured" error:**
+- Check environment variables are set correctly
+- Verify token has required permissions
+- Test API connectivity manually
+
+**"Operation restricted" error:**
+- File modification operations are blocked for security
+- Use read-only operations: `read`, `list`, `search`, `backup`
+- Make file changes through your local development environment
+
+**"Safety warning" error:**
+- Review the detailed warning message
+- Consider safer alternatives suggested
+- Use `confirmDestructive: true` only if absolutely necessary
+
+**"Network error" errors:**
+- Check internet connectivity
+- Verify provider URLs are correct
+- Check firewall/proxy settings
+
+### Getting Help
+
+1. **Check error messages** - They include specific suggestions
+2. **Review safety warnings** - They explain risks and alternatives  
+3. **Validate credentials** - Server validates on startup
+4. **Use read-only operations** - Safe file operations are always available
+
+## Development
+
+### Building from Source
+
+```bash
+git clone https://github.com/your-repo/git-mcp.git
+cd git-mcp
+npm install
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Submit a pull request
+
+---
+
+**⚠️ Important Security Notes:**
+
+- File content modification is intentionally restricted for security
+- Always review safety warnings before destructive operations
+- Keep your API tokens secure and rotate them regularly
+- Use `confirmDestructive: true` only when absolutely necessary