MCP AST Explorer

What MCP AST Explorer does

The MCP AST Explorer MCP server builds a parsed index of Python source files and makes focused code-navigation operations available to an MCP client. Its supported symbol types are modules, classes, functions, and methods. Results are based on the parsed source rather than generated explanations, so a missing symbol produces a structured not-found response instead of an invented answer.

The server is intended for codebase onboarding workflows. It can provide the location and kind of a definition, show a function or method signature, list same-module references, identify direct callers, and report direct subclasses for simple inheritance relationships. It is the semantic symbol layer in the documented wayfinder onboarding stack, alongside repository mapping and test-running servers.

How it works

Python files are parsed with LibCST. Queries accept a path, symbol or class name, and an optional language value that defaults to Python. The implementation analyzes local syntax and symbol containers rather than performing package-wide semantic resolution.

For reference searches, the MCP AST Explorer MCP server looks for same-module CST name references associated with an existing symbol. Call-chain queries use those local references to identify direct callers. Class-hierarchy queries detect direct subclasses written with simple base-class names, such as class Child(Base):. The health tool returns ok for smoke checks.

Setup and configuration

Local development uses uv. Install the project dependencies with:

uv sync --extra dev

Run the server with:

uv run mcp-ast-explorer

The provided material does not specify environment variables, API credentials, or additional configuration values. Verification commands are available for Ruff, mypy, and pytest:

uv run ruff check .
uv run mypy
uv run pytest

Tools and capabilities

The MCP AST Explorer MCP server exposes these tools:

• health() returns an ok status for smoke testing.
• find_definition(path, symbol, language="python") locates a module, class, function, or method definition.
• function_signature(path, symbol, language="python") returns a function or method signature.
• find_references(path, symbol, language="python") returns same-module CST name references for an existing symbol.
• call_chain(path, from_symbol, depth=2, language="python") reports direct callers detected from local references.
• class_hierarchy(path, class_name, language="python") reports direct subclasses found through simple base-class names.

Unsupported languages and missing symbols receive structured error responses. TypeScript has a registered unsupported backend placeholder, but its analysis is not implemented.

Limitations and notes

The server is Python-only in its current v1 scope. It does not resolve cross-file imports or package-wide relationships. Aliases, star imports, dynamic attribute access, and qualified references are not resolved. Call-chain results contain direct callers only; recursive multi-hop expansion is not implemented. Class-hierarchy results contain direct subclasses only and depend on simple base-class syntax.

Because lookup is syntax-based and deterministic, results should be treated as local source analysis rather than a complete language-server-style model of the project. The repository lists the project under the MIT license.

Getting started with this MCP AST Explorer MCP server

Always refer to the official documentation for the most accurate and up-to-date information.