Code AST MCP Server (code-ast-mcp)

code-ast-mcp — это архитектурный сервер Model Context Protocol (MCP), построенный на нативном парсере Abstract Syntax Tree (ast) из Python. Он позволяет моделям ИИ (в Claude Desktop, Cursor, Antigravity или пользовательских MCP-клиентах) анализировать структуру локальных кодовых баз Python, искать определения символов, строить графы зависимостей, проверять покрытие docstring'ами и рефакторить код без загрузки целых исходных файлов в контекстные окна LLM.

🔗 Живой репозиторий: https://github.com/m-sameerkhan/code-ast-mcp
🔗 Реестр Smithery: https://smithery.ai/servers/sameerbalouch758/code-ast-mcp

⚡ Функции и возможности

🛠️ Инструменты

1. analyze_file_ast(file_path: str)

   • Разбирает .py-файл в аккуратную структуру AST.

   • Извлекает docstring'и модуля, количество строк, импорты, функции верхнего уровня, классы, методы и переменные.

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

   • Находит конкретный класс и возвращает сигнатуры методов, аннотации типов, диапазоны строк и docstring'и.

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

   • Рекурсивно ищет в каталоге классы, функции, методы или присваивания переменных, соответствующие symbol_name.

4. get_imports_graph(target_dir: str)

   • Сканирует Python-файлы для построения карты импортов зависимостей и выводит строку диаграммы Mermaid.

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

   • Проводит аудит docstring в кодовой базе и вычисляет общий процент покрытия docstring'ами.

📝 Промпты

• refactor_code_summary(file_path: str)

  • Формирует структурированный промпт с инструкцией для LLM просмотреть структуру AST файла и предложить рефакторинг, улучшения паттернов проектирования и исправления документации.

📊 Ресурсы

• codeast://stats

  • Живой JSON-ресурс, предоставляющий статистику рабочей области (количество просканированных файлов, процент покрытия docstring, количество отсутствующих элементов).

Related MCP server: codeweave-mcp

🚀 Быстрый старт и установка

Вариант 1: установка через Smithery CLI

smithery mcp add sameerbalouch758/code-ast-mcp

Вариант 2: локальная установка из исходного кода

Клонируйте репозиторий и установите зависимости в режиме 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 .

Вариант 3: упаковка в MCP-бандл (.mcpb)

Для десктопных клиентов, поддерживающих MCP-бандлы (например, Claude Desktop):

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

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

🧪 Локальное тестирование

Запуск модульных тестов

pytest

Тестирование с помощью MCP Inspector

Используйте официальный MCP Inspector для интерактивного тестирования инструментов и ресурсов:

npx @modelcontextprotocol/inspector python -m code_ast_mcp.server

⚙️ Конфигурация клиента

Интеграция с Claude Desktop / Cursor / Antigravity

Добавьте code-ast-mcp в файл конфигурации вашего клиента (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"
    }
  }
}

Примечание для пользователей Windows: вы можете указать в "command" путь к вашему виртуальному окружению или Python в Conda (например, C:/Users/<Username>/.conda/envs/code-ast-mcp/python.exe или D:/my_mcp/.venv/Scripts/python.exe).

📦 Структура проекта

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

📄 Лицензия

Лицензия MIT. Автор: m-sameerkhan.