mcp-gh-forge 🛠️

mcp-gh-forge is a lightweight, ultra-minimal Model Context Protocol (MCP) server designed to act as a secure proxy between your AI terminal assistants (Claude Code and GitHub Copilot CLI) and your local automation workflows.

Instead of forcing your AI model to execute slow, separate, step-by-step commands, mcp-gh-forge lets the AI run robust, multi-step local Git operations and cloud GitHub API macros simultaneously through a single execution layer.

---

💎 Features

• Dual-Universe Automation: Bridges local workspace operations (Git branches, files, builds) and remote cloud platform operations (GitHub Issues, Pull Requests).
• Token & Cost Efficiency: Packs multi-stage developer chores into single-turn executions, slashing LLM context window bloat and API latency.
• Cross-Platform Compatibility: Runs identically on Debian 13 and Windows 11 (Git Bash).
• Fail-Safe Security Boundary: The AI cannot execute arbitrary terminal commands. It is bounded strictly to the execution parameter switches defined in your script blueprint directory.

---

📂 Project Structure

mcp-gh-forge/
├── index.js             # Core MCP Node.js server bridge
├── package.json         # Node.js module configuration
└── README.md            # Documentation

---

🚀 Getting Started

1. Prerequisites

Ensure you have Node.js (v18+) installed on your local operating system.

2. Installation

Clone or navigate into your server folder and set up your project dependencies:

# Initialize project directory
cd mcp-gh-forge
npm install

3. Exposing Your Custom Automations

By default, the server expects your automated shell script (git-orchestrator.sh) to reside in your local machine's user path (~/bin/mcp-git-helpers/).

Make sure your shell scripts are executable (especially on Linux/Debian):

chmod +x ~/bin/mcp-git-helpers/git-orchestrator.sh

---

🔌 Linking to Your AI Assistants

To connect mcp-gh-forge to Claude Code, update your global ~/.claude.json configuration profile.

For Debian 13

{
  "mcpServers": {
    "mcp-gh-forge": {
      "command": "node",
      "args": ["/home/yourusername/projects/mcp-gh-forge/index.js"],
      "env": {
        "MCP_SCRIPT_DIR": "/home/yourusername/bin/mcp-git-helpers"
      }
    }
  }
}

For Windows 11 (Git Bash)

Note: Always use forward slashes (/) for paths within your JSON string parameters to ensure seamless cross-platform execution runtime support.

{
  "mcpServers": {
    "mcp-gh-forge": {
      "command": "node",
      "args": ["C:/Users/YourName/projects/mcp-gh-forge/index.js"],
      "env": {
        "MCP_SCRIPT_DIR": "C:/Users/YourName/bin/mcp-git-helpers"
      }
    }
  }
}

---

🛠️ Expose Actions & Capabilities

Once connected, mcp-gh-forge exposes the run_forge_macro tool to your interactive terminal sessions. The tool accepts the following parameters:

Action	Core Responsibility	Expected Argument Parameter
consolidate	Pulls issue/PR logs & comments together.	PR or Issue Number (45)
get-changed-files	Extracts unique lists of updated files.	Revision Tag or Git Hash (v2.1.0)
draft-and-save	Creates a local MD file & drafts a live GH issue.	Issue Title ("Bug: Auth Loop Failure")
branch-init	Safely fetches main & initializes clean branch.	New Branch Suffix ("login-fix")
branch-cleanup	Hard purges and cleans a dead branch layout.	Targeted Branch Suffix ("login-fix")

---

🦾 Usage Example

Launch your interactive assistant inside any active target git repository:

claude

Use natural language commands to kick off your automated multi-step processes:

"Use mcp-gh-forge to run get-changed-files for v1.0.4. Analyze the output and write an engine summary changelog."

"Please initialize a new local feature branch using action branch-init for argument user-dashboard-patch."