内容
# 代码透镜 MCP
> ## ⚠️ 已被 [lens-mcp](https://github.com/segentic-lab/lens-mcp) 取代
>
> **代码透镜已合并到 [`lens-mcp`](https://github.com/segentic-lab/lens-mcp)** — 一个 MCP 服务器，可以映射 **代码和 Markdown 文档**。它包含了所有的代码透镜工具（`map`、`overview`、`functions`、`function_body`、`comments`、`find`、`info`），并且新增了文档工具（`outline`、`heading`、`links`、`search`）和一个统一的 `map`，可以在一次调用中返回整个项目的代码结构和文档大纲。
>
> **请使用 lens-mcp 代替** — `git clone https://github.com/segentic-lab/lens-mcp`。
> 该仓库仅保留以便现有的链接能够解析；它不再被开发。
>
> _(下面的描述保留以供参考。)_
---
用于 AI 代理的确定性结构化代码映射。MCP 服务器（stdio），为代理提供代码库的结构 - 导入、导出、类、函数、签名、注释、TODO 标记 - 而无需读取整个文件到上下文中。
由 tree-sitter WASM 语法提供支持：无需本地构建步骤，任何 Node 18+ 运行环境都可安装。
**约定：** 代码透镜是一个导航地图。使用它来 *定位* 代码，然后 `读取` 实际源代码，然后再进行判断或修改。签名不是函数体；大纲不是章节。
## 工具
7 个只读工具。每个响应中的每个列表都有上限，并且每个上限都带有明确的 `truncated` 标志 - 没有无声截断。
| 工具 | 功能 |
|------|--------------|
| `map` | 单次调用获取整个目录树的每个文件的结构概述。跳过 `node_modules`、`dist`、`venv`、隐藏目录等。定位工具。 |
| `overview` | 单个文件的顶级结构：导入、导出、类（带方法名）、函数 - 均带有 1 为基准的 `line`/`endLine`。 |
| `functions` | 文件中的每个 **可寻址** 函数 - 嵌套函数、方法、获取/设置属性、类字段箭头、对象字面属性、默认导出 - 带有重建的签名、参数类型、返回类型、`async`/`exported` 标志和 `parent` 作用域。（作为参数传递的匿名回调和 Python 匿名函数不列出 - 它们没有导航到的名称。） |
| `comments` | 所有注释均带有行范围、类型（`line`/`block`/`doc`）和 TODO/FIXME/FIX/BUG/HACK/NOTE/XXX 标记检测（仅大写、无虚假阳性）。`markersOnly: true` 只返回债务列表。 |
| `function_body` | 按裸名或点名（`Widget.render`）获取单个函数的逐字源代码（带有装饰器）- 替换整个文件读取的聚焦读取。模糊名称会列出候选项；它永远不会猜测。 |
| `find` | “X 在哪里定义？” - 按名称在目录中定位函数/方法/类定义。只有定义，不包括调用站点。 |
| `info` | 服务器自我描述：版本、工作目录（路径沙盒根）、语言、功能上限。 |
`overview`、`functions` 和 `comments` 接受单个路径或每次调用最多 20 个路径。
## 语言
| 扩展名 | 语言 | 语法 |
|-----------|----------|---------|
| `.ts`、`.mts`、`.cts` | TypeScript | tree-sitter-typescript |
| `.tsx` | TypeScript + JSX | tree-sitter-tsx（专用语法 - JSX 解析正确） |
| `.js`、`.jsx`、`.mjs`、`.cjs` | JavaScript | tree-sitter-javascript |
| `.py` | Python | tree-sitter-python |
## 路径沙盒
服务器仅读取 **在其自己的工作目录**（启动目录）下的文件。相对路径相对于它解析；绝对路径仅在指向内部时被接受；逃离它的符号链接被拒绝。
`info` 工具报告根目录，每个拒绝都命名它。从要映射的项目启动服务器。
## 诚实保证
- 具有语法错误的的文件永远不会被报告为干净成功：
`hasErrors: true` 加上 `parseErrors` 行范围，因为 tree-sitter 错误恢复可以在错误附近删除代码。
- 错误会将 `isError` 设置在 MCP 结果上并返回
`{error, path, hint}` - 提示说明如何修复调用。
- 批量调用返回每个文件的结果以及诚实的
`{requested, succeeded, failed}` 摘要；`isError` 仅在所有文件都失败时。
- 每个上限都是可见的：`truncated` 标志带有真实总数。
## 安装和运行
```bash
npm install
npm run build # tsc → dist/
npm test # build + 62 tests (51 unit, 11 stdio e2e)
node dist/index.js # stdio MCP 服务器（从要分析的项目启动）
```
MCP 客户端配置：
```json
{
"mcpServers": {
"codelens": {
"command": "node",
"args": ["/path/to/codelens-mcp/dist/index.js"],
"cwd": "/path/to/project-to-analyze"
}
}
}
```
## 代理作者
此仓库中的 `AGENTS.md` 是一个可粘贴的指南，用于教导代理如何有效地使用这些工具 - 核心模型、每个工具的提示和陷阱（路径沙盒、语言覆盖、地图与领土规则）。
## 许可证
AGPL-3.0 - 请参阅 [LICENSE](LICENSE)。
