Context Mode MCP Server

Context Mode is an MCP (Model Context Protocol) server designed to solve the 'context problem' in LLM-based agent workflows. It prevents context window bloat by keeping raw data (like large file snapshots, logs, or GitHub issues) out of the main conversation window and instead managing it via sandbox tools and indexed storage.

Key capabilities include:

• Context Saving: Reduces context usage significantly (e.g., 98% reduction) by keeping raw data in sandboxes rather than the context window.
• Session Continuity: Uses SQLite and FTS5 indexing to track file edits, git operations, tasks, and errors. This allows the model to retrieve relevant historical data via BM25 search even after conversation compaction, ensuring it picks up exactly where it left off.
• Code-Centric Analysis: Encourages the LLM to write and execute scripts to process data rather than reading large amounts of raw data into the context.
• Non-Intrusive: It manages where data is stored without dictating the model's conversational style or prose length.

When using ctx_execute, each call spawns an isolated subprocess with its own process boundary. Scripts cannot access the memory or state of other scripts.

Key behaviors:

• Context Isolation: Only the stdout of the subprocess enters the conversation context. Raw data (log files, API responses, snapshots) remains inside the sandbox.
• Supported Languages: JavaScript, TypeScript, Python, Shell, Ruby, Go, Rust, PHP, Perl, R, Elixir, and C#.
• Performance: Bun is automatically detected to provide 3-5x faster JS/TS execution.
• CLI Authentication: Authenticated CLIs like gh, aws, gcloud, kubectl, and docker work via credential passthrough. They inherit environment variables and config paths without exposing them to the conversation.
• Intent-Driven Filtering: If output exceeds 5 KB and an intent is provided, Context Mode indexes the full output and returns only the relevant matches based on your intent.

When implementing or modifying deny reasons in hooks/core/routing.mjs, you must distinguish between two distinct types of denials. Using the wrong vocabulary can cause LLM agents to incorrectly assume a security restriction exists when they should actually be redirecting to a more efficient tool.

CASE A: Routing Redirect

Use this when an action is supported but should be performed via a different, more context-efficient tool (e.g., using ctx_fetch_and_index instead of WebFetch).

Requirements for CASE A strings:

• Opening verb: Must start with "redirected to <ctx_tool>".
• Affirm Capability: Must include a positive statement like <ctx_tool> has full network access to signal this is not a restriction.
• Specify Tool: Must name the alternative tool as an imperative call (e.g., Call ctx_fetch_and_index(url, source) now).
• Retry Hint: Must end with a positive imperative retry hint (e.g., "Retry the same call on a transient DNS error (EAI_AGAIN, ETIMEDOUT, ENETUNREACH)").
• Prohibitions:
  • DO NOT use the word BLOCKED (case-insensitive/bare).
  • DO NOT use negations like "NOT a network restriction" or "Do NOT retry with...".
  • DO NOT include organizational rationale like "for context-window efficiency" or "for performance".

CASE B: True Security / Policy Restriction

Use this when an action is genuinely denied by a security gate, deny-pattern check (e.g., accessing private IPs), or unsupported sandbox capability.

Requirements for CASE B strings:

• Opening verb: Use "denied" or "blocked by security policy".
• Cite Rule: Must cite the specific pattern or rule being violated.
• Suggestion: May optionally suggest a safe alternative.

To protect the context window from being flooded with large amounts of raw data (which can dump up to 56 KB per unrouted command), follow the Think in Code principle.

Instead of reading raw data, large files, or web content directly into the context, you must program the analysis. Use the sandbox tools to process data and only return the final answer via console.log() to stdout. This ensures only the relevant result enters the context, rather than the entire dataset.

Key Rules:

• Analyze/Filter/Search: Use ctx_execute(language, code) with Node.js built-ins (fs, path, child_process).
• Web Content: Never use curl or wget directly. Use ctx_fetch_and_index(url, source) or ctx_execute with fetch to ensure raw HTML stays out of the context.
• Large Files: Use ctx_execute_file(path, language, code) for analysis/exploration instead of the read tool.

// Instead of reading a 100KB file into context, do this:
// ctx_execute(language: "javascript", code: "...")

const fs = require('fs');
const path = require('path');

try {
  const data = fs.readFileSync(path.join(process.cwd(), 'large_data.json'), 'utf8');
  const parsed = JSON.parse(data);
  // Perform analysis logic here
  console.log(parsed.target_value); // ONLY the answer enters context
} catch (err) {
  console.error(err.message);
}

Use the following tool hierarchy to optimize context usage and performance:

1. MEMORY: Use ctx_search(sort: "timeline") to check prior context after resuming a session before asking the user for information.
2. GATHER: Use ctx_batch_execute(commands, queries) to run multiple commands and auto-index results. This replaces many individual calls. Each command should follow the format: {label: "header", command: "..."}.
3. FOLLOW-UP: Use ctx_search(queries: ["q1", "q2", ...]) to pass multiple questions as an array in a single call.
4. PROCESSING: Use ctx_execute(language, code) or ctx_execute_file(path, language, code) for sandbox-based processing. Only stdout is returned to the context.
5. WEB: Use ctx_fetch_and_index(url, source) followed by ctx_search(queries).
6. INDEX: Use ctx_index(content, source) to store content in FTS5 for later retrieval.

Parallel I/O

For network or API-heavy batches, pass concurrency: 4-8 to ctx_batch_execute and ctx_fetch_and_index. For CPU-bound tasks (testing, building, linting), keep concurrency: 1.