MCP AST Explorer

mcp-ast-explorer

用于确定性探索 Python 代码库符号的 MCP 服务。

mcp-ast-explorer 使用 LibCST 为 Python 源文件建立索引，并提供专注于代码库入门的 MCP 工具：查找定义、查看函数签名、本地引用、直接调用链，以及简单的类层级查询。

代码库入门工具栈

mcp-ast-explorer 是 Project 6 wayfinder（一个代码库入门 Agent）的三服务 MCP 工具栈中的语义符号层。

• mcp-repo-mapper 映射仓库结构、语言、入口点、框架证据和 Python 依赖边。
• mcp-ast-explorer 提供基于符号的 Python 定义、签名、引用、调用链和类层级查询。
• mcp-test-runner 运行本地 pytest/Jest 检查并生成覆盖率摘要，以便 Agent 根据执行结果验证其声明。

在 wayfinder 中，该服务负责说明入口点和符号，同时拒绝臆造缺失的符号。

状态

这是一个仅支持 Python 的 v1 版本。TypeScript 已注册为不受支持的后端占位项，为服务提供明确的扩展点，但目前尚未实现 TypeScript 分析。

该服务不会使用大模型查找符号。如果请求的符号或类不在已解析的索引中，工具会返回结构化的未找到结果，而不是臆造答案。

工具

工具	用途
health()	在冒烟检查中返回 ok。
find_definition(path, symbol, language="python")	查找模块、类、函数或方法的定义。
function_signature(path, symbol, language="python")	返回函数或方法符号的签名。
find_references(path, symbol, language="python")	返回现有符号在同一模块中的 CST 名称引用。
call_chain(path, from_symbol, depth=2, language="python")	返回根据本地引用检测到的直接调用方。
class_hierarchy(path, class_name, language="python")	返回根据简单基类名称检测到的直接子类。

支持范围

• 使用 LibCST 解析的 Python 文件。
• 符号类型：模块、类、函数和方法。
• 对简单名称进行同一模块内的引用查找。
• 从函数或方法容器中检测直接调用方。
• 检测简单 class Child(Base): 继承关系中的直接子类。
• 对不受支持的语言和缺失的符号返回结构化错误。

当前限制

• v1 不支持跨文件导入和整个包范围的解析。
• 不解析别名、星号导入、动态属性访问和限定引用。
• call_chain 目前仅返回直接调用方；尚未实现递归的多跳展开。
• class_hierarchy 目前仅返回直接子类，并处理简单的基类名称。
• v1 有意不支持 TypeScript。

本地开发

安装依赖：

uv sync --extra dev

运行 MCP 服务：

uv run mcp-ast-explorer

运行验证：

uv run ruff check .
uv run mypy
uv run pytest

许可证

MIT