# Read-only MCP Bridge

A defense-in-depth MCP server that exposes explicitly approved filesystem roots through read-only tools.

## Capabilities

- Read files beneath administrator-approved roots
- List and search approved filesystem trees
- Inspect Git repositories read-only
- Inspect SQLite databases read-only
- Query SQLite using bounded SELECT-style queries
- Inspect and query DuckDB databases read-only
- Add and remove approved roots through an out-of-band administrator CLI
- Mount remote Linux roots through read-only NFS exports

The MCP interface itself cannot grant access to additional roots.

## Security model

Root administration is deliberately separate from MCP access. The MCP client can operate only against roots already present in `config/allowed_roots.yaml`.

Filesystem access includes traversal and symlink escape protections. Git tools are inspection-only. SQLite and DuckDB connections use read-only controls and bounded query execution.

## Requirements

- Linux
- Python 3.12 or newer
- Git
- NFS utilities if remote-root support is used

## Install

```bash
python3 -m venv venv
venv/bin/pip install -r requirements.txt

cp config/allowed_roots.example.yaml config/allowed_roots.yaml
cp config/removed_roots.example.yaml config/removed_roots.yaml
```

Edit `config/allowed_roots.yaml` and add only directories that should be visible through MCP.

Run the server with:

```bash
venv/bin/python scripts/server.py
```

## Root administration

The included `bin/mcp-r` command provides workflows for adding local roots, adding remote read-only roots, and removing approved roots.

Machine-specific locations can be overridden with environment variables. See `config/runtime.env.example`.

## Public repository note

Runtime root registries, secrets, local paths, backups, virtual environments, and machine-specific configuration should never be committed.