token-optimization-mcp v0.2.0

Production-ready Model Context Protocol server for token counting, prompt compression, model routing and semantic caching. Zero external API calls — works fully offline.

Tools

| Tool | Description | |------------------------|-----------------------------------------------------------------------| | estimate_tokens | Count tokens for any text+model (calibrated chars/token ratios) | | compress_prompt | Shrink prompts with trim, summarize_hint or aggressive strategy | | route_model | Pick cheapest model meeting quality + context requirements | | cache_lookup | Semantic cache hit/miss by prompt or pre-computed key | | cache_store | Store prompt+result with token-savings metadata | | cache_invalidate | Remove one or all cache entries | | analyze_context | Conversation health: role breakdown, issues, recommendations | | savings_report | Session-level token/USD savings dashboard | | deduplicate_messages | Remove duplicate turns, count saved tokens |

Quick Start

cd mcps/token-optimization-mcp
uv sync

# stdio – Claude Code / Copilot
uv run main.py

# SSE – LangGraph / CrewAI / browser
uv run main.py --sse --port 8001

Environment Variables

| Variable | Default | Description | |------------------------|----------------------------|---------------------------| | USE_REDIS | false | Enable Redis backend | | REDIS_URL | redis://localhost:6379/1 | Redis connection URL | | CACHE_TTL_SECONDS | 86400 | Default cache TTL (1 day) | | RATE_LIMIT_PER_MIN | 120 | Requests/min per client | | AUDIT_LOG_ENABLED | true | Print audit log to stdout |

Registration

Claude Code (~/.claude/settings.json)

{
  "mcpServers": {
    "token-optimization": {
      "command": "uv",
      "args": ["run", "/path/to/token-optimization-mcp/main.py"]
    }
  }
}

VS Code Copilot (.vscode/mcp.json)

{
  "servers": {
    "token-optimization": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "${workspaceFolder}/mcps/token-optimization-mcp/main.py"]
    }
  }
}

SSE (LangGraph / CrewAI / Cursor)

http://127.0.0.1:8001/sse

Supported Models (routing catalogue)

| Model | Context | Quality | Cost/1k | |---------------------|---------|---------|-----------| | github:copilot | 128k | 8 | free | | gpt-4o-mini | 128k | 7 | $0.00015 | | claude-3-5-haiku | 200k | 7 | $0.00025 | | gemini-1.5-flash | 1M | 6 | $0.000075 | | gpt-4o | 128k | 9 | $0.005 | | claude-3-5-sonnet | 200k | 9 | $0.003 | | claude-3-opus | 200k | 10 | $0.015 |

Testing

uv run --group test pytest
# 118 tests, 100% coverage

Architecture

token-optimization-mcp/
├── main.py                      ← FastMCP server (9 tools)
├── pyproject.toml
├── README.md
├── tests/
│   ├── conftest.py              ← state-reset fixtures
│   ├── test_helpers.py          ← unit tests + Hypothesis
│   └── test_tools.py            ← integration tests per tool
└── mcp-servers/
    └── context-cache-server/    ← standalone Redis-backed sub-server
        ├── server.py
        ├── config.py
        └── security.py