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

Core idea

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

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:

mcp://help/index

Focused topics are available at:

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 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:

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:

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:

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.

Deployment

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

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 the deployment documentation in docs/ for persistent storage, credentials, HTTPS, and configuration details.

License

EUPL-1.2