{
"markdown": "# Massive Context MCP\n\n\n\n[](https://pypi.org/project/massive-context-mcp/)\n[](https://registry.mcp.so/servers/io.github.egoughnour/massive-context-mcp)\n[](https://github.com/egoughnour/massive-context-mcp/releases/latest/download/massive-context-mcp.mcpb)\n[](https://github.com/egoughnour/massive-context-mcp/actions/workflows/test.yml)\n[](https://github.com/egoughnour/massive-context-mcp/actions/workflows/release.yml)\n[](https://opensource.org/licenses/MIT)\n\n[](https://github.com/egoughnour/massive-context-mcp/languages) [](https://github.com/egoughnour/massive-context-mcp) [](https://github.com/egoughnour/massive-context-mcp/commits/main) [](https://github.com/egoughnour/massive-context-mcp)\n\nHandle massive contexts (10M+ tokens) with chunking, sub-queries, and free local inference via Ollama.\n\n```mermaid\nflowchart TD\n A[Claude Code] --> B[RLM MCP Server]\n B --> C{rlm_ollama_status}\n C -->|cached 60s| D{provider = auto}\n\n D -->|Ollama running| E[π¦ Ollama
gemma3:12b]\n D -->|Ollama unavailable| F[βοΈ Claude SDK
claude-haiku-4-5]\n\n E --> G[[\"π° $0
Free local inference\"]]\n F --> H[[\"π° ~$0.80/1M
Cloud inference\"]]\n\n style A fill:#ff922b,color:#fff\n style B fill:#339af0,color:#fff\n style E fill:#51cf66,color:#fff\n style F fill:#748ffc,color:#fff\n style G fill:#51cf66,color:#fff\n style H fill:#748ffc,color:#fff\n```\n\nBased on the [Recursive Language Model pattern](https://arxiv.org/html/2512.24601v1). Inspired by [richardwhiteii/rlm](https://github.com/richardwhiteii/rlm).\n\n\nπΈ Screenshots
\n\n\n\n \n\n## Core Idea\n\nInstead of feeding massive contexts directly into the LLM:\n1. **Load** context as external variable (stays out of prompt)\n2. **Inspect** structure programmatically\n3. **Chunk** strategically (lines, chars, or paragraphs)\n4. **Sub-query** recursively on chunks\n5. **Aggregate** results for final synthesis\n\n## Quick Start\n\n### Installation\n\n**Option 1: PyPI (Recommended)**\n\n```bash\nuvx massive-context-mcp\n# or\npip install massive-context-mcp\n```\n\n**With Optional Extras:**\n\n```bash\n# With Code Firewall integration (security filter for rlm_exec)\npip install massive-context-mcp[firewall]\n\n# With Claude Agent SDK (for programmatic Claude API access)\npip install massive-context-mcp[claude]\n\n# With all extras\npip install massive-context-mcp[firewall,claude]\n```\n\n**Option 2: Claude Desktop One-Click**\n\nDownload the `.mcpb` from [Releases](https://github.com/egoughnour/massive-context-mcp/releases) and double-click to install.\n\n**Option 3: From Source**\n\n```bash\ngit clone https://github.com/egoughnour/massive-context-mcp.git\ncd massive-context-mcp\nuv sync\n```\n\n### Wire to Claude Code / Claude Desktop\n\nAdd to `~/.claude/.mcp.json` (Claude Code) or `claude_desktop_config.json` (Claude Desktop):\n\n```json\n{\n \"mcpServers\": {\n \"massive-context\": {\n \"command\": \"uvx\",\n \"args\": [\"massive-context-mcp\"],\n \"env\": {\n \"RLM_DATA_DIR\": \"~/.rlm-data\",\n \"OLLAMA_URL\": \"http://localhost:11434\"\n }\n }\n }\n}\n```\n\n## Tools\n\n### Setup & Status Tools\n\n| Tool | Purpose |\n|------|---------|\n| `rlm_system_check` | **Check system requirements** β verify macOS, Apple Silicon, 16GB+ RAM, Homebrew |\n| `rlm_setup_ollama` | **Install via Homebrew** β managed service, auto-updates, requires Homebrew |\n| `rlm_setup_ollama_direct` | **Install via direct download** β no sudo, fully headless, works on locked-down machines |\n| `rlm_ollama_status` | **Check Ollama availability** β detect if free local inference is available |\n\n### Analysis Tools\n\n| Tool | Purpose |\n|------|---------|\n| `rlm_auto_analyze` | **One-step analysis** β auto-detects type, chunks, and queries |\n| `rlm_load_context` | Load context as external variable |\n| `rlm_inspect_context` | Get structure info without loading into prompt |\n| `rlm_chunk_context` | Chunk by lines/chars/paragraphs |\n| `rlm_get_chunk` | Retrieve specific chunk |\n| `rlm_filter_context` | Filter with regex (keep/remove matching lines) |\n| `rlm_exec` | Execute Python code against loaded context (sandboxed) |\n| `rlm_sub_query` | Make sub-LLM call on chunk |\n| `rlm_sub_query_batch` | Process multiple chunks in parallel |\n| `rlm_store_result` | Store sub-call result for aggregation |\n| `rlm_get_results` | Retrieve stored results |\n| `rlm_list_contexts` | List all loaded contexts |\n\n### Quick Analysis with `rlm_auto_analyze`\n\nFor most use cases, just use `rlm_auto_analyze` β it handles everything automatically:\n\n```python\nrlm_auto_analyze(\n name=\"my_file\",\n content=file_content,\n goal=\"find_bugs\" # or: summarize, extract_structure, security_audit, answer:\n)\n```\n\n**What it does automatically:**\n1. Detects content type (Python, JSON, Markdown, logs, prose, code)\n2. Selects optimal chunking strategy\n3. Adapts the query for the content type\n4. Runs parallel sub-queries\n5. Returns aggregated results\n\n**Supported goals:**\n\n| Goal | Description |\n|------|-------------|\n| `summarize` | Summarize content purpose and key points |\n| `find_bugs` | Identify errors, issues, potential problems |\n| `extract_structure` | List functions, classes, schema, headings |\n| `security_audit` | Find vulnerabilities and security issues |\n| `answer:` | Answer a custom question about the content |\n\n### Programmatic Analysis with `rlm_exec`\n\nFor deterministic pattern matching and data extraction, use `rlm_exec` to run Python code directly against a loaded context. This is closer to the paper's REPL approach and provides full control over analysis logic.\n\n**Tool**: `rlm_exec`\n\n**Purpose**: Execute arbitrary Python code against a loaded context in a sandboxed subprocess.\n\n**Parameters**:\n- `code` (required): Python code to execute. Set the `result` variable to capture output.\n- `context_name` (required): Name of a previously loaded context.\n- `timeout` (optional, default 30): Maximum execution time in seconds.\n\n**Features**:\n- Context available as read-only `context` variable\n- Pre-imported modules: `re`, `json`, `collections`\n- Subprocess isolation (won't crash the server)\n- Timeout enforcement\n- Works on any system with Python (no Docker needed)\n\n**Example β Finding patterns in a loaded context**:\n\n```python\n# After loading a context\nrlm_exec(\n code=\"\"\"\nimport re\namounts = re.findall(r'\\$[\\d,]+', context)\nresult = {'count': len(amounts), 'sample': amounts[:5]}\n\"\"\",\n context_name=\"bill\"\n)\n```\n\n**Example Response**:\n\n```json\n{\n \"result\": {\n \"count\": 1247,\n \"sample\": [\"$500\", \"$1,000\", \"$250,000\", \"$100,000\", \"$50\"]\n },\n \"stdout\": \"\",\n \"stderr\": \"\",\n \"return_code\": 0,\n \"timed_out\": false\n}\n```\n\n**Example β Extracting structured data**:\n\n```python\nrlm_exec(\n code=\"\"\"\nimport re\nimport json\n\n# Find all email addresses\nemails = re.findall(r'\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b', context)\n\n# Count by domain\nfrom collections import Counter\ndomains = [e.split('@')[1] for e in emails]\ndomain_counts = Counter(domains)\n\nresult = {\n 'total_emails': len(emails),\n 'unique_domains': len(domain_counts),\n 'top_domains': domain_counts.most_common(5)\n}\n\"\"\",\n context_name=\"dataset\",\n timeout=60\n)\n```\n\n**When to use `rlm_exec` vs `rlm_sub_query`**:\n\n| Use Case | Tool | Why |\n|----------|------|-----|\n| Extract all dates, IDs, amounts | `rlm_exec` | Regex is deterministic and fast |\n| Find security vulnerabilities | `rlm_sub_query` | Requires reasoning and context |\n| Parse JSON/XML structure | `rlm_exec` | Standard libraries work perfectly |\n| Summarize themes or tone | `rlm_sub_query` | Natural language understanding needed |\n| Count word frequencies | `rlm_exec` | Simple computation, no AI needed |\n| Answer \"Why did X happen?\" | `rlm_sub_query` | Requires inference and reasoning |\n\n**Tip**: For large contexts, combine both β use `rlm_exec` to filter/extract, then `rlm_sub_query` for semantic analysis of filtered results.\n\n### Code Firewall Integration (Optional)\n\nFor enhanced security, integrate [code-firewall-mcp](https://github.com/egoughnour/code-firewall-mcp) to filter dangerous code patterns before execution:\n\n```bash\npip install massive-context-mcp[firewall]\n```\n\nWhen installed, `rlm_exec` can automatically check code against a blacklist of known dangerous patterns (e.g., `os.system()`, `eval()`, `subprocess` with `shell=True`). The firewall uses structural similarity matching β normalizing code to its skeleton and comparing against blacklisted patterns via embeddings.\n\n**How it works:**\n1. Code is parsed to a syntax tree and normalized (identifiers β `_`, strings β `\"S\"`)\n2. Normalized structure is embedded via Ollama\n3. Similarity is checked against blacklisted patterns in ChromaDB\n4. Code is blocked if similarity exceeds threshold (default: 0.85)\n\n**Configuration** (environment variables):\n- `RLM_FIREWALL_ENABLED=true` β Enable firewall checks (auto-enabled when package installed)\n- `RLM_FIREWALL_MODE=warn|block` β Warn or block on matches (default: `warn`)\n\n**Example blocked patterns:**\n- `os.system(user_input)` β Command injection\n- `eval(untrusted_data)` β Code injection\n- `subprocess.Popen(..., shell=True)` β Shell injection\n\nUse `rlm_firewall_status` to check firewall availability and configuration.\n\n## Providers & Auto-Detection\n\nRLM automatically detects and uses the best available provider:\n\n| Provider | Default Model | Cost | Use Case |\n|----------|--------------|------|----------|\n| `auto` | (best available) | $0 or ~$0.80/1M | **Default** β prefers Ollama if available |\n| `ollama` | gemma3:12b | $0 | Local inference, requires Ollama |\n| `claude-sdk` | claude-haiku-4-5 | ~$0.80/1M input | Cloud inference, always available |\n\n### How Auto-Detection Works\n\nWhen you use `provider=\"auto\"` (the default), RLM:\n\n1. **Checks if Ollama is running** at `OLLAMA_URL` (default: `http://localhost:11434`)\n2. **Checks if gemma3:12b is available** (or any gemma3 variant)\n3. **Uses Ollama if available**, otherwise falls back to Claude SDK\n\nThe status is cached for 60 seconds to avoid repeated network checks.\n\n### Check Ollama Status\n\nUse `rlm_ollama_status` to see what's available:\n\n```python\nrlm_ollama_status()\n```\n\n**Response when Ollama is ready:**\n```json\n{\n \"running\": true,\n \"models\": [\"gemma3:12b\", \"llama3:8b\"],\n \"default_model_available\": true,\n \"best_provider\": \"ollama\",\n \"recommendation\": \"Ollama is ready! Sub-queries will use free local inference by default.\"\n}\n```\n\n**Response when Ollama is not available:**\n```json\n{\n \"running\": false,\n \"error\": \"connection_refused\",\n \"best_provider\": \"claude-sdk\",\n \"recommendation\": \"Ollama not available. Sub-queries will use Claude API. To enable free local inference, install Ollama and run: ollama serve\"\n}\n```\n\n### Transparent Provider Selection\n\nAll sub-query responses include which provider was actually used:\n\n```json\n{\n \"provider\": \"ollama\",\n \"model\": \"gemma3:12b\",\n \"requested_provider\": \"auto\",\n \"response\": \"...\"\n}\n```\n\n## Autonomous Usage\n\nEnable Claude to use RLM tools automatically without manual invocation:\n\n**1. CLAUDE.md Integration**\nCopy `CLAUDE.md.example` content to your project's `CLAUDE.md` (or `~/.claude/CLAUDE.md` for global) to teach Claude when to reach for RLM tools automatically.\n\n**2. Hook Installation**\nCopy the `.claude/hooks/` directory to your project to auto-suggest RLM when reading files >10KB:\n```bash\ncp -r .claude/hooks/ /Users/your_username/your-project/.claude/hooks/\n```\nThe hook provides guidance but doesn't block reads.\n\n**3. Skill Reference**\nCopy the `.claude/skills/` directory for comprehensive RLM guidance:\n```bash\ncp -r .claude/skills/ /Users/your_username/your-project/.claude/skills/\n```\n\nWith these in place, Claude will autonomously detect when to use RLM instead of reading large files directly into context.\n\n### Setting Up Ollama (Free Local Inference)\n\nRLM can automatically install and configure Ollama on macOS with Apple Silicon. There are **two installation methods** with different trade-offs:\n\n#### Choosing an Installation Method\n\n| Aspect | `rlm_setup_ollama` (Homebrew) | `rlm_setup_ollama_direct` (Direct Download) |\n|--------|------------------------------|---------------------------------------------|\n| **Sudo required** | Only if Homebrew not installed | β Never |\n| **Homebrew required** | β
Yes | β No |\n| **Auto-updates** | β
Yes (`brew upgrade`) | β Manual |\n| **Service management** | β
`brew services` (launchd) | β οΈ `ollama serve` (foreground) |\n| **Install location** | `/opt/homebrew/` | `~/Applications/` |\n| **Locked-down machines** | β οΈ May fail | β
Works |\n| **Fully headless** | β οΈ May prompt for sudo | β
Yes |\n\n**Recommendation:**\n- Use **Homebrew method** if you have Homebrew and want managed updates\n- Use **Direct Download** for automation, locked-down machines, or when you don't have admin access\n\n#### Method 1: Homebrew Installation (Recommended if you have Homebrew)\n\n```python\n# 1. Check if your system meets requirements\nrlm_system_check()\n\n# 2. Install via Homebrew\nrlm_setup_ollama(install=True, start_service=True, pull_model=True)\n```\n\n**What this does:**\n- Installs Ollama via Homebrew (`brew install ollama`)\n- Starts Ollama as a managed background service (`brew services start ollama`)\n- Pulls gemma3:12b model (~8GB download)\n\n**Requirements:**\n- macOS with Apple Silicon (M1/M2/M3/M4)\n- 16GB+ RAM (gemma3:12b needs ~8GB to run)\n- Homebrew installed\n\n#### Method 2: Direct Download (Fully Headless, No Sudo)\n\n```python\n# 1. Check system (Homebrew NOT required for this method)\nrlm_system_check()\n\n# 2. Install via direct download - no sudo, no Homebrew\nrlm_setup_ollama_direct(install=True, start_service=True, pull_model=True)\n```\n\n**What this does:**\n- Downloads Ollama from https://ollama.com/download/Ollama-darwin.zip\n- Extracts to `~/Applications/Ollama.app` (user directory, no admin needed)\n- Starts Ollama via `ollama serve` (background process)\n- Pulls gemma3:12b model\n\n**Requirements:**\n- macOS with Apple Silicon (M1/M2/M3/M4)\n- 16GB+ RAM\n- No special permissions needed!\n\n**Note on PATH:** After direct installation, the CLI is at:\n```bash\n~/Applications/Ollama.app/Contents/Resources/ollama\n```\nAdd to your shell config if needed:\n```bash\nexport PATH=\"$HOME/Applications/Ollama.app/Contents/Resources:$PATH\"\n```\n\n#### For Systems with Less RAM\n\nUse a smaller model on either installation method:\n```python\nrlm_setup_ollama(install=True, start_service=True, pull_model=True, model=\"gemma3:4b\")\n# or\nrlm_setup_ollama_direct(install=True, start_service=True, pull_model=True, model=\"gemma3:4b\")\n```\n\n#### Manual Setup\n\nIf you prefer manual installation or are on a different platform:\n\n1. **Install Ollama** from https://ollama.ai or via Homebrew:\n ```bash\n brew install ollama\n ```\n\n2. **Start the service:**\n ```bash\n brew services start ollama\n # or: ollama serve\n ```\n\n3. **Pull the model:**\n ```bash\n ollama pull gemma3:12b\n ```\n\n4. **Verify it's working:**\n ```python\n rlm_ollama_status()\n ```\n\n#### Provider Selection\n\nRLM automatically uses Ollama when available. You can also force a specific provider:\n\n```python\n# Auto-detection (default) - uses Ollama if available\nrlm_sub_query(query=\"Summarize\", context_name=\"doc\")\n\n# Explicitly use Ollama\nrlm_sub_query(query=\"Summarize\", context_name=\"doc\", provider=\"ollama\")\n\n# Explicitly use Claude SDK\nrlm_sub_query(query=\"Summarize\", context_name=\"doc\", provider=\"claude-sdk\")\n```\n\n## Usage Example\n\n### Basic Pattern\n\n```\n# 0. (Optional) First-time setup on macOS - choose ONE method:\n\n# Option A: Homebrew (if you have it)\nrlm_system_check()\nrlm_setup_ollama(install=True, start_service=True, pull_model=True)\n\n# Option B: Direct download (no sudo, fully headless)\nrlm_system_check()\nrlm_setup_ollama_direct(install=True, start_service=True, pull_model=True)\n\n# 0b. (Optional) Check if Ollama is available for free inference\nrlm_ollama_status()\n\n# 1. Load a large document\nrlm_load_context(name=\"report\", content=)\n\n# 2. Inspect structure\nrlm_inspect_context(name=\"report\", preview_chars=500)\n\n# 3. Chunk into manageable pieces\nrlm_chunk_context(name=\"report\", strategy=\"paragraphs\", size=1)\n\n# 4. Sub-query chunks in parallel (auto-uses Ollama if available)\nrlm_sub_query_batch(\n query=\"What is the main topic? Reply in one sentence.\",\n context_name=\"report\",\n chunk_indices=[0, 1, 2, 3],\n concurrency=4\n)\n\n# 5. Store results for aggregation\nrlm_store_result(name=\"topics\", result=)\n\n# 6. Retrieve all results\nrlm_get_results(name=\"topics\")\n```\n\n### Processing a 2MB Document\n\nTested with H.R.1 Bill (2MB):\n\n```\n# Load\nrlm_load_context(name=\"bill\", content=<2MB XML>)\n\n# Chunk into 40 pieces (50K chars each)\nrlm_chunk_context(name=\"bill\", strategy=\"chars\", size=50000)\n\n# Sample 8 chunks (20%) with parallel queries\n# (auto-uses Ollama if running, otherwise Claude SDK)\nrlm_sub_query_batch(\n query=\"What topics does this section cover?\",\n context_name=\"bill\",\n chunk_indices=[0, 5, 10, 15, 20, 25, 30, 35],\n concurrency=4\n)\n```\n\nResult: Comprehensive topic extraction at $0 cost (with Ollama) or ~$0.02 (with Claude).\n\n### Analyzing War and Peace (3.3MB)\n\nLiterary analysis of Tolstoy's epic novel from Project Gutenberg:\n\n```bash\n# Download the text\ncurl -o war_and_peace.txt https://www.gutenberg.org/files/2600/2600-0.txt\n```\n\n```python\n# Load into RLM (3.3MB, 66K lines)\nrlm_load_context(name=\"war_and_peace\", content=open(\"war_and_peace.txt\").read())\n\n# Chunk by lines (1000 lines per chunk = 67 chunks)\nrlm_chunk_context(name=\"war_and_peace\", strategy=\"lines\", size=1000)\n\n# Sample 10 chunks evenly across the book (15% coverage)\nsample_indices = [0, 7, 14, 21, 28, 35, 42, 49, 56, 63]\n\n# Extract characters from each sampled section\nrlm_sub_query_batch(\n query=\"List major characters in this section with brief descriptions.\",\n context_name=\"war_and_peace\",\n chunk_indices=sample_indices,\n provider=\"claude-sdk\", # Haiku 4.5\n concurrency=8\n)\n```\n\nResult: Complete character arc across the novel β Pierre's journey from idealist to prisoner to husband, NatΓ‘sha's growth, NikolΓ‘i RostΓ³v's journey from soldier to landowner β all for ~$0.03.\n\n| Metric | Value |\n|--------|-------|\n| File size | 3.35 MB |\n| Lines | 66,033 |\n| Chunks | 67 |\n| Sampled | 10 (15%) |\n| Cost | ~$0.03 |\n\n## Data Storage\n\n```mermaid\ngraph TD\n A[(\"$RLM_DATA_DIR\")] --> B[\"π contexts/\"]\n A --> C[\"π chunks/\"]\n A --> D[\"π results/\"]\n\n B --> B1[\".txt files\"]\n B --> B2[\".meta.json\"]\n C --> C1[\"by context name\"]\n D --> D1[\".jsonl files\"]\n\n style A fill:#339af0,color:#fff\n style B fill:#51cf66,color:#fff\n style C fill:#51cf66,color:#fff\n style D fill:#51cf66,color:#fff\n```\n\nContexts persist across sessions. Chunked contexts are cached for reuse.\n\n## Learning Prompts\n\nUse these prompts with Claude Code to explore the codebase and learn RLM patterns. The code is the single source of truth.\n\n### Understanding the Tools\n\n```\nRead src/rlm_mcp_server.py and list all RLM tools with their parameters and purpose.\n```\n\n```\nExplain the chunking strategies available in rlm_chunk_context.\nWhen would I use each one?\n```\n\n```\nWhat's the difference between rlm_sub_query and rlm_sub_query_batch?\nShow me the implementation.\n```\n\n### Understanding the Architecture\n\n```\nRead src/rlm_mcp_server.py and explain how contexts are stored and persisted.\nWhere does the data live?\n```\n\n```\nHow does the claude-sdk provider extract text from responses?\nWalk me through _call_claude_sdk.\n```\n\n```\nWhat happens when I call rlm_load_context? Trace the full flow.\n```\n\n### Hands-On Learning\n\n```\nLoad the README as a context, chunk it by paragraphs,\nand run a sub-query on the first chunk to summarize it.\n```\n\n```\nShow me how to process a large file in parallel using rlm_sub_query_batch.\nUse a real example.\n```\n\n```\nI have a 1MB log file. Walk me through the RLM pattern to extract all errors.\n```\n\n### Extending RLM\n\n```\nRead the test file and explain what scenarios are covered.\nWhat edge cases should I be aware of?\n```\n\n```\nHow would I add a new chunking strategy (e.g., by regex delimiter)?\nShow me where to modify the code.\n```\n\n```\nHow would I add a new provider (e.g., OpenAI)?\nWhat functions need to change?\n```\n\n## License\n\nMIT\n",
"bytes": 21514,
"sha": "52fd71382e2abc38758cf6f13708a85e06faefdbd0356392255c341fd16b07cf",
"repo_slug": "egoughnour/massive-context-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_egoughnour_massive_context_mcp_b8cd6d97/readme"
}