Massive Context MCP

🚀 Massive Context MCP

Massive Context MCP 能夠通過分塊、子查詢和藉助 Ollama 進行免費本地推理，來處理大規模上下文（1000 萬個以上的標記）。

🚀 快速開始

📦 安裝指南

選項 1：通過 PyPI 安裝（推薦）

uvx massive-context-mcp
# 或者
pip install massive-context-mcp

安裝可選擴展

# 集成代碼防火牆（rlm_exec 的安全過濾器）
pip install massive-context-mcp[firewall]

# 集成 Claude 代理 SDK（用於以編程方式訪問 Claude API）
pip install massive-context-mcp[claude]

# 安裝所有擴展
pip install massive-context-mcp[firewall,claude]

選項 2：Claude 桌面版一鍵安裝

從 Releases 下載 .mcpb 文件，然後雙擊安裝。

選項 3：從源代碼安裝

git clone https://github.com/egoughnour/massive-context-mcp.git
cd massive-context-mcp
uv sync

連接到 Claude Code / Claude 桌面版

將以下內容添加到 ~/.claude/.mcp.json（Claude Code）或 claude_desktop_config.json（Claude 桌面版）中：

{
  "mcpServers": {
    "massive-context": {
      "command": "uvx",
      "args": ["massive-context-mcp"],
      "env": {
        "RLM_DATA_DIR": "~/.rlm-data",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

✨ 主要特性

核心思想

不直接將大規模上下文輸入到大語言模型（LLM）中，而是採用以下步驟：

1. 加載：將上下文作為外部變量加載（不包含在提示中）。
2. 檢查：以編程方式檢查結構。
3. 分塊：採用策略性的分塊方式（按行、字符或段落）。
4. 子查詢：對分塊進行遞歸子查詢。
5. 聚合：聚合結果以進行最終合成。

自動檢測和選擇最佳可用的提供者

RLM 會自動檢測並使用最佳可用的提供者：

提供者	默認模型	成本	使用場景
auto	（最佳可用）	$0 或約 $0.80/100 萬個標記	默認 — 如果 Ollama 可用，則優先使用
ollama	gemma3:12b	$0	本地推理，需要安裝 Ollama
claude-sdk	claude-haiku-4-5	約 $0.80/100 萬個輸入標記	雲推理，始終可用

支持多種工具進行上下文分析和處理

設置與狀態工具

工具	用途
rlm_system_check	檢查系統要求 — 驗證是否為 macOS、Apple Silicon 芯片、16GB 以上內存以及是否安裝了 Homebrew
rlm_setup_ollama	通過 Homebrew 安裝 — 託管服務，自動更新，需要安裝 Homebrew
rlm_setup_ollama_direct	通過直接下載安裝 — 無需 sudo 權限，完全無頭模式，適用於受限機器
rlm_ollama_status	檢查 Ollama 可用性 — 檢測是否可以進行免費本地推理

分析工具

工具	用途
rlm_auto_analyze	一步分析 — 自動檢測類型、分塊並進行查詢
rlm_load_context	將上下文作為外部變量加載
rlm_inspect_context	獲取結構信息，而不將其加載到提示中
rlm_chunk_context	按行、字符或段落進行分塊
rlm_get_chunk	檢索特定分塊
rlm_filter_context	使用正則表達式進行過濾（保留或移除匹配的行）
rlm_exec	針對加載的上下文執行 Python 代碼（沙盒環境）
rlm_sub_query	對分塊進行子 LLM 調用
rlm_sub_query_batch	並行處理多個分塊
rlm_store_result	存儲子調用結果以進行聚合
rlm_get_results	檢索存儲的結果
rlm_list_contexts	列出所有加載的上下文

💻 使用示例

基礎用法

# 0. （可選）在 macOS 上進行首次設置 - 選擇一種方法：

# 選項 A：使用 Homebrew（如果已安裝）
rlm_system_check()
rlm_setup_ollama(install=True, start_service=True, pull_model=True)

# 選項 B：直接下載（無需 sudo 權限，完全無頭模式）
rlm_system_check()
rlm_setup_ollama_direct(install=True, start_service=True, pull_model=True)

# 0b. （可選）檢查 Ollama 是否可用於免費推理
rlm_ollama_status()

# 1. 加載大型文檔
rlm_load_context(name="report", content=<large document>)

# 2. 檢查結構
rlm_inspect_context(name="report", preview_chars=500)

# 3. 將文檔分塊為可管理的部分
rlm_chunk_context(name="report", strategy="paragraphs", size=1)

# 4. 並行對子分塊進行查詢（如果 Ollama 可用，則自動使用）
rlm_sub_query_batch(
    query="What is the main topic? Reply in one sentence.",
    context_name="report",
    chunk_indices=[0, 1, 2, 3],
    concurrency=4
)

# 5. 存儲結果以進行聚合
rlm_store_result(name="topics", result=<response>)

# 6. 檢索所有結果
rlm_get_results(name="topics")

高級用法

處理 2MB 的文檔

# 加載
rlm_load_context(name="bill", content=<2MB XML>)

# 分塊為 40 個部分（每個部分 50000 個字符）
rlm_chunk_context(name="bill", strategy="chars", size=50000)

# 對 8 個分塊（20%）進行採樣並並行查詢
# （如果 Ollama 正在運行，則自動使用；否則使用 Claude SDK）
rlm_sub_query_batch(
    query="What topics does this section cover?",
    context_name="bill",
    chunk_indices=[0, 5, 10, 15, 20, 25, 30, 35],
    concurrency=4
)

結果：以 $0 成本（使用 Ollama）或約 $0.02（使用 Claude）進行全面的主題提取。

分析《戰爭與和平》（3.3MB）

# 下載文本
curl -o war_and_peace.txt https://www.gutenberg.org/files/2600/2600-0.txt

# 加載到 RLM 中（3.3MB，66000 行）
rlm_load_context(name="war_and_peace", content=open("war_and_peace.txt").read())

# 按行分塊（每個分塊 1000 行 = 67 個分塊）
rlm_chunk_context(name="war_and_peace", strategy="lines", size=1000)

# 從整本書中均勻採樣 10 個分塊（覆蓋率 15%）
sample_indices = [0, 7, 14, 21, 28, 35, 42, 49, 56, 63]

# 從每個採樣部分提取角色信息
rlm_sub_query_batch(
    query="List major characters in this section with brief descriptions.",
    context_name="war_and_peace",
    chunk_indices=sample_indices,
    provider="claude-sdk",  # Haiku 4.5
    concurrency=8
)

結果：完整呈現小說中的角色弧線 — 皮埃爾從理想主義者到囚犯再到丈夫的旅程、娜塔莎的成長、尼古拉·羅斯托夫從士兵到地主的轉變 — 全部成本約為 $0.03。

指標	值
文件大小	3.35 MB
行數	66033
分塊數	67
採樣數	10（15%）
成本	約 $0.03

📚 詳細文檔

使用 rlm_auto_analyze 進行快速分析

對於大多數用例，只需使用 rlm_auto_analyze，它會自動處理所有事情：

rlm_auto_analyze(
    name="my_file",
    content=file_content,
    goal="find_bugs"  # 或者: summarize, extract_structure, security_audit, answer:<question>
)

自動執行的操作：

1. 檢測內容類型（Python、JSON、Markdown、日誌、散文、代碼）。
2. 選擇最佳的分塊策略。
3. 根據內容類型調整查詢。
4. 運行並行子查詢。
5. 返回聚合結果。

支持的目標：

目標	描述
summarize	總結內容的目的和關鍵點
find_bugs	識別錯誤、問題和潛在風險
extract_structure	列出函數、類、模式、標題
security_audit	查找漏洞和安全問題
answer:<question>	回答關於內容的自定義問題

使用 rlm_exec 進行編程式分析

對於確定性的模式匹配和數據提取，可以使用 rlm_exec 直接針對加載的上下文運行 Python 代碼。這更接近論文中的 REPL 方法，並且可以完全控制分析邏輯。

工具：rlm_exec

用途：在沙盒子進程中針對加載的上下文執行任意 Python 代碼。

參數：

• code（必需）：要執行的 Python 代碼。設置 result 變量以捕獲輸出。
• context_name（必需）：之前加載的上下文的名稱。
• timeout（可選，默認 30）：最大執行時間（秒）。

特性：

• 上下文作為只讀 context 變量可用。
• 預導入模塊：re、json、collections。
• 子進程隔離（不會使服務器崩潰）。
• 超時強制機制。
• 適用於任何安裝了 Python 的系統（無需 Docker）。

示例 — 在加載的上下文中查找模式：

# 加載上下文後
rlm_exec(
    code="""
import re
amounts = re.findall(r'\$[\d,]+', context)
result = {'count': len(amounts), 'sample': amounts[:5]}
""",
    context_name="bill"
)

示例響應：

{
  "result": {
    "count": 1247,
    "sample": ["$500", "$1,000", "$250,000", "$100,000", "$50"]
  },
  "stdout": "",
  "stderr": "",
  "return_code": 0,
  "timed_out": false
}

示例 — 提取結構化數據：

rlm_exec(
    code="""
import re
import json

# 查找所有電子郵件地址
emails = re.findall(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', context)

# 按域名統計
from collections import Counter
domains = [e.split('@')[1] for e in emails]
domain_counts = Counter(domains)

result = {
    'total_emails': len(emails),
    'unique_domains': len(domain_counts),
    'top_domains': domain_counts.most_common(5)
}
""",
    context_name="dataset",
    timeout=60
)

何時使用 rlm_exec 與 rlm_sub_query：

使用場景	工具	原因
提取所有日期、ID、金額	rlm_exec	正則表達式具有確定性且速度快
查找安全漏洞	rlm_sub_query	需要推理和上下文理解
解析 JSON/XML 結構	rlm_exec	標準庫可以完美工作
總結主題或語氣	rlm_sub_query	需要自然語言理解
統計單詞頻率	rlm_exec	簡單計算，無需 AI
回答 “為什麼 X 會發生？”	rlm_sub_query	需要推理和推斷

提示：對於大型上下文，可以結合使用兩者 — 使用 rlm_exec 進行過濾/提取，然後使用 rlm_sub_query 對過濾後的結果進行語義分析。

代碼防火牆集成（可選）

為了增強安全性，可以集成 code-firewall-mcp，在執行前過濾危險的代碼模式：

pip install massive-context-mcp[firewall]

安裝後，rlm_exec 可以自動檢查代碼是否符合已知危險模式的黑名單（例如，os.system()、eval()、subprocess 且 shell=True）。防火牆使用結構相似性匹配 — 將代碼規範化為骨架，並通過嵌入與黑名單模式進行比較。

工作原理：

1. 將代碼解析為語法樹並進行規範化（標識符 → _，字符串 → "S"）。
2. 通過 Ollama 對規範化結構進行嵌入。
3. 在 ChromaDB 中檢查與黑名單模式的相似性。
4. 如果相似度超過閾值（默認：0.85），則阻止代碼執行。

配置（環境變量）：

• RLM_FIREWALL_ENABLED=true — 啟用防火牆檢查（安裝包時自動啟用）
• RLM_FIREWALL_MODE=warn|block — 匹配時警告或阻止（默認：warn）

示例被阻止的模式：

• os.system(user_input) — 命令注入
• eval(untrusted_data) — 代碼注入
• subprocess.Popen(..., shell=True) — shell 注入

使用 rlm_firewall_status 檢查防火牆的可用性和配置。

自動檢測提供者的工作原理

當使用 provider="auto"（默認設置）時，RLM 會執行以下操作：

1. 檢查 Ollama 是否正在運行：在 OLLAMA_URL（默認：http://localhost:11434）上進行檢查。
2. 檢查 gemma3:12b 是否可用：（或任何 gemma3 變體）。
3. 如果可用，則使用 Ollama：否則，回退到 Claude SDK。

狀態會緩存 60 秒，以避免重複的網絡檢查。

檢查 Ollama 狀態

使用 rlm_ollama_status 查看可用情況：

rlm_ollama_status()

當 Ollama 準備就緒時的響應：

{
  "running": true,
  "models": ["gemma3:12b", "llama3:8b"],
  "default_model_available": true,
  "best_provider": "ollama",
  "recommendation": "Ollama is ready! Sub-queries will use free local inference by default."
}

當 Ollama 不可用時的響應：

{
  "running": false,
  "error": "connection_refused",
  "best_provider": "claude-sdk",
  "recommendation": "Ollama not available. Sub-queries will use Claude API. To enable free local inference, install Ollama and run: ollama serve"
}

透明的提供者選擇

所有子查詢響應都會包含實際使用的提供者信息：

{
  "provider": "ollama",
  "model": "gemma3:12b",
  "requested_provider": "auto",
  "response": "..."
}

自主使用

讓 Claude 自動使用 RLM 工具，無需手動調用：

1. 集成 CLAUDE.md：將 CLAUDE.md.example 的內容複製到項目的 CLAUDE.md（或全局的 ~/.claude/CLAUDE.md）中，以教導 Claude 何時自動使用 RLM 工具。
2. 安裝鉤子：將 .claude/hooks/ 目錄複製到項目中，以便在讀取大於 10KB 的文件時自動建議使用 RLM：

cp -r .claude/hooks/ /Users/your_username/your-project/.claude/hooks/

鉤子提供指導，但不會阻止文件讀取。 3. 技能參考：複製 .claude/skills/ 目錄以獲取全面的 RLM 指導：

cp -r .claude/skills/ /Users/your_username/your-project/.claude/skills/

完成上述步驟後，Claude 將自動檢測何時使用 RLM，而不是直接將大文件讀取到上下文中。

設置 Ollama（免費本地推理）

RLM 可以在配備 Apple Silicon 的 macOS 上自動安裝和配置 Ollama。有 兩種安裝方法，各有優缺點：

選擇安裝方法

方面	rlm_setup_ollama（Homebrew）	rlm_setup_ollama_direct（直接下載）
是否需要 sudo 權限	僅在未安裝 Homebrew 時需要	❌ 從不
是否需要 Homebrew	✅ 是	❌ 否
自動更新	✅ 是（brew upgrade）	❌ 手動
服務管理	✅ brew services（launchd）	⚠️ ollama serve（前臺）
安裝位置	/opt/homebrew/	~/Applications/
受限機器	⚠️ 可能失敗	✅ 可用
完全無頭模式	⚠️ 可能會提示輸入 sudo 密碼	✅ 是

建議：

• 如果已安裝 Homebrew 並希望進行託管更新，請使用 Homebrew 方法。
• 如果需要自動化、在受限機器上使用或沒有管理員權限，請使用 直接下載方法。

方法 1：使用 Homebrew 安裝（如果已安裝 Homebrew，推薦使用）

# 1. 檢查系統是否滿足要求
rlm_system_check()

# 2. 通過 Homebrew 安裝
rlm_setup_ollama(install=True, start_service=True, pull_model=True)

執行的操作：

• 通過 Homebrew 安裝 Ollama（brew install ollama）。
• 將 Ollama 作為託管後臺服務啟動（brew services start ollama）。
• 拉取 gemma3:12b 模型（約 8GB 下載量）。

要求：

• 配備 Apple Silicon（M1/M2/M3/M4）的 macOS。
• 16GB 以上內存（gemma3:12b 需要約 8GB 內存才能運行）。
• 已安裝 Homebrew。

方法 2：直接下載（完全無頭模式，無需 sudo 權限）

# 1. 檢查系統（此方法不需要 Homebrew）
rlm_system_check()

# 2. 通過直接下載安裝 - 無需 sudo 權限，無需 Homebrew
rlm_setup_ollama_direct(install=True, start_service=True, pull_model=True)

執行的操作：

• 從 https://ollama.com/download/Ollama-darwin.zip 下載 Ollama。
• 解壓到 ~/Applications/Ollama.app（用戶目錄，無需管理員權限）。
• 通過 ollama serve 啟動 Ollama（後臺進程）。
• 拉取 gemma3:12b 模型。

要求：

• 配備 Apple Silicon（M1/M2/M3/M4）的 macOS。
• 16GB 以上內存。
• 無需特殊權限！

關於 PATH 的說明：直接安裝後，CLI 位於：

~/Applications/Ollama.app/Contents/Resources/ollama

如果需要，可將其添加到 shell 配置中：

export PATH="$HOME/Applications/Ollama.app/Contents/Resources:$PATH"

對於內存較少的系統

在任何一種安裝方法中，都可以使用較小的模型：

rlm_setup_ollama(install=True, start_service=True, pull_model=True, model="gemma3:4b")
# 或者
rlm_setup_ollama_direct(install=True, start_service=True, pull_model=True, model="gemma3:4b")

手動設置

如果您更喜歡手動安裝或使用不同的平臺：

1. 安裝 Ollama：從 https://ollama.ai 或通過 Homebrew 安裝：

brew install ollama

2. 啟動服務：

brew services start ollama
# 或者: ollama serve

3. 拉取模型：

ollama pull gemma3:12b

4. 驗證是否正常工作：

rlm_ollama_status()

提供者選擇

RLM 在可用時會自動使用 Ollama。您也可以強制使用特定的提供者：

# 自動檢測（默認） - 如果 Ollama 可用，則使用
rlm_sub_query(query="Summarize", context_name="doc")

# 顯式使用 Ollama
rlm_sub_query(query="Summarize", context_name="doc", provider="ollama")

# 顯式使用 Claude SDK
rlm_sub_query(query="Summarize", context_name="doc", provider="claude-sdk")

學習提示

使用以下提示與 Claude Code 一起探索代碼庫並學習 RLM 模式。代碼是唯一的事實來源。

理解工具

Read src/rlm_mcp_server.py and list all RLM tools with their parameters and purpose.

Explain the chunking strategies available in rlm_chunk_context.
When would I use each one?

What's the difference between rlm_sub_query and rlm_sub_query_batch?
Show me the implementation.

理解架構

Read src/rlm_mcp_server.py and explain how contexts are stored and persisted.
Where does the data live?

How does the claude-sdk provider extract text from responses?
Walk me through _call_claude_sdk.

What happens when I call rlm_load_context? Trace the full flow.

實踐學習

Load the README as a context, chunk it by paragraphs,
and run a sub-query on the first chunk to summarize it.

Show me how to process a large file in parallel using rlm_sub_query_batch.
Use a real example.

I have a 1MB log file. Walk me through the RLM pattern to extract all errors.

擴展 RLM

Read the test file and explain what scenarios are covered.
What edge cases should I be aware of?

How would I add a new chunking strategy (e.g., by regex delimiter)?
Show me where to modify the code.

How would I add a new provider (e.g., OpenAI)?
What functions need to change?

🔧 技術細節

數據存儲

graph TD
    A[("$RLM_DATA_DIR")] --> B["📁 contexts/"]
    A --> C["📁 chunks/"]
    A --> D["📁 results/"]

    B --> B1[".txt files"]
    B --> B2[".meta.json"]
    C --> C1["by context name"]
    D --> D1[".jsonl files"]

    style A fill:#339af0,color:#fff
    style B fill:#51cf66,color:#fff
    style C fill:#51cf66,color:#fff
    style D fill:#51cf66,color:#fff

上下文會在會話之間持久化。分塊後的上下文會被緩存以便重用。

📄 許可證

本項目採用 MIT 許可證。