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

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

Run the server over MCP stdio:

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