repoctx-mcp 0.2.0

Local repository intelligence for coding agents

RepoCtx

Give your coding agent the right files for the task at hand.

RepoCtx scans a local repository and returns a focused context pack: the docs, source files, tests, and import neighbors most relevant to a task like "add retry jitter to webhook delivery" or "refactor auth middleware for OAuth".

It is built for developers using tools like Cursor, Claude Desktop, and Codex who want better results without manually pasting half their repo into chat.

Why Developers Use It

When an AI agent misses the right files, it guesses. RepoCtx reduces that guesswork by surfacing:

• relevant docs like AGENTS.md, README.md, and architecture notes
• relevant source files for the task
• likely related tests
• nearby modules from the local import graph

The result is a compact Markdown pack or JSON payload your agent can use directly.

Start Here

Install RepoCtx with MCP support:

python3 -m pip install "repoctx-mcp[mcp]"

Requires Python 3.11+.

The package name is repoctx-mcp, but the command and module name are still repoctx.

If you use Cursor, start with the Cursor section below.

5-Minute Setup

Cursor

If you use Cursor, this is the default path.

1. Add RepoCtx to your MCP config

Use one of these locations:

• global config: ~/.cursor/mcp.json
• project config: .cursor/mcp.json

You can also add the same server through Cursor's Tools & MCP settings UI, but the JSON file is the most direct copy-paste path.

Add:

{
  "mcpServers": {
    "repoctx": {
      "command": "python3",
      "args": ["-m", "repoctx.mcp_server", "--repo", "/absolute/path/to/your/repo"]
    }
  }
}

Replace /absolute/path/to/your/repo with the repo you want Cursor to understand.

2. Restart Cursor

Cursor loads MCP servers from mcp.json when it starts.

3. Use your agent normally

Ask Cursor to work on a task in that repo. RepoCtx shows up as an MCP tool, and Cursor can call it when it needs context.

What you do not need to do

• You do not need to run python3 -m repoctx.mcp_server ... yourself.
• You do not need to write a custom skill.
• You do not need to manually paste repo files into chat.

Claude Desktop

Claude Desktop can use the same RepoCtx MCP server.

1. Open the Claude Desktop MCP config

In Claude Desktop, open Settings > Developer > Edit Config.

Common config locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

RepoCtx is intended for the Claude Desktop app, not the web app.

2. Add RepoCtx

{
  "mcpServers": {
    "repoctx": {
      "command": "python3",
      "args": ["-m", "repoctx.mcp_server", "--repo", "/absolute/path/to/your/repo"]
    }
  }
}

3. Restart Claude Desktop

After restart, Claude can call RepoCtx as a tool when it needs repository context.

Codex

Codex supports MCP in both the CLI and the IDE extension. They share the same config.

Option A: Add RepoCtx to config.toml

Use one of these locations:

• global config: ~/.codex/config.toml
• project config: .codex/config.toml in a trusted project

Add:

[mcp_servers.repoctx]
command = "python3"
args = ["-m", "repoctx.mcp_server", "--repo", "/absolute/path/to/your/repo"]

Option B: Add it from the Codex CLI

codex mcp add repoctx -- python3 -m repoctx.mcp_server --repo /absolute/path/to/your/repo

You can inspect configured servers with:

codex mcp list

If you use the Codex IDE extension, it will read the same MCP configuration.

What To Ask Your Agent

Once RepoCtx is configured, you can ask your client to do normal development work, for example:

• "Add retry jitter to webhook delivery."
• "Refactor the auth middleware to support OAuth."
• "Find the files involved in syncing local env with Vercel."
• "Show me the tests related to the billing webhook flow."

RepoCtx helps the agent find the most relevant files before it starts editing.

What RepoCtx Returns

For a task like "add retry jitter to webhook delivery", RepoCtx returns a focused pack like:

## Summary
Identified 2 docs, 2 files, 1 test, and 1 graph neighbor relevant to
'add retry jitter to webhook delivery'.

## Relevant Docs
- AGENTS.md — matches: retry, webhook
- docs/WEBHOOKS.md — matches: retry, webhook
  > Webhook delivery retries should use exponential backoff with jitter.

## Relevant Files
- src/webhook/retry_policy.py — matches: retry
  > def compute_retry_delay(): ...

## Related Tests
- tests/test_retry_policy.py — stem match + imports retry_policy.py

## Graph Neighbors
- src/webhook/delivery.py — imported by retry_policy.py

Use --format json if you want structured output instead of Markdown.

FAQ

Do I need to run a server manually?

No, not in Cursor, Claude Desktop, or Codex. Those clients start the RepoCtx MCP server for you from the config you provide.

You would only run python3 -m repoctx.mcp_server --repo ... yourself if you were debugging the server directly.

Do I need to write a skill?

No. RepoCtx is an MCP server, not a skill. Once your client is configured, it becomes an available tool the agent can call.

Do I need one config per repo?

Not necessarily.

• Use a global config if you want RepoCtx available everywhere.
• Use a project config if you want RepoCtx tied to one repo and shared with teammates.

Can I test RepoCtx from the terminal first?

Yes. RepoCtx also works as a normal CLI.

repoctx "refactor the auth middleware to support OAuth" --repo ./my-app

CLI Usage

If you want to use RepoCtx outside an MCP client:

python3 -m pip install repoctx-mcp
repoctx "your task" --repo /path/to/repo

JSON output:

repoctx "your task" --repo /path/to/repo --format json

Module entry point:

python3 -m repoctx "your task" --repo /path/to/repo

CLI flags:

Flag	Description
--repo PATH	Repository root to inspect
--format markdown|json	Output format
--verbose	Enable debug logging
--debug-scores	Print heuristic/embedding/final score breakdown
--no-embeddings	Disable embedding retrieval for this query

Embedding-Based Retrieval (v2)

RepoCtx v2 adds optional local embeddings using Qwen3-Embedding-0.6B to improve recall when your task description doesn't match filenames or code tokens.

Embeddings are additive — the existing heuristic ranking (token overlap, doc priority, graph expansion) still runs. Embedding similarity scores are blended in as a boost, and files with strong semantic similarity can surface even without token overlap.

Install embedding dependencies

pip install "repoctx-mcp[embeddings]"

This installs sentence-transformers and numpy. The model weights (~1.2 GB) are downloaded automatically on first use.

Build the embedding index

repoctx index --repo /path/to/repo

This scans the repository, embeds every file (with enriched metadata), and writes the index to .repoctx/embeddings/ inside the repo. Add .repoctx/ to your .gitignore.

Query with hybrid retrieval

Once the index exists, all queries automatically use hybrid retrieval:

repoctx "refactor payment processing" --repo /path/to/repo

To see the score breakdown:

repoctx query "refactor payment processing" --repo /path/to/repo --debug-scores

Update a single file

After editing a file, you can re-embed just that file:

repoctx update src/billing/invoice.py --repo /path/to/repo

Rebuild the index from scratch

repoctx rebuild --repo /path/to/repo

How hybrid scoring works

For each candidate file, the final score is:

final_score = heuristic_score + embedding_weight × max(0, cosine_similarity)

Default embedding_weight is 12.0. Files with cosine similarity above 0.3 bypass heuristic filters, so semantically relevant files surface even without keyword matches.

Fallback behavior

If embedding dependencies are not installed or no index exists, RepoCtx silently falls back to pure heuristic retrieval. The MCP tool contract is unchanged — get_task_context(task) always works.

Supported Files

Category	Extensions
Code	.py, .ts, .tsx, .js, .jsx
Config	.json, .yaml, .yml
Docs	.md, .mdc

Import graph expansion works for Python (import, from) and JavaScript/TypeScript (import, require).

Telemetry

RepoCtx writes local JSONL telemetry to ~/.repoctx/telemetry/ by default. Task text and repo identifiers are hashed before storage. Set REPOCTX_TELEMETRY_DIR to change the storage location.

Development

git clone https://github.com/gald33/repoctx.git
cd repoctx
python3 -m pip install -e ".[dev]"
python3 -m pytest -q

To develop with embedding support:

python3 -m pip install -e ".[dev,embeddings]"

License

MIT