mcp-injector

# mcp-injector

AI 编码助手常常会因获取到错误的上下文而失败。在大型代码库中，盲目地将原始文件全部塞进提示词，会导致幻觉、响应变慢和 API 成本高昂。

Foldwork 可以解决这个问题。它是一款确定性代码库理解引擎，会预先将整个代码库编入本地 SQLite 目录。它充当 IDE 的上下文层，只提供 AI 所需的函数——不多也不少，从而最大限度地提高首次尝试成功率，并减少 41-89% 的令牌用量。

Foldwork 将 AST 函数体折叠（移除函数体，同时保留签名）与规范确定性（确保输出逐字节一致，以最大限度地提高 Anthropic 的 KV 缓存命中率）相结合，将庞大的企业级单体仓库转换为轻量、适合缓存的负载。这能大幅减少令牌消耗、将 API 成本降低最多 90%，并避免上下文窗口溢出。

无云服务。无遥测。完全在你的设备上运行。--

真实代码库上下文基准测试

估算 AST 代码压缩对大型开源代码库的影响（按 Claude Sonnet 5 的每百万输入令牌 $2.00 计算）：

代码库	总文件数	原始上下文令牌数	压缩后上下文令牌数	令牌减少比例	每次运行节省的成本
Django	2,359	5,554,607	596,752	89.3%	$10.99
Tokio	789	1,597,813	444,164	72.2%	$3.11
Gin	99	197,300	47,718	75.8%	$0.39

这些数据可复现。可在任意公开代码库上运行开源基准测试工具：
mcp-benchmark 代码库

---

效果一览

在自己的项目上运行 mcp-benchmark，无需安装任何东西，即可查看确切的节省情况：

mcp-benchmark ./your-project

════════════════════════════════════════════════════════════════════════════════
  mcp-injector Benchmark — context
  Tier 3 compression  |  $2.00/1M tokens  |  2026-07-15T12:00:00Z
════════════════════════════════════════════════════════════════════════════════

FILE                                          RAW TOKENS    COMPRESSED     SAVED   COST SAVED*
──────────────────────────────────────────────────────────────────────────────────────────
cmd/license-gen/main.go                            3,633           214       94%       $0.0072
main.go                                           17,555         1,917       89%       $0.0347
website/api/webhook.go                             2,682           295       89%       $0.0053
main_test.go                                       1,576           353       78%       $0.0031
──────────────────────────────────────────────────────────────────────────────────────────
TOTAL (4 files)                                   25,446         2,779     89.1%       $0.0503

  * Based on $2.00 / 1M input tokens

  💡 Running this codebase through Claude 10×/day costs $0.51/day raw.
     With mcp-injector:  $0.01/day.  You save $0.50/day ($15/month).

---

工具

get_project_map

返回工作区的压缩结构概览。函数体会折叠并替换为占位符，以减少令牌用量。

• tier（整数，可选）：要应用的压缩级别（默认值：2）。
• unfolded_files（字符串数组，可选）：工作区相对路径或 glob 模式，这些文件将以完整分辨率（未压缩）提供。
• path_prefixes（字符串数组，可选）：将项目映射限定到特定微服务或软件包，大幅减少负载膨胀。
• git_context：响应中始终包含当前分支、已更改文件和最近的提交。
• secrets_redacted：发送给 Claude 之前自动脱敏的凭据数量。

调用示例：

{
  "tool": "get_project_map",
  "arguments": {
    "tier": 3,
    "unfolded_files": ["src/auth/handler.go", "**/*_test.go"],
    "path_prefixes": ["src/auth/"]
  }
}

injector_retrieve

从本地缓存中检索文件的完整、未压缩源代码。

• path（字符串，必需）：要检索文件的工作区相对路径。
• retrievalKey（字符串，可选）：先前压缩负载中返回的 SHA-256 检索密钥。
• start_line（整数，可选）：范围检索的起始行，从 1 开始计数。
• end_line（整数，可选）：范围检索的结束行，从 1 开始计数。
• expand_graph（布尔值，可选）：解析并附加跨文件依赖项（最多 50 个第一层依赖项）。

injector_search

在本地 SQLite 目录中进行按 BM25 排名的全文符号搜索。支持 FTS5 布尔逻辑（例如，user AND (auth OR login)）。

• query（字符串，必需）：FTS5 查询字符串（裸词、"短语"、前缀*）。
• limit（整数，可选）：最大结果数（默认值：20）。
• search_paths（字符串数组，可选）：将搜索范围限定到特定目录。

injector_diagram

通过遍历给定符号的出站依赖项，生成 Mermaid 时序图（达到 500 个节点后停止）。

• symbol（字符串，必需）：确切的符号名称。
• max_depth（整数，可选）：最大遍历深度（默认值：3）。
• include_primitives（布尔值，可选）：包含基本类型（String、boolean）和框架边界。

### `injector_regex_search` 对文件内容进行精确字面匹配或正则搜索的备用工具。绕过 FTS5 分词。 - `query`（字符串，必填）：要搜索的字符串或正则表达式模式。 - `is_regex`（布尔值，可选）：将 query 视为扩展正则表达式（-E）。

injector_write_file

将完整文件写入磁盘。重要：通过拦截并拒绝包含压缩折叠标记的负载，防止数据丢失。

injector_blast_radius

通过遍历依赖关系图，分析更改某个符号的架构影响范围。支持入站和出站方向遍历。

injector_git_context

与本地 Git 历史记录集成，将提交上下文、作者信息和代码演变情况直接呈现到大模型上下文中。

injector_inspect_table

提供直接检查数据库的功能。目前支持 PostgreSQL 和 MySQL。 重要： 启动守护进程时，必须设置 FOLDWORK_DB_DSN 环境变量，并将其值设为数据库连接字符串（例如 postgres://user:pass@localhost:5432/dbname），才能启用此工具。

injector_clear_cache

清除 SQLite 索引缓存，并触发干净的冷启动全量重新索引。

injector_stats

返回索引状态、当前压缩率、已索引文件总数和缓存命中率。

injector_sync（已弃用）

读取工具会自动等待待处理的索引任务。无需手动调用此工具。

---

快速安装

在本地安装守护进程并配置 IDE：

curl -fsSL https://foldwork.dev/install | sh

自动配置 Claude Desktop、Cursor IDE、VS Code、Devin Desktop 和 Antigravity。

---

入门

第 1 步：检查项目是否符合免费层级的条件

在项目上运行基准测试 CLI，查看节省的令牌数量和代码行数：

mcp-benchmark ./your-project

如果项目少于 50,000 行，mcp-injector 完全免费。基准测试输出会显示确切的代码行数。

第 2 步：安装守护进程

curl -fsSL https://foldwork.dev/install | sh

安装程序会自动检测 Claude Desktop、Cursor、VS Code、Devin Desktop 和 Antigravity，并自动写入 MCP 配置。你应该会看到类似以下的输出：

* mcp-injector v0.2.0 installed to /usr/local/bin/mcp-injector
* Claude Desktop configured
* Cursor configured
Restart your IDE and mcp-injector will be active.

第 3 步：重启 IDE

IDE 启动时，MCP 服务会自动启动。无需管理单独的守护进程。

第 4 步：确认其正常运行

在 Claude Code 或 Cursor 中，向 Claude 提问：

“使用 get_project_map 展示此项目的结构”

Claude 会调用 mcp-injector 工具，并返回整个代码库的压缩映射。如果你看到模块名称、入口点和依赖信息，就说明它正常运行。

第 5 步：需要时获取完整源码

当 Claude 需要查看压缩函数的完整实现时，会自动调用 injector_retrieve。你也可以明确触发此操作：

“展示 UserService.java 的完整实现”

Claude 会从本地缓存中获取未压缩的源码。

编辑代码： 必须使用 injector_write_file 工具编辑代码。如果 Claude 试图将折叠占位符写回源代码，守护进程会直接拒绝该负载，以防止数据丢失。

第 6 步：查看节省情况

injector_stats

或者直接询问 Claude：“调用 injector_stats 并告诉我当前节省的令牌数量。”

---

Agent 使用场景与高级用法

现在，你的 AI 已拥有可确定性地搜索、遍历和检索代码的工具，可以向它提出一些在原始代码库上通常难以回答的高层架构问题：

• 追踪身份验证流程 — 请 Agent 梳理登录序列；它会使用 injector_retrieve 并设置 expand_graph=true，遍历中间件、验证和数据库层。
• 查找无用代码 — Agent 可以利用 injector_blast_radius（入向遍历）识别未使用的函数和孤立的结构体。
• 生成架构图 — 告诉 AI：“为此工作流生成 Mermaid 图”；它会使用 injector_diagram 即时绘制完整的出向执行序列。
• 了解依赖关系图 — 使用 injector_blast_radius，准确查看哪些服务或软件包依赖特定核心模块。
• 定位实现 — Agent 使用 injector_search（BM25 全文索引），在数百万行代码中查找确切的函数定义。
• 安全重构 — 在进行破坏性更改之前，Agent 会检查 injector_blast_radius，找出所有会受影响的调用方。
• 审查拉取请求 — 指示 Agent 分析未提交的更改或分支差异。它会使用 injector_git_context，结合代码了解近期提交和作者意图。
• 浏览大型单体仓库 — get_project_map 为 AI 提供整个架构的压缩鸟瞰图，让它能够使用 path_prefixes 深入查看特定微服务。

查看未压缩的特定文件

有时，你需要让 Claude 查看某个文件的确切实现，同时让其余内容保持压缩。请使用 unfolded_files 参数：

在 MCP 调用中，或直接询问 Claude：

“获取项目地图，但以完整分辨率显示 src/auth/handler.go”

这会向 get_project_map 传递 "unfolded_files": ["src/auth/handler.go"]。该文件将以原始形式提供；其他内容仍保持压缩。

也支持 glob 模式：

• "**/*_test.go" - 所有测试文件均不压缩
• "src/auth/*.go" - 目录中的所有文件均不压缩

切换分支

mcp-injector 首次运行时会安装 post-checkout git 钩子。切换分支会自动触发完整的重新索引。你会在守护进程日志中看到：

[mcp-injector] Branch switched to feature/auth-refactor, re-indexing...
[mcp-injector] Re-index complete in 4.2s (47,293 lines indexed)

安全至上：零泄漏保证

企业安全团队经常会禁止使用 AI 编码工具，因为开发者可能会意外地在上下文窗口中泄露敏感凭据。

mcp-injector 在本地解决了这个问题。守护进程内置 Shannon 熵过滤器，可实时分析所有 AST 字符串和注释。如果检测到高熵字符串（例如 AWS Access Key、SSH 私钥或数据库密码），便会在这些内容离开你的机器之前动态将其替换为 [REDACTED: high entropy]。你的 API 凭据绝不会发送给 Anthropic。

如果你的代码库中有硬编码的 API 密钥或 AWS 凭据，get_project_map 响应将包含：

"secrets_redacted": 2,
"files_with_redactions": ["config/db.go", "scripts/deploy.sh"]

实际值会替换为 [REDACTED: high entropy]。变量名会保留，因此 Claude 仍能理解代码结构。

手动配置 MCP

如果自动安装程序未检测到你的 IDE，请将以下内容手动添加到 MCP 配置中：

{
  "mcpServers": {
    "mcp-injector": {
      "command": "/usr/local/bin/mcp-injector",
      "env": {
        "MCP_WORKSPACE": "/absolute/path/to/your/project",
        "FOLDWORK_DB_DSN": "postgres://user:pass@localhost:5432/dbname"
      }
    }
  }
}

注意： VS Code 支持 "${workspaceFolder}"，但 Claude Desktop、Cursor 和 Devin Desktop 需要填写项目的绝对路径。

配置文件位置：

• Claude Desktop（Mac）：~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop（Windows）：%APPDATA%\Claude\claude_desktop_config.json
• Claude Desktop（Linux）：~/.config/Claude/claude_desktop_config.json
• Cursor：~/.cursor/mcp.json
• VS Code：.vscode/mcp.json
• Devin Desktop：~/.codeium/windsurf/mcp_config.json
• Antigravity：~/.gemini/antigravity/mcp_config.json

---

工作原理

• 增量解析： Foldwork 使用单次扫描 AST 解析器即时扫描你的代码仓库，无需阻塞即可识别所有接口、类和函数签名。
• 图生成： 它以确定性的方式构建两种结构：用于精确定义的符号图，以及用于跟踪出站调用方／被调用方关系的依赖图。
• 本地目录： 这些图会持久存储在本地 SQLite FTS5 目录中。每个文件变更只会建立索引一次，因此 AI 提示词不会产生额外开销。
• MCP 服务： 你的 AI Agent 通过模型上下文协议与 Foldwork 安全通信，以毫秒级获取子图，代码不会离开你的设备。
• 分支感知且确定性： 切换分支会通过 git hooks 自动触发增量重新索引。通过确保每次运行的输出逐字节一致，Foldwork 最大限度地提升 Claude 的 KV 提示词缓存命中率。

支持： Go、Python、TypeScript、JavaScript、Java、C++、C、C#、Rust。

---

定价方案

• 免费方案： 工作区源代码总行数少于 50,000 行（所有工具和功能均可完整使用）。
• 专业版（$12/月或 $99/年）： 解锁不限大小的工作区和高速增量差异索引。
  在 foldwork.dev 激活专业版

---

查看你的投资回报率（节省情况面板）

你可以随时在终端中运行 mcp-injector status。这个 CLI 面板会实时比较原始代码库的令牌数与 AST 压缩后的令牌数，直观展示你确切节省的令牌数和预估节省金额。

---

安全

mcp-injector 会自动编辑机密信息和凭据，防止它们进入 Claude 的上下文窗口：

• AWS 访问密钥、GitHub PAT、Stripe 密钥
• JWT 令牌和 bearer 令牌
• 通过香农熵分析检测到的高熵字符串
• 私钥标头（-----BEGIN RSA PRIVATE KEY-----）
• 可用于气隙环境： 专业版许可证验证严格使用离线 Ed25519 加密。守护进程绝不会发起出站网络请求，甚至不会为了验证订阅而联网。

被编辑的内容会替换为 [REDACTED BY MCP-INJECTOR]。get_project_map 响应中会包含编辑项数量，让你始终了解哪些内容受到了保护。

你的代码绝不会离开你的设备。编辑会在压缩前于本地完成，并且始终开启，无法禁用。

---

卸载

要彻底移除 mcp-injector：

# Remove binary
sudo rm /usr/local/bin/mcp-injector

# Remove index cache and logs
rm -rf ~/.mcp-injector/

# Remove from IDE MCP config (edit manually):
# Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json
# Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
# Cursor: ~/.cursor/mcp.json
# VS Code: .vscode/mcp.json
# Devin Desktop: ~/.codeium/windsurf/mcp_config.json
# Antigravity: ~/.gemini/antigravity/mcp_config.json
# (Remove the "mcp-injector" entry from mcpServers)

---

会编辑哪些内容

在你的代码进入 Claude 之前，mcp-injector 会自动编辑以下内容：

模式	匹配示例
AWS 访问密钥 ID	AKIAIOSFODNN7EXAMPLE
GitHub PAT（ghp_、ghs_）	ghp_aBcDeFg...
Stripe 密钥	sk_live_abc... / sk_test_abc...
JWT 令牌	eyJ...
PEM 私钥标头	-----BEGIN RSA PRIVATE KEY-----
通用高熵字符串（>20 个字符）	通过香农熵检测
密码／机密／令牌赋值	password = "abc123"

被编辑的值会替换为 [REDACTED BY MCP-INJECTOR]。文件路径和变量名称绝不会被编辑，只有值会被编辑。

---

许可证

商业软件。提供免费方案。源代码不公开。
支持联系邮箱：[email protected]