你的 AI 代理正在翻垃圾箱式地浏览你的代码,,,

Source: Dev.to

Introduction

…于是我们构建了一个解决方案来阻止它。

每个使用 AI 代理的开发者最终都会注意到一种模式。你让代理去寻找身份验证的处理位置。它打开一个文件，浏览 2 000 行，又打开另一个文件，继续浏览，再打开第三个文件。等它给出答案时，已经消耗了 40 000 个 token——大多数都是无关的——而你的上下文窗口在真正的工作开始前就已经被耗尽了一半。

我们把这称为 dumpster diving（垃圾箱潜水）。代理并没有有策略地阅读；它在所有内容中挖掘，只为寻找可以利用的东西。

我们在 jCodeMunch 和 jDocMunch 上观察了数百万次会话的这种现象。于是我们构建了一个解决方案：jMRI —— jMunch Retrieval Interface（jMunch 检索接口）。

今天我们发布规范、基准以及开源 SDK，全部采用 Apache 2.0 许可证。

数字

我们对两个真实代码库（FastAPI 和 Flask）进行了基准测试。比较了三种方法：朴素文件读取、块 RAG，以及通过 jCodeMunch 的 jMRI 检索。每个仓库执行十次查询。以下是结果。

FastAPI（约 950 K 源令牌）

Flask（约 148 K 源令牌）

在 FastAPI 上，jMRI 使用的令牌比朴素方法少 1,979 ×。它还 在精度上超过块 RAG —— 96 % 对比 74 %。

最后一点很重要。通常的假设是，精度是为效率所做的权衡。块 RAG 比朴素方法更便宜，但遗漏更多。jMRI 比两者都更便宜且遗漏更少。这并非偶然——它是使用结构而非文本相似性的结果。

在 5 分钟内自行复现

git clone https://github.com/jgravelle/mcp-retrieval-spec
cd mcp-retrieval-spec/benchmark
python benchmark.py --all

为什么 Chunk RAG 在精确度上表现不佳

Chunk RAG 将文件拆分为重叠的文本窗口，并根据关键词重叠或嵌入相似度对它们进行排序。块的边界可能恰好落在函数的中间。排名最高的块可能包含正确的词汇，却不包含正确的代码。检索本质上是近似的。

jMRI 检索是 结构上精确 的。jCodeMunch 将源文件解析为基于 AST 的索引：每个函数、类和方法都是具名、可寻址的符号，拥有稳定的 ID。当你搜索 "OAuth2 password bearer authentication" 时，会得到类似 fastapi/security/oauth2.py::OAuth2PasswordBearer#class 的 ID。检索该 ID 时，你得到的正是该类——既不多也不少。没有边界意外。没有半个函数。

96 % 的精确度数字反映了顶部搜索结果恰好是查询对应的正确符号的情况。那 4 % 的不精确则来源于真正模糊的查询——即使是人类也会对正确答案存有争议。

什么是 jMRI？

jMRI（jMunch Retrieval Interface）是一个用于 MCP 服务器的开放规范，旨在实现检索的正确性。

四个操作，一个响应封装，两个合规级别：

Agent
 ├─ discover()    → 有哪些知识源可用？
 ├─ search(query) → 哪些符号/章节是相关的？（仅返回 ID 和摘要）
 ├─ retrieve(id)  → 给我该 ID 的确切来源。
 └─ metadata(id?) → 朴素阅读会产生多少成本？

每个响应都包含一个 _meta 块：

{
  "source": "def get_db():\n    db = SessionLocal()\n    try:\n        yield db\n    finally:\n        db.close()\n",
  "_meta": {
    "tokens_saved": 42318,
    "total_tokens_saved": 1284950,
    "cost_avoided": { "claude-sonnet-4-6": 0.127 },
    "timing_ms": 12
  }
}

代理不需要猜测它是否高效。它在每一次调用时都知道。

该规范刻意保持简约。我们并不是在构建一个平台；而是想为已经在大规模环境中有效的模式命名，并让其他人更容易实现它。

实现

规范是开放的，最佳实现是商业化的。

两者都实现了 jMRI‑Full — 完整规范，包括批量检索、基于哈希的漂移检测、字节偏移寻址，以及完整的 _meta 包装。

这两台服务器在2026年3月第一周的用户会话中累计节省了超过 180 亿 token。该数字在设备上通过真实会话遥测计算得出——每个参与的响应都会通过 os.stat 上报 tokens_saved，没有估算。

入门

Claude 代码

将以下内容添加到 ~/.claude.json：

{
  "mcpServers": {
    "jcodemunch-mcp": {
      "command": "uvx",
      "args": ["jcodemunch-mcp"]
    },
    "jdocmunch-mcp": {
      "command": "uvx",
      "args": ["jdocmunch-mcp"]
    }
  }
}

Python SDK

pip install jmri-sdk

from jmri.client import MRIClient

client = MRIClient()

# 已索引的内容是什么？
sources = client.discover()

# 查找它
results = client.search(
    "database session dependency injection",
    repo="fastapi/fastapi"
)

# 精确获取
symbol = client.retrieve(results[0]["id"], repo="fastapi/fastapi")
print(symbol["source"])
print(f"Tokens saved this call: {symbol['_meta']['tokens_saved']:,}")

TypeScript SDK

npm install @jmri/sdk

import { MRIClient } from "@jmri/sdk";

const client = new MRIClient();

// 发现可用的来源
const sources = await client.discover();

// 搜索符号
const results = await client.search(
  "database session dependency injection",
  { repo: "fastapi/fastapi" }
);

// 检索精确的源代码
const symbol = await client.retrieve(results[0].id, { repo: "fastapi/fastapi" });
console.log(symbol.source);
console.log(`Tokens saved this call: ${symbol._meta.tokens_saved.toLocaleString()}`);

示例用法 (TypeScript)

import "mri-client";

const client = new MRIClient();
const results = await client.search("OAuth2 bearer auth", "fastapi/fastapi");
const symbol = await client.retrieve(results[0].id, "fastapi/fastapi");

开放规范

所有内容托管在 github.com/jgravelle/mcp-retrieval-spec。

• SPEC.md – 完整的 jMRI v1.0 规范（Apache 2.0）
• sdk/python/ – Python 客户端辅助工具
• sdk/typescript/ – TypeScript 客户端
• reference/server.py – 最小的符合 jMRI 标准的 MCP 服务器
• examples/ – Claude Code、Cursor 以及通用代理集成

规范故意保持简洁。欢迎提交改进示例或添加语言 SDK 的 PR。若要扩展核心接口，则需要充分的理由。

如果你正在构建检索型 MCP 服务器，请实现 jMRI‑Core。你的用户代理会感谢你的。
— J. Gravelle，2026年3月

基准来源：
github.com/jgravelle/mcp-retrieval-spec/benchmark

SDK 安装：

pip install jmri-sdk      # Python
npm install mri-client    # TypeScript / JavaScript

规范仓库：
github.com/jgravelle/mcp-retrieval-spec