mcp-server-grf

中文文档

MCP server for managing Git reference repositories - add, load, and sync reference code from any Git repository.

Overview

mcp-server-grf (Git Reference) is a Model Context Protocol (MCP) server that enables AI assistants to manage Git reference repositories. It allows you to:

• Add any Git repository as a reference code source
• Load reference code into your current project
• Sync loaded reference code to the latest version
• Manage globally cached repositories

Primary Use Case

When an AI assistant needs to reference code implementations from open-source projects, this tool enables quick loading of reference code into the current working directory for the AI to read and learn from.

Features

• Smart URL Parsing - Supports both HTTPS and SSH Git URL formats
• Flexible Repository Matching - Match by full name, owner/repo, or just repo name
• Shallow Clone Optimization - Uses shallow clones by default to save disk space and download time
• Automatic .gitignore Management - Automatically adds loaded reference code to .gitignore
• Subdirectory Loading - Load only specific subdirectories from a repository
• Multi-Workspace Support - Independently manage loading state across different projects
• Sync Status Tracking - Track commit ID changes and support incremental sync

Installation

Using npx (Recommended)

No installation required - run directly with npx:

npx mcp-server-grf

Global Installation

npm install -g mcp-server-grf

Then run:

mcp-server-grf

Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "grf": {
      "command": "npx",
      "args": ["-y", "mcp-server-grf"]
    }
  }
}

Other MCP Clients

For other MCP-compatible clients, configure the server command as:

npx -y mcp-server-grf

Tools Reference

Repository Management

#### grf_add

Add a reference repository to the global cache.

#### grf_list

List all cached repositories.

_No parameters required._

#### grf_get

Get detailed information about a repository.

#### grf_update

Update cached repositories.

#### grf_clean

Clean cached repositories.

#### grf_switch_branch

Switch repository branch.

Loading/Unloading

#### grf_load

Copy reference repository to the current directory.

#### grf_unload

Remove reference code from the project.

#### grf_loaded

List loaded reference code.

Synchronization

#### grf_sync

Sync loaded reference code to the latest version.

#### grf_sync_status

Get sync status of loaded reference code.

Configuration

#### grf_config

Manage global configuration.

Usage Examples

Basic Workflow

1. Add a reference repository:

   grf_add url="https://github.com/expressjs/express"

1. Load reference code into your project:

   grf_load name="express"

1. Check loaded references:

   grf_loaded

1. Sync to latest version:

   grf_sync all=true

1. Remove reference code when done:

   grf_unload name="express"

Load Specific Subdirectory

Load only the lib directory from a repository:

grf_load name="express" subdir="lib"

Quick Load from URL

Load directly from a Git URL without pre-adding:

grf_load name="https://github.com/lodash/lodash" subdir="src"

Check for Updates

Check if updates are available without pulling:

grf_update checkOnly=true

Configuration Options

View/Modify Configuration

# List all configuration
grf_config action="list"

# Get specific configuration
grf_config action="get" key="shallowClone"

# Set configuration
grf_config action="set" key="shallowDepth" value=5

Data Storage

Global Storage

~/.gitreference/
├── config.json           # Global configuration
├── repos-index.json      # Repository index
├── loading-state.json    # Loading state records
└── repos/                # Cached repositories

Project Local Storage

<project>/
├── .gitreference/        # Default loading directory
└── .gitignore            # Automatically adds .gitreference/ entry

Requirements

• Node.js >= 18.0.0
• Git installed and available in PATH

License

MIT