mcp-context-guard 1.0.0

Context window management: compress, deduplicate, filter tool outputs

MCP Context Guard — Context Window Management for AI Agents

Compress tool outputs, manage token budgets, deduplicate content, and filter by relevance. Zero dependencies, pure Python stdlib.

The Problem

AI agents waste context window tokens on:

• Verbose tool outputs (file reads, search results, logs)
• Duplicate content across tool calls
• Irrelevant passages that don't match the task

The Solution

MCP Context Guard sits between your tools and the LLM, compressing and filtering everything that enters the context window.

Tools (14)

Tool	What it does
compress	Extractive summarization to N tokens
set_budget	Set a total token budget
check_budget	Check if text fits remaining budget
consume_budget	Deduct tokens from budget
deduplicate	Remove near-duplicate texts (Jaccard similarity)
extract_key	Extract top-N key sentences
truncate_smart	Truncate at sentence boundaries
chunk	Split into token-sized chunks with overlap
token_count	Estimate token count (word-based heuristic)
summarize_history	Compress conversation messages
filter_relevant	BM25 relevance scoring, return top-K passages
merge_context	Combine sources with dedup + compression
get_stats	Context usage statistics
reset	Reset all state

Install

git clone https://github.com/aaameobius-crypto/mcp-context-guard.git
cd mcp-context-guard
python -m src.server --stdio

Tests

python -m pytest tests/ -v  # 36 tests, all passing

Inspiration

• headroom — 60-95% token reduction
• context-mode — Intercept tool output
• LLMLingua — Prompt compression
• Autonomous Context Compression

License

MIT — aaameobius-crypto