mcp-agent-opt

Code-aware context compression for AI agents.

An MCP server that reads your code, strips what the LLM doesn't need (comments, docstrings, type annotations, whitespace), and returns what it does — with full fidelity on the logic.

The "Third Way": Between reading raw files (100% tokens, wasteful) and execution sandboxes (2% tokens, but the LLM can't see the code), mcp-agent-opt gives you 10-40% of the tokens with 100% of the logic.

Install

Claude Code

// .mcp.json (project-level) or ~/.claude/settings.json (global)
{
  "mcpServers": {
    "mcp-agent-opt": {
      "command": "npx",
      "args": ["-y", "mcp-agent-opt"]
    }
  }
}

Cursor

Settings > Features > MCP > Add New MCP Server

• Name: mcp-agent-opt
• Type: command
• Command: npx -y mcp-agent-opt

VS Code Copilot

// .vscode/mcp.json
{
  "servers": {
    "mcp-agent-opt": {
      "command": "npx",
      "args": ["-y", "mcp-agent-opt"]
    }
  }
}

Gemini CLI

// ~/.gemini/settings.json
{
  "mcpServers": {
    "mcp-agent-opt": {
      "command": "npx",
      "args": ["-y", "mcp-agent-opt"]
    }
  }
}

Tools

tpf_context — Compressed file read (15-50% savings)

Strips comments, docstrings, type annotations, and whitespace. Preserves logic, structure, and line-number anchoring via virtual markers.

Before (raw TypeScript, 485 lines, ~1,477 tokens):

/**
 * Execute code in a sandboxed subprocess.
 * Supports 11 languages with automatic runtime detection.
 * @param language - Target language identifier
 * @param code - Source code to execute
 * @param timeout - Maximum execution time in ms
 */
export async function execute(language: string, code: string, timeout: number = 30000): Promise<ExecutionResult> {
  // Validate inputs
  const runtime = detectRuntime(language);
  if (!runtime) {
    throw new Error(`Unsupported language: ${language}`);
  }
  // Build command array for subprocess
  const cmd = buildCommand(runtime, code);
  // ...200 more lines
}

After (compressed, ~926 tokens — 37% saved):

export async function execute(language: string, code: string, timeout: number = 30000): Promise<ExecutionResult> {
  const runtime = detectRuntime(language);
  if (!runtime) {
    throw new Error(`Unsupported language: ${language}`);
  }
  const cmd = buildCommand(runtime, code);
  // ...
}

tpf_skeleton — Signatures only (75-97% savings)

Collapses function/class bodies to placeholders. Shows only the API surface: what functions exist, their parameters, and what the file imports/exports.

Output (same file, ~48 tokens — 97% saved):

// EXPORTS: { execute, detectRuntime, buildCommand }
// IMPORTS: { spawn, existsSync, writeFileSync }
     1 export async function execute(language, code, timeout = 30000) { /* ... */ }
    45 function detectRuntime(language) { /* ... */ }
    89 function buildCommand(runtime, code) { /* ... */ }

tpf_search — Compressed grep (30-60% savings)

Wraps ripgrep, filters results through language recipes. Use for exploratory searches.

tpf_usages — Symbol usage finder

Find where a function, class, or variable is imported/referenced across the project. Results grouped by file.

Usages of "AuthService" (4 files):

── routes/auth.ts (3 matches):
  1: import { AuthService } from '../services/auth';
  15: const auth = new AuthService(config);
  42: AuthService.validateToken(token);

── middleware/session.ts (1 match):
  3: import { AuthService } from '../services/auth';

tpf_batch_context — Multi-file read with budget mode

Read multiple files in one call. Supports token budgeting: set max_total_tokens and the tool auto-downshifts lower-priority files from full context to skeleton to fit.

tpf_project — Codebase orientation + entry point detection

One call returns: filtered directory tree, compressed config files, git status, and detected entry points with their critical-path dependencies.

tpf_verify_line — Safe edit re-anchoring

Takes a line number from a compressed view, returns the actual raw line with ±5 lines of context. Use before editing to confirm exact location.

tpf_stats — Session savings tracker

Session: 23 files compressed, 45,201 tokens saved (62.3%)
Estimated cost savings: ~$0.68 (at $15/1M tokens)

Context-rot warnings:
  registry.rs read 3x (skeleton, context, context) — consider dropping older reads

Real Savings

Measured on real production code (10 files, 7,077 total lines):

Context mode saves 20% on already-lean production code. On heavily documented code (JSDoc, docstrings, verbose comments), savings reach 40-60%.

Skeleton mode saves 81% average — the star performer for architecture review.

Supported Languages

Tier 1 — Full recipe + skeleton

Tier 2 — Recipe only

Ruby, PHP, Swift, Kotlin, Scala, HCL/Terraform

Tier 3 — Generic + docs

Markdown, JSON, YAML, TOML, HTML, CSS, XML, config files, logs

System Prompt (recommended)

Add this to your agent's system instructions:

# Compression Protocol
You have access to mcp-agent-opt tools for context-efficient code reading.

## Strategy:
1. EXPLORATION: Use `tpf_project` to orient yourself in new codebases.
2. ARCHITECTURE: Use `tpf_skeleton` on large files (>200 lines) to map symbols.
3. LOGIC REVIEW: Use `tpf_context` to read implementation while ignoring boilerplate.
4. EDITING: NEVER use compression tools for files you intend to write. Always use full-fidelity `read_file` before an `edit`.

## Monitoring:
Observe the [tpf: X → Y tokens] header in every response to track context efficiency.

How It Works

8-Step Filter Pipeline

Every tpf_context call runs through:

1. strip_ansi — remove terminal color codes
2. remove_lines — drop lines matching patterns (comments, console.log, etc.)
3. keep_lines — keep only matching lines (optional)
4. replace — per-line regex substitution (trailing comments, whitespace)
5. multiline_replace — cross-line patterns (block comments, docstrings)
6. remove_blank_lines — collapse consecutive blank lines
7. max_lines — truncate with head/tail/both mode
8. on_empty — fallback message if result is empty

Safety

• Fallback: if any filter step fails, raw content is returned unchanged
• Edit safety: every compressed response includes a footer warning not to use line numbers for editing
• Virtual line markers: stripped blocks show // ... [N lines stripped] to prevent line-number hallucination

Comparison with Other Approaches

See COMPARISON.md for a detailed analysis.

TL;DR: Execution sandboxes prevent raw data from entering context (98%+ reduction, but the LLM can't see the code). mcp-agent-opt strips the noise while keeping the logic visible (20-97% reduction, full code comprehension). They're complementary — use sandboxes for execution, mcp-agent-opt for code understanding, and raw reads for editing.

Development

npm install
npm test          # 101 tests
npm run benchmark # savings data against real files

License

MIT