MCP Git Repo Browser (Node.js)

A Node.js implementation of a Git repository browser using the Model Context Protocol (MCP).

Installation

NPM (Recommended)

npm install -g git-commands-mcp

Manual Installation

git clone https://github.com/bsreeram08/git-commands-mcp.git
cd git-commands-mcp
npm install

Configuration

Add this to your MCP settings configuration file:

{
  "mcpServers": {
    "git-commands-mcp": {
      "command": "git-commands-mcp"
    }
  }
}

For manual installation, use:

{
  "mcpServers": {
    "git-commands-mcp": {
      "command": "node",
      "args": ["/path/to/git-commands-mcp/src/index.js"]
    }
  }
}

Features

The server provides the following tools:

Basic Repository Operations

1. git_directory_structure: Returns a tree-like representation of a repository's directory structure

   • Input: Repository URL
   • Output: ASCII tree representation of the repository structure

2. git_read_files: Reads and returns the contents of specified files in a repository

   • Input: Repository URL and list of file paths
   • Output: Dictionary mapping file paths to their contents

3. git_search_code: Searches for patterns in repository code

   • Input: Repository URL, search pattern, optional file patterns, case sensitivity, and context lines
   • Output: JSON with search results including matching lines and context

Branch Operations

4. git_branch_diff: Compare two branches and show files changed between them
   • Input: Repository URL, source branch, target branch, and optional show_patch flag
   • Output: JSON with commit count and diff summary

Commit Operations

5. git_commit_history: Get commit history for a branch with optional filtering

   • Input: Repository URL, branch name, max count, author filter, since date, until date, and message grep
   • Output: JSON with commit details

6. git_commits_details: Get detailed information about commits including full messages and diffs

   • Input: Repository URL, branch name, max count, include_diff flag, author filter, since date, until date, and message grep
   • Output: JSON with detailed commit information

7. git_local_changes: Get uncommitted changes in the working directory

   • Input: Local repository path
   • Output: JSON with status information and diffs

Project Structure

git-commands-mcp/
├── src/
│   ├── index.js         # Entry point
│   ├── server.js        # Main server implementation
│   ├── handlers/        # Tool handlers
│   │   └── index.js     # Tool implementation functions
│   └── utils/           # Utility functions
│       └── git.js       # Git-related helper functions
├── package.json
└── readme.md

Implementation Details

• Uses Node.js native modules (crypto, path, os) for core functionality
• Leverages fs-extra for enhanced file operations
• Uses simple-git for Git repository operations
• Implements clean error handling and resource cleanup
• Creates deterministic temporary directories based on repository URL hashes
• Reuses cloned repositories when possible for efficiency
• Modular code structure for better maintainability

Requirements

• Node.js 14.x or higher
• Git installed on the system

Usage

If installed globally via npm:

git-commands-mcp

If installed manually:

node src/index.js

The server runs on stdio, making it compatible with MCP clients.

CI/CD

This project uses GitHub Actions for continuous integration and deployment:

Automatic NPM Publishing

The repository is configured with a GitHub Actions workflow that automatically publishes the package to npm when changes are pushed to the master branch.

Setting up NPM_AUTOMATION_TOKEN

To enable automatic publishing, you need to add an npm Automation token as a GitHub secret (this works even with accounts that have 2FA enabled):

1. Generate an npm Automation token:

   • Log in to your npm account on npmjs.com
   • Go to your profile settings
   • Select "Access Tokens"
   • Click "Generate New Token"
   • Select "Automation" token type
   • Set the appropriate permissions (needs "Read and write" for packages)
   • Copy the generated token

2. Add the token to your GitHub repository:

   • Go to your GitHub repository
   • Navigate to "Settings" > "Secrets and variables" > "Actions"
   • Click "New repository secret"
   • Name: NPM_AUTOMATION_TOKEN
   • Value: Paste your npm Automation token
   • Click "Add secret"

Once configured, any push to the master branch will trigger the workflow to publish the package to npm.

License

MIT License - see the LICENSE file for details.

Links

• GitHub Repository
• NPM Package
• Report Issues

Shared threads will appear here, showcasing real-world applications and insights from the community. Check back soon for updates!