🧹 token-filter-mcp

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

npm version license node MCP

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.

⚡ The Solution

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

🎨 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

{
  "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" }

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

{ "command": "npm test" }

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

[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)

{ "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 }
}

📊 Built-in Observability

{
  "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"
}

🛡️ 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