# mcp-server-grf

[中文文档](./README_CN.md)

[![npm version](https://img.shields.io/npm/v/mcp-server-grf.svg)](https://www.npmjs.com/package/mcp-server-grf)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/mcp-server-grf.svg)](https://nodejs.org)

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)](https://modelcontextprotocol.io/) 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:

```bash
npx mcp-server-grf
```

### Global Installation

```bash
npm install -g mcp-server-grf
```

Then run:

```bash
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`

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

### Other MCP Clients

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

```bash
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