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