# MCP Server for git-quick-stats

This folder contains a small MCP server that exposes git-quick-stats commands as MCP tools.

## Setup

Install `uv` first (one-time):

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
```

```bash
cd mcp-server
uv venv .venv
uv sync --dev
```

Or using Make:

```bash
make install
```

This installs:
- Runtime dependencies from `pyproject.toml`
- Development tools (including Black) from the `dev` dependency group

## Run

```bash
uv run -m src.server
```

The server uses stdio transport, so configure your MCP client to launch this command.

On first tool execution, the server automatically downloads `git-quick-stats`
into `.mcp-tools/git-quick-stats` inside this project if the script is not
already present at project root.

To pin a specific upstream branch/tag/commit for downloads, set:

```bash
export GIT_QUICK_STATS_REF=<ref>
```

## Example MCP Client Config

```json
{
  "mcpServers": {
    "git-quick-stats": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/git-quick-stats/mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}
```

## VS Code Config

Add one of the following entries to your VS Code MCP settings depending on your OS.

### Windows (native Python/uv)

```json
{
  "mcpServers": {
    "git-quick-stats": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\absolute\\path\\to\\git-quick-stats\\mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}
```

### Windows (WSL Ubuntu)

```json
{
  "mcpServers": {
    "git-quick-stats": {
      "command": "wsl.exe",
      "args": [
        "-d",
        "Ubuntu",
        "uv",
        "run",
        "--directory",
        "/home/your-user/projects/git-quick-stats/mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}
```

### Linux

```json
{
  "mcpServers": {
    "git-quick-stats": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/git-quick-stats/mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}
```

### macOS

```json
{
  "mcpServers": {
    "git-quick-stats": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/your-user/path/to/git-quick-stats/mcp-server",
        "-m",
        "src.server"
      ]
    }
  }
}
```

## Make Targets

```bash
make help
make bootstrap-uv
make install
make run
make format
make format-check
```

## Docker Compose

Run the MCP server with Docker Compose:

```bash
docker compose up --build
```

Or via Make:

```bash
make docker-up
make docker-logs
make docker-down
```

## Usage Notes

- Set `repo_path` to the git repository you want to inspect.
- Some options need extra values, which should be passed using tool arguments:
  - `author` for options that need `_GIT_AUTHOR`
  - `branch` for options that need `_GIT_BRANCH`
  - `tag` for options that need `_GIT_TAG`
- The `--new-contributors` option prompts for a date in the shell script. Use `stdin_input` with one date line, for example: `2025-01-01\n`.

## AI Output Example

Example tool call from an AI assistant:

```json
{
  "tool": "run_git_quick_stats",
  "arguments": {
    "option": "--new-contributors",
    "repo_path": "/absolute/path/to/git-quick-stats",
    "stdin_input": "2025-01-01\n"
  }
}
```

Example tool result:

```json
{
  "ok": true,
  "exit_code": 0,
  "stdout": "New contributors since 2025-01-01:\\n\\n     1  example.user@example.com\\n...",
  "stderr": ""
}
```

Example AI response to user:

```text
New contributors report generated successfully using stdin date input (2025-01-01). I can also run the same report for another date range if you want.
```