# MCP AST Explorer [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/LovRanRan/mcp-ast-explorer  
**GitHub Stars:** 0  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-ast-explorer

## Description
Python symbol exploration for codebase onboarding agents.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `uvx` (confidence: low):

```json
"mcpServers": {
  "mcp-ast-explorer": {
    "command": "uvx",
    "args": ["mcp-ast-explorer"]
  }
}
```

## Documentation

## 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:

```bash
uv sync --extra dev
```

Run the server with:

```bash
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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/mcp-ast-explorer/readme_