# personal-repo-mcp

A self-hosted, multi-repository MCP server for AI agents. It gives an agent a persistent Git workspace on your own VPS, with controlled access to administrator-approved repositories and normal Git operations.

**Version 1.0.0 — MVP**

## Quick install

The quickest way to run the MVP is the Docker Compose deployment described in [`docs/QUICK_INSTALL.md`](docs/QUICK_INSTALL.md).

In short:

```bash
git clone https://github.com/jsilvanus/personal-repo-mcp.git
cd personal-repo-mcp
cp .env.example .env
mkdir -p config repositories secrets
cp config/repositories.example.json config/repositories.json
printf '%s\n' "$(openssl rand -hex 32)" > secrets/mcp_token
printf '%s\n' 'your-github-pat' > secrets/github_pat
chmod 600 secrets/mcp_token secrets/github_pat
docker compose up -d --build
```

Before starting the container, edit `.env`, `config/repositories.json`, and `secrets/github_pat`. The MCP token is generated locally above; keep it secret. The default Compose deployment binds the MCP endpoint to `127.0.0.1:8000`, so an HTTPS reverse proxy is required for remote access.

For the full production checklist, see [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md).

## Core idea

The administrator controls **what repositories the agent may access**. The agent controls **which allowed repositories it actually clones**.

```text
Administrator
    |
    | mcp-config add repo jsilvanus/*
    v
repositories.json (allow-list)
    |
    v
MCP server
    |
    +-- clone_repository("jsilvanus/project")
    |
    v
persistent workspace
```

The workspace is an ordinary Git repository. GitHub remains an upstream remote; the MCP server is the persistent local workspace and control boundary.

## MCP help resources

The server provides modular, MCP-native operational documentation. Start with:

```text
mcp://help/index
```

Focused topics are available at:

```text
mcp://help/repositories
mcp://help/files
mcp://help/git
mcp://help/chain-command
mcp://help/resources
```

The help resources are intentionally separate from `tools/list`: the MCP tool list remains the authoritative API surface, while the help resources provide progressive-disclosure workflow guidance for agents.

## Features

- Persistent multi-repository workspaces
- Administrator-controlled repository allow-list
- GitHub PAT authentication for Git operations
- Streamable HTTP transport
- File reads, line-range reads, writes, line edits, search, and patches
- Git status, diff, history, branches, fetch/pull/push, merge/rebase, and conflict handling
- Single-repository `chain_command` for composing operations
- MCP resources for system, repository, Git, and individual file state
- Resource subscriptions and change notifications
- Secret scrubbing from MCP output
- Git submodule safeguards
- Docker deployment
- Optional OAuth 2.1 + OIDC single sign-on for OAuth MCP clients
- Optional **hot-git** backend for persistent, treeless repository reads and edits

## Git backends

The existing Git command backend remains the default compatibility path.

The new hot-git backend can be enabled with:

```bash
export PERSONAL_REPO_MCP_GIT_BACKEND=hot-git
```

The dependency is declared in `pyproject.toml` and is installed as a normal Python package; it is **not a Git submodule**.

The backend boundary is deliberately small:

```text
MCP tool
   |
   v
Repository backend
   |
   +-- Git backend
   |
   +-- hot-git backend
          |
          +-- persistent object reader
          +-- treeless object/tree/commit edits
          +-- Git CAS ref publication
```

When hot-git is selected, each repository gets one lazily-created long-lived backend instance. It is shared by callers and closed with the server. This keeps the persistent `cat-file --batch` reader alive without creating one process per MCP request.

The first integrated operations are:

- `git_read_file` — read a file from a ref or commit through the configured backend;
- `git_edit` — perform a multi-file treeless edit and publish it with an expected-ref CAS.

The existing Git command tools remain available during the migration. Operations that depend on a working tree or Git's higher-level merge/rebase machinery continue to use the compatibility backend.

### Chained edits

`git_edit` returns the resulting commit. A caller can use that commit as the expected base for the next edit:

```text
A(base=X) -> commit A
B(base=A) -> commit B
C(base=B) -> commit C
```

This is the foundation for integrating the backend with `chain_command` without allowing concurrent writers to silently overwrite each other.

## OAuth and single sign-on (optional)

Set `OIDC_ISSUER` (plus `OIDC_CLIENT_ID`, `PERSONAL_REPO_MCP_PUBLIC_URL` and `JWT_SECRET`) to let OAuth MCP clients such as ChatGPT or Claude connect: the server then runs an embedded OAuth authorization server (CIMD client ids, PKCE, refresh tokens) whose sign-in step goes through your OIDC identity provider, e.g. authentik. The server is an OIDC relying party, never an OpenID provider. The static bearer token keeps working. There are no local accounts: the identity provider's application policy decides who may sign in, and everyone who can sign in and approve gets full access. With `OIDC_ISSUER` unset nothing changes. Setup and all variables: [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md#oauth-and-single-sign-on-oidc).

## Deployment

Configure the host with `mcp-config`, then start the single Docker deployment:

```bash
mcp-config pat
mcp-config add repo jsilvanus/*
docker compose up -d --build
```

`mcp-config add repo` changes only the administrator allow-list. It does **not** clone repositories. The agent clones an allowed repository through the MCP when needed.

For hot-git mode, the normal Python dependency installation installs the library. No submodule checkout is required.

See [`docs/QUICK_INSTALL.md`](docs/QUICK_INSTALL.md) for the shortest setup path and [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) for persistent storage, credentials, HTTPS, and configuration details.

## License

EUPL-1.2