RepoScout MCP

RepoScout is a tiny OCI-containerized MCP server that gives Codex or another harness a read-only repository scout before broad manual repo exploration.

This repository is the canonical source for the reposcout-mcp Python package, the reposcout and reposcout-mcp commands, and the OCI image.

The FastContext model does not run in this container. RepoScout mounts the current checkout at /workspace, exposes a single MCP tool, and lets the model use only bounded GLOB, GREP, and READ operations against that workspace.

Codex starts MCP command
  -> scripts/codex-reposcout.sh detects the current git root
  -> Podman starts with that root mounted read-only at /workspace
  -> RepoScout exposes find_context
  -> Codex receives compact file-line citations

Tool

The MCP server exposes one v0 tool:

find_context(query: string, max_citations?: number)

Return shape:

{
  "repo": {
    "source": "workspace",
    "root": "/workspace"
  },
  "model": "FastContext-1.0-4B-RL-mlx-4Bit",
  "query": "Find where wakeword false positives are logged",
  "summary": "Found 3 relevant citation range(s).",
  "citations": [
    {"path": "modules/ears/src/wakeword.ts", "start": 80, "end": 145}
  ],
  "raw_final_answer": "<final_answer>...",
  "turns": 4,
  "used_native_tool_calls": true,
  "warning": null
}

Install

Install the Python package from this repository:

python -m venv .venv
.venv/bin/pip install -e '.[test]'
.venv/bin/pytest

Published package installation will be documented after the first registry release. Until then, do not assume pip install reposcout-mcp resolves from PyPI.

Build

podman build -t reposcout-mcp:latest .

Published image:

forge.elephanthand.com/turnercore/reposcout-mcp:latest

Backend Modes

LM Studio / OpenAI-Compatible

Use FASTCONTEXT_BACKEND=openai for normal /v1/chat/completions servers such as LM Studio.

From the host, LM Studio is usually:

export FASTCONTEXT_BACKEND=openai
export FASTCONTEXT_BASE_URL=http://localhost:1234/v1
export FASTCONTEXT_MODEL=FastContext-1.0-4B-RL-mlx-4Bit

When launched through scripts/codex-reposcout.sh, localhost is rewritten to host.containers.internal for the container.

Manual Podman preflight:

export FASTCONTEXT_BACKEND=openai
export FASTCONTEXT_BASE_URL=http://host.containers.internal:1234/v1
export FASTCONTEXT_MODEL=FastContext-1.0-4B-RL-mlx-4Bit

podman run --rm -it \
  -v "$PWD:/workspace:ro" \
  -e FASTCONTEXT_BACKEND \
  -e FASTCONTEXT_BASE_URL \
  -e FASTCONTEXT_MODEL \
  reposcout-mcp:latest \
  reposcout "Find where wakeword false positives are logged and added to training data"

Expected output:

<final_answer>
modules/ears/src/wakeword.ts:80-145
apps/hud/src/actions/mark_false_positive.ts:1-70
</final_answer>

Elephant Hand AI Gateway

Use FASTCONTEXT_BACKEND=gateway for the native FastContext loop API. This mode does not call /v1/chat/completions; it starts a loop, sends each RepoScout turn to the loop, then stops the loop when done.

export FASTCONTEXT_BACKEND=gateway
export FASTCONTEXT_GATEWAY_URL=http://100.66.204.27:41800
export FASTCONTEXT_MODEL=FastContext
export FASTCONTEXT_TOKEN=local-dev-token

The client calls:

POST /v1/fastcontext/loops
POST /v1/fastcontext/loops/{loop_id}/turn?wait=true
POST /v1/fastcontext/loops/{loop_id}/stop

Manual Podman preflight:

podman run --rm -it \
  -v "$PWD:/workspace:ro" \
  -e FASTCONTEXT_BACKEND=gateway \
  -e FASTCONTEXT_GATEWAY_URL=http://100.66.204.27:41800 \
  -e FASTCONTEXT_MODEL=FastContext \
  -e FASTCONTEXT_TOKEN=local-dev-token \
  reposcout-mcp:latest \
  reposcout "Find where tool calls are registered"

Codex MCP Config

Point Codex at the wrapper script, not directly at Podman:

[mcp_servers.reposcout]
command = "/path/to/reposcout/scripts/codex-reposcout.sh"
startup_timeout_sec = 20
tool_timeout_sec = 180
enabled = true

The wrapper resolves the host workspace path in this order:

1. REPOSCOUT_REPO_ROOT
2. Git root of CODEX_WORKSPACE_DIR
3. Git root of the current working directory
4. Current working directory

It then runs:

podman run --rm -i \
  -v "${HOST_REPO_ROOT}:/workspace:ro" \
  -e REPOSCOUT_DEFAULT_REPO=/workspace \
  -e FASTCONTEXT_BACKEND \
  -e FASTCONTEXT_BASE_URL \
  -e FASTCONTEXT_GATEWAY_URL \
  -e FASTCONTEXT_MODEL \
  forge.elephanthand.com/turnercore/reposcout-mcp:latest

LM Studio environment:

FASTCONTEXT_BACKEND=openai
FASTCONTEXT_BASE_URL=http://localhost:1234/v1
FASTCONTEXT_MODEL=FastContext-1.0-4B-RL-mlx-4Bit

AI gateway environment:

FASTCONTEXT_BACKEND=gateway
FASTCONTEXT_GATEWAY_URL=http://100.66.204.27:41800
FASTCONTEXT_MODEL=FastContext
FASTCONTEXT_TOKEN=local-dev-token

Optional:

FASTCONTEXT_API_KEY=...
REPOSCOUT_REPO_ROOT=/path/to/repo
REPOSCOUT_MAX_TURNS=6
REPOSCOUT_MAX_GREP_RESULTS=80
REPOSCOUT_MAX_READ_LINES=220
REPOSCOUT_MAX_OBSERVATION_CHARS=12000
REPOSCOUT_MAX_TOOL_CALLS_PER_TURN=8
REPOSCOUT_MAX_LINE_CHARS=1000

Safety

• Local repositories are mounted read-only.
• The internal scout has no shell or write tools.
• Path resolution must stay inside /workspace.
• Common dependency/build directories are ignored.
• Secret-looking paths such as .env, private keys, and certificate/key files are blocked by default.

Remote clone mode is intentionally not part of v0. Local mount mode sees the same checkout Codex is editing, including uncommitted changes.