🧹 token-filter-mcp

Your LLM is wasting 80% of its context window on noise. This fixes that.

An MCP server that sits between your AI coding assistant and its tools, intelligently compressing outputs before they consume your precious context. Longer sessions. Better reasoning. Lower costs.

💸 The Problem Nobody Talks About

Every time your AI assistant runs a command, it dumps the entire raw output into its context window:

+ ✓ src/auth.test.ts (14 tests)          ← you don't need this
+ ✓ src/utils.test.ts (8 tests)          ← or this
+ ✓ src/payments.test.ts (12 tests)      ← or this
+ ✓ src/users.test.ts (10 tests)         ← or this
- ✗ src/orders.test.ts (3 tests)         ← THIS is what matters
-   ● should validate quantity > 0
-     Expected: error
-     Received: success

The vast majority of tool output is noise: tests that pass, git headers, resolution trees, progress bars, whitespace. ~80% of what goes into the context window is information the LLM will never act on.

That noise eats your context window, degrades reasoning quality, and costs you money.

Related MCP server: claw-tsaver

⚡ The Solution

❌ Without token-filter-mcp

• Context fills up fast

• LLM loses track of conversation

• Paying for tokens it ignores

• Sessions hit context limit early

• Reads 14 lines to find 1 failure

✅ With token-filter-mcp

• Context stays lean

• LLM maintains coherence longer

• Only paying for useful tokens

• Sessions last significantly longer

• Reads exactly the failure, acts immediately

token-filter-mcp intercepts every tool output and applies intelligent, context-aware filtering — returning only what the LLM actually needs to make decisions.

No configuration needed. No changes to your workflow. Just plug it in.

🎯 Real Results

Average savings across real-world tool outputs: 60-90% fewer tokens consumed

🧠 How It Works

flowchart LR
    A[🤖 LLM Agent] -->|tool call| B[🧹 token-filter-mcp]
    B -->|execute| C[💻 System]
    C -->|raw output| B
    B -->|filtered output| A

    style B fill:#7c3aed,stroke:#5b21b6,color:#fff
    style A fill:#2563eb,stroke:#1d4ed8,color:#fff
    style C fill:#059669,stroke:#047857,color:#fff

1️⃣ Detect — Identifies what command was run (test runner? git? linter?)

2️⃣ Execute — Runs the command and captures full output

3️⃣ Filter — Applies the optimal strategy for that command type

4️⃣ Verify — Ensures no errors or actionable info was removed

5️⃣ Return — Sends compressed output to the LLM

🎨 Contextual Detection

The server doesn't blindly truncate. It understands what you ran and applies the right strategy:

🛡️ Zero Information Loss

The #1 design principle: never hide an error.

✅ Lines matching error patterns (FAIL, Error:, TypeError, panic...) → NEVER removed
✅ Non-zero exit codes → full error output preserved
✅ Parser can't understand format → returns raw output
✅ passthrough mode available for when you need everything

🚀 Installation

Add this to your MCP client config — that's it:

{
  "mcpServers": {
    "token-filter": {
      "command": "npx",
      "args": ["-y", "token-filter-mcp"]
    }
  }
}

npm install -g token-filter-mcp

{
  "mcpServers": {
    "token-filter": {
      "command": "token-filter-mcp"
    }
  }
}

📍 Where does the config go?

🔧 5 Tools, One Purpose

{ "command": "npm test", "filter_level": "normal" }

{ "path": "src/app.ts", "mode": "signatures" }

Supports: TypeScript, JavaScript, Python, Rust, Go

{ "pattern": "useState", "path": "src", "group_by": "file", "max_results": 20 }

Results grouped by file, deduplicated, with context lines. Uses ripgrep when available.

{ "command": "npm test" }

All pass:

[PASS] 47/47 tests passed (3.2s)

Failures:

[PASS] 44/47 tests passed
[FAIL] 3 failures:

1. src/auth.test.ts:42 — "should refresh token"
   Expected: 200
   Received: 401

2. src/payments.test.ts:89 — "should validate 3DS"
   TypeError: Cannot read property 'status' of undefined
   at processPayment (src/payments.ts:156)

Auto-detects: Jest, Vitest, pytest, cargo test, go test

{ "operation": "status" }

⚙️ Configuration (Optional)

Works great out of the box. Customize only if you want to.

{
  "defaults": {
    "max_output_lines": 100,
    "test_show_passes": false,
    "git_log_max": 15,
    "diff_context_lines": 3,
    "dedup_threshold": 3
  },
  "commands": {
    "my-custom-script.sh": { "filter_level": "passthrough" }
  },
  "metrics": { "enabled": true }
}

Same schema. Project config overrides global. Global overrides built-in defaults.

📊 Built-in Observability

When enabled, every invocation is logged to ~/.config/token-filter-mcp/metrics.jsonl:

{
  "tool": "smart_test",
  "command": "npm test",
  "rawChars": 5200,
  "filteredChars": 480,
  "savingsPercent": 90.7,
  "strategy": "test_result_filter",
  "filterDurationMs": 3,
  "timestamp": "2026-06-30T15:30:00Z"
}

Auto-rotated at 5MB, max 5 history files.

What it tracks:

• Real savings per tool and command type

• Which filters are most effective

• Passthrough re-invocations (signal that a filter might be too aggressive)

🛡️ Guarantees

🛠️ Development

git clone https://github.com/VMexicano/token-filter-mcp
cd token-filter-mcp
npm install
npm run build
npm test        # 57 tests, all passing

The best token is the one you never spend.

Made with 💖 by Victor Mexicano