# git-simple-read-mcp

**Repository Path**: 573363031/git-simple-read-mcp

## Basic Information

- **Project Name**: git-simple-read-mcp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-01
- **Last Updated**: 2026-02-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Git Simple Read MCP

A Model Context Protocol (MCP) server for Git read operations with workspace management.

## Features

This MCP server provides the following tools for Git repository read operations:

### Workspace Management
- **clone_repository**: Clone a Git repository into the managed workspace
- **list_workspace_repositories**: List all repositories in the workspace
- **remove_repository**: Remove a repository from the workspace

**Security**: All operations are restricted to repositories within the specified workspace directory.

### Repository Information
- **get_repository_info**: Get basic repository information including:
  - Commit count
  - Last update date
  - Current branch
  - License file detection
  - README content (first 50 lines)
  - Remote URL

### Repository Operations
- **pull_repository**: Execute `git pull` on the specified repository

### Branch Management
- **list_branches**: List all branches in the repository (supports pagination)
- **switch_branch**: Switch to a specified branch

### File Operations
- **search_files**: Search for files containing specified keywords with enhanced filtering
  - AND/OR logic support
  - File pattern filtering (include/exclude patterns)
  - Context lines around matches
  - Filename and content search
- **list_files**: List files in specified directory with enhanced information
  - Recursive expansion
  - File pattern filtering (include/exclude patterns) 
  - Character count and line count for each file
  - File size information
- **get_file_content**: Get the content of files
  - Single file or multiple files in one request
  - Start reading from specified line (`start_line`)
  - Line numbers always displayed for AI-friendly output
  - File metadata included (path, line range, total lines)
  - Individual error handling for each file
  - Minimal output format for reduced token usage
- **get_readme_files**: Find all README files in repository
  - Supports recursive search
  - Returns file metadata (size, modification time, line count)

## Installation

1. Clone this repository:
```bash
git clone <repository-url>
cd git-simple-read-mcp
```

2. Build the project:
```bash
go build .
```

## Usage

### Standalone Server

Start the MCP server using stdio transport (default):
```bash
./git-simple-read-mcp mcp --workspace ./my-workspace
```

Start the MCP server using HTTP transport:
```bash
./git-simple-read-mcp mcp --transport http --port 8080 --workspace ./my-workspace
```

The workspace directory will be created automatically if it doesn't exist. All Git operations will be restricted to repositories within this workspace.

## Remote MCP Usage

To use this as a remote MCP server:

### 1. Build and Start HTTP Server
```bash
# Build the server
go build .

# Start HTTP server (default port 8080)
./git-simple-read-mcp mcp --transport http --port 8080 --workspace ./workspace

# Or use the provided script
./start-server.sh ./workspace 8080
```

### 2. Configure MCP Client

Add to your MCP client configuration (e.g., Claude Code):

```json
{
  "mcpServers": {
    "git-remote": {
      "url": "http://localhost:8080/mcp",
      "description": "Git Simple Read MCP Server for repository read operations"
    }
  }
}
```

### 3. Remote Access

For remote access across network:

```bash
# Start server on all interfaces
./git-simple-read-mcp mcp --transport http --port 8080 --workspace ./workspace --host 0.0.0.0

# Then connect from client with
# "url": "http://your-server-ip:8080/mcp"
```

**Security Note**: When exposing over network, consider adding authentication, HTTPS, and firewall rules.

### 4. Docker Deployment

Run with Docker:

```bash
# Build the image
docker build -t git-simple-read-mcp .

# Run the container
docker run -d \
  --name git-simple-read-mcp \
  -p 8080:8080 \
  -v $(pwd)/workspace:/workspace \
  git-simple-read-mcp

# Or use docker-compose
docker-compose up -d
```

### 5. Production Deployment

For systemd-based systems:

```bash
# Copy files to production location
sudo cp git-simple-read-mcp /opt/git-simple-read-mcp/
sudo cp git-simple-read-mcp.service /etc/systemd/system/

# Create user and directories
sudo useradd -r -s /bin/false git-mcp
sudo mkdir -p /var/lib/git-simple-read-mcp/workspace
sudo chown -R git-mcp:git-mcp /var/lib/git-simple-read-mcp

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable git-simple-read-mcp
sudo systemctl start git-simple-read-mcp
```

### Tool Parameters

Each tool accepts JSON parameters:

#### clone_repository
```json
{
  "url": "https://github.com/user/repository.git",
  "name": "my-repo"
}
```

#### list_repositories
```json
{}
```

#### remove_repository
```json
{
  "name": "repository-name"
}
```

#### get_repository_info
```json
{
  "repository": "my-repo"
}
```

#### pull_repository
```json
{
  "repository": "my-repo"
}
```

#### list_branches
```json
{
  "repository": "my-repo",
  "limit": 10
}
```

#### switch_branch
```json
{
  "repository": "my-repo",
  "branch": "branch-name"
}
```

#### list_commits
```json
{
  "repository": "my-repo",
  "limit": 20
}
```

**Parameters:**
- `limit`: Maximum number of commits to return, default: 20

#### get_commit_diff
```json
{
  "repository": "my-repo",
  "commit_hash": "a1b2c3d4"
}
```

**Parameters:**
- `commit_hash`: The hash of the commit to get the diff for.

#### search_files
```json
{
  "repository": "my-repo",
  "keywords": ["keyword1", "keyword2"],
  "search_mode": "and",
  "include_filename": false,
  "context_lines": 0,
  "include_patterns": ["*.go", "*.js"],
  "exclude_patterns": ["*_test.go", "vendor/*"],
  "limit": 20
}
```

**Parameters:**
- `keywords`: Array of search terms
- `search_mode`: "and" (all keywords) or "or" (any keyword), default: "and"
- `include_filename`: Search in filenames too, default: false
- `context_lines`: Lines of context around matches, default: 0
- `include_patterns`: File patterns to include (glob format)
- `exclude_patterns`: File patterns to exclude (glob format)
- `limit`: Maximum results, default: 20

#### list_files
```json
{
  "repository": "my-repo",
  "directory": "src",
  "recursive": true,
  "include_patterns": ["*.go", "*.js"],
  "exclude_patterns": ["*_test.go", "node_modules/*"],
  "limit": 50
}
```

**Parameters:**
- `directory`: Target directory, default: "."
- `recursive`: Include subdirectories, default: false
- `include_patterns`: File patterns to include (glob format)
- `exclude_patterns`: File patterns to exclude (glob format)
- `limit`: Maximum files to return, default: 50

**Output includes:**
- File path and name
- Directory flag
- File size (bytes/KB/MB)
- Character count (for text files)
- Line count (for text files)
- Modification time

#### get_file_content

**Single file:**
```json
{
  "repository": "my-repo",
  "file_path": "src/main.go",
  "start_line": 1,
  "max_lines": 100
}
```

**Multiple files:**
```json
{
  "repository": "my-repo",
  "file_paths": ["src/main.go", "src/utils.go", "config.json"],
  "start_line": 50,
  "max_lines": 100
}
```

**Parameters:**
- `file_path`: Single file path (for backward compatibility)
- `file_paths`: Array of file paths (for multiple files)
- `start_line`: Line number to start reading from (1-based), default: 1
- `max_lines`: Maximum lines per file, default: 100

**Output format (AI-optimized):**
```
[src/main.go L1-50/200]
   1: package main
   2:
   3: func main() {
...
```

Format: `[path L{start}-{end}/{total}]` followed by line-numbered content.

**Multiple file output:**
```
[src/main.go L1-50/200]
   1: package main
...

[src/utils.go L1-30/30]
   1: package main
...

[config.json ERR:file not found]
```

#### get_readme_files
```json
{
  "repository": "my-repo",
  "recursive": true
}
```

**Parameters:**
- `recursive`: Search subdirectories, default: false

## Enhanced Features Examples

### File Pattern Filtering

**List only Go files:**
```json
{
  "repository": "my-repo",
  "include_patterns": ["*.go"]
}
```

**List all files except tests and vendor:**
```json
{
  "repository": "my-repo",
  "exclude_patterns": ["*_test.go", "vendor/*", "node_modules/*"]
}
```

**Search for functions only in source files:**
```json
{
  "repository": "my-repo", 
  "keywords": ["func"],
  "include_patterns": ["src/*.go", "lib/*.go"],
  "exclude_patterns": ["*_test.go"]
}
```

### Character Count and File Information

The `list_files` tool now returns detailed file information:
```
📄 main.go (2.1 KB, 156 chars, 8 lines)
📄 utils.go (1.5 KB, 98 chars, 5 lines)
📁 src/
📄 src/app.js (856 bytes, 45 chars, 3 lines)
```

### Multiple File Content Retrieval

```json
{
  "repository": "my-repo",
  "file_paths": ["main.go", "config.json", "README.md"],
  "start_line": 1,
  "max_lines": 50
}
```

Returns content for all files with individual error handling (AI-optimized minimal format):
```
[main.go L1-10/10]
   1: package main
   2:
   3: func main() {}

[config.json ERR:file not found]

[README.md L1-5/5]
   1: # My Project
   2: This is a sample project
```

### Reading from Specific Line

```json
{
  "repository": "my-repo",
  "file_path": "large_file.go",
  "start_line": 100,
  "max_lines": 50
}
```

Output:
```
[large_file.go L100-149/500]
 100: func processData() {
 101:     // Processing logic
...
```

## Error Handling

All tools return appropriate error messages when:
- Repository path is invalid or not a Git repository
- Git commands fail
- File operations encounter errors
- Parameters are missing or invalid

## Pagination

Several tools support pagination to prevent large outputs:
- `list_branches`: Limit number of branches returned
- `search_files`: Limit search results (default: 20)
- `list_files`: Limit file listing (default: 50)
- `get_file_content`: Limit lines read (default: 100)

## Security Considerations

- This server performs read-only operations on Git repositories
- The `switch_branch` operation modifies the working directory but doesn't commit changes
- The `pull_repository` operation updates the repository from its remote origin
- Always ensure the server has appropriate permissions for the target repositories

## Dependencies

- Go 1.23.0 or later
- [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk)
- [Cobra CLI](https://github.com/spf13/cobra)
- Git command-line tools

## License

This project is provided as-is for educational and development purposes.