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 会自动检测并使用最佳可用的提供者：

支持多种工具进行上下文分析和处理

设置与状态工具

分析工具

💻 使用示例

基础用法

# 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。

📚 详细文档

使用 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. 返回聚合结果。

支持的目标：

使用 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：

提示：对于大型上下文，可以结合使用两者 — 使用 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。有 两种安装方法，各有优缺点：

选择安装方法

建议：

• 如果已安装 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 许可证。