Metadata-Version: 2.4
Name: mcp-context-guard
Version: 1.0.0
Summary: Context window management: compress, deduplicate, filter tool outputs
Author: aaameobius-crypto
License: MIT
Project-URL: Homepage, https://github.com/aaameobius-crypto/darkbot-ai-templates
Project-URL: Repository, https://github.com/aaameobius-crypto/darkbot-ai-templates
Keywords: mcp,ai,agent,harness,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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 — aaameobius-crypto
