Scythe Context MCP

No longer maintained — 2026-10-19. Development and releases have ended. This public archive preserves the source, historical usage instructions and evaluation results. The evaluations did not establish a general speed or token-saving advantage over rg. See the final larger TypeScript evaluation. Existing npm versions remain available for reference; the installation instructions below describe the historical setup.

English | 繁體中文 | 简体中文

Scythe Context MCP helps coding agents find relevant code and trace symbols, imports, and reverse imports. It returns file paths, line ranges, and selected snippets through CLI + Skill or MCP. Local keyword search works without an API key; semantic search is optional.

When to use it

Keyword search depends on matching terms. Scythe's additional value is ranking and cross-file context; it is not a replacement for every rg lookup.

Related MCP server: ragbox-mcp

Choose an interface

Both interfaces ship in the same scythe-context-mcp npm package. Choose either, or use both.

Scythe requires Node.js >=24.11.0 <27; Node.js 24 is the tested baseline. Your target repository does not need Node.js. Install and run Scythe in the same environment as its files; see Windows, WSL, Linux, and macOS setup.

Quick start

CLI + Skill

1. Install the CLI and search your repository. Replace the path and query with your own repository and relevant terms:

cd /absolute/path/to/your/repo
npm install -g scythe-context-mcp@0.1.24
scythe-context index
scythe-context context "auth token" --format compact --max-results 1

The example limits results to one with --max-results 1 for display; remove that option to return more matches.

index writes local metadata to .scythe-context/; it does not request embeddings. Refresh it after source changes. The terminal commands work without installing a Skill.

2. Install the Skill for your agent. Locate the global npm package directory:

npm root -g

Inside that directory, install the entire scythe-context-mcp/skills/scythe-context/ folder using your agent's skill installer, or copy it into the agent's configured skill directory. It teaches the agent when to use rg, Scythe, and embeddings. npm installation or upgrades do not install or refresh this separate copy. See client-specific Skill locations and invocation.

MCP

Codex configuration example. For Claude Code and Antigravity CLI, see client-specific MCP registration.

For Codex on Linux, macOS, or WSL, add the following to ~/.codex/config.toml (or your configured Codex home), then restart the client. For native Windows or Windows App + WSL, use the platform setup guide.

[mcp_servers.scythe_context]
command = "npx"
args = ["-y", "scythe-context-mcp"]

Ask the agent to execute these MCP tool calls, not shell commands. Replace the path; reindex only when metadata is missing/stale:

repo_index_status({ "project_path": "/absolute/path/to/your/repo" })
repo_reindex({ "project_path": "/absolute/path/to/your/repo", "dry_run": false, "index_embeddings": false })
repo_context_pack({ "project_path": "/absolute/path/to/your/repo", "query": "auth token", "mode": "keyword" })

This example stays local by explicitly selecting keyword. If setup fails, use repo_doctor and troubleshooting.

What a result looks like

Actual CLI output from a two-file src/auth.ts / src/app.ts example, using the command above; the project path is normalized. Results depend on your repository:

Project: /absolute/path/to/your/repo
Mode: keyword
src/auth.ts:1-3
  keyword/path match
export function validateToken(token: string) {
  return token.length > 0;
}
Related: src/auth.ts (source)
Related: src/app.ts (source)
Suggested: src/auth.ts
Suggested: src/app.ts

The agent can read the returned ranges and follow related files. See the command and output reference for search, related, status, doctor, JSON, budgets, and saved results.

Language support

Text search works on supported text files. Structure and local navigation cover:

No target-language compiler or SDK is required. Navigation uses conservative source parsing, with language-specific limits; see language support and config-driven navigation. Older installs should read index upgrade notes.

Optional: embeddings

Use keyword first when likely source terms are known. When wording differences make local results insufficient, hybrid combines keyword and vector retrieval; semantic uses vectors alone. The Skill guides initial vector creation and updates when useful and within the task's authorized scope.

Embeddings require a Gemini-compatible endpoint. Vector indexing sends code chunks; hybrid/semantic queries send query text when matching code vectors exist. Provider charges may apply. Without matching vectors, hybrid falls back locally and semantic errors before sending a query. CLI defaults to keyword; MCP defaults to hybrid.

See semantic search, credentials, updates, and privacy. An API key alone neither creates vectors nor enables automatic CLI mode switching.

Limits and privacy

• Indexes need refreshing after edits; there is no automatic watcher. Related files are navigation hints, not compiler binding or a complete runtime call graph.

• Exclude private files with the root .gitignore. Keep .scythe-context/, legacy .repo-beacon/, .env, and local/ out of version control.

• Retrieval benchmarks do not establish faster agent task completion or lower total token use. See the benchmark and task A/B protocol (Traditional Chinese).

More information

• Client setup: Codex CLI, Claude Code, Antigravity CLI

• Documentation index · Setup and command reference · Troubleshooting

• Architecture · Workflow verification and remaining limits

• Changelog · Contributing and source development · Release process