Code AST MCP 서버 (code-ast-mcp)

code-ast-mcp 는 Python의 네이티브 추상 구문 트리(ast) 파서로 구축된 아키텍처 기반 Model Context Protocol (MCP) 서버입니다. Claude Desktop, Cursor, Antigravity 또는 사용자 정의 MCP 클라이언트의 AI 모델이 전체 원시 소스 파일을 LLM 컨텍스트 창에 로드하지 않고도 로컬 Python 코드베이스 구조를 분석하고, 심볼 정의를 검색하고, 의존성 그래프를 구축하고, docstring 적용 범위를 감사하고, 코드를 리팩터링할 수 있게 해줍니다.

🔗 실시간 저장소: 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)

  • 파일의 AST 개요를 검토하고 리팩터링, 디자인 패턴 개선 및 문서화 수정을 제안하도록 LLM에 지시하는 구조화된 프롬프트를 생성합니다.

📊 리소스

• codeast://stats

  • 작업공간 통계(스캔된 총 파일 수, docstring 적용 범위 %, 누락 항목 수)를 제공하는 실시간 JSON 리소스입니다.

Related MCP server: codeweave-mcp

🚀 빠른 시작 및 설치

옵션 1: Smithery CLI로 설치

smithery mcp add sameerbalouch758/code-ast-mcp

옵션 2: 소스에서 로컬 설치

저장소를 클론하고 편집 가능 모드로 의존성을 설치합니다:

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 통합

클라이언트 구성 파일(claude_desktop_config.json 또는 mcp_config.json)에 code-ast-mcp를 추가하세요:

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

Windows 사용자 참고: "command"를 가상 환경 또는 Conda Python 경로로 지정할 수 있습니다 (예: 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 제작.