vcs-agent-interface-gateway

This component serves as an MCP (Model Context Protocol) Gateway, abstracting the complexities of raw shell interaction with the native git command-line utility into structured, safe API calls consumable by autonomous agents (LLMs). It facilitates all primary repository lifecycle operations: duplication, modification tracking, history traversal, and remote synchronization.

Engineered atop the cyanheads/mcp-ts-template, the architecture prioritizes deterministic operation, fault tolerance, and rigorous security boundaries.

🎯 Rationale for Adoption

• Workflow Orchestration: Empower autonomous agents to script version control tasks (e.g., initialization, branching strategies, publishing updates).
• Introspection & State Query: Provide agents with reliable mechanisms to ascertain repository status, view audit trails, and analyze delta changes without direct filesystem access.
• AI-Centric VCM Integration: Seamlessly embed version control management into AI-driven software development lifecycles.
• Enterprise Readiness: Inherits robust logging mechanisms, validated error reporting, and defensive programming patterns from the foundational template.

🛠️ Primary Functionality: Git Command Set

This gateway exposes a curated vocabulary of Git primitives for agent interaction:

🧭 Navigational Index

| Core Purpose | Operational Features | Deployment Setup | | Configuration Parameters | System Architecture Overview | Development Guide | Licensing Details |

Core Purpose

The Git MCP Gateway functions as the secure intermediary, translating high-level instructions from MCP-compliant consumers (advanced LLM reasoning engines, integrated development environments, custom automation scripts) into safe, executed commands against the host machine's Git installation. This methodology bypasses direct agent shell exposure.

Key Automation Scenarios:

• Automated Lifecycle Management: Programmatic handling of cloning, branch creation, staging, committing artifactual work, and remote publishing.
• Contextual State Retrieval: Secure querying of repository metrics (status, audit logs, patch comparisons) for analysis by reasoning systems.
• AI-Native VCM Control: Facilitating agent-led version control management as an integral part of code generation or modification tasks, thereby guaranteeing history fidelity.
• Template Benefits: Incorporates inherent logging, robust error capture, and security measures inherited from the underlying service template.

This server leverages the Node.js child_process primitives to execute the standard git binary, ensuring full feature parity with the installed Git version.

Developer Insight: The included .clinerules file acts as a living guide for AI coding assistants, detailing architectural conventions, key file locations, and critical implementation fragments.

Operational Features

This system benefits significantly from the features embedded within the mcp-ts-template infrastructure:

• Auditing: Context-aware, configurable logging (JSON output, file rotation, MCP stream notification) with automatic redaction of sensitive payload data.
• Exception Management: Centralized handling of runtime exceptions, mapping them to standardized McpError types, and ensuring all failures are logged.
• Environment Configuration: Secure loading and validation of configuration settings via environment variables (dotenv integration).
• Data Integrity Checks: Implementation of schema validation and input sanitization using zod (essential for path traversal mitigation).
• Request Context Preservation: Utilization of AsyncLocalStorage to ensure unique correlation identifiers track operations end-to-end.
• Type Rigor: Comprehensive type checking enforced by TypeScript throughout the service.
• Transport Layer: Utilizes the high-throughput Hono framework for HTTP transport, supporting session tracking, CORS policies, and pluggable authentication middleware.
• Deployment Artifacts: Multi-stage Dockerfiles engineered for minimal production image size and optimal native dependency handling.

Git Specializations

• Native CLI Execution: Direct, secure invocation of the installed system git binary via Node.js runtime subprocesses.
• Broad Command Exposure: Nearly all significant Git operations are mapped to dedicated MCP tools (reference Tools).
• Lifecycle Support: Full spectrum interaction, including index staging, history viewing, remote updates, pruning, and tagging.
• Contextual Persistence: Ability to define and persist a working directory context across multiple service calls within a session.
• Safety Gates: Mandatory confirmation or explicit flag requirements for potentially destructive actions like git clean or hard resets (git reset --hard).
• Commit Verification: Configuration support for GPG/SSH signing via the GIT_SIGN_COMMITS setting, including a fallback mechanism if the primary signing attempt fails.

Deployment Setup

Prerequisites

• Node.js Runtime (Minimum version 20.0.0)
• npm Package Manager
• Git CLI (must be available in the execution environment's PATH).

MCP Client Integration Snippet

For automatic discovery and invocation by an existing MCP host, integrate this configuration object into the client's settings file (e.g., cline_mcp_settings.json). This uses npx for on-demand installation:

{ "mcpServers": { "vcs-agent-interface-gateway": { "command": "npx", "args": ["@cyanheads/git-mcp-server"], "env": { "MCP_LOG_LEVEL": "info", "GIT_SIGN_COMMITS": "false" } } } }

Execution Modes (Manual or Development)

1. Installation: Use npm install @cyanheads/git-mcp-server if running outside the automatic client mechanism.
2. Server Launch:
   • Stdio (Default/Production): npm run start:stdio
   • HTTP (Networked Service): npm run start:http (Check MCP_HTTP_PORT)
   • Development/Watch: Use npm run dev:* counterparts for live reloading.

Configuration Parameters

Configuration is primarily managed via environmental variables (or a standard .env file):

System Architecture Overview

• src/mcp-server/: Houses the core MCP routing logic, tool definitions, resource handlers, and transport adapters.
• src/config/: Centralized module responsible for secure environment variable ingestion and schema validation.
• src/types-global/: Repository for shared TypeScript interfaces and canonical data structures.
• src/utils/: Contains fundamental, cross-cutting utilities: structured logging framework, standardized error representation, and security primitives.
• src/index.ts: The primary bootstrap script initializing configuration and commencing server operation (stdio or HTTP).

Visualizing the Structure: For an up-to-date directory map, consult the generated file tree documentation:

bash npm run tree

📦 Resources

Beyond transactional tools, the gateway exposes informational resources accessible via the MCP query mechanism:

Development Guide

This project utilizes a modern toolchain to enforce high fidelity and maintainability:

Code Quality Enforcement

• Linting & Formatting: ESLint (with TypeScript support) governs style and correctness. Prettier handles automated formatting.
• Check for issues: npm run lint
• Auto-correct issues: npm run format

Type Verification

Ensure strict type correctness across all files without compilation:

bash npm run typecheck

Testing Suite

We employ Vitest for unit and integration testing.

• Execute all tests: npm test
• Interactive watch mode: npm run test:watch
• Generate test coverage report: npm run test:coverage

Documentation Generation

API reference documentation is automatically generated from comprehensive JSDoc blocks using TypeDoc. Run the following command to regenerate the documentation in the docs/api folder:

bash npm run docs:generate

🧩 Extensibility Pattern

The mandated architecture for adding new capabilities adheres strictly to the guidelines outlined in .clinerules:

1. Logic Isolation (logic.ts): Contains the core, pure Git operation, input schemas (zod), and type definitions. This file must propagate errors using structured exception types.
2. Handler Wrapper (registration.ts): This file registers the tool endpoint. It exclusively manages the service contract—wrapping the pure logic execution in try...catch blocks to handle the thrown exceptions and correctly serialize the final success or failure response payload for the MCP client.

This 'Logic Throws, Handler Encapsulates' paradigm ensures testability of the core mechanism while centralizing transport-level concerns.