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.

| Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ---------------------------------------- | | url | string | Yes | - | Git repository URL (HTTPS or SSH format) | | name | string | No | - | Custom repository name | | branch | string | No | - | Specify branch | | shallow | boolean | No | true | Use shallow clone | | depth | number | No | 1 | Shallow clone depth |

grf_list

List all cached repositories.

No parameters required.

grf_get

Get detailed information about a repository.

| Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------- | | name | string | Yes | Repository name (supports full name or short name) |

grf_update

Update cached repositories.

| Parameter | Type | Required | Default | Description | | ----------- | ------- | -------- | ------- | ---------------------------------------------- | | name | string | No | - | Repository name (updates all if not specified) | | checkOnly | boolean | No | false | Only check for updates, don't pull |

grf_clean

Clean cached repositories.

| Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ------------------------------ | | name | string | No | - | Repository name to delete | | all | boolean | No | false | Delete all cached repositories |

grf_switch_branch

Switch repository branch.

| Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------- | | name | string | Yes | Repository name | | branch | string | Yes | Target branch |

Loading/Unloading

grf_load

Copy reference repository to the current directory.

| Parameter | Type | Required | Default | Description | | ------------------ | ------- | -------- | --------------------------- | --------------------------------------- | | name | string | Yes | - | Repository name, short name, or Git URL | | targetPath | string | No | .gitreference/<repo-path> | Target path | | subdir | string | No | - | Only copy specified subdirectory | | updateGitignore | boolean | No | true | Update .gitignore | | branch | string | No | - | Specify branch (only for Git URL) | | workingDirectory | string | No | Current directory | Working directory |

grf_unload

Remove reference code from the project.

| Parameter | Type | Required | Default | Description | | ------------------ | ------- | -------- | ----------------- | ------------------------- | | name | string | No | - | Repository name | | all | boolean | No | false | Remove all reference code | | workingDirectory | string | No | Current directory | Working directory |

grf_loaded

List loaded reference code.

| Parameter | Type | Required | Default | Description | | ------------------ | ------- | -------- | ----------------- | -------------------------------------------------- | | workingDirectory | string | No | Current directory | Working directory (returns all if not specified) | | all | boolean | No | false | Return loading entries for all working directories |

Synchronization

grf_sync

Sync loaded reference code to the latest version.

| Parameter | Type | Required | Default | Description | | ------------------ | ------- | -------- | ----------------- | --------------------------------- | | entryId | string | No | - | Entry ID (specify entry to sync) | | all | boolean | No | false | Sync all entries | | force | boolean | No | false | Force sync (ignore version check) | | workingDirectory | string | No | Current directory | Working directory |

grf_sync_status

Get sync status of loaded reference code.

| Parameter | Type | Required | Default | Description | | ------------------ | ------ | -------- | ----------------- | ----------------- | | workingDirectory | string | No | Current directory | Working directory |

Configuration

grf_config

Manage global configuration.

| Parameter | Type | Required | Description | | --------- | --------------------- | -------- | ---------------------------------------- | | action | string | Yes | Operation type: get, set, or list | | key | string | No | Configuration key (required for get/set) | | value | string/number/boolean | No | Configuration value (required for set) |

Usage Examples

Basic Workflow

1. Add a reference repository:

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

2. Load reference code into your project:

   grf_load name="express"

3. Check loaded references:

   grf_loaded

4. Sync to latest version:

   grf_sync all=true

5. 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

| Key | Type | Default | Description | | --------------- | ------- | -------- | ------------------- | | defaultBranch | string | "main" | Default branch name | | shallowClone | boolean | true | Use shallow clone | | shallowDepth | number | 1 | Shallow clone depth |

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