# ab_mcp — give an AI a folder, not your whole disk

I kept wanting to let Claude help with a project folder — "what's in here?",
"find every TODO", "read me that config" — without giving it the keys to my
entire filesystem. So I wrote this.

It's a tiny [Model Context Protocol](https://modelcontextprotocol.io) server: it
hands an AI assistant a handful of file tools, all locked to **one folder you
choose**. Reading is on by default; writing is off until you say otherwise.
The whole thing is a single, readable `server.py` — so before you trust it, you
can actually read it.

> **Why you might want this:** "AI can read my files" and "AI can rewrite my
> files" are very different levels of trust. This server lets you start with the
> first and opt into the second only when you mean to.

## What it can do

| Tool | What it does |
|------|--------------|
| `list_files(subdir=".")` | List files/folders under the root |
| `read_file(path)` | Read a text file (size-capped) |
| `read_lines(path, start=1, end=0)` | Read a line range — for files too big to read whole |
| `search_files(query, subdir=".", max_results=0)` | Case-insensitive text search across files |
| `find_files(pattern="*", subdir=".")` | Find files by name/glob, e.g. `*.py` |
| `file_stats(path=".")` | Line/word/char counts, or directory size |
| `write_file(path, content)` | Create/overwrite a file — **disabled unless `AB_MCP_ALLOW_WRITE` is set** |

Every path is confined to the **root directory** — requests that try to escape it
(`../../etc/passwd`) are rejected.

## Setup

```bash
cd ab_mcp
python -m venv .venv
source .venv/Scripts/activate      # Windows Git Bash
# .venv\Scripts\activate           # Windows PowerShell/cmd
pip install -r requirements.txt
```

## Try it standalone (dev inspector)

```bash
mcp dev server.py
```

This opens the MCP Inspector in your browser so you can click each tool and see output.

## Run it directly

```bash
python server.py
```

The server speaks **stdio** — it waits for an MCP client to connect. That's normal;
it won't print anything on its own.

## Configuration

Everything is controlled with environment variables — no code edits needed:

| Variable | Default | Purpose |
|----------|---------|---------|
| `AB_MCP_NAME` | `ab_mcp` | Server name advertised to MCP clients |
| `AB_MCP_ROOT` | this project folder | The single folder all tools are confined to |
| `AB_MCP_MAX_BYTES` | `200000` | Max file size (bytes) that `read_file` will read whole |
| `AB_MCP_MAX_RESULTS` | `50` | Default number of search hits before stopping |
| `AB_MCP_LINE_PREVIEW` | `200` | Characters of each matching line shown in search results |
| `AB_MCP_ENCODING` | `utf-8` | Text encoding used to read files |
| `AB_MCP_ALLOW_WRITE` | _(off)_ | Set to `1`/`true`/`yes` to enable the `write_file` tool |
| `AB_MCP_IGNORE` | `.venv,venv,__pycache__,.git,node_modules,.idea` | Comma-separated folders to skip |

Example — point it at any folder, allow larger files, ignore a `dist` dir:

```bash
AB_MCP_ROOT="/path/to/your/folder" \
AB_MCP_MAX_BYTES=500000 \
AB_MCP_IGNORE=".git,dist,build" \
python server.py
```

## Connect it to Claude Desktop

Edit `claude_desktop_config.json`
(`%APPDATA%\Claude\claude_desktop_config.json` on Windows) and add:

Replace the paths with the absolute path to your own clone:

```json
{
  "mcpServers": {
    "ab_mcp": {
      "command": "C:\\path\\to\\ab_mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\ab_mcp\\server.py"],
      "env": {
        "AB_MCP_ROOT": "C:\\path\\to\\the\\folder\\to\\expose"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see the `ab_mcp` tools available in the chat.

## Connect it to Claude Code

```bash
claude mcp add ab_mcp -- /path/to/ab_mcp/.venv/Scripts/python.exe /path/to/ab_mcp/server.py
```

## License

[MIT](LICENSE) — see the LICENSE file. Add your name to the copyright line before publishing.