{"id":"475b90ab-5a7b-4001-bd45-3802830a35ed","slug":"ar5en1c-context-guardian","kind":"mcp","name":"context-guardian","summary":"MCP server that indexes code, logs and config locally and gives coding agents search tools over the index.","owner":"Ar5en1c","repoUrl":"https://github.com/Ar5en1c/context-guardian","license":"MIT","licenseTier":"permissive","trust":"community","stars":7,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-04-08T17:25:06.000Z","addedAt":"2026-10-21T08:38:03.188Z","logoUrl":"https://avatars.githubusercontent.com/u/91252414?u=6491b45a2e3b151ed0df88893e43973b531cbc24&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["search","memory-knowledge","developer-tools"],"tags":["ai-agent","anthropic","cli","coding-agent","context-window","developer-tools","llm","ollama"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T18:33:21.889Z","sample":false,"url":"https://conduits.dev/tools/ar5en1c-context-guardian","language":"TypeScript","transports":["stdio"],"install":{"npm":"context-guardian-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Context Guardian\n\nMCP server that indexes context locally and gives agents search tools instead of raw context dumps.\n\nWorks with any MCP-compatible agent (Claude Code, Cursor, Aider, Cline, Factory Droid). Also works as a transparent proxy for agents that use OpenAI/Anthropic APIs directly.\n\n## How It Works\n\n1. Your agent sends a massive prompt (code + logs + configs) to the cloud\n2. Context Guardian intercepts it, chunks and indexes it locally using Ollama\n3. Instead of the raw dump, the cloud model gets **tools** to search the indexed content\n4. The model retrieves only what it needs → fewer tokens processed → lower cost\n\nThe local LLM (Qwen 3.5 4B) handles classification and embedding. The cloud model does the reasoning. You pay for focused retrieval, not haystack scanning.\n\n## Quick Start (MCP Mode)\n\n```bash\n# Install\nnpm install -g context-guardian-mcp\n\n# Start the MCP server\ncontext-guardian mcp\n\n# Add to your agent's MCP config:\n#   URL: http://localhost:9120/mcp\n```\n\n### Factory Droid\n```bash\ndroid mcp add context-guardian http://localhost:9120/mcp --type http\n```\n\n### Claude Code / Cursor / Cline\nAdd to your MCP settings:\n```json\n{\n  \"mcpServers\": {\n    \"context-guardian\": {\n      \"url\": \"http://localhost:9120/mcp\"\n    }\n  }\n}\n```\n\n## Quick Start (Proxy Mode)\n\n```bash\n# Start the proxy\ncontext-guardian start\n\n# Point your agent to the proxy instead of OpenAI/Anthropic:\nexport OPENAI_BASE_URL=http://localhost:9119/v1\n```\n\nThe proxy intercepts requests above the token threshold, rewrites them with RAG tools, runs a multi-round tool loop with the cloud, and returns the final response. Requests below the threshold pass through unchanged.\n\n## Requirements\n\n- **Node.js 20+**\n- **Ollama** running locally with:\n  - `ollama pull qwen3.5:4b` (intent extraction + classification)\n  - `ollama pull nomic-embed-text` (embeddings)\n\n## MCP Tools Exposed\n\n| Tool | Description |\n|------|-------------|\n| `index_content` | Index raw text (code, logs, configs) into the local store |\n| `grep` | Regex search across all indexed content with context lines |\n| `log_search` | Search logs/errors by query with relevance scoring |\n| `file_read` | Read a specific indexed file or path |\n| `summary` | Get a summary of indexed content by topic |\n| `repo_map` | Structural map of indexed repository (key files + symbols) |\n| `file_tree` | Compact file tree with coverage summary |\n| `symbol_find` | Find functions/classes/interfaces across indexed code |\n| `git_diff` | Inspect git changes (working/staged/all scope) |\n| `test_failures` | Summarize failing tests from logs or run project tests |\n| `run_checks` | Run lint/typecheck/test/build validation |\n\n## Benchmark Results\n\nMeasured on a **real codebase** (WebLLM/Bonsai-WebGPU R&D repository — public), 3 scenarios (75K-98K tokens each), 3 repeats, live Claude Opus via Factory Droid.\n\n| Mode | Accuracy | Token Reduction |\n|------|----------|-----------------|\n| Baseline (raw dump) | 100% | n/a |\n| **MCP (unguided)** | **100%** | **43.3%** |\n| Guided (search plan) | 94.4% | 53.6% |\n\n**Key findings:**\n- **Zero accuracy loss** when the cloud model uses tools autonomously (unguided MCP mode)\n- Dollar figures in the benchmark script come from a price table inside the script, not from a bill. Treat the token counts as the measurement.\n- On investigation tasks (finding bugs in 75K+ token logs), cost savings reach **50-67%**\n- On dense, mostly-relevant code contexts, savings are minimal (~2-14%) — CG correctly adds less value when context is already focused\n- Adds **15-25 seconds** per request (MCP indexing + tool calls). Negligible for 20-30 minute agent sessions\n\n### Methodology\n- Real files, not synthetic noise. Context is actual GPU kernel code, audit documents, and analysis reports\n- Facts scattered at random positions (not head/tail) to avoid primacy/recency bias\n- Ground truth is regex-checked against specific values in the codebase\n- 95% confidence intervals computed via Student's t-distribution\n- Reproducible: `npm run bench:oss` (local, no API key needed) or `npm run bench:realworld` (requires Droid CLI)\n- Full results in `benchmark/realworld-3way-results.json`\n\n## CLI Commands\n\n```bash\ncontext-guardian start          # Start proxy server (port 9119)\ncontext-guardian mcp            # Start MCP server (port 9120)\ncontext-guardian init           # Generate default config file\ncontext-guardian sessions       # List recent proxy sessions\ncontext-guardian compact        # Manual session compaction\ncontext-guardian eval --prompt  # A/B evaluation of a prompt\ncontext-guardian dry-run --file # Preview rewrite without cloud call\ncontext-guardian check          # Verify Ollama + model availability\n```\n\n## Configuration\n\nCreate `.context-guardian.json` with `context-guardian init`, or pass CLI flags:\n\n```bash\ncontext-guardian start \\\n  --port 9119 \\\n  --threshold 8000 \\      # tokens above this trigger interception\n  --budget 4000 \\         # max tokens in rewritten request\n  --model qwen3.5:4b \\    # local LLM model\n  --endpoint http://localhost:11434  # Ollama URL\n```\n\n## Architecture\n\n```\nAgent (Claude Code, Cursor, Aider...)\n  │\n  ├─[MCP mode]─→ Context Guardian MCP Server ──→ Ollama (local)\n  │               index_content / grep / search    ↓\n  │               ←── tool results ────────────── chunks + embeddings\n  │\n  └─[Proxy mode]→ Context Guardian Proxy ──→ Cloud API (OpenAI/Anthropic)\n                   intercept → rewrite → tool loop → response\n```\n\n**Local processing:** Chunking, classification (7 types), embedding (nomic-embed-text), cosine similarity search, entity extraction, session memory with SQLite persistence.\n\n**Cloud forwarding:** OpenAI and Anthropic format detection, multi-round tool call loop (up to 10 rounds), streaming SSE synthesis, auto-compaction of tool loop context.\n\n## License\n\nMIT\n\n## Author\n\nKuldeep Singh — [LinkedIn](https://www.linkedin.com/in/kuldeep-5ingh/)\n"}