# github-summary-mcp

An MCP server that generates a **daily GitHub work summary** by analysing commits across all repositories the authenticated user owns or contributes to.

Designed for use with **Claude Code**, **Qwen Code**, and the **MCP Inspector**.

---

## Features

- Discovers all repos: owned, collaborated on, and organisation member
- Fetches today's commits (since 00:00 UTC) authored by the authenticated user
- Inspects commit messages and changed files
- Groups and deduplicates commits per repository
- Exposes three MCP tools: `get_daily_summary`, `list_repositories`, `get_repo_commits_today`

---

## Prerequisites

- Python 3.11+
- [uv](https://github.com/astral-sh/uv) package manager
- A GitHub [Personal Access Token](https://github.com/settings/tokens) with `repo` scope

---

## Setup

### 1. Clone the repository

```bash
git clone <repo-url>
cd github-summary-mcp
```

### 2. Install dependencies

```bash
uv sync
```

### 3. Export your GitHub token

```bash
export GITHUB_TOKEN=ghp_your_token_here
```

---

## Running the server

### stdio transport (for Claude Code / Qwen Code)

```bash
uv run server.py
```

### HTTP transport (for MCP Inspector)

Edit `server.py` and change the `mcp.run()` call:

```python
mcp.run(transport="http", host="127.0.0.1", port=8000)
```

Then run:

```bash
uv run server.py
```

---

## Connecting via MCP Inspector

1. Install the inspector:

```bash
npx @modelcontextprotocol/inspector
```

2. Point it at your running server or use it in stdio mode:

```bash
npx @modelcontextprotocol/inspector uv run server.py
```

---

## Connecting to Claude Code

Add the server to your Claude Code MCP configuration (`~/.claude/claude_desktop_config.json` or `.mcp.json` in your project):

```json
{
  "mcpServers": {
    "github-summary": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/github-summary-mcp/server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

---

## Connecting to Qwen Code

Add to your Qwen Code MCP settings:

```json
{
  "mcpServers": {
    "github-summary": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/github-summary-mcp/server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

---

## MCP Tools

### `get_daily_summary`

Generate a complete daily work summary across all repositories.

**No parameters required.**

**Returns:**

```json
{
  "summary": "> Evorgs\n\n* Simplified layout structure in VendorMainLayout\n* Enhanced DashboardPage with better spacing\n\n> BMS\n\n* Work in payment feature\n* Add auto redirection to PayFast checkout page"
}
```

---

### `list_repositories`

List all repositories accessible to the authenticated user.

**No parameters required.**

**Returns:**

```json
{
  "repositories": [
    {
      "full_name": "octocat/Hello-World",
      "name": "Hello-World",
      "owner": "octocat",
      "private": false,
      "default_branch": "main"
    }
  ]
}
```

---

### `get_repo_commits_today`

Get today's commits for a specific repository.

**Parameters:**

| Name        | Type   | Description                                              |
|-------------|--------|----------------------------------------------------------|
| `repo_name` | string | Short name (`Hello-World`) or full `owner/repo` string   |

**Returns:**

```json
{
  "repo": "octocat/Hello-World",
  "commits": [
    {
      "sha": "abc123ef",
      "message": "Fix login redirect bug",
      "files": ["auth/login.py", "tests/test_auth.py"],
      "insertions": 12,
      "deletions": 3,
      "committed_at": "2024-01-15T09:30:00+00:00"
    }
  ],
  "summary": "> Hello-World\n\n* Fix login redirect bug"
}
```

---

## Project Structure

```
github-summary-mcp/
│
├─ pyproject.toml          # uv/hatch project config
├─ README.md
│
├─ server.py               # FastMCP server + tool definitions
├─ github_client.py        # GitHub REST API client (httpx)
├─ summarizer.py           # Commit grouping & formatting
├─ utils.py                # Date helpers, normalizers
│
└─ services/
   └─ commit_service.py    # Orchestration: fetches commits across all repos
```

---

## Environment Variables

| Variable       | Required | Description                                      |
|----------------|----------|--------------------------------------------------|
| `GITHUB_TOKEN` | Yes      | GitHub Personal Access Token with `repo` scope   |

---

## Future Extensions

The codebase is structured for easy extension:

- **LLM summarisation** – replace `summarizer.py` logic with an Anthropic/OpenAI call
- **Slack standup posting** – add a `post_standup` MCP tool in `server.py`
- **Weekly reports** – add a `since` parameter to `CommitService.get_today_commits_all_repos`
- **File-level diff summaries** – the `CommitRecord.files` field already carries filenames; fetch full diffs from `GET /repos/{owner}/{repo}/commits/{sha}`

---

## License

MIT