Code AST MCP Server (code-ast-mcp)

code-ast-mcp es un servidor MCP arquitectónico del Model Context Protocol (MCP) construido con el analizador nativo de árbol de sintaxis abstracta (ast) de Python. Permite a los modelos de IA (en Claude Desktop, Cursor, Antigravity o clientes MCP personalizados) analizar estructuras de bases de código Python locales, buscar definiciones de símbolos, construir grafos de dependencias, auditar la cobertura de docstrings y refactorizar código sin cargar archivos fuente completos en las ventanas de contexto del LLM.

🔗 Repositorio en vivo: https://github.com/m-sameerkhan/code-ast-mcp
🔗 Registro de Smithery: https://smithery.ai/servers/sameerbalouch758/code-ast-mcp

⚡ Características y capacidades

🛠️ Herramientas

1. analyze_file_ast(file_path: str)

   • Analiza un archivo .py y lo convierte en un esquema AST limpio.

   • Extrae docstrings del módulo, recuentos de líneas, importaciones, funciones de nivel superior, clases, métodos y variables.

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

   • Localiza una clase específica y devuelve firmas de métodos, anotaciones de tipo, rangos de líneas y docstrings.

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

   • Busca recursivamente en un directorio clases, funciones, métodos o asignaciones de variables que coincidan con symbol_name.

4. get_imports_graph(target_dir: str)

   • Escanea archivos Python para crear un mapa de importaciones de dependencias y genera una cadena de diagrama Mermaid.

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

   • Audita los docstrings de la base de código y calcula el porcentaje general de cobertura de docstrings.

📝 Prompts

• refactor_code_summary(file_path: str)

  • Genera una indicación estructurada que instruye al LLM a revisar el esquema AST de un archivo y proponer refactorización, mejoras de patrones de diseño y correcciones de documentación.

📊 Recursos

• codeast://stats

  • Recurso JSON en vivo que proporciona estadísticas del espacio de trabajo (total de archivos escaneados, % de cobertura de docstrings, recuentos de elementos faltantes).

Related MCP server: codeweave-mcp

🚀 Inicio rápido e instalación

Opción 1: Instalar mediante la CLI de Smithery

smithery mcp add sameerbalouch758/code-ast-mcp

Opción 2: Instalación local desde el código fuente

Clona el repositorio e instala las dependencias en modo editable:

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 .

Opción 3: Empaquetar como un paquete MCP (.mcpb)

Para clientes de escritorio que admiten paquetes MCP (como Claude Desktop):

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

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

🧪 Pruebas locales

Ejecutar pruebas unitarias

pytest

Probar con MCP Inspector

Usa el MCP Inspector oficial para probar herramientas y recursos de forma interactiva:

npx @modelcontextprotocol/inspector python -m code_ast_mcp.server

⚙️ Configuración del cliente

Integración con Claude Desktop / Cursor / Antigravity

Añade code-ast-mcp a tu archivo de configuración del cliente (claude_desktop_config.json o mcp_config.json):

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

Nota para usuarios de Windows: puedes apuntar "command" a tu entorno virtual o a la ruta de Python de Conda (p. ej., C:/Users/<Username>/.conda/envs/code-ast-mcp/python.exe o D:/my_mcp/.venv/Scripts/python.exe).

📦 Estructura del proyecto

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

📄 Licencia

Licencia MIT. Creado por m-sameerkhan.