Repo Context Forge

Repo Context Forge is a local-first MCP-based repository intelligence platform. It inspects local codebases through deterministic and security-restricted analyzers, then produces compact, source-grounded context packs for coding agents such as Codex, Claude Code, and Cursor.

Current prerelease: v0.2.0-alpha.1 - Local Source-Grounded Repository Agent

Why This Exists

Coding agents often spend substantial time rebuilding the same repository map, symbol index, dependency context, and current-state understanding. Repo Context Forge makes that evidence reusable while preserving repository-relative file and line references.

The platform operates locally. It does not send repository content to a hosted model, execute analyzed code, or install dependencies from analyzed projects.

Related MCP server: ProjectBrain

What It Generates

.context-output/<workspace>/
├── manifest.json
├── project-overview.md
├── repository-map.md
├── architecture.md
├── development-guide.md
├── current-state.md
├── risks-and-debt.md
├── agent-handoff.md
├── symbols.json
├── dependencies.json
├── integrations.json
├── git-state.json
└── bundles/

agent-handoff.md is the primary compact repository index. Bundles under bundles/ gather bounded evidence for a specific objective. Generated context is an index, not a substitute for inspecting source files before editing them.

Key Capabilities

• Secure named workspaces with path containment, denied-pattern, symlink, binary, and file-size controls.

• Deterministic repository trees, metadata, and bounded UTF-8 file reads.

• Lexical text, regex, definition, reference, environment-name, and config-file search without shell commands.

• Static Python AST symbols, imports, references, callers, callees, and bounded symbol source ranges without importing analyzed modules.

• Direct dependency declarations, Python internal import graphs, cycle detection, and rule-based integration evidence.

• Allowlisted read-only local Git status, history, revision comparison, file history, and changed-symbol analysis.

• Atomic, hash-validated context packs, freshness checks, and deterministic task bundles.

Architecture

flowchart TD
    A[CLI / MCP Clients] --> B[Application Factories]
    B --> C[Repository Intelligence Services]
    C --> C1[Repository Access]
    C --> C2[Code Search]
    C --> C3[Python Symbols]
    C --> C4[Dependency Analysis]
    C --> C5[Read-Only Git Analysis]
    C --> C6[Context Pack Generation]
    C1 --> R[Read-Only Mounted Repositories]
    C2 --> R
    C3 --> R
    C4 --> R
    C5 --> R
    C6 --> O[Writable Context Output]

Typer and FastMCP are adapters. Domain services remain independent of both, and application factories construct explicit dependencies without scanning a repository during import.

Quick Start

Prerequisites are Docker Desktop or a compatible Docker Engine with Docker Compose. Host Python, uv, Ruff, mypy, and pytest are not required.

git clone https://github.com/negativexq/repo-context-forge.git
cd repo-context-forge

docker compose build repo-context-forge
docker compose run --rm repo-context-forge uv run rcf doctor
docker compose run --rm repo-context-forge uv run pytest

The development image uses Python 3.12, pinned uv, the committed uv.lock, a non-root user, and the project installed in editable mode.

Mounting Local Repositories

Copy the public examples and replace only the individual host repository paths:

cp docker-compose.local.example.yml docker-compose.local.yml
cp config.docker.example.yaml config.docker.yaml

Example mapping:

Host:      /Users/example/projects/service-a
Container: /workspaces/service-a

Compose mounts each analyzed repository with :ro; configuration always uses the container path. Never mount an entire home directory, SSH keys, cloud credentials, Docker credentials, or global Git configuration.

docker compose \
  -f docker-compose.yml \
  -f docker-compose.local.yml \
  run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml workspace list

Missing configured mounts fail with a safe invalid-workspace-root error.

Generating a Context Pack

docker compose \
  -f docker-compose.yml \
  -f docker-compose.local.yml \
  run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  context generate service-a

Validate integrity and inspect freshness without regenerating:

docker compose -f docker-compose.yml -f docker-compose.local.yml run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml context validate service-a

docker compose -f docker-compose.yml -f docker-compose.local.yml run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml context freshness service-a

Generated output persists through the writable ./.context-output:/app/.context-output mount. Analyzed repository mounts remain read-only. On macOS Docker Desktop, generated files are visible through the normal bind-mounted project directory and retain Docker Desktop's mapped host ownership behavior.

Creating a Task Bundle

docker compose -f docker-compose.yml -f docker-compose.local.yml run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  context bundle service-a inspect-service \
  --objective "Understand the service and repository interaction" \
  --term service \
  --term repository

Task bundles rank validated seed files, lexical matches, Python symbols, static calls and imports, module dependencies, relevant tests, and available local Git evidence. They do not copy the complete repository.

For a self-contained public demonstration, run:

make docker-demo

This analyzes the synthetic read-only fixture under examples/demo-repository, validates its pack, creates bundles/understand-service.md, and lists generated artifacts.

MCP Servers

Each FastMCP server runs independently over stdio and accepts --config:

Repository MCP tools are read-only, accept repository-relative paths rather than host filesystem paths, and publish model-oriented parameter guidance in their generated schemas. Glama server metadata is provided in glama.json.

Example startup:

docker compose run --rm -i repo-context-forge \
  uv run rcf-mcp-context --config config.docker.yaml

Repository tools: list_workspaces, get_repository_tree, find_files, read_file, read_file_range, get_file_metadata.

Code-search tools: search_text, search_regex, find_definitions, find_references, find_environment_variables, find_config_files.

Symbol tools: list_symbols, get_symbol, find_symbol_definitions, find_symbol_references, get_module_imports, get_symbol_source, get_callers, get_callees.

Dependency tools: get_external_dependencies, get_internal_dependency_graph, find_dependency_cycles, find_external_integrations, get_module_dependencies, find_dependency_usage.

Git tools: get_repository_state, get_git_status, get_recent_commits, get_changed_files, compare_revisions, get_file_history, get_recently_changed_symbols.

Context tools: generate_context_pack, validate_context_pack, get_context_pack_freshness, inspect_context_manifest, create_task_bundle, list_context_artifacts, read_context_artifact.

CLI Reference

All repository-specific commands use one global option:

rcf --config CONFIG workspace list
rcf --config CONFIG repo tree WORKSPACE
rcf --config CONFIG repo find WORKSPACE PATTERN
rcf --config CONFIG repo read WORKSPACE RELATIVE_PATH
rcf --config CONFIG repo read-range WORKSPACE RELATIVE_PATH START END
rcf --config CONFIG repo metadata WORKSPACE RELATIVE_PATH

rcf --config CONFIG search text WORKSPACE QUERY
rcf --config CONFIG search regex WORKSPACE PATTERN
rcf --config CONFIG search definitions WORKSPACE NAME
rcf --config CONFIG search references WORKSPACE NAME
rcf --config CONFIG search env WORKSPACE
rcf --config CONFIG search config-files WORKSPACE

rcf --config CONFIG symbols list WORKSPACE
rcf --config CONFIG symbols find WORKSPACE NAME
rcf --config CONFIG symbols get WORKSPACE QUALIFIED_NAME
rcf --config CONFIG symbols references WORKSPACE NAME
rcf --config CONFIG symbols imports WORKSPACE RELATIVE_PATH
rcf --config CONFIG symbols source WORKSPACE QUALIFIED_NAME
rcf --config CONFIG symbols callers WORKSPACE NAME
rcf --config CONFIG symbols callees WORKSPACE QUALIFIED_NAME

rcf --config CONFIG dependencies list WORKSPACE
rcf --config CONFIG dependencies graph WORKSPACE
rcf --config CONFIG dependencies cycles WORKSPACE
rcf --config CONFIG dependencies integrations WORKSPACE
rcf --config CONFIG dependencies module WORKSPACE MODULE_OR_PATH
rcf --config CONFIG dependencies usage WORKSPACE DEPENDENCY

rcf --config CONFIG git state WORKSPACE
rcf --config CONFIG git status WORKSPACE
rcf --config CONFIG git log WORKSPACE
rcf --config CONFIG git changed-files WORKSPACE
rcf --config CONFIG git compare WORKSPACE BASE TARGET
rcf --config CONFIG git file-history WORKSPACE RELATIVE_PATH
rcf --config CONFIG git changed-symbols WORKSPACE

rcf --config CONFIG context generate WORKSPACE
rcf --config CONFIG context validate WORKSPACE
rcf --config CONFIG context freshness WORKSPACE
rcf --config CONFIG context manifest WORKSPACE
rcf --config CONFIG context list WORKSPACE
rcf --config CONFIG context read WORKSPACE ARTIFACT
rcf --config CONFIG context bundle WORKSPACE NAME --objective OBJECTIVE

rcf --version and rcf doctor do not inspect repositories. Workspace registration mutations remain service-level and in-memory; the CLI exposes only workspace list rather than misleading non-persistent add/remove commands.

Security Model

• Every repository path is resolved and checked for containment after symlink resolution.

• POSIX and Windows absolute paths, traversal, external symlinks, denied files, directories-as-files, oversized files, binary data, and invalid UTF-8 are rejected.

• Denied patterns such as .env, *.pem, *.key, .git, node_modules, and virtual environments take precedence over analysis patterns.

• Repository-wide scans are deterministic and bounded. Explicit denied reads fail rather than returning misleading empty results.

• Analyzed modules and dependency manifests are never imported or executed.

• Git is the only subprocess boundary. It uses argument lists, shell=False, a controlled environment, time/output bounds, and allowlisted read-only commands.

• Context output has a separate containment policy, fixed artifact names, atomic replacement, and validated SHA-256 manifest hashes.

• The container has no Docker socket, privileged mode, host networking, SSH forwarding, cloud credentials, or writable analyzed-repository mounts.

See SECURITY.md for vulnerability reporting.

Deterministic Analysis and Limitations

Lexical search may include comments and strings and does not resolve symbol identity. Python AST analysis excludes comments and strings but cannot fully resolve dynamic dispatch, reflection, aliases, or dynamic imports. Only Python has AST symbol support.

Dependency intelligence parses direct declarations from pyproject.toml, requirements files, setup.cfg, static literal setup.py, and package.json. It does not resolve transitive dependencies. Docker and Compose are parsed only as infrastructure evidence. Integration detection is explicit and rule-based.

Git analysis is local and read-only. It returns metadata and changed ranges, not full patches or remote state. Context classifications and architectural interpretations are marked as inferences. Packs can become stale after source, Git, configuration, or generator changes. The alpha local agent remains deterministic at its security boundaries but model behavior is not guaranteed. No embeddings, semantic search, remote API, or web UI are included.

Experimental Local LLM Provider

The v0.2.0-alpha.1 prerelease adds local model connectivity, normal chat, structured tool calls, and a bounded read-only repository agent. It does not enrich context packs or permit repository mutation.

Start Ollama

Ollama is optional and pinned under the Compose llm profile. Its host port is bound only to loopback.

docker compose --profile llm up -d ollama

Pull a Model

Model downloads are always explicit and may require several gigabytes.

docker compose --profile llm exec ollama \
  ollama pull qwen3:4b

The equivalent Make targets are make docker-ollama-up, make docker-model-pull MODEL=qwen3:4b, and make docker-model-list.

Configure the Model

Container commands use the Compose service hostname:

models:
  default: qwen-local
  providers:
    qwen-local:
      provider: ollama
      model: qwen3:4b
      base_url: http://ollama:11434/v1
      api_key: ollama
      enabled: true
      tool_calling: true
      context_window: 32768
      request_timeout_seconds: 120
      temperature: 0
      max_output_tokens: 2048

api_key: ollama is the conventional non-secret placeholder for the local OpenAI-compatible endpoint. Real keys are excluded from public summaries and must never be committed.

Check Model Health

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml models health qwen-local

Run a Chat Test

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  models chat qwen-local "Reply with the word READY."

Run a Tool-Call Test

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml models tool-test qwen-local

The test asks for find_symbol_definitions with synthetic arguments and only prints the validated call. Tool-calling reliability varies by model, especially for smaller models.

Host vs Container URLs

Use http://ollama:11434/v1 from the application container. Use http://127.0.0.1:11434/v1 for a host-side CLI. Container configuration must not use localhost, and Compose does not use host networking.

Current Limitations

• Model pulling is manual and never occurs during application startup or tests.

• Only Ollama's OpenAI-compatible local endpoint is supported.

• Agent execution is stateless, sequential, and read-only; context-pack model enrichment is not implemented.

• Provider output and tool arguments remain untrusted and strictly validated.

• Live tests are opt-in: RCF_RUN_OLLAMA_TESTS=1 uv run pytest -m ollama_live.

Experimental MCP Client Runtime

The MCP client runtime starts explicitly configured local servers over stdio, discovers and namespaces their tools, validates call arguments, and normalizes bounded results. MCP commands remain available for manual inspection; the agent uses the same manager and validation boundary for model-requested calls. The six configured servers currently expose 40 tools in total.

Configure MCP Servers

config.docker.example.yaml defines the six existing servers using explicit argument lists. Configuration loading starts no process. Only stdio transport is accepted, namespaces must be unique, and disabled servers are skipped.

mcp:
  default_tool_timeout_seconds: 20
  startup_timeout_seconds: 15
  shutdown_timeout_seconds: 5
  max_tool_result_chars: 30000
  servers:
    symbols:
      transport: stdio
      command: uv
      args: [run, rcf-mcp-symbols, --config, /app/config.docker.yaml]
      enabled: true
      namespace: symbols
      allowed_tools: ["*"]

MCP server stdout is reserved for protocol messages. Diagnostics must use stderr. Child processes receive a conservative runtime environment plus only explicitly configured values.

Inspect Configured Servers

This reads configuration without starting child processes:

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml mcp servers

Check MCP Health

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml mcp health

Health checks eagerly initialize enabled servers, report independent failures, and close every session before returning.

Discover Tools

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml mcp tools

Canonical names use <namespace>.<tool>, such as symbols.find_symbol_definitions. Ordering is deterministic and denied tools are omitted.

Inspect a Tool Schema

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  mcp tool symbols.find_symbol_definitions

Call a Tool Manually

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  mcp call symbols.find_symbol_definitions \
  --arguments '{"workspace":"demo","name":"RepositoryService"}'

Arguments must be a JSON object and are validated against the discovered schema without coercion before one request is sent. MCP error results produce a non-zero status. Resources and URLs in results are never fetched.

Export LLM Tool Definitions

docker compose run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml mcp llm-tools

OpenAI-compatible function names use reversible namespace__tool encoding, for example symbols__find_symbol_definitions; canonical MCP routing continues to use symbols.find_symbol_definitions. This command does not contact a model.

Current Limitations

Only local stdio child processes are supported. There is no HTTP/SSE transport, automatic retry, remote server discovery, or conversation persistence. Tool configuration is trusted local input, while tool schemas, arguments, and results are untrusted and bounded. Existing repository and read-only Git policies continue to apply.

Experimental Local Repository Agent

The development branch includes a stateless, read-only loop that connects the local model provider to discovered MCP tools. It does not modify repositories, run shell commands, or permit the model to change process configuration. The default policy exposes 38 read-only tools and excludes the two context-output-writing tools.

Start Ollama

docker compose --profile llm up -d ollama
docker compose --profile llm exec ollama ollama list

Model downloads remain an explicit user action; see the local-provider section above.

Configure the Agent

The agent configuration bounds iterations, calls, messages, results, answers, and source references. default_model falls back to models.default when omitted. Parallel calls are disabled. The selected workspace must exist before the provider or MCP processes start.

agent:
  default_model: qwen-local
  max_tool_iterations: 8
  max_tool_calls_per_iteration: 4
  max_total_tool_calls: 20
  max_total_tool_result_chars: 120000
  require_sources_for_repository_claims: true
  allow_parallel_tool_calls: false
  duplicate_tool_call_limit: 2

Ask a Repository Question

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  agent ask demo \
  "Where is WidgetRepository defined?"

Inspect the Tool Trace

docker compose --profile llm run --rm repo-context-forge \
  uv run rcf --config config.docker.yaml \
  agent trace demo \
  "Explain how the demo service reaches the repository layer."

The trace contains bounded iteration, tool-name, status, duration, and result size metadata. It omits prompts, complete tool results, API keys, child stderr, and raw provider payloads.

Restrict Servers and Tools

Request filters only reduce locally configured permissions:

uv run rcf --config config.docker.yaml agent ask demo \
  "Where is WidgetRepository defined?" \
  --server symbols \
  --tool symbols.find_symbol_definitions

Use agent tools demo with the same filters to inspect the resulting LLM-facing tool set without calling a model.

Source-Grounding Behavior

Repository citations are checked against source paths and line ranges observed in normalized MCP results. Unsupported citations are reported rather than accepted. If a small model omits citations but valid evidence was collected, the runtime appends a bounded Sources used list deterministically; this list does not claim that every source supports every sentence.

Read-Only Security Model

The workspace is fixed for one run and injected only into tools that declare a workspace parameter. Conflicting workspace arguments are rejected. Calls are schema-validated, sequential, bounded, and routed only through discovered local tools. context.generate_context_pack and context.create_task_bundle are excluded from the default agent policy because they write context output.

Current Limitations

Small-model tool selection and citation quality vary. Analysis remains lexical or static where documented and does not resolve dynamic runtime behavior. There is no conversation persistence, automatic repository editing, cloud provider, semantic retrieval, evaluation framework, or multi-agent orchestration.

The opt-in live test never downloads a model and is skipped by default:

RCF_RUN_OLLAMA_AGENT_TESTS=1 uv run pytest -m ollama_agent_live

Development

make docker-build
make docker-format
make docker-lint
make docker-typecheck
make docker-test
make docker-check
make docker-doctor

Local uv commands remain available, but Docker is the supported validation environment. See CONTRIBUTING.md and AGENTS.md for engineering and source-grounding rules.

Test and Quality Status

The v0.2.0-alpha.1 prerelease was verified in Docker:

Python 3.12
206 tests passed
2 opt-in Ollama tests skipped
87% coverage
Ruff passed
mypy passed

The public CI workflow repeats formatting, linting, strict typing, and tests with coverage on pushes and pull requests.

Roadmap

Future directions are documented in docs/ROADMAP.md. They are plans, not commitments. Evaluation remains the next milestone after this alpha.

License

Repo Context Forge is available under the MIT License.