gclluch/ts-ast-mcp

# TypeScript AST MCP Server 一个用于对 TypeScript 和 JavaScript 源代码进行深度结构分析的 Model Context Protocol (MCP) 服务器。与基于文本的搜索不同，该服务器使用 TypeScript Compiler API 解析您的代码，并遍历真实的 AST——包括类型、函数、调用关系、接口实现等。 大多数工具在语法层（`ts.createSourceFile`，无类型解析）运行，因为它速度快且不需要构建。`find_implementations` 在语义层运行——一个完整的 `ts.Program` 及其类型检查器——因为仅凭语法无法判断一个类是否满足某个接口。每个工具所属的层级在下表中进行了说明。 它是 [py-ast-mcp](https://github.com/gclluch/py-ast-mcp) 的配套项目，将相同的理念应用于 Python；另一位作者编写的 Go AST MCP server 是本项目的先驱。 ## 功能 - **20 个分析工具**，涵盖文件级、目录级和跨文件的结构查询 - **快速语法解析** - 每个文件的 `ts.createSourceFile()` 耗时不到 5ms；跨文件工具会在作用域内重新解析，因此结果始终反映最新的编辑内容 - **箭头函数感知** - 始终将 `const foo = () => {}` 视为一等函数 - **签名提取** - 参数、带有类限定名称以及返回类型均**按原样**提取。这些信息来自注解，因此未添加注解的返回类型会显示为空，而不是推断出的类型 - **调用图生成**，包含 Mermaid 图表、正向和反向遍历、文件或 package 作用域 - 每个函数的**圈复杂度**计算 - **接口实现发现** - 显式的 `implements` 以及由类型检查器自身的可赋值性规则决定的结构匹配，因此会考量成员类型和调用签名，而不仅仅是成员名称 - 文件版本之间的**结构差异比对**（添加/移除/修改的 symbol） - 面向 IDE 集成的**光标位置感知** - **JSX/TSX 解析** - `.tsx`/`.jsx` 文件会在正确的 `ScriptKind` 下解析，因此每个工具都能在 React 源码上运行。这里没有针对 React 的特定分析：组件与任何其他函数一样对待 - **TypeScript 特定的质量检查** - `any` 类型转换、非空断言、未处理的 promise、空的 catch 块、双重断言 - **死代码检测** - 在其自身文件中从未被引用的未导出 symbol。未导出意味着文件局部，因此这就是全部的搜索范围。同一文件另一个作用域中的同名绑定仍然会被视为一种使用，这使得该功能倾向于少报而不是多报 - 提取任何 symbol 的 **JSDoc/TSDoc** ## 工具 ### 结构查询 | 工具 | 描述 | 参数 | |------|-------------|------------| | `analyze_file` | 所有 symbol（类、接口、类型、枚举、函数）的高级摘要 | `path` | | `list_functions` | 列出所有具有完整签名和行范围的函数/方法 | `path` | | `get_function_body` | 提取函数/方法体（支持 `Class.method` 语法） | `path`, `name` | | `list_methods` | 列出类的所有方法 | `path`, `type` | | `get_type_definition` | 提取任何类型定义（接口、type alias、类、枚举） | `path`, `name` | | `list_declarations` | 列出带有类型的模块级 const/let/var | `path` | | `list_exports` | 列出所有已导出的 symbol 及其种类（函数、类、类型、重新导出） | `path` | | `list_imports` | 列出所有包含绑定和模块路径的 import 语句 | `path` | | `find_usages` | 查找具有源码上下文的标识符的所有出现位置 | `path`, `identifier` | ### 调用分析 | 工具 | 描述 | 参数 | |------|-------------|------------| | `call_graph` | 生成 Mermaid 调用图图表 | `path`, `function`\*, `direction`\*, `include_external`\*, `scope`\* | | `get_callers` | 反向调用图 - 查找函数的所有调用者 | `path`, `function`, `scope`\* | \* 可选的 `call_graph` 参数： - `function` - 仅关注可从该函数到达的调用 - `direction` - `TD`（自上而下，默认）或 `LR`（从左到右） - `include_external` - 包含对文件中未定义的函数的调用（默认：`false`） - `scope` - `file`（默认）或 `package`（跨文件分析） \* 可选的 `get_callers` 参数： - `scope` - `file`（默认）或 `package`（搜索目录中的所有文件） ### 代码质量 | 工具 | 描述 | 参数 | |------|-------------|------------| | `code_complexity` | 每个函数的圈复杂度 | `path`, `function`\* | | `code_smells` | 过长的函数、深层嵌套、God class、`any` 类型转换、非空断言 | `path`, `function`\* | | `find_errors` | 未处理的 promise、空的 catch 块、双重类型断言、可选链 + 非空断言 | `path`, `function`\* | | `dead_code` | 查找在其自身文件中从未被引用的未导出 symbol | `path` (目录), `include_tests`\* | | `find_implementations` | 查找满足接口的类 - 显式 `implements` 或类型检查过的结构匹配（**语义层**） | `path`, `interface` | \* 可选 - 省略以报告所有函数 / 排除测试文件。 ### 文档与元数据 | 工具 | 描述 | 参数 | |------|-------------|------------| | `get_doc` | 提取任何 symbol 的 JSDoc/TSDoc 注释（支持 `Class.method`） | `path`, `name` | ### 多文件分析 | 工具 | 描述 | 参数 | |------|-------------|------------| | `analyze_package` | 所有 TS/JS 文件的目录级摘要 | `path`, `include_tests`\* | | `diff_ast` | 两个文件版本之间的结构差异（添加/移除/修改） | `old_path`, `new_path` | \* 可选 - 包含测试文件（默认：`false`）。 ### IDE 集成 | 工具 | 描述 | 参数 | |------|-------------|------------| | `find_node_at_position` | 识别光标位置处的 AST 节点 | `path`, `line`, `column` | ## 配置 ### Claude Code 将 `.mcp.json` 文件添加到仓库根目录： ``` { "mcpServers": { "ts-ast": { "command": "npx", "args": ["-y", "github:gclluch/ts-ast-mcp"] } } } ``` ### Claude Desktop 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)： ``` { "mcpServers": { "ts-ast": { "command": "npx", "args": ["-y", "github:gclluch/ts-ast-mcp"] } } } ``` ### GitHub Copilot (VS Code) 在项目根目录下创建 `.vscode/mcp.json`： ``` { "mcpServers": { "ts-ast": { "command": "npx", "args": ["-y", "github:gclluch/ts-ast-mcp"] } } } ``` ### VSCode 扩展 (Cline / Roo Code) 添加到扩展的 MCP 设置中： ``` { "mcpServers": { "ts-ast": { "command": "npx", "args": ["-y", "github:gclluch/ts-ast-mcp"], "env": {} } } } ``` ### 本地开发 如需在 ts-ast-mcp 本身上进行开发，请在本地克隆并构建： ``` git clone https://github.com/gclluch/ts-ast-mcp.git cd ts-ast-mcp npm install # prepare script builds automatically ``` 然后将您的 `.mcp.json` 指向本地构建版本： ``` { "mcpServers": { "ts-ast": { "command": "node", "args": ["/path/to/ts-ast-mcp/dist/index.js"] } } } ``` ## 双层解析 大多数工具使用**语法层** - `ts.createSourceFile()` 在 5ms 内解析单个文件。不需要 tsconfig 或类型检查器。 跨文件操作的工具（`dead_code`、`analyze_package`）以及带有 `scope: "package"` 的工具（`call_graph`、`get_callers`）通过语法解析器在每次调用时重新解析作用域内的每个文件来实现这一点——在最新的编辑内容上始终保持正确，代价是反复重新解析。 **语义层**支持 `find_implementations`，这是语法无法回答的唯一问题：一个类是否满足一个接口取决于成员*类型*和调用签名，而不是成员名称。`loadProgram()`（位于 `src/parse.ts`）构建了一个缓存的 `ts.Program`，并将真正的类型检查器交给工具，然后通过 `isTypeAssignableTo` 进行回答——这与编译器应用于 `implements` 子句的规则相同。 编译器选项来自最近的 `tsconfig.json`；文件列表则不是。`findConfigFile` 会向*上*查找，因此您查询的目录通常会位于该配置的 `include` 之外，如果从配置自身的文件列表进行构建，将会生成一个不包含正在分析的文件的 program。当 tsconfig 的 mtime 发生变化，或者馈送给该 program 的任何文件发生变化时，缓存就会失效，因此编辑内容始终会在下一次调用时得到反映，而未更改的树则会复用该 `Program`。 语义层的代价是真实存在的：在目录上进行的第一次 `find_implementations` 调用需要付出完整的解析-绑定-检查过程。在未更改的树上进行的后续调用都是缓存命中。 箭头函数（`const foo = () => {}`）在整个过程中都被检测为一等函数——它们会出现在 `list_functions`、`get_function_body`、`code_complexity`、`code_smells` 以及所有其他具有函数感知能力的工具中。 所有输出均为纯文本，而非 JSON。 ## 开发 ``` npm install npm test # builds, then runs the vitest suite ``` 测试套件涵盖了纯辅助函数（`listTsFiles`、`bindingNames`），外加一个集成层， 该集成层会启动真实的 stdio 服务器并通过 JSON-RPC 驱动它， 因此工具的连接方式与客户端实际使用的方式完全一致。 ## 如何验证 注册后，您可以要求您的 AI 助手执行以下操作： - *"列出 `Dashboard.tsx` 中的所有函数及其签名。"* - *"提取 `UserConfig` 接口的完整定义。"* - *"给我看看谁调用了 `useApiQuery` hook。"* - *"为 `utils/ErrorUtils.ts` 生成调用图。"* - *"`DataTable.tsx` 中函数的圈复杂度是多少？"* - *"哪些类实现了 `DataProvider` 接口？"* - *"在结构上比较 `api.ts` 的新旧版本。"* - *"第 42 行第 10 列的 AST 节点是什么？"* - *"给我一份 `src/hooks/` 的目录级摘要。"* - *"在 `AuthService.ts` 中查找错误模式。"* - *"对 `BigComponent.tsx` 进行代码异味（code smell）检查。"* - *"在 `src/utils/` 中查找死代码。"* - *"`useApiQuery` 函数的 JSDoc 是什么？"* - *"列出 `src/types/index.ts` 中的所有导出。"*

标签：MCP, SOC Prime, TypeScript, 云安全监控, 代码分析, 凭证管理, 安全插件, 开发工具, 数据可视化, 自动化攻击, 静态分析