ercan-ermis

token-saver

MCP plugin that alerts you when AI token usage is wasteful. Works with Claude Code, Cursor, Windsurf, Zed, Continue.dev — any MCP-compatible client, any model. Fires warnings, errors, and alerts on large outputs, verbose logs, and repetitive history. Auto-suppresses noise to keep your context lean.

---

Overview

In agentic coding sessions, AI model responses often contain massive log outputs, repeated tool results, or near-duplicate history entries — all of which are re-sent on every turn, burning tokens. token-saver monitors every output and tells you when something is wasteful, so you can suppress it before it poisons your context window.

Works with any MCP-compatible client: Claude Code, Cursor, Windsurf, Zed, Continue.dev, and any other tool that speaks the Model Context Protocol. No dependency on any specific AI provider or API — token-saver analyzes plain text and is model-agnostic by design.

Core value proposition: Most token waste in long AI sessions comes from outputs nobody actually reads — stack traces, verbose logs, repeated file contents. token-saver catches these early and tells you exactly why and how much you're wasting.

---

How it works

Your AI model output (Claude, GPT, Gemini, or any other)
        │
        ▼
  check_output          ← estimates tokens, detects log/noise patterns
        │
        ▼
  alert level           ← info / warning / error / alert
        │
        ▼
  shouldSuppress        ← true if output matches suppression criteria
        │
        ▼
  get_session_stats     ← cumulative waste report for the session

---

Installation

Three ways — pick what suits you:

Option A — npx (no install, always latest)

No global install needed. Add directly to your MCP client config:

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

Option B — npm global

npm install -g token-saver-mcp

Then add to your MCP client config:

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

Option C — install directly from GitHub

npm install -g github:flightlesstux/token-saver

Same config as Option B. Works without a build step — compiled output is included in the repo.

---

Tools

Tool	Description
set_mode	Switch mode: off (default, silent) · monitor (analyze only) · active (full suppression). Start here.
check_output	Analyze a text output. Returns alert level, token count, suppression flag, and detected patterns.
analyze_history	Scan a messages array for near-duplicates and ignored log outputs. Returns suggested truncation and savings estimate.
get_session_stats	Cumulative session statistics: tokens analyzed, suppressed, saved, and alert counts.
reset_session_stats	Reset session statistics to zero.
set_thresholds	Override warning/error/alert token thresholds and suppression flags for the current session.

---

Example usage

1. Enable the plugin (off by default)

{ "name": "set_mode", "arguments": { "mode": "active" } }

{ "mode": "active" }

2. Check a suspicious output

{ "name": "check_output", "arguments": { "text": "[INFO] server started\n[DEBUG] connection ok\n[TRACE] request received\n..." } }

{
  "alertLevel": "warning",
  "tokens": 87,
  "outputType": "log",
  "shouldSuppress": true,
  "reason": "Output matches log/noise patterns and will be suppressed",
  "detectedPatterns": [
    { "pattern": "\\[INFO\\]", "matchCount": 5, "description": "Log pattern matched 5 times" },
    { "pattern": "\\[DEBUG\\]", "matchCount": 5, "description": "Log pattern matched 5 times" }
  ]
}

3. Scan conversation history for waste

{ "name": "analyze_history", "arguments": { "messages": [ ...your messages array... ] } }

{
  "totalMessages": 6,
  "totalTokens": 114,
  "repetitiveMessages": [
    { "index": 2, "role": "user", "tokens": 19, "reason": "Near-duplicate of message 0" },
    { "index": 4, "role": "user", "tokens": 19, "reason": "Near-duplicate of message 0" }
  ],
  "suggestedTruncation": 2,
  "estimatedTokenSavings": 38,
  "alertLevel": "alert"
}

4. Session summary