# MCP Context Condenser ⚡

[![rafim-dev/mcp-context-condenser MCP server](https://glama.ai/mcp/servers/rafim-dev/mcp-context-condenser/badges/score.svg)](https://glama.ai/mcp/servers/rafim-dev/mcp-context-condenser)
[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](LICENSE)
[![Runtime: Standalone Node.js](https://img.shields.io/badge/Runtime-Node.js%2018%2B-blue.svg)](dist/index.js)

> **Token-slimming AST code outliner, surgical symbol extractor, and log compressor cutting AI agent context usage and API bills by up to 85%.**

Designed for **Cursor**, **Claude Desktop**, **Cline**, and **Antigravity**. Works seamlessly as an **MCP stdio server** or standalone **terminal CLI**.

---

## 🛑 The Problem: LLM Context Saturation & Financial Bleed

Feeding entire 1,000–3,000 line source files into Claude 3.7 Sonnet or GPT-4o context windows causes two critical issues:
1. **Financial Bleed**: Massive prompt token burns ($15–$50+/day on active pair-programming sessions).
2. **"Lost in the Middle" Degradation**: Drowning models in boilerplate internal implementations increases hallucination rates and degrades adherence to subtle architectural rules.

Most agent interactions only need **exported interfaces, type signatures, or one specific helper function**.

---

## ✨ Superpowers

| Tool / Command | Description | Token Reduction |
| :--- | :--- | :--- |
| `condense_source` / `outline` | Generates type-safe AST code skeletons preserving imports, interfaces, types, and method signatures while condensing function bodies. | **Up to 85%** |
| `extract_symbol` / `symbol` | Surgically extracts only the requested class, interface, or function with relevant file-level imports. | **Up to 95%** |
| `compress_log` / `log` | Strips noisy terminal passes and boilerplate, pinpointing failing assertions, compiler errors, and app stack frames. | **Up to 90%** |
| `token_budget` / `budget` | Calculates token weight (~3.8 chars/token) and provides context-window safety warnings before ingesting huge files. | Proactive Guardrail |

---

## 📊 Live Benchmark

Ingesting a 450-line TypeScript payment gateway service (`PaymentGatewayService.ts`):

```diff
- RAW FULL FILE DUMP:
- Lines: 450 lines
- Token Weight: ~4,820 tokens
- Latency / Cost: High token latency, potential context degradation
- Cost per 100 queries: $1.44 (Sonnet 3.7)

+ MCP CONTEXT CONDENSER (AST SKELETON):
+ Lines: 58 lines
+ Token Weight: ~680 tokens (85.9% reduction)
+ Latency / Cost: Instant TTFT, razor-sharp instruction following
+ Cost per 100 queries: $0.20 (Sonnet 3.7)
```

---

## 🚀 Quickstart Installation

### Option 1: Claude Desktop
Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "context-condenser": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-context-condenser/dist/index.js"]
    }
  }
}
```

### Option 2: Cursor
Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "context-condenser": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-context-condenser/dist/index.js"]
    }
  }
}
```

### Option 3: Terminal CLI (Zero Configuration)
Run directly from your terminal:

```bash
# Outline an entire file into a compact skeleton
node dist/index.js outline src/services/auth.ts

# Surgically extract a single function or class
node dist/index.js symbol src/services/auth.ts validateToken

# Compress voluminous test or build logs
node dist/index.js log test_output.log

# Check token budget of a file
node dist/index.js budget src/large_file.ts
```

---

## 🛠️ MCP Tool Reference

### 1. `condense_source`
* **Inputs**:
  * `sourceCode` *(string)*: Raw code to outline.
  * `preserveDocstrings` *(boolean, optional)*: Whether to preserve JSDoc / TSDoc comments.
* **Returns**: Condensed outline, line count diff, token reduction percentage.

### 2. `extract_symbol`
* **Inputs**:
  * `sourceCode` *(string)*: Full source code.
  * `symbolName` *(string)*: Name of function, class, interface, or type.
* **Returns**: Extracted symbol with file imports and line numbers.

### 3. `compress_log`
* **Inputs**:
  * `rawLog` *(string)*: Raw test, compiler, or build output.
* **Returns**: Isolated failures, root-cause assertion messages, and source code line pointers.

### 4. `token_budget`
* **Inputs**:
  * `filePath` *(string)*: File path being evaluated.
  * `content` *(string)*: Raw file content.
* **Returns**: Estimated tokens, oversized flag, and optimization recommendations.

---

## 📦 Zero-Dependency Standalone Build

Unlike standard MCP servers with hundreds of nested `node_modules`, `mcp-context-condenser` is pre-bundled with `esbuild` into a single, self-contained standalone binary (`dist/index.js`).
* **Instant Startup**: $< 10\text{ms}$ process boot time.
* **Firecracker & Docker Ready**: Zero runtime installation required.

---

## 📄 License & Commercial Distribution

Released under the **MIT License**. Available on:
* **Gumroad**: [Buy or PWYW ($5.00+)](https://rafi860.gumroad.com/l/mcp-context-condenser)
* **itch.io**: [Download on itch.io](https://rafi-m.itch.io/mcp-context-condenser)