Code AST MCP Server (code-ast-mcp)

code-ast-mcp ist ein Architektur-MCP-Server (Model Context Protocol), der mit Pythons nativem Abstract-Syntax-Tree-Parser (ast) erstellt wurde. Er ermöglicht KI-Modellen (in Claude Desktop, Cursor, Antigravity oder benutzerdefinierten MCP-Clients), lokale Python-Codebasisstrukturen zu analysieren, Symboldefinitionen zu suchen, Abhängigkeitsgraphen zu erstellen, die Docstring-Abdeckung zu prüfen und Code umzugestalten, ohne vollständige rohe Quelldateien in die LLM-Kontextfenster zu laden.

🔗 Live-Repository: https://github.com/m-sameerkhan/code-ast-mcp
🔗 Smithery Registry: https://smithery.ai/servers/sameerbalouch758/code-ast-mcp

⚡ Funktionen & Fähigkeiten

🛠️ Tools

1. analyze_file_ast(file_path: str)

   • Parst eine .py-Datei in eine saubere AST-Gliederung.

   • Extrahiert Modul-Docstrings, Zeilenzahlen, Importe, Funktionen auf oberster Ebene, Klassen, Methoden und Variablen.

2. find_class_methods(file_path: str, class_name: str)

   • Lokalisiert eine bestimmte Klasse und gibt Methodensignaturen, Typannotationen, Zeilenbereiche und Docstrings zurück.

3. find_symbol(target_dir: str, symbol_name: str)

   • Durchsucht ein Verzeichnis rekursiv nach Klassen, Funktionen, Methoden oder Variablenzuweisungen, die mit symbol_name übereinstimmen.

4. get_imports_graph(target_dir: str)

   • Scannt Python-Dateien, um eine Abhängigkeits-Importkarte zu erstellen, und gibt einen Mermaid-Diagramm-String aus.

5. find_missing_docstrings(target_dir: str, include_private: bool = False)

   • Prüft die Docstrings der Codebasis und berechnet die gesamte Docstring-Abdeckung in Prozent.

📝 Prompts

• refactor_code_summary(file_path: str)

  • Erzeugt einen strukturierten Prompt, der das LLM anweist, die AST-Gliederung einer Datei zu überprüfen und Refactoring, Verbesserungen von Entwurfsmustern und Dokumentationskorrekturen vorzuschlagen.

📊 Ressourcen

• codeast://stats

  • Live-JSON-Ressource, die Arbeitsbereichsstatistiken bereitstellt (gescannte Dateien insgesamt, Docstring-Abdeckung in %, Anzahl fehlender Elemente).

Related MCP server: codeweave-mcp

🚀 Schnellstart & Installation

Option 1: Installation über die Smithery-CLI

smithery mcp add sameerbalouch758/code-ast-mcp

Option 2: Lokale Installation aus dem Quellcode

Klonen Sie das Repository und installieren Sie die Abhängigkeiten im Editable-Modus:

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

# Create & activate virtual environment (or Conda)
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install project and dependencies
pip install -r requirements.txt
pip install -e .

Option 3: Als MCP-Bundle (.mcpb) paketieren

Für Desktop-Clients, die MCP-Bundles unterstützen (z. B. Claude Desktop):

# Install MCPB toolchain
npm install -g @anthropic-ai/mcpb

# Build bundle
mcpb pack . code-ast-mcp.mcpb

🧪 Lokales Testen

Unit-Tests ausführen

pytest

Mit dem MCP Inspector testen

Verwenden Sie den offiziellen MCP Inspector, um Tools und Ressourcen interaktiv zu testen:

npx @modelcontextprotocol/inspector python -m code_ast_mcp.server

⚙️ Client-Konfiguration

Integration in Claude Desktop / Cursor / Antigravity

Fügen Sie code-ast-mcp zu Ihrer Client-Konfigurationsdatei hinzu (claude_desktop_config.json oder mcp_config.json):

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

Hinweis für Windows-Benutzer: Sie können "command" auf den Pfad Ihrer virtuellen Umgebung oder den Conda-Python-Pfad einstellen (z. B. C:/Users/<Username>/.conda/envs/code-ast-mcp/python.exe oder D:/my_mcp/.venv/Scripts/python.exe).

📦 Projektstruktur

code-ast-mcp/
├── code_ast_mcp/          # Core 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
├── manifest.json          # MCPB extension manifest
├── smithery.yaml          # Smithery registry configuration
├── Dockerfile             # Container image definition
├── pyproject.toml         # Packaging & metadata
└── requirements.txt       # Dependencies

📄 Lizenz

MIT-Lizenz. Erstellt von m-sameerkhan.