mcplens

为 AI 编码助手提供的语义代码库搜索 —— 减少 70-85% 的 Token 使用，100% 本地运行，零云依赖。

Claude Code、Cursor 和 Codex 等 AI 编码助手非常强大，但它们有一个根本问题：当你提出问题时，它们会根据路径和文件名启发式地猜测哪些文件是相关的。在一个中等规模的项目中，单次查询仅加载可能并不相关的文件就可能消耗 10,000–20,000 个上下文 Token。

claude-context-optimizer 通过为你的 AI 助手提供代码库的语义搜索功能解决了这个问题。它不再盲目读取文件，而是调用 search_code("how does payment work?") 并仅返回 5 个最相关的代码块 —— 这些代码块在本地使用嵌入进行索引，存储在 SQLite 中，数据完全不出本地。

工作原理

当你在项目中打开 AI 助手时：

1. MCP 服务器自动启动（由助手通过 stdio 启动）

2. 它将文件哈希与上次索引进行比较，并仅对更改的内容进行重新索引（增量索引）

3. 文件监视器在你编码时保持索引同步

4. 你的助手现在可以使用 3 个语义搜索工具，而无需读取原始文件

You ask: "how does the Asaas webhook work?"

Without cco: With cco:
 Read AsaasWebhookController.php search_code("asaas webhook")
 Read AsaasWebhookService.php → returns 5 relevant chunks
 Read PaymentService.php → ~800 tokens total
 Read BillingModule.php
 Read ...8 more files
 → ~15,000 tokens total

技术细节

• 嵌入： 使用 nomic-embed-text (768-dim) 的 Ollama —— 100% 本地，免费，无需 API 密钥

• 向量存储： SQLite，在进程内计算余弦相似度 —— 无需额外基础设施

• 分块： 通过 tree-sitter 实现 AST 感知（按函数/类拆分），并带有滑动窗口回退机制

• 传输： MCP stdio —— 助手启动进程并通过管道进行通信

• 持久化： 索引存储在 .claude-context/index.db 中，并在会话间保留

Related MCP server: CodeRAG

兼容性

claude-context-optimizer 适用于任何兼容 MCP 的 AI 编码助手。MCP (Model Context Protocol) 是一种开放标准 —— 同一个服务器无需修改即可在所有客户端上运行。

init 命令会自动检测你使用的助手，并在正确的位置自动注册服务器。

Token 节省

索引存储在本地。助手仅获取相关内容。数据说明了一切：

这些是上下文 Token —— 你可以控制的部分。节省比例随项目规模增加，因为大型项目默认会触发更多的启发式文件读取。

暴露的工具

将此内容添加到你项目的 CLAUDE.md（或等效文件）中以引导助手：

## Context Search

Always use MCP tools before reading files:

- search_code() — for conceptual or natural language queries
- get_symbol() — for exact class/function/method lookups
 Only read full files if both tools return insufficient context.

安装选项

选项 A — npm (需要 Ollama)

零开销。最适合已经安装了 Ollama 的开发者。

npm install -g @vmsfigueredo/mcplens
ollama pull nomic-embed-text:latest
cd your-project && mcplens init

请参阅 INSTALL.md 获取完整的设置说明。

选项 B — Docker

暂不可用。 Docker 分发（捆绑 Node + Ollama + 模型）已在计划中但尚未实现。请关注 Roadmap 中的进度。

配置

.claude-context/config.json 由 init 自动创建。编辑它以自定义行为：

{
 "embeddings": {
 "provider": "ollama",
 "ollamaUrl": "http://localhost:11434",
 "ollamaModel": "nomic-embed-text:latest"
 },
 "search": {
 "topK": 5,
 "minScore": 0.3
 },
 "ignore": [
 "**/tests/fixtures/**"
 ]
}

若要改用 OpenAI 嵌入：

{
 "embeddings": {
 "provider": "openai",
 "openaiApiKey": "sk-...",
 "openaiModel": "text-embedding-3-small"
 }
}

索引内容

默认包含： .ts .tsx .js .jsx .mjs .php .svelte .vue .py .rb .go .rs .css .scss .json .yaml .yml .md .sql

默认忽略： node_modules, .git, vendor, dist, build, .next, .claude-context

.claude-context/ 目录会自动添加到 .gitignore 中。

索引大小参考

仪表盘

服务器运行时，可在 http://localhost:3000 访问轻量级 Web 仪表盘：

• 概览 — 已索引文件、代码块、索引大小、Ollama 状态

• 活动 — 重新索引事件的实时流

• 搜索 — 手动测试查询并查看分数（有助于校准 minScore）

• 文件 — 已索引文件的完整列表及代码块计数

仪表盘默认运行在 3333 端口。如果该端口已被占用（例如同时打开了两个项目），端口会自动根据项目名称计算。打开方式：

mcplens dashboard

禁用方式：在 MCP 配置的服务器参数中添加 --no-dashboard。

隐私

一切都在你的机器上运行：

• 嵌入通过 Ollama 在本地生成 —— 你的代码永远不会离开本地

• 索引存储在项目中的 .claude-context/index.db

• 无遥测、无分析、无账户

⚠️ 如果你使用 OpenAI 嵌入选项，代码块会被发送到 OpenAI 的 API。

为什么不直接使用现有工具？

我们的目标是成为 JS/TS 开发者最易用的选择 —— 而不是功能最全的。如果你已经安装了 Node.js，只需一条命令即可使用。

路线图

• [x] 通过 tree-sitter 进行基于 AST 的分块

• [x] 按文件哈希进行增量索引

• [x] 实时文件监视器

• [x] 仪表盘

• [x] 多客户端初始化 (Claude Code, Cursor, Windsurf, Trae)

• [x] 混合搜索 (BM25 + 语义)

• [ ] 捆绑 Ollama 的 Docker 选项

• [ ] 上下文检索 (LLM 生成的代码块摘要)

• [ ] 通过 Claude Code 钩子进行 Token 使用分析

贡献

欢迎提交 PR。请参阅 INSTALL.md 进行本地开发设置。

构建工具

本项目是使用 Claude Code 构建的 —— 这正是它存在的原因。

许可证

MIT

Maintenance

Resources

• NPM Package
• GitHub Repository
Need Help?Related Servers