# 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

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

## Tests

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

## Inspiration

- [headroom](https://github.com/chopratejas/headroom) — 60-95% token reduction
- [context-mode](https://github.com/mksglu/context-mode) — Intercept tool output
- [LLMLingua](https://github.com/microsoft/LLMLingua) — Prompt compression
- [Autonomous Context Compression](https://blog.langchain.com/autonomous-context-compression/)

## License

MIT — AMEOBIUS