FastContext Agent Tools

MCP server and Codex skill for using Microsoft's FastContext as a read-only
repository exploration subagent.

FastContext answers one narrow question for a coding agent:

Which files and line ranges should the main agent inspect before solving this task?

This repository provides the complete integration:

• fastcontext-mcp: a Python stdio MCP server that installs Microsoft FastContext as a pinned runtime dependency.
• skills/fastcontext-explorer: a Codex skill that teaches an agent when to delegate repository exploration.
• MCP setup guides in English, Traditional Chinese, and Japanese.

It does not bundle model weights, run inference, or modify repositories. The MCP
server runs the bundled fastcontext.cli module in the same Python environment
and returns candidate file-line citations for the main agent to verify.

One-Line LLM Agent Install Prompt

Ask an LLM agent:

Install FastContext Agent Tools from https://github.com/Jakevin/fastcontext-agent-tools; its package installation includes Microsoft FastContext. Configure python -m fastcontext_mcp as a stdio MCP server with BASE_URL, MODEL, API_KEY, and FASTCONTEXT_ALLOWED_ROOTS, then enable skills/fastcontext-explorer.

Direct install command for Codex-style local skills:

git clone https://github.com/Jakevin/fastcontext-agent-tools && cd fastcontext-agent-tools && python -m pip install -e . && mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills" && ln -sfn "$(pwd)/skills/fastcontext-explorer" "${CODEX_HOME:-$HOME/.codex}/skills/fastcontext-explorer"

Why This Exists

Microsoft FastContext separates repository exploration from code solving. The
upstream project describes a dedicated explorer that uses read-only READ,
GLOB, and GREP tools, issues parallel tool calls, and returns compact
<final_answer> citations. Microsoft reports Mini-SWE-Agent integration gains
of up to 5.5 score improvement and up to 60% main-agent token reduction.

Primary sources:

• Microsoft FastContext: https://github.com/microsoft/fastcontext
• Model card: https://huggingface.co/microsoft/FastContext-1.0-4B-SFT
• Paper: https://arxiv.org/abs/2606.14066

Quick Install

git clone https://github.com/Jakevin/fastcontext-agent-tools
cd fastcontext-agent-tools
python -m pip install -e .
python -m fastcontext_mcp --print-health

If your Python scripts directory is on PATH, fastcontext-mcp --print-health
works too.

Requirements

• Python 3.12+.
• An OpenAI-compatible endpoint serving a FastContext-compatible model.

Installing this package also installs Microsoft FastContext from the pinned
official source revision. No separate FastContext checkout or CLI installation
is required.

Endpoint environment:

export BASE_URL="http://127.0.0.1:30000/v1"
export MODEL="microsoft/FastContext-1.0-4B-SFT"
export API_KEY="your-api-key"
export FASTCONTEXT_ALLOWED_ROOTS="/path/to/repos"

FASTCONTEXT_ALLOWED_ROOTS is an os.pathsep separated allowlist. If unset,
the MCP server only allows repositories under the directory where the server was
started.

MCP Configuration

Example stdio config:

{
  "mcpServers": {
    "fastcontext": {
      "command": "python",
      "args": ["-m", "fastcontext_mcp"],
      "env": {
        "BASE_URL": "http://127.0.0.1:30000/v1",
        "MODEL": "microsoft/FastContext-1.0-4B-SFT",
        "API_KEY": "your-api-key",
        "FASTCONTEXT_ALLOWED_ROOTS": "/path/to/repos"
      }
    }
  }
}

Localized MCP guides:

• Traditional Chinese: docs/mcp.zh-TW.md
• Japanese: docs/mcp.ja.md

MCP Tools

fastcontext_health

Checks whether the bundled fastcontext.cli module is importable and whether
the endpoint environment is set.

fastcontext_explore

Runs FastContext against a repository and returns parsed citations plus raw
output.

{
  "repo_path": "/path/to/repo",
  "query": "Locate the request validation logic for uploaded files",
  "max_turns": 6,
  "citation": true,
  "timeout_seconds": 300
}

fastcontext_explore_with_trace

Same as fastcontext_explore, but saves a FastContext JSONL trajectory. Relative
trajectory_path values are resolved inside repo_path.

Codex Skill

The bundled skill lives at:

skills/fastcontext-explorer

Install by copying or symlinking that folder into your Codex skills directory:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s "$(pwd)/skills/fastcontext-explorer" "${CODEX_HOME:-$HOME/.codex}/skills/fastcontext-explorer"

Use the skill when a coding task requires repository localization before
editing. FastContext citations are candidate evidence; the main agent should
still read the cited files before changing code.

Additional project report:

• Full report: docs/REPORT.md

Development

Run tests:

PYTHONPATH=src python -m unittest discover -s tests

Validate the bundled Codex skill:

python /path/to/skill-creator/scripts/quick_validate.py skills/fastcontext-explorer

Safety Notes

• The MCP server exposes no edit/write tools.
• repo_path must resolve under FASTCONTEXT_ALLOWED_ROOTS.
• Secrets are read from environment variables only.
• Trajectories are written only when requested.

License

MIT