lens-mcp

lens-mcp

为代码和 Markdown 提供确定性导航地图，面向 AI Agent。 一个 MCP 服务，两种视角：使用 tree-sitter 解析源代码（TypeScript / JavaScript / Python），并使用 Markdown 视角解析文档。只需一次低成本调用，就能回答 “X 在哪里，这个项目的结构是什么？”，让 Agent 将上下文用在思考上，而不是浏览文件。

支持 Model Context Protocol；可与任何 MCP 客户端搭配使用——Claude Code、Cursor、Codex，或你自己的 Agent。

为什么

Agent 在不熟悉的仓库中摸清方向时，往往会耗费 token 来执行 ls、grep， 并阅读整个文件，只为找到某一个函数或正确的 文档。lens 返回的是地图，而非领土：

• function_body 只读取一个函数——与阅读函数所在的整个文件相比，上下文通常减少约 99%。
• heading 只读取一个文档章节——指定标题及其子章节，除此之外别无其他。
• map 返回整个项目的概览——每个代码文件的结构以及每篇文档的大纲，一次调用即可获取。

所有输出都是确定性的（通过实际解析，而非由模型总结），并设有明确的 truncated 标记，同时遵循一条约定：

lens 是导航地图。先用它定位，再阅读真实的 源代码／章节，然后再进行判断或修改。签名不是函数体； 大纲不是章节内容。

工具（13 个）

项目概览

工具	功能
map	一次调用获取整个项目的概览：每个代码文件 → 结构；每篇文档 → 标题 + 大纲。涵盖两类内容，统一返回。
info	版本、沙盒根目录、支持的语言／扩展名、工具列表、所有输出上限，以及 lens 约定。
lens_system	安装状态、自我更新（底层使用 update.sh），以及获取当前 AGENTS.md——lens 的自维护工具。

代码（tree-sitter — .ts .tsx .mts .cts .js .jsx .mjs .cjs .py）+ Prisma（.prisma）

工具	功能
overview	单个文件的导入、导出、类（及方法）、顶层函数，以及对应的行范围。
functions	所有函数，包括嵌套函数——签名、参数／类型、parent 作用域、种类。
function_body	一个函数的原样源代码——用于聚焦阅读。
comments	注释 + TODO/FIXME/BUG/HACK/… 标记（可通过 markersOnly 获取待处理事项列表）。
find	按名称定位定义——函数、类，以及现在还包括 const／type／enum／导出项——范围为整个目录。
references	反向查找：哪些位置使用某个符号——调用位置、导入、类型引用；由 tree-sitter 精确识别，不会像 grep 一样产生误报。

文档（Markdown — .md .markdown .mdx）

工具	功能
outline	完整的标题层级（目录），包含行号。
heading	按标题文本／slug／行号读取一个章节。
links	提取行内链接／图片链接／Wiki 链接／自动链接／引用链接。
search	对文档进行不区分大小写的全文搜索（优先排列标题匹配结果）。

overview／find／map 也支持 Prisma schema（schema.prisma → 模型、枚举、字段、关系）。JSON 配置／i18n 不会进行结构化映射——lens 会如实说明，并提示你使用 grep。

对 .md 文件调用代码工具（或对 .ts 文件调用文档工具）时，工具会失败并提示应该使用哪个工具——不会让你摸不着头脑。

从设计上保证诚实

• 绝不悄悄丢失数据——语法错误的文件会返回 hasErrors + parseErrors，并继续提取可解析的内容；无法解析的文件在 map／find 中会以内联 error 显示，绝不会消失。
• 处处设有上限——每个列表都有长度限制（参见 info.limits），每次达到上限时都会报告真实总数。一个输出没有上限、声称能节省上下文的工具，未免自相矛盾。
• 路径沙盒——只能读取 MCP 服务工作目录下的文件；会拒绝逃逸沙盒的符号链接。info 会报告根目录。
• 错误会说明如何修复——{error, path, hint}，并设置 isError。

安装

一条命令即可克隆、安装，并写入可直接粘贴的 MCP 配置，其中包含本次安装的绝对路径：

git clone https://github.com/segentic-lab/lens-mcp && cd lens-mcp && ./install.sh

无需安装系统软件包，也无需本机构建——tree-sitter 以 WebAssembly 形式运行，因此只要能运行 Node 18+，就能使用（Linux、macOS、Windows 上的 WSL/Git Bash）。安装程序会检查 Node、运行 npm ci、进行构建（tsc → dist/）、运行完整测试套件（143 项测试），并生成 mcp-config.json。

将其注册到客户端——生成的 mcp-config.json 如下所示：

{
  "mcpServers": {
    "lens": { "command": "node", "args": ["/abs/path/lens-mcp/dist/index.js"] }
  }
}

• Claude Code： claude mcp add lens -- node /abs/path/lens-mcp/dist/index.js （或者将 mcp-config.json 复制到项目中并命名为 .mcp.json）
• Cursor / Windsurf： 将 mcp-config.json 合并到 ~/.cursor/mcp.json
• Codex CLI： 在 ~/.codex/config.toml 中添加 [mcp_servers.lens]，并使用相同的命令和参数

lens 会读取其工作目录下的文件——也就是客户端启动它时所在的项目。将它指向一个项目，然后调用 map(".")。无法读取工作目录以外的任何内容。

稍后可在原位置更新：

./update.sh          # git pull --ff-only + reinstall + self-test

_{更喜欢手动操作？运行 npm install && npm run build && npm test，然后执行 node dist/index.js。}

发展沿革

lens-mcp 取代了早期拆分的服务 codelens-mcp（代码）和 docslens-mcp（文档）——使用相同的引擎，一个服务，一条流水线。它与 periscope-mcp（Web 应用 QA）是姊妹项目； 并按相同标准构建：如实报告错误、处处设置上限和截断标记、文档与实际行为一致、发布前先测试。

由 Segentic Lab 构建。AGPL-3.0。