# Repository Inspector MCP

A small read-only MCP server for inspecting a local source repository from an AI client.
The project is designed as a portfolio and learning example. It exposes a narrow set of
tools instead of giving the model unrestricted shell access.

## Features

- `list_files`: list source files below the configured root;
- `read_file`: read UTF-8 text files with a size limit;
- `search_in_repo`: search text files and return matching lines;
- path traversal protection and symlink rejection;
- sensitive-file filtering for `.env` and private-key filenames;
- ignored generated directories such as `.git`, `.venv`, `vendor`, and `node_modules`;
- deterministic unit tests for the security boundaries.

## Requirements

- Python 3.10 or newer;
- an MCP-compatible client such as Codex.

## Local setup

```bash
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
pytest
```

Run the server over MCP stdio:

```bash
MCP_REPO_ROOT=/absolute/path/to/target/repository repo-inspector-mcp
```

The server is intentionally read-only. It does not execute shell commands, write files,
or expose files outside `MCP_REPO_ROOT`.

## Codex configuration

Use the example in `docs/codex-config.toml`. Replace the executable path and the repository
root with absolute paths. After restarting the client, the following tools are available:

- `list_files(path, max_depth)`;
- `read_file(path, max_chars)`;
- `search_in_repo(query, path, max_results)`.

## Design notes

The MCP layer in `server.py` is intentionally thin. Path validation, file-size limits,
binary-file detection, and search behavior live in the dependency-free `core.py`, which
makes the security-sensitive behavior easy to test without starting an MCP client.

## License

MIT