mcp-ast-explorer 0.1.0__tar.gz

mcp_ast_explorer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run mypy
+      - run: uv run pytest

mcp_ast_explorer-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/

mcp_ast_explorer-0.1.0/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.analysis.extraPaths": ["${workspaceFolder}/src"],
+  "python.testing.pytestEnabled": true,
+  "python.testing.pytestArgs": ["tests"]
+}

mcp_ast_explorer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haichuan Zhou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_ast_explorer-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: mcp-ast-explorer
+Version: 0.1.0
+Summary: MCP server for Python AST/CST symbol exploration.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: libcst>=1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-ast-explorer
+
+<!-- mcp-name: io.github.LovRanRan/mcp-ast-explorer -->
+
+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`](https://github.com/LovRanRan/mcp-repo-mapper) maps repository structure, languages, entry points, framework evidence, and Python dependency edges.
+- [`mcp-ast-explorer`](https://github.com/LovRanRan/mcp-ast-explorer) provides symbol-grounded Python definition, signature, reference, call-chain, and class-hierarchy lookups.
+- [`mcp-test-runner`](https://github.com/LovRanRan/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:
+
+```bash
+uv sync --extra dev
+```
+
+Run the MCP server:
+
+```bash
+uv run mcp-ast-explorer
+```
+
+Run verification:
+
+```bash
+uv run ruff check .
+uv run mypy
+uv run pytest
+```
+
+## License
+
+MIT

mcp_ast_explorer-0.1.0/README.md

@@ -0,0 +1,77 @@
+# mcp-ast-explorer
+
+<!-- mcp-name: io.github.LovRanRan/mcp-ast-explorer -->
+
+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`](https://github.com/LovRanRan/mcp-repo-mapper) maps repository structure, languages, entry points, framework evidence, and Python dependency edges.
+- [`mcp-ast-explorer`](https://github.com/LovRanRan/mcp-ast-explorer) provides symbol-grounded Python definition, signature, reference, call-chain, and class-hierarchy lookups.
+- [`mcp-test-runner`](https://github.com/LovRanRan/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:
+
+```bash
+uv sync --extra dev
+```
+
+Run the MCP server:
+
+```bash
+uv run mcp-ast-explorer
+```
+
+Run verification:
+
+```bash
+uv run ruff check .
+uv run mypy
+uv run pytest
+```
+
+## License
+
+MIT

mcp_ast_explorer-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_ast_explorer"]
+
+[project]
+name = "mcp-ast-explorer"
+version = "0.1.0"
+description = "MCP server for Python AST/CST symbol exploration."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "fastmcp>=2.0",
+    "libcst>=1.0",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.10",
+    "pytest>=8.0",
+    "ruff>=0.5",
+]
+
+[project.scripts]
+mcp-ast-explorer = "mcp_ast_explorer.server:main"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+packages = ["mcp_ast_explorer"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

mcp_ast_explorer-0.1.0/pyrightconfig.json

@@ -0,0 +1,16 @@
+{
+  "venvPath": ".",
+  "venv": ".venv",
+  "pythonVersion": "3.11",
+  "typeCheckingMode": "strict",
+  "executionEnvironments": [
+    {
+      "root": "src",
+      "extraPaths": ["src"]
+    },
+    {
+      "root": "tests",
+      "extraPaths": ["src"]
+    }
+  ]
+}

mcp_ast_explorer-0.1.0/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.LovRanRan/mcp-ast-explorer",
+  "title": "MCP AST Explorer",
+  "description": "Python symbol exploration for codebase onboarding agents.",
+  "repository": {
+    "url": "https://github.com/LovRanRan/mcp-ast-explorer",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "mcp-ast-explorer",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

mcp_ast_explorer-0.1.0/src/mcp_ast_explorer/__init__.py

@@ -0,0 +1 @@
+"""Python AST/CST exploration MCP server."""

mcp_ast_explorer-0.1.0/src/mcp_ast_explorer/backends.py

@@ -0,0 +1,72 @@
+from typing import Protocol
+
+PYTHON_ONLY_ERROR = "Only Python is supported in v1."
+
+
+class LanguageBackend(Protocol):
+    @property
+    def language(self) -> str: ...
+
+    @property
+    def display_name(self) -> str: ...
+
+    @property
+    def is_supported(self) -> bool: ...
+
+    def unsupported_error(self) -> str | None: ...
+
+
+class PythonLanguageBackend:
+    @property
+    def language(self) -> str:
+        return "python"
+
+    @property
+    def display_name(self) -> str:
+        return "Python"
+
+    @property
+    def is_supported(self) -> bool:
+        return True
+
+    def unsupported_error(self) -> str | None:
+        return None
+
+
+class TypeScriptLanguageBackend:
+    @property
+    def language(self) -> str:
+        return "typescript"
+
+    @property
+    def display_name(self) -> str:
+        return "TypeScript"
+
+    @property
+    def is_supported(self) -> bool:
+        return False
+
+    def unsupported_error(self) -> str | None:
+        return PYTHON_ONLY_ERROR
+
+
+_BACKENDS: dict[str, LanguageBackend] = {
+    "python": PythonLanguageBackend(),
+    "typescript": TypeScriptLanguageBackend(),
+}
+
+
+def get_language_backend(language: str) -> LanguageBackend | None:
+    return _BACKENDS.get(language.lower())
+
+
+def is_supported_language(language: str) -> bool:
+    backend = get_language_backend(language)
+    return backend is not None and backend.is_supported
+
+
+def unsupported_language_error(language: str) -> str:
+    backend = get_language_backend(language)
+    if backend is None:
+        return PYTHON_ONLY_ERROR
+    return backend.unsupported_error() or PYTHON_ONLY_ERROR