MCP server wrapping Microsoft FastContext with request-scoped MLX inference on Apple Silicon.
Loads the fine-tuned rubybear/FastContext-1.0-4B-SFT-mlx-4bit-g32 model via mlx_lm in a disposable worker — no external HTTP server or API keys. A single fastcontext_explore call replaces what would otherwise be many sequential Read/Glob/Grep calls.
The runtime dependency is pinned to the original installed revision 788342a5c1f5ffbd9280fdbc813cc6bdb0024db4 in the preserved upstream fork, because the original upstream URL is no longer accessible.
# 1. Install the setup skill
npx skills add rubybear-lgtm/fastcontext@fastcontext-setup -g -y
# 2. In your AI coding tool (Claude Code, OpenCode, or Codex CLI), say:
# "Install FastContext"The agent follows the skill, runs the install script, and registers the MCP server with your detected tool(s). After restart, fastcontext_explore is available.
Prefer running the installer yourself?
curl -fsSL https://raw.githubusercontent.com/rubybear-lgtm/fastcontext/main/scripts/install.sh | bashOnce installed, your AI agent can call fastcontext_explore:
fastcontext_explore(query="Find authentication middleware and session handling", work_dir="/absolute/path/to/repository", max_turns=4)
| Parameter | Default | Range | Description |
|---|---|---|---|
query |
(required) | — | Natural-language description of what to find |
max_turns |
4 |
1–10 | Exploration turns (more = deeper search) |
work_dir |
Server launch directory | Absolute directory | Repository/worktree to search; supply explicitly on each call |
# Parsed registration and lightweight server import; no model loading:
"$HOME/.cache/fastcontext/venv/bin/python" -m fastcontext_mcp.verify --tool codex
# Real MCP handshake and tool discovery:
"$HOME/.cache/fastcontext/venv/bin/python" -m fastcontext_mcp.verify --tool codex --connect
# Optional model inference check, using an existing absolute repository path:
"$HOME/.cache/fastcontext/venv/bin/python" -m fastcontext_mcp.verify --tool codex --inference --work-dir /absolute/path/to/repositoryChoose claude, opencode, or codex for the relevant registration. Inference completion does not guarantee citation accuracy.
The installer’s --update flag reinstalls the package without deleting the venv and refreshes already installed FastContext skills. Add --install-skills to install both skills, --from-source to use current source, or --repair-config to explicitly reset FastContext launch fields while preserving other entry options. Reconnect the client after changes. Older release wheels missing the current diagnostic APIs fall back to current source.
| Value | Use case |
|---|---|
| 2 | Quick lookup, single file |
| 4 (default) | Standard exploration |
| 6–8 | Deep exploration, large codebase |
| 10 | Exhaustive cross-cutting search |
"Find all database migration files and the schema definition for the users table"
"Locate the API route handlers for /api/v2/users and their request validation"
"Find error handling patterns: custom error classes, error middleware, and error logging"
"Locate the CLI entry point and trace the command registration pattern"
"Find all places where environment variables are read and how they're validated"
FastContext returns exploration steps and file:line citations:
## Exploration steps
- [turn 1] Glob **/*.py
- [turn 1] Grep 'def authenticate' in src/
- [turn 2] Read src/auth/middleware.py
- [turn 2] Read src/auth/session.py
## Result
src/auth/middleware.ts:15-42 (JWT validation middleware)
src/auth/session.ts:8-31 (Session store implementation)
src/auth/routes.ts:120-156 (Login route handler)
The engine accepts citations only for existing, unchanged source lines actually displayed by Read or content search. It strips model-written descriptions and rejects unverified final citations after a bounded correction opportunity. If only some citations verify at the end of the budget, it returns those with an explicit partial-result notice. Read the cited source to assess relevance and meaning before relying on it or editing files. A shell cd does not retarget a running MCP connection; pass work_dir explicitly.
- Unfamiliar code areas — before editing files not yet explored
- Cross-cutting concerns — finding all files related to a feature
- Architecture discovery — understanding module connections
- Dependency tracing — finding callers or implementors of a function
- Already-explored files — context is in the conversation
- Single known file — direct Read is faster
- Simple keyword search — a single Grep suffices
FastContext is a two-part system:
┌─────────────────────────────────────────────────────────────┐
│ AI agent (Claude Code / OpenCode / Codex CLI) │
│ │ │
│ ├── reads SKILL.md ──▶ knows when/how to call the tool │
│ │ │
│ └── calls fastcontext_explore ──┐ │
│ │ │
└────────────────────────────────────│────────────────────────┘
│ stdio (MCP protocol)
▼
┌─────────────────────────────────────────────────────────────┐
│ fastcontext-mcp (long-running Python process) │
│ │ │
│ ├── starts a model worker only for an exploration │
│ │ │
│ └── worker exits after Read / Glob / Grep agent loop │
│ returns file:line citations │
└─────────────────────────────────────────────────────────────┘
| Part | What it is | What it does |
|---|---|---|
MCP server (fastcontext-mcp) |
Lightweight connection spawning request-scoped MLX workers | Provides the fastcontext_explore tool — the actual engine |
Skill (SKILL.md) |
Markdown instructions the agent loads | Tells the agent when and how to use fastcontext_explore |
Both are needed: the MCP server provides the tool, the skill tells the agent to use it.
Install the setup skill, then let your agent handle the rest:
npx skills add rubybear-lgtm/fastcontext@fastcontext-setup -g -yThen in your AI coding tool, say "Install FastContext". The agent will:
- Check your platform (Apple Silicon required)
- Create a venv and install the package (prebuilt wheel by default)
- Auto-detect which AI coding tools you have
- Register the MCP server in the right config file(s)
- Verify the MCP server imports without loading the model
- Tell you to restart
# Auto-detect tools, prebuilt wheel
curl -fsSL https://raw.githubusercontent.com/rubybear-lgtm/fastcontext/main/scripts/install.sh | bash
# Target a specific tool
curl -fsSL https://raw.githubusercontent.com/rubybear-lgtm/fastcontext/main/scripts/install.sh | bash -s -- --target claude
# Also install skill files + symlinks
curl -fsSL https://raw.githubusercontent.com/rubybear-lgtm/fastcontext/main/scripts/install.sh | bash -s -- --install-skills
# Force building from git source (no prebuilt wheel)
curl -fsSL https://raw.githubusercontent.com/rubybear-lgtm/fastcontext/main/scripts/install.sh | bash -s -- --from-sourceFlags:
| Flag | Description |
|---|---|
--target <tool> |
claude | opencode | codex | both | auto (default: auto) |
--install-skills |
Also install skill files to ~/.agents/skills/ + symlink into tool dirs |
--from-source |
Build from git instead of downloading a prebuilt wheel |
--help |
Show usage |
# 1. Create venv and install
uv venv ~/.cache/fastcontext/venv --python ">=3.12"
uv pip install --python ~/.cache/fastcontext/venv/bin/python "fastcontext-mcp @ git+https://github.com/rubybear-lgtm/fastcontext.git"
# 2. Register the MCP server (see Configuration below)Releases include a prebuilt fastcontext_mcp-<version>-py3-none-any.whl wheel. The install script downloads it automatically by default. To install manually:
uv pip install --python ~/.cache/fastcontext/venv/bin/python \
https://github.com/rubybear-lgtm/fastcontext/releases/latest/download/fastcontext_mcp-0.1.0-py3-none-any.whlThe wheel is platform-independent (pure Python) — only the mlx-lm and fastcontext dependencies require Apple Silicon at runtime.
The MCP server needs to be registered with your AI coding tool. The install script handles this automatically, but for manual setup:
{
"mcpServers": {
"fastcontext": {
"command": "~/.cache/fastcontext/venv/bin/fastcontext-mcp"
}
}
}{
"mcp": {
"fastcontext": {
"type": "local",
"command": ["~/.cache/fastcontext/venv/bin/fastcontext-mcp"],
"enabled": true
}
}
}[mcp_servers.fastcontext]
command = "~/.cache/fastcontext/venv/bin/fastcontext-mcp"
args = []| Tool | Command |
|---|---|
| Claude Code | /mcp — fastcontext should appear |
| OpenCode | /mcp or status command — fastcontext listed |
| Codex CLI | codex mcp list — fastcontext connected |
| Direct | ~/.cache/fastcontext/venv/bin/python -c "from fastcontext_mcp.server import mcp; print('OK')" |
The model (rubybear/FastContext-1.0-4B-SFT-mlx-4bit-g32, a 4-bit quantized 4B parameter model) loads via mlx_lm in a disposable worker only when exploration is requested. Each MCP client has its own lightweight stdio connection; idle connections do not load MLX or keep model weights.
A machine-wide file lock (~/.cache/fastcontext/inference.lock) permits only one inference worker to load a model at a time. Concurrent clients wait for that slot. The worker exits after every request, releasing model weights and KV caches. Model loading is paid on each exploration, while the on-disk model cache remains available.
Cancellation or a 10-minute request deadline terminates and reaps the worker process group. If the MCP parent disappears, closure of its stdin pipe terminates the worker. The kernel releases the inference lock on worker exit. No external HTTP server or API keys are required.
The MlxLLM class maintains a KV cache across agent turns (make_prompt_cache). Each turn only prefills new tokens (tool results) instead of re-processing the entire conversation — roughly 5x speedup on subsequent turns.
The worker resolves rg from its environment’s PATH; it does not assume /usr/bin/rg. Ripgrep must be installed and visible to the MCP process. Read, Glob, and Grep are scoped to the selected repository, including resolved symlink targets. Relative tool paths resolve against that repository.
Before inference, a bounded file listing supplies actual candidate paths, ranked by query terms. The model still decides what to inspect. File discovery alone is not evidence: successful Read and Grep content results record the displayed line numbers and a source digest. Final citations must fall within those observed ranges, with the source unchanged. Unverified descriptions are discarded; an unsupported answer causes a correction within the existing turn budget, then an explicitly partial result if only some citations verify, or an error if none verify. A verified range establishes that source was observed, not that it completely answers the question.
FastContext uses Microsoft's FastContext agent framework with three tools:
- Read — read file contents
- Glob — find files by pattern
- Grep — search file contents
The local model decides which tools to call and in what order, running up to max_turns iterations before producing a final answer with file:line citations.
src/fastcontext_mcp/
├── server.py # MCP server + MlxLLM (KV-cached inference)
├── _shared.py # Response parsing (tool call extraction)
├── configwriter.py # MCP config + skill file installation
└── release.py # Prebuilt wheel resolution from GitHub releases
scripts/install.sh # One-command installer
skills/
├── fastcontext/ # Usage skill (when/how to call the tool)
└── fastcontext-setup/ # Setup skill (agent-driven installation)
benchmark/ # Benchmark harness (bench, scoring, plotting)
tests/ # Test suite (111 tests)
- macOS with Apple Silicon (M1/M2/M3/M4) — required for MLX
- ~5 GB free RAM for the 4B model
- Python ≥ 3.12
uv(installed automatically by the install script)
# Clone and install in editable mode
git clone https://github.com/rubybear-lgtm/fastcontext.git
cd fastcontext
uv venv ~/.cache/fastcontext/venv --python ">=3.12"
uv pip install --python ~/.cache/fastcontext/venv/bin/python -e ".[test]"~/.cache/fastcontext/venv/bin/python -m pytest tests/ -vTests use temporary directories and mocks — they don't touch real config files or require network access. The heavy mlx-lm / fastcontext deps aren't needed for the test suite (only the pure-Python modules: configwriter, release).
ruff check src/fastcontext_mcp/ tests/uv build --wheel
# Output: dist/fastcontext_mcp-<version>-py3-none-any.whlReleases are automated via GitHub Actions. To cut a new release:
# Tag and push
git tag v0.1.0
git push origin v0.1.0The release.yml workflow will:
- Build the wheel
- Verify it contains all required modules
- Create a GitHub Release with the wheel attached
- The install script will then automatically download it
For manual triggers, use the GitHub Actions "Run workflow" button with a version tag.
Model load errors / out of memory
The 4B model requires ~5 GB RAM. Close memory-intensive apps. The 4-bit quantization (-4bit-g32) keeps memory usage minimal while preserving quality.
MCP server not showing after restart
Verify the config was written correctly:
- Claude Code: check
mcpServers.fastcontextin~/.mcp.json - OpenCode: check
mcp.fastcontextin~/.config/opencode/opencode.json - Codex CLI: check
[mcp_servers.fastcontext]in~/.codex/config.toml
Re-run the install script with --target <tool> if needed.
Import errors
Check the underlying error:
~/.cache/fastcontext/venv/bin/python -c "from fastcontext_mcp.server import mcp; print('OK')"Common causes: missing uv, wrong Python version (< 3.12), or corrupted venv. Delete ~/.cache/fastcontext/venv and re-run the installer.
First call to fastcontext_explore is slow
The model loads into memory for each exploration and is released when that request finishes. The KV cache is reused across turns within one exploration. Concurrent clients wait for the shared inference slot.
Prebuilt wheel download fails
The install script automatically falls back to building from git source. To force source builds, use --from-source. To check available releases, visit the releases page.
MIT