# Local Git MCP Server

A **local Model Context Protocol (MCP) server** for interacting with Git repositories. This server extends the `mcp_server_git` with custom tools for **listing repository directories** and **viewing file contents**, making it easier to navigate and inspect codebases programmatically.

---

## ✅ Features

- **Custom Tools**:
  - `list_repo_dir`: Recursively list files and directories in a Git repository. If no path is provided, it lists the root directory.
  - `view_repo_file`: Read and return the contents of a specific file in the repository.

- **Git Integration**: Inherits all standard Git operations from `mcp_server_git` (e.g., `git_status`, `git_diff`, `git_log`, etc.).

- **Flexible Configuration**: Supports environment variables for repository path configuration.

- **MCP Compatibility**: Works with any MCP-compatible client (e.g., [Model Context Protocol clients](https://github.com/modelcontextprotocol/spec)).

---

## 🛠️ Prerequisites

Before running the server, ensure the following are installed:

### 1. **Python 3.8+**
   - Download: [Python Official Website](https://www.python.org/downloads/)
   - Verify installation:
     ```bash
     python --version
     ```

### 2. **pip (Python Package Manager)**
   - Ensure `pip` is installed and up-to-date:
     ```bash
     python -m pip install --upgrade pip
     ```

### 3. **Required Python Packages**
   Install the dependencies using `pip`:
   ```bash
   pip install starlette uvicorn mcp-server-git
   ```

### 4. **Git**
   - Download: [Git Official Website](https://git-scm.com/downloads)
   - Verify installation:
     ```bash
     git --version
     ```

### 5. **Target Git Repository**
   - Ensure the repository you want to interact with is **cloned locally** on your machine.
   - By default, the server uses the path specified in the `TARGET_REPO` environment variable. If not set, it defaults to:
     ```
     C:\Users\bpweathe\code\SCIP\scipai
     ```

---

## 🚀 Installation & Setup

### Step 1: Clone the Repository
```bash
git clone https://github.com/bpweatherill/local-git-mcp.git
cd local-git-mcp
```

### Step 2: Install Dependencies
```bash
pip install -r requirements.txt
```

> **Note**: If `requirements.txt` does not exist, install the required packages manually:
> ```bash
> pip install starlette uvicorn mcp-server-git
> ```

### Step 3: Configure the Target Repository
Set the `TARGET_REPO` environment variable to point to your local Git repository:

#### **Windows (PowerShell)**
```powershell
$env:TARGET_REPO = "C:\path\to\your\repo"
```

#### **macOS/Linux (Terminal)**
```bash
export TARGET_REPO="/path/to/your/repo"
```

> **Tip**: If you don’t set `TARGET_REPO`, the server will default to `C:\Users\bpweathe\code\SCIP\scipai`.

---

## 🏃 Running the Server

Start the MCP server using the following command:

```bash
python mcp_server.py
```

The server will start on:
- **Host**: `localhost`
- **Port**: `8808`

You should see output similar to:
```
INFO:     Uvicorn running on http://localhost:8808 (Press CTRL+C to quit)
```

---

## 🛠️ Using the Server

### Connecting with an MCP Client
Once the server is running, you can connect to it using any MCP-compatible client. Here’s how to test it:

#### **1. List Root Directory**
Call the `list_repo_dir` tool with no arguments to list the root of the repository:
```json
{
  "method": "tools/call",
  "params": {
    "name": "list_repo_dir",
    "arguments": {}
  }
}
```

#### **2. List a Subdirectory**
Pass a relative path to list the contents of a subdirectory:
```json
{
  "method": "tools/call",
  "params": {
    "name": "list_repo_dir",
    "arguments": {
      "path": "docs/clients"
    }
  }
}
```

#### **3. View a File**
Use the `view_repo_file` tool to read a file:
```json
{
  "method": "tools/call",
  "params": {
    "name": "view_repo_file",
    "arguments": {
      "path": "README.md"
    }
  }
}
```

#### **4. Standard Git Tools**
The server also supports all standard Git tools from `mcp_server_git`. For example:
```json
{
  "method": "tools/call",
  "params": {
    "name": "git_status",
    "arguments": {}
  }
}
```

---

## 📡 API Endpoints

The server exposes the following endpoints:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | SSE endpoint for streaming server events |
| `/` | POST | Messages endpoint for MCP tool calls |
| `/sse` | GET | Alternative SSE endpoint |
| `/messages` | POST | Alternative messages endpoint |
| `/mcp` | GET/POST | Unified MCP endpoint (SSE for GET, messages for POST) |

---

## 🔧 Custom Tools

### 1. `list_repo_dir`
**Description**: Lists files and directories in a repository path.

**Parameters**:
- `path` (optional): Relative path of the subdirectory to list. If omitted, lists the root directory.

**Example Output**:
```
Items inside 'docs/clients':
- copilot-byok.md
- pageassist.md
- openai-api.md
```

---

### 2. `view_repo_file`
**Description**: Reads and returns the complete text contents of a file.

**Parameters**:
- `path` (required): Relative path of the file to view.

**Example Output**:
```
# README.md
This is the content of the README file...
```

---

## 📜 Standard Git Tools

The server inherits all tools from `mcp_server_git`, including:
- `git_status`: Show working tree status.
- `git_diff`: Show changes between branches or commits.
- `git_log`: Show commit history.
- `git_add`: Stage files for commit.
- `git_commit`: Commit changes to the repository.
- `git_branch`: List branches.
- `git_reset`: Unstage changes.

For a full list, call the `tools/list` method after connecting to the server.

---

## 🧪 Testing

To verify the server is working correctly, you can use a tool like `curl` or Postman to send a test request:

### Example `curl` Request
```bash
curl -X POST http://localhost:8808/messages \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
```

**Expected Response**:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_repo_dir",
        "description": "Lists files and items inside a specific sub-folder of the repository.",
        "inputSchema": { ... }
      },
      {
        "name": "view_repo_file",
        "description": "Reads and returns the complete text contents of a specific file.",
        "inputSchema": { ... }
      },
      {
        "name": "git_status",
        "description": "Shows the working tree status.",
        "inputSchema": { ... }
      }
    ]
  }
}
```

---

## 🐛 Troubleshooting

### Common Issues

#### **1. Server Fails to Start**
- **Cause**: Missing dependencies or incorrect Python version.
- **Solution**: Ensure Python 3.8+ and all required packages are installed:
  ```bash
  pip install starlette uvicorn mcp-server-git
  ```

#### **2. Repository Not Found**
- **Cause**: The `TARGET_REPO` path is incorrect or the repository does not exist.
- **Solution**: Set `TARGET_REPO` to the correct local path:
  ```bash
  # Windows (PowerShell)
  $env:TARGET_REPO = "C:\path\to\your\repo"
  
  # macOS/Linux
  export TARGET_REPO="/path/to/your/repo"
  ```

#### **3. Permission Denied**
- **Cause**: The server does not have read access to the repository.
- **Solution**: Ensure the repository is accessible and the server has read permissions.

#### **4. Timeouts**
- **Cause**: The server takes too long to respond.
- **Solution**: Check if the `mcp_server_git` subprocess is running correctly. Restart the server if needed.

---

## 📚 Example Use Cases

### **1. Navigate a Codebase**
```json
// List the root directory
{
  "method": "tools/call",
  "params": {
    "name": "list_repo_dir",
    "arguments": {}
  }
}

// List the 'src' directory
{
  "method": "tools/call",
  "params": {
    "name": "list_repo_dir",
    "arguments": {
      "path": "src"
    }
  }
}

// View a file
{
  "method": "tools/call",
  "params": {
    "name": "view_repo_file",
    "arguments": {
      "path": "src/main.py"
    }
  }
}
```

---

### **2. Check Git Status and Diffs**
```json
// Check Git status
{
  "method": "tools/call",
  "params": {
    "name": "git_status",
    "arguments": {}
  }
}

// Show unstaged changes
{
  "method": "tools/call",
  "params": {
    "name": "git_diff_unstaged",
    "arguments": {}
  }
}
```

---

## 🔒 Security Notes

- The server **only allows access to files within the `TARGET_REPO` directory**. Attempts to access files outside this path will result in a "Path out of bounds" error.
- **Never expose this server to untrusted networks** without proper authentication and authorization.

---

## 📜 License

This project is **open-source** and licensed under the [MIT License](LICENSE).

---

## 🤝 Contributing

Contributions are welcome! Feel free to:
- Report bugs or suggest features by [opening an issue](https://github.com/bpweatherill/local-git-mcp/issues).
- Submit pull requests with improvements.

---

## 📞 Support

For questions or issues:
- Check the [GitHub Issues](https://github.com/bpweatherill/local-git-mcp/issues) for known problems.
- Open a new issue if you encounter unexpected behavior.

---

## 🏷️ Tags

`mcp-server`, `git`, `python`, `starlette`, `uvicorn`, `model-context-protocol`