Code AST MCP Server (code-ast-mcp)

code-ast-mcp is an architectural Model Context Protocol (MCP) server built with Python's native Abstract Syntax Tree (ast) parser. It allows AI models (in Claude Desktop, Cursor, Antigravity, or custom MCP clients) to analyze Python codebase structures, search symbol definitions, build dependency graphs, audit docstring coverage, and refactor code without loading entire raw source files into LLM context windows.

🔗 Live Repository: https://github.com/m-sameerkhan/code-ast-mcp
🔗 Glama Registry: https://glama.ai/mcp/servers/m-sameerkhan/code-ast-mcp

---

⚡ Features & Capabilities

🛠️ Tools

1. analyze_file_ast(file_path: str)
   • Parses a .py file into a clean AST outline.
   • Extracts module docstrings, line counts, imports, top-level functions, classes, methods, and variables.
2. find_class_methods(file_path: str, class_name: str)
   • Locates a specific class and returns method signatures, type annotations, line ranges, and docstrings.
3. find_symbol(target_dir: str, symbol_name: str)
   • Recursively searches a directory for classes, functions, methods, or variable assignments matching symbol_name.
4. get_imports_graph(target_dir: str)
   • Scans Python files to build a dependency import map and outputs a Mermaid diagram string.
5. find_missing_docstrings(target_dir: str, include_private: bool = False)
   • Audits codebase docstrings and calculates overall docstring coverage percentage.

📝 Prompts

• refactor_code_summary(file_path: str)
  • Generates a structured prompt instructing the LLM to review the AST outline of a file and propose refactoring, design pattern improvements, and documentation fixes.

📊 Resources

• codeast://stats
  • Live JSON resource providing workspace statistics (total files scanned, docstring coverage %, missing item counts).

---

🚀 Deployment & Usage Modes

Mode 1: Deploy via Glama MCP Registry

Deploy code-ast-mcp to the Glama MCP Registry — Glama automatically clones your GitHub repo, builds it using the included Dockerfile, and hosts it with built-in OAuth 2.1, monitoring, and access control.

Steps:

1. Go to glama.ai/mcp/servers.
2. Click "Add Server".
3. Authenticate with GitHub OAuth (you must have write access to the repo).
4. Submit the repository URL:

   https://github.com/m-sameerkhan/code-ast-mcp
   

5. Glama will auto-build using the Dockerfile and verify MCP compliance.
6. Once the build succeeds, your server will be live on the Glama registry.

Registry URL:

https://glama.ai/mcp/servers/m-sameerkhan/code-ast-mcp

Note: No manual hosting required — Glama handles building, deployment, and verification automatically.

---

Mode 2: Local Stdio MCP Server (Recommended for Local Codebases)

Best for inspecting local Python projects directly on your machine in Claude Desktop, Cursor, or Antigravity.

Installation:

git clone https://github.com/m-sameerkhan/code-ast-mcp.git
cd code-ast-mcp

# Virtual environment setup
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt
pip install -e .

Client Configuration (claude_desktop_config.json / mcp_config.json):

{
  "mcpServers": {
    "code-ast-mcp": {
      "command": "python",
      "args": [
        "-m",
        "code_ast_mcp.server"
      ],
      "cwd": "/path/to/code-ast-mcp"
    }
  }
}

---

🧪 Testing Locally

Run Unit Tests

pytest

Test with MCP Inspector

npx @modelcontextprotocol/inspector python -m code_ast_mcp.server

---

📦 Project Structure

code-ast-mcp/
├── code_ast_mcp/          # Core MCP package
│   ├── __init__.py        # Package exports
│   ├── analyzer.py        # Python AST parsing & static analysis engine
│   └── server.py          # FastMCP server definition & tool handlers
├── tests/                 # Test suite
│   └── test_analyzer.py   # Unit tests with pytest
├── Dockerfile             # Container image definition (used by Glama)
├── pyproject.toml         # Packaging & metadata
└── requirements.txt       # Dependencies

---

📄 License

MIT License. Created by m-sameerkhan.