mcp-repo-context

A small, zero-runtime-dependency Model Context Protocol server that gives a coding agent read-only, bounded context from a local Git repository.

It is intentionally narrower than a shell:

• paths are confined to one --root
• secret-like and binary files are skipped
• every result has a size/entry/line limit
• git is invoked without a shell
• the server exposes 5 focused tools, not arbitrary command execution

This is useful when an MCP client needs to understand a repository without being handed the whole filesystem.

What it is not

This is not a sandbox, a code executor, or a replacement for Git. It reads files with the permissions of the user who starts it. Run it under an account with the least privilege you can afford, and keep real credentials out of the repository.

It deliberately does not support write operations, shell commands, URL fetching, package installation, or arbitrary binary reads.

Tools

All tools are exposed through MCP tools/list and tools/call.

Security model

The server applies several independent checks:

1. Root confinement — absolute paths, drive-letter paths, and .. components are rejected before resolution. The resolved path must remain under --root.
2. Symlink refusal — symlinked files and directories are not followed or read.
3. Secret filtering — .env files (except .env.example/.sample/.template), private-key files, .ssh, .aws, .gnupg, .docker, common credential files, and key/keystore suffixes are skipped.
4. Redaction — output is best-effort redacted for private keys, GitHub tokens, AWS access keys, bearer tokens, URL credentials, and common password=, token:, and api_key= assignments.
5. Bounded output — file bytes, line lengths, result counts, tree depth, tree entries, diff lines, and total output characters have hard caps.
6. No shell — git_diff uses an argument list and validates the revision string. It checks that the revision resolves to a commit before running the diff.

Redaction is defense in depth, not a guarantee. A secret that does not match a known pattern can still be returned. Use repository permissions and secret-management tools as the primary control.

Requirements

• Python 3.8+
• Git on PATH only if you use git_diff
• No third-party runtime packages

Quick start

From this checkout:

python -m mcp_repo_context --root C:\path\to\your\repo

Or install the console script:

python -m pip install -e . --no-build-isolation
mcp-repo-context --root C:\path\to\your\repo

--no-build-isolation keeps the install working on older Python 3.8/pip setups that do not fetch a newer setuptools into a temporary build environment.

The process speaks newline-delimited JSON-RPC over stdin/stdout. Logs go to stderr so stdout stays protocol-clean.

Try it without an MCP client

On Windows PowerShell:

Get-Content .\examples\session.jsonl | python -m mcp_repo_context --root .

On macOS/Linux:

python -m mcp_repo_context --root . < examples/session.jsonl

The session initializes, lists tools, and calls project_summary.

Claude Desktop configuration

Add this to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "repo-context": {
      "command": "python",
      "args": [
        "-m",
        "mcp_repo_context",
        "--root",
        "C:\\path\\to\\your\\repo"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Use the absolute path to the Python interpreter that has this package installed if python is ambiguous. The exact configuration file location varies by client and operating system; check your MCP client's documentation.

Any MCP client that supports stdio servers can use the same command and arguments.

Example protocol exchange

Request:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{}}}

Response (abridged):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {"tools": {"listChanged": false}},
    "serverInfo": {"name": "mcp-repo-context", "version": "0.1.0"}
  }
}

Call a tool:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"src/app.py","start_line":1,"end_line":20}}}

The result is a normal MCP text content block. Tool-level failures (unknown tool, invalid path, binary file, missing Git) set isError to true and return a short readable message. Parse/validation failures use JSON-RPC error codes (-32700, -32600, -32601, -32602).

Configuration

Project layout

mcp_repo_context/
  config.py       settings and bounds
  errors.py       ToolError
  paths.py        root confinement, ignore and secret rules, text reads
  redact.py       best-effort credential redaction
  service.py      the five tools and their JSON schemas
  server.py       MCP stdio loop and JSON-RPC dispatch
  __main__.py     python -m entry point
tests/
  support.py      temporary-repository helpers
  test_paths.py   path, ignore, binary, and secret rules
  test_redact.py  redaction patterns
  test_service.py tool behavior and limits
  test_protocol.py JSON-RPC methods and errors
  test_stdio.py   real subprocess handshake
  test_cli.py     argument parsing
examples/
  mcp_config.json client configuration example
  session.jsonl   raw stdio handshake
setup.py          Python 3.8-compatible packaging shim
pyproject.toml    PEP 517 build configuration
Dockerfile        optional stdio container
SECURITY.md       vulnerability-reporting policy

Tests

python -m unittest discover -v

Current suite: 40 tests (39 pass + 1 skipped on this Windows machine). The skipped test creates a symlink pointing outside the repository; Windows refused the symlink without Developer Mode/administrator privileges. On Linux/macOS the same test runs.

The end-to-end suite launches the real process, sends a JSON-RPC handshake over stdin, and checks that stdout contains only protocol messages.

CI runs the suite on Python 3.8, 3.9, 3.10, 3.11, and 3.12 via .github/workflows/tests.yml.

Design notes

• SQLite/vector search was intentionally not added. This project is about bounded context and MCP behavior; a local text search is enough for the stated surface.
• No third-party SDK. Implementing the JSON-RPC framing directly keeps the server easy to audit and run in restricted environments.
• Secret filtering happens in the file iterator, not only at the tool boundary. repo_tree, search_text, and project_summary therefore do not enumerate secret files, while read_file and git_diff still reject them explicitly.
• Fail closed for paths, fail readable for tools. Invalid input is an error; a missing optional Git executable is a tool error, not a crash.

Known limitations

• Text search is literal and line-oriented, not regex, glob, or semantic search.
• There is no authentication, TLS, or remote transport; this is a local stdio process.
• The secret denylist is not exhaustive. A repository can still contain sensitive text in a normal .md or .py file.
• The symlink test is skipped on Windows when symlink creation is unavailable.
• The server was tested with its own subprocess harness, not against every third-party MCP client.
• A single process serves one client. Multi-client deployment is out of scope.

License

MIT. See LICENSE.