Command Palette

Search for a command to run...

UnylyUnyly
Browse all

MCP AST Explorer

FreeNot checked

Python symbol exploration for codebase onboarding agents.

io.github.LovRanRanby io.github.LovRanRan
GitHubEmbed

About

Python symbol exploration for codebase onboarding agents.

README

MCP server for deterministic Python codebase symbol exploration.

mcp-ast-explorer indexes Python source files with LibCST and exposes focused MCP tools for codebase onboarding: definition lookup, function signatures, local references, direct call chains, and simple class hierarchy queries.

Codebase Onboarding Stack

mcp-ast-explorer is the semantic symbol layer in a three-server MCP tool stack for Project 6 wayfinder, a codebase onboarding agent.

  • mcp-repo-mapper maps repository structure, languages, entry points, framework evidence, and Python dependency edges.
  • mcp-ast-explorer provides symbol-grounded Python definition, signature, reference, call-chain, and class-hierarchy lookups.
  • mcp-test-runner runs local pytest/Jest checks and coverage summaries so agent claims can be verified against execution.

In wayfinder, this server feeds entry-point and symbol explanation while refusing to invent missing symbols.

Status

This is a Python-only v1. TypeScript is registered as an unsupported backend placeholder so the server has an explicit extension point, but TypeScript analysis is not implemented yet.

The server does not use an LLM for symbol lookup. If a requested symbol or class is not present in the parsed index, tools return a structured not-found result instead of inventing an answer.

Tools

Tool Purpose
health() Returns ok for smoke checks.
find_definition(path, symbol, language="python") Finds a module, class, function, or method definition.
function_signature(path, symbol, language="python") Returns the signature for a function or method symbol.
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") Returns direct callers detected from local references.
class_hierarchy(path, class_name, language="python") Returns direct subclasses detected from simple base-class names.

Supported Scope

  • Python files parsed by LibCST.
  • Symbol kinds: modules, classes, functions, and methods.
  • Same-module reference lookup for simple names.
  • Direct caller detection from function or method containers.
  • Direct subclass detection for simple class Child(Base): inheritance.
  • Structured error responses for unsupported languages and missing symbols.

Current Limitations

  • Cross-file imports and package-wide resolution are out of scope for v1.
  • Aliases, star imports, dynamic attribute access, and qualified references are not resolved.
  • call_chain currently returns direct callers only; recursive multi-hop expansion is not implemented.
  • class_hierarchy currently returns direct subclasses only and handles simple base names.
  • TypeScript is intentionally unsupported in v1.

Local Development

Install dependencies:

uv sync --extra dev

Run the MCP server:

uv run mcp-ast-explorer

Run verification:

uv run ruff check .
uv run mypy
uv run pytest

License

MIT

from github.com/LovRanRan/mcp-ast-explorer

Install MCP AST Explorer in Claude Desktop, Claude Code & Cursor

Recommended · one command, every IDE
unyly install mcp-ast-explorer

Installs into Claude Desktop, Claude Code, Cursor & VS Code — handles npx, uvx and build-from-source repos for you.

First time? Get the CLI: curl -fsSL https://unyly.org/install | sh

Or configure manually

Run in your terminal:

claude mcp add mcp-ast-explorer -- uvx mcp-ast-explorer

FAQ

Is MCP AST Explorer MCP free?

Yes, MCP AST Explorer MCP is free — one-click install via Unyly at no cost.

Does MCP AST Explorer need an API key?

No, MCP AST Explorer runs without API keys or environment variables.

Is MCP AST Explorer hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install MCP AST Explorer in Claude Desktop, Claude Code or Cursor?

Open MCP AST Explorer on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

GitHub

PRs, issues, code search, CI status

GitHubby GitHub

Filesystem

Secure file operations with configurable access controls.

by Community

Memory

Knowledge graph-based persistent memory system.

by Community

Template MCP Server

A CLI tool to create a new Model Context Protocol server project with TypeScript support, dual transport options, and an extensible structure

mcpdotdirectby mcpdotdirect

Compare MCP AST Explorer with

MCP AST ExplorervsGitHubMCP AST ExplorervsFilesystemMCP AST ExplorervsMemoryMCP AST ExplorervsTemplate MCP Server

Not sure what to pick?

Find your stack in 60 seconds

Author?

Embed badge for your README

Browse similar

All development MCPs