mcp-context-guard 1.0.0__tar.gz

mcp_context_guard-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+MIT License
+Copyright (c) 2026 AMEOBIUS
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_context_guard-1.0.0/PKG-INFO

@@ -0,0 +1,79 @@
+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

mcp_context_guard-1.0.0/README.md

@@ -0,0 +1,58 @@
+# 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

mcp_context_guard-1.0.0/mcp_context_guard.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+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

mcp_context_guard-1.0.0/mcp_context_guard.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+./src/__init__.py
+./src/context_guard_engine.py
+./src/server.py
+mcp_context_guard.egg-info/PKG-INFO
+mcp_context_guard.egg-info/SOURCES.txt
+mcp_context_guard.egg-info/dependency_links.txt
+mcp_context_guard.egg-info/top_level.txt
+src/__init__.py
+src/context_guard_engine.py
+src/server.py
+tests/test_context_guard.py

mcp_context_guard-1.0.0/mcp_context_guard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcp_context_guard-1.0.0/mcp_context_guard.egg-info/top_level.txt

@@ -0,0 +1 @@
+src

mcp_context_guard-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-context-guard"
+version = "1.0.0"
+description = "Context window management: compress, deduplicate, filter tool outputs"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [{name = "aaameobius-crypto"}]
+keywords = ["mcp", "ai", "agent", "harness", "tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/aaameobius-crypto/darkbot-ai-templates"
+Repository = "https://github.com/aaameobius-crypto/darkbot-ai-templates"
+
+[tool.setuptools]
+packages = ["src"]
+package-dir = {"" = "."}

mcp_context_guard-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_context_guard-1.0.0/src/__init__.py

@@ -0,0 +1,5 @@
+"""mcp-context-guard package — MCP server for context window management."""
+from .context_guard_engine import ContextGuard
+from .server import MCPContextGuardServer, TOOL_DEFS
+__all__ = ["ContextGuard", "MCPContextGuardServer", "TOOL_DEFS"]
+__version__ = "1.0.0"

mcp_context_guard-1.0.0/src/context_guard_engine.py

@@ -0,0 +1,324 @@
+"""Context Guard engine — zero dependencies.
+Compresses tool outputs, manages token budgets, deduplicates content,
+extracts key passages, and provides BM25-like relevance filtering.
+"""
+import re, json, math, hashlib, collections
+from typing import Any, Dict, List, Optional, Tuple, Set
+
+class ContextGuard:
+    # Token estimation: avg English word = 1.3 tokens
+    TOKEN_RATIO = 1.3
+
+    @staticmethod
+    def create_store() -> Dict:
+        return {
+            "stats": {"compressed": 0, "tokens_saved": 0, "chunks_created": 0, "filtered": 0, "errors": 0},
+            "budget": {"limit": 0, "used": 0},
+            "seen_hashes": set(),
+            "history": [],
+        }
+
+    @staticmethod
+    def _track(store: Dict, op: str, count: int = 1):
+        store["stats"][op] = store["stats"].get(op, 0) + count
+
+    @staticmethod
+    def estimate_tokens(text: str) -> int:
+        """Estimate token count using word-based heuristic."""
+        words = len(re.findall(r"\b\w+\b", text))
+        return max(1, int(words * ContextGuard.TOKEN_RATIO))
+
+    @staticmethod
+    def _split_sentences(text: str) -> List[str]:
+        """Split text into sentences."""
+        sentences = re.split(r"(?<=[.!?])\s+", text.strip())
+        return [s.strip() for s in sentences if s.strip()]
+
+    @staticmethod
+    def _word_freq(text: str) -> Dict[str, int]:
+        """Compute word frequency map."""
+        words = re.findall(r"\b\w+\b", text.lower())
+        return dict(collections.Counter(words))
+
+    @staticmethod
+    def _sentence_score(sentence: str, word_freqs: Dict[str, int], total_words: int) -> float:
+        """Score a sentence by sum of word frequencies normalized by length."""
+        words = re.findall(r"\b\w+\b", sentence.lower())
+        if not words:
+            return 0.0
+        score = sum(word_freqs.get(w, 0) for w in words) / math.sqrt(len(words))
+        # Boost sentences with numbers, code, or keywords
+        if re.search(r"\d|def |class |import |function |error |warning ", sentence, re.I):
+            score *= 1.2
+        # Penalize very short or very long sentences
+        if len(words) < 3:
+            score *= 0.5
+        if len(words) > 40:
+            score *= 0.7
+        return score
+
+    @staticmethod
+    def compress(store: Dict, text: str, max_tokens: int = 500, strategy: str = "extractive") -> Dict:
+        """Compress text to approximately max_tokens using extractive summarization."""
+        ContextGuard._track(store, "compressed")
+        original_tokens = ContextGuard.estimate_tokens(text)
+        if original_tokens <= max_tokens:
+            return {"success": True, "text": text, "original_tokens": original_tokens, "compressed_tokens": original_tokens, "saved": 0, "ratio": 1.0}
+
+        sentences = ContextGuard._split_sentences(text)
+        if not sentences:
+            return {"success": True, "text": text, "original_tokens": original_tokens, "compressed_tokens": original_tokens, "saved": 0, "ratio": 1.0}
+
+        word_freqs = ContextGuard._word_freq(text)
+        total_words = sum(word_freqs.values())
+
+        scored = [(ContextGuard._sentence_score(s, word_freqs, total_words), i, s) for i, s in enumerate(sentences)]
+        scored.sort(key=lambda x: (-x[0], x[1]))  # Best score first, preserve order for ties
+
+        # Greedily add sentences until we hit token budget
+        selected = []
+        current_tokens = 0
+        for score, idx, sent in scored:
+            sent_tokens = ContextGuard.estimate_tokens(sent)
+            if current_tokens + sent_tokens > max_tokens:
+                continue
+            selected.append((idx, sent))
+            current_tokens += sent_tokens
+
+        selected.sort(key=lambda x: x[0])  # Restore original order
+        result = " ".join(s for _, s in selected)
+
+        compressed_tokens = ContextGuard.estimate_tokens(result)
+        saved = original_tokens - compressed_tokens
+        ContextGuard._track(store, "tokens_saved", saved)
+
+        return {
+            "success": True,
+            "text": result,
+            "original_tokens": original_tokens,
+            "compressed_tokens": compressed_tokens,
+            "saved": saved,
+            "ratio": round(compressed_tokens / max(original_tokens, 1), 4),
+            "strategy": strategy,
+            "sentences_kept": len(selected),
+            "sentences_total": len(sentences),
+        }
+
+    @staticmethod
+    def set_budget(store: Dict, limit: int) -> Dict:
+        store["budget"]["limit"] = limit
+        return {"success": True, "limit": limit, "used": store["budget"]["used"]}
+
+    @staticmethod
+    def check_budget(store: Dict, text: str) -> Dict:
+        """Check if text fits within remaining budget."""
+        tokens = ContextGuard.estimate_tokens(text)
+        remaining = store["budget"]["limit"] - store["budget"]["used"]
+        return {
+            "success": True,
+            "tokens": tokens,
+            "remaining": remaining,
+            "fits": tokens <= remaining if store["budget"]["limit"] > 0 else True,
+            "would_overflow": tokens > remaining if store["budget"]["limit"] > 0 else False,
+        }
+
+    @staticmethod
+    def consume_budget(store: Dict, text: str) -> Dict:
+        """Add text tokens to budget usage."""
+        tokens = ContextGuard.estimate_tokens(text)
+        store["budget"]["used"] += tokens
+        remaining = store["budget"]["limit"] - store["budget"]["used"] if store["budget"]["limit"] > 0 else -1
+        return {"success": True, "consumed": tokens, "total_used": store["budget"]["used"], "remaining": remaining}
+
+    @staticmethod
+    def deduplicate(store: Dict, texts: List[str], similarity_threshold: float = 0.8) -> Dict:
+        """Remove near-duplicate texts using Jaccard similarity on word sets."""
+        ContextGuard._track(store, "filtered")
+        if not texts:
+            return {"success": True, "unique": [], "removed": 0, "kept": 0}
+
+        unique = []
+        removed = 0
+        for text in texts:
+            words = set(re.findall(r"\b\w+\b", text.lower()))
+            is_dup = False
+            for u in unique:
+                u_words = set(re.findall(r"\b\w+\b", u.lower()))
+                if u_words and words:
+                    jaccard = len(words & u_words) / len(words | u_words)
+                    if jaccard >= similarity_threshold:
+                        is_dup = True
+                        removed += 1
+                        break
+            if not is_dup:
+                unique.append(text)
+
+        ContextGuard._track(store, "tokens_saved", ContextGuard.estimate_tokens(" ".join(texts)) - ContextGuard.estimate_tokens(" ".join(unique)))
+        return {"success": True, "unique": unique, "removed": removed, "kept": len(unique)}
+
+    @staticmethod
+    def extract_key(store: Dict, text: str, num_keys: int = 5) -> Dict:
+        """Extract key sentences from text."""
+        ContextGuard._track(store, "compressed")
+        sentences = ContextGuard._split_sentences(text)
+        if not sentences:
+            return {"success": True, "keys": [], "count": 0}
+
+        word_freqs = ContextGuard._word_freq(text)
+        total_words = sum(word_freqs.values())
+        scored = [(ContextGuard._sentence_score(s, word_freqs, total_words), i, s) for i, s in enumerate(sentences)]
+        scored.sort(key=lambda x: (-x[0], x[1]))
+        top = scored[:num_keys]
+        top.sort(key=lambda x: x[1])  # Restore order
+
+        return {"success": True, "keys": [s for _, _, s in top], "count": len(top)}
+
+    @staticmethod
+    def truncate_smart(store: Dict, text: str, max_tokens: int = 200) -> Dict:
+        """Smart truncation that preserves structure."""
+        ContextGuard._track(store, "compressed")
+        original_tokens = ContextGuard.estimate_tokens(text)
+        if original_tokens <= max_tokens:
+            return {"success": True, "text": text, "truncated": False, "original_tokens": original_tokens, "final_tokens": original_tokens}
+
+        # Try to cut at sentence boundary
+        sentences = ContextGuard._split_sentences(text)
+        result = ""
+        for s in sentences:
+            candidate = result + " " + s if result else s
+            if ContextGuard.estimate_tokens(candidate) > max_tokens:
+                break
+            result = candidate
+
+        if not result:
+            # Fallback: hard cut at word boundary
+            words = text.split()
+            while words and ContextGuard.estimate_tokens(" ".join(words)) > max_tokens:
+                words.pop()
+            result = " ".join(words) + "..."
+
+        final_tokens = ContextGuard.estimate_tokens(result)
+        saved = original_tokens - final_tokens
+        ContextGuard._track(store, "tokens_saved", saved)
+
+        return {"success": True, "text": result, "truncated": True, "original_tokens": original_tokens, "final_tokens": final_tokens, "saved": saved}
+
+    @staticmethod
+    def chunk(store: Dict, text: str, max_tokens: int = 500, overlap: int = 50) -> Dict:
+        """Split text into token-sized chunks with optional overlap."""
+        ContextGuard._track(store, "chunks_created")
+        sentences = ContextGuard._split_sentences(text)
+        chunks = []
+        current = ""
+        for s in sentences:
+            candidate = current + " " + s if current else s
+            if ContextGuard.estimate_tokens(candidate) > max_tokens and current:
+                chunks.append(current.strip())
+                # Overlap: keep last few words
+                if overlap > 0:
+                    words = current.split()
+                    overlap_text = " ".join(words[-overlap:])
+                    current = overlap_text + " " + s
+                else:
+                    current = s
+            else:
+                current = candidate
+        if current.strip():
+            chunks.append(current.strip())
+
+        return {"success": True, "chunks": chunks, "count": len(chunks), "total_tokens": sum(ContextGuard.estimate_tokens(c) for c in chunks)}
+
+    @staticmethod
+    def token_count(store: Dict, text: str) -> Dict:
+        """Estimate token count for text."""
+        tokens = ContextGuard.estimate_tokens(text)
+        words = len(re.findall(r"\b\w+\b", text))
+        chars = len(text)
+        return {"success": True, "tokens": tokens, "words": words, "chars": chars, "ratio": round(tokens / max(words, 1), 2)}
+
+    @staticmethod
+    def summarize_history(store: Dict, messages: List[Dict], max_tokens: int = 300) -> Dict:
+        """Compress conversation history into key points."""
+        ContextGuard._track(store, "compressed")
+        # Extract text content from messages
+        texts = []
+        for msg in messages:
+            role = msg.get("role", "unknown")
+            content = msg.get("content", "")
+            if isinstance(content, str):
+                texts.append(f"[{role}] {content}")
+            elif isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "text":
+                        texts.append(f"[{role}] {block.get('text', '')}")
+
+        combined = " ".join(texts)
+        result = ContextGuard.compress(store, combined, max_tokens=max_tokens)
+        result["messages_processed"] = len(messages)
+        return result
+
+    @staticmethod
+    def filter_relevant(store: Dict, query: str, passages: List[str], top_k: int = 5) -> Dict:
+        """BM25-like relevance scoring. Return top-K passages for query."""
+        ContextGuard._track(store, "filtered")
+        if not passages:
+            return {"success": True, "results": [], "count": 0}
+
+        query_words = set(re.findall(r"\b\w+\b", query.lower()))
+        # Build document frequency map
+        doc_freqs = collections.Counter()
+        for p in passages:
+            p_words = set(re.findall(r"\b\w+\b", p.lower()))
+            for w in p_words:
+                doc_freqs[w] += 1
+
+        N = len(passages)
+        avg_len = sum(len(re.findall(r"\b\w+\b", p)) for p in passages) / N
+        k1, b = 1.5, 0.75  # BM25 params
+
+        scored = []
+        for i, p in enumerate(passages):
+            p_words = re.findall(r"\b\w+\b", p.lower())
+            p_len = len(p_words)
+            p_word_counts = collections.Counter(p_words)
+            score = 0.0
+            for qw in query_words:
+                if qw not in p_word_counts:
+                    continue
+                tf = p_word_counts[qw]
+                df = doc_freqs.get(qw, 0)
+                idf = math.log((N - df + 0.5) / (df + 0.5) + 1)
+                score += idf * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * p_len / max(avg_len, 1)))
+            scored.append((score, i, p))
+
+        scored.sort(key=lambda x: -x[0])
+        top = scored[:top_k]
+        results = [{"passage": p, "score": round(s, 4), "index": i} for s, i, p in top if s > 0]
+
+        return {"success": True, "results": results, "count": len(results), "total_passages": len(passages)}
+
+    @staticmethod
+    def merge_context(store: Dict, sources: List[str], max_tokens: int = 1000, deduplicate: bool = True) -> Dict:
+        """Merge multiple text sources, deduplicate, sort by relevance, truncate."""
+        ContextGuard._track(store, "compressed")
+        if deduplicate:
+            dedup = ContextGuard.deduplicate(store, sources)
+            sources = dedup["unique"]
+
+        combined = " ".join(sources)
+        result = ContextGuard.compress(store, combined, max_tokens=max_tokens)
+        result["sources_merged"] = len(sources)
+        return result
+
+    @staticmethod
+    def get_stats(store: Dict) -> Dict:
+        return {"success": True, **store["stats"], "budget": store["budget"]}
+
+    @staticmethod
+    def reset(store: Dict) -> Dict:
+        old = ContextGuard.get_stats(store)
+        store["stats"] = {"compressed": 0, "tokens_saved": 0, "chunks_created": 0, "filtered": 0, "errors": 0}
+        store["budget"] = {"limit": 0, "used": 0}
+        store["seen_hashes"] = set()
+        store["history"] = []
+        return {"success": True, "reset": old}

mcp_context_guard-1.0.0/src/server.py

@@ -0,0 +1,75 @@
+"""MCP Server for Context Guard — compress, budget, deduplicate, filter."""
+import json, sys, argparse
+from .context_guard_engine import ContextGuard
+
+_store = ContextGuard.create_store()
+
+TOOL_DEFS = [
+    {"name":"compress","description":"Compress text to a token budget using extractive summarization.","inputSchema":{"type":"object","properties":{"text":{"type":"string"},"max_tokens":{"type":"integer","default":500},"strategy":{"type":"string","default":"extractive"}},"required":["text"]}},
+    {"name":"set_budget","description":"Set a token budget limit.","inputSchema":{"type":"object","properties":{"limit":{"type":"integer"}},"required":["limit"]}},
+    {"name":"check_budget","description":"Check if text fits within remaining token budget.","inputSchema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}},
+    {"name":"consume_budget","description":"Add text tokens to budget usage.","inputSchema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}},
+    {"name":"deduplicate","description":"Remove near-duplicate texts using Jaccard similarity.","inputSchema":{"type":"object","properties":{"texts":{"type":"array","items":{"type":"string"}},"similarity_threshold":{"type":"number","default":0.8}},"required":["texts"]}},
+    {"name":"extract_key","description":"Extract key sentences from text.","inputSchema":{"type":"object","properties":{"text":{"type":"string"},"num_keys":{"type":"integer","default":5}},"required":["text"]}},
+    {"name":"truncate_smart","description":"Truncate text at sentence boundaries to fit token budget.","inputSchema":{"type":"object","properties":{"text":{"type":"string"},"max_tokens":{"type":"integer","default":200}},"required":["text"]}},
+    {"name":"chunk","description":"Split text into token-sized chunks with overlap.","inputSchema":{"type":"object","properties":{"text":{"type":"string"},"max_tokens":{"type":"integer","default":500},"overlap":{"type":"integer","default":50}},"required":["text"]}},
+    {"name":"token_count","description":"Estimate token count for text.","inputSchema":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}},
+    {"name":"summarize_history","description":"Compress conversation history into key points.","inputSchema":{"type":"object","properties":{"messages":{"type":"array","items":{"type":"object"}},"max_tokens":{"type":"integer","default":300}},"required":["messages"]}},
+    {"name":"filter_relevant","description":"BM25 relevance scoring. Return top-K passages for a query.","inputSchema":{"type":"object","properties":{"query":{"type":"string"},"passages":{"type":"array","items":{"type":"string"}},"top_k":{"type":"integer","default":5}},"required":["query","passages"]}},
+    {"name":"merge_context","description":"Merge multiple text sources with dedup and compression.","inputSchema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"string"}},"max_tokens":{"type":"integer","default":1000},"deduplicate":{"type":"boolean","default":True}},"required":["sources"]}},
+    {"name":"get_stats","description":"Get context guard statistics.","inputSchema":{"type":"object","properties":{},"required":[]}},
+    {"name":"reset","description":"Reset all stats, budgets, and history.","inputSchema":{"type":"object","properties":{},"required":[]}},
+]
+
+class MCPContextGuardServer:
+    def __init__(self,name="mcp-context-guard",version="1.0.0"):
+        self.name=name;self.version=version
+    def list_tools(self):return TOOL_DEFS
+    def manifest(self):return{"server":{"name":self.name,"version":self.version},"capabilities":{"tools":{"listChanged":False}},"tools":self.list_tools()}
+    def handle_tool_call(self,name,args):
+        try:
+            if name=="compress":return json.dumps(ContextGuard.compress(_store,args["text"],args.get("max_tokens",500),args.get("strategy","extractive")))
+            elif name=="set_budget":return json.dumps(ContextGuard.set_budget(_store,args["limit"]))
+            elif name=="check_budget":return json.dumps(ContextGuard.check_budget(_store,args["text"]))
+            elif name=="consume_budget":return json.dumps(ContextGuard.consume_budget(_store,args["text"]))
+            elif name=="deduplicate":return json.dumps(ContextGuard.deduplicate(_store,args["texts"],args.get("similarity_threshold",0.8)))
+            elif name=="extract_key":return json.dumps(ContextGuard.extract_key(_store,args["text"],args.get("num_keys",5)))
+            elif name=="truncate_smart":return json.dumps(ContextGuard.truncate_smart(_store,args["text"],args.get("max_tokens",200)))
+            elif name=="chunk":return json.dumps(ContextGuard.chunk(_store,args["text"],args.get("max_tokens",500),args.get("overlap",50)))
+            elif name=="token_count":return json.dumps(ContextGuard.token_count(_store,args["text"]))
+            elif name=="summarize_history":return json.dumps(ContextGuard.summarize_history(_store,args["messages"],args.get("max_tokens",300)))
+            elif name=="filter_relevant":return json.dumps(ContextGuard.filter_relevant(_store,args["query"],args["passages"],args.get("top_k",5)))
+            elif name=="merge_context":return json.dumps(ContextGuard.merge_context(_store,args["sources"],args.get("max_tokens",1000),args.get("deduplicate",True)))
+            elif name=="get_stats":return json.dumps(ContextGuard.get_stats(_store))
+            elif name=="reset":return json.dumps(ContextGuard.reset(_store))
+            else:return json.dumps({"error":f"Unknown tool: {name}"})
+        except KeyError as e:return json.dumps({"error":f"Missing required parameter: {e}","tool":name})
+        except Exception as e:return json.dumps({"error":str(e),"tool":name})
+
+def _run_stdio():
+    server=MCPContextGuardServer()
+    for line in sys.stdin:
+        line=line.strip()
+        if not line:continue
+        try:request=json.loads(line)
+        except json.JSONDecodeError:print(json.dumps({"jsonrpc":"2.0","error":{"code":-32700,"message":"Parse error"}}),flush=True);continue
+        method=request.get("method","");req_id=request.get("id");params=request.get("params",{})
+        if method=="initialize":response={"jsonrpc":"2.0","id":req_id,"result":{"server":server.name,"version":server.version}}
+        elif method=="tools/list":response={"jsonrpc":"2.0","id":req_id,"result":{"tools":server.list_tools()}}
+        elif method=="tools/call":
+            result=server.handle_tool_call(params.get("name",""),params.get("arguments",{}))
+            response={"jsonrpc":"2.0","id":req_id,"result":{"content":[{"type":"text","text":result}]}}
+        elif method=="shutdown":response={"jsonrpc":"2.0","id":req_id,"result":{}};print(json.dumps(response),flush=True);break
+        else:response={"jsonrpc":"2.0","id":req_id,"error":{"code":-32601,"message":f"Method not found: {method}"}}
+        print(json.dumps(response),flush=True)
+
+def main():
+    parser=argparse.ArgumentParser(description="MCP Context Guard Server")
+    parser.add_argument("--stdio",action="store_true")
+    parser.add_argument("--manifest",action="store_true")
+    args=parser.parse_args()
+    if args.manifest:print(json.dumps(MCPContextGuardServer().manifest(),indent=2))
+    elif args.stdio:_run_stdio()
+    else:parser.print_help()
+
+if __name__=="__main__":main()

mcp_context_guard-1.0.0/tests/test_context_guard.py

@@ -0,0 +1,217 @@
+"""Tests for MCP Context Guard — compress, budget, deduplicate, filter, chunk."""
+import json, pytest, os, sys
+from unittest.mock import patch
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from src.server import MCPContextGuardServer, TOOL_DEFS
+from src.context_guard_engine import ContextGuard
+
+class TestToolDefs:
+    def test_names(self):
+        for t in TOOL_DEFS: assert "name" in t and len(t["name"])>0
+    def test_descs(self):
+        for t in TOOL_DEFS: assert "description" in t and len(t["description"])>15
+    def test_schema(self):
+        for t in TOOL_DEFS: assert "inputSchema" in t and t["inputSchema"]["type"]=="object"
+    def test_count(self):
+        assert len(TOOL_DEFS)==14
+    def test_required(self):
+        names={t["name"] for t in TOOL_DEFS}
+        expected={"compress","set_budget","check_budget","consume_budget","deduplicate","extract_key","truncate_smart","chunk","token_count","summarize_history","filter_relevant","merge_context","get_stats","reset"}
+        assert names==expected
+
+class TestManifest:
+    def test_manifest(self):
+        s=MCPContextGuardServer();m=s.manifest()
+        assert m["server"]["name"]=="mcp-context-guard"
+        assert len(m["tools"])==14
+
+class TestTokenCount:
+    def test_basic(self):
+        s=ContextGuard.create_store()
+        r=ContextGuard.token_count(s,"hello world test")
+        assert r["tokens"]>0
+        assert r["words"]==3
+    def test_empty(self):
+        s=ContextGuard.create_store()
+        r=ContextGuard.token_count(s,"")
+        assert r["tokens"]==1  # max(1, 0)
+
+class TestCompress:
+    def test_short_text(self):
+        s=ContextGuard.create_store()
+        r=ContextGuard.compress(s,"Hello world.",max_tokens=100)
+        assert r["ratio"]==1.0
+        assert r["saved"]==0
+    def test_long_text(self):
+        s=ContextGuard.create_store()
+        text = ". ".join(f"Sentence number {i} about topic {i%3}" for i in range(50))
+        r=ContextGuard.compress(s,text,max_tokens=50)
+        assert r["compressed_tokens"]<=60  # approximate
+        assert r["saved"]>0
+        assert r["ratio"]<1.0
+    def test_preserves_structure(self):
+        s=ContextGuard.create_store()
+        text = "First important sentence. Second sentence here. Third one is also key. Fourth is filler about nothing. Fifth concludes everything."
+        r=ContextGuard.compress(s,text,max_tokens=20)
+        assert len(r["text"])>0
+
+class TestBudget:
+    def test_set_and_check(self):
+        s=ContextGuard.create_store()
+        ContextGuard.set_budget(s, 100)
+        r=ContextGuard.check_budget(s, "hello world")
+        assert r["fits"] is True
+    def test_overflow(self):
+        s=ContextGuard.create_store()
+        ContextGuard.set_budget(s, 5)
+        r=ContextGuard.check_budget(s, "this is a very long text that exceeds the budget")
+        assert r["would_overflow"] is True
+    def test_consume(self):
+        s=ContextGuard.create_store()
+        ContextGuard.set_budget(s, 100)
+        r=ContextGuard.consume_budget(s, "hello world test")
+        assert r["consumed"]>0
+        assert r["total_used"]>0
+
+class TestDeduplicate:
+    def test_removes_dup(self):
+        s=ContextGuard.create_store()
+        texts = ["hello world", "hello world", "different text"]
+        r=ContextGuard.deduplicate(s, texts)
+        assert r["kept"]==2
+        assert r["removed"]==1
+    def test_near_dup(self):
+        s=ContextGuard.create_store()
+        texts = ["The quick brown fox jumps over the lazy dog", "The quick brown fox jumps over the lazy dog today"]
+        r=ContextGuard.deduplicate(s, texts, similarity_threshold=0.7)
+        assert r["kept"]==1
+    def test_no_dup(self):
+        s=ContextGuard.create_store()
+        texts = ["completely different", "totally unrelated", "no similarity here"]
+        r=ContextGuard.deduplicate(s, texts)
+        assert r["kept"]==3
+    def test_empty(self):
+        s=ContextGuard.create_store()
+        r=ContextGuard.deduplicate(s, [])
+        assert r["kept"]==0
+
+class TestExtractKey:
+    def test_basic(self):
+        s=ContextGuard.create_store()
+        text = "Python is great. The weather is nice. Machine learning uses Python. I like pizza. Data science requires Python skills."
+        r=ContextGuard.extract_key(s, text, num_keys=2)
+        assert r["count"]==2
+        # Python sentences should score higher due to frequency
+    def test_empty(self):
+        s=ContextGuard.create_store()
+        r=ContextGuard.extract_key(s, "", num_keys=3)
+        assert r["count"]==0
+
+class TestTruncateSmart:
+    def test_short(self):
+        s=ContextGuard.create_store()
+        r=ContextGuard.truncate_smart(s, "Hello world.", max_tokens=100)
+        assert r["truncated"] is False
+    def test_long(self):
+        s=ContextGuard.create_store()
+        text = ". ".join(f"Sentence {i}" for i in range(100))
+        r=ContextGuard.truncate_smart(s, text, max_tokens=30)
+        assert r["truncated"] is True
+        assert r["saved"]>0
+
+class TestChunk:
+    def test_basic(self):
+        s=ContextGuard.create_store()
+        text = ". ".join(f"Sentence {i}" for i in range(20))
+        r=ContextGuard.chunk(s, text, max_tokens=30, overlap=0)
+        assert r["count"]>1
+        assert all(c for c in r["chunks"])
+    def test_overlap(self):
+        s=ContextGuard.create_store()
+        text = ". ".join(f"Sentence {i}" for i in range(20))
+        r=ContextGuard.chunk(s, text, max_tokens=30, overlap=5)
+        assert r["count"]>1
+
+class TestSummarizeHistory:
+    def test_basic(self):
+        s=ContextGuard.create_store()
+        msgs = [
+            {"role": "user", "content": "How do I write a Python function?"},
+            {"role": "assistant", "content": "You can use def keyword to define a function in Python."},
+            {"role": "user", "content": "What about classes?"},
+            {"role": "assistant", "content": "Use class keyword to define a class."},
+        ]
+        r=ContextGuard.summarize_history(s, msgs, max_tokens=50)
+        assert r["messages_processed"]==4
+        assert len(r["text"])>0
+
+class TestFilterRelevant:
+    def test_basic(self):
+        s=ContextGuard.create_store()
+        query = "Python function"
+        passages = [
+            "Python functions are defined with def",
+            "Java classes use different syntax",
+            "def is a Python keyword for functions",
+            "The weather is nice today",
+            "Python also has lambda functions",
+        ]
+        r=ContextGuard.filter_relevant(s, query, passages, top_k=3)
+        assert r["count"]<=3
+        assert r["results"][0]["score"]>0
+        # Python passages should rank higher
+    def test_no_match(self):
+        s=ContextGuard.create_store()
+        r=ContextGuard.filter_relevant(s, "xyzabc", ["hello world", "foo bar"], top_k=5)
+        assert r["count"]==0
+    def test_empty(self):
+        s=ContextGuard.create_store()
+        r=ContextGuard.filter_relevant(s, "test", [], top_k=5)
+        assert r["count"]==0
+
+class TestMergeContext:
+    def test_basic(self):
+        s=ContextGuard.create_store()
+        sources = [
+            "Python is a programming language.",
+            "Python is used for data science.",
+            "Java is also a programming language.",
+        ]
+        r=ContextGuard.merge_context(s, sources, max_tokens=50)
+        assert r["sources_merged"]>=1
+        assert len(r["text"])>0
+    def test_dedup(self):
+        s=ContextGuard.create_store()
+        sources = ["hello world", "hello world"]
+        r=ContextGuard.merge_context(s, sources, max_tokens=100, deduplicate=True)
+        assert r["sources_merged"]==1
+
+class TestStatsReset:
+    def test_stats(self):
+        s=ContextGuard.create_store()
+        ContextGuard.compress(s, "test text here now")
+        r=ContextGuard.get_stats(s)
+        assert r["compressed"]==1
+    def test_reset(self):
+        s=ContextGuard.create_store()
+        ContextGuard.compress(s, "test text here now")
+        r=ContextGuard.reset(s)
+        assert r["reset"]["compressed"]==1
+        assert ContextGuard.get_stats(s)["compressed"]==0
+
+class TestDispatch:
+    def test_unknown(self):
+        s=MCPContextGuardServer();assert "error" in json.loads(s.handle_tool_call("nope",{}))
+    def test_missing(self):
+        s=MCPContextGuardServer();assert "error" in json.loads(s.handle_tool_call("compress",{}))
+    def test_compress_dispatch(self):
+        s=MCPContextGuardServer()
+        r=json.loads(s.handle_tool_call("compress",{"text":"hello world"}))
+        assert r["success"] is True
+
+class TestSTDIO:
+    def test_manifest_flag(self,capsys):
+        from src.server import main
+        with patch("sys.argv",["server","--manifest"]):main()
+        parsed=json.loads(capsys.readouterr().out.strip())
+        assert parsed["server"]["name"]=="mcp-context-guard"