🗺️ CodeAtlas MCP 서버

npm version License TypeScript Node

CodeAtlas 분석 데이터를 Gemini, Claude, Cursor, Windsurf, VS Code Copilot 등 AI 어시스턴트에 제공하는 독립형 MCP 서버입니다.

v1.4.0 신규 기능: 🧠 AI 시스템 메모리 — AI가 대화 간의 시스템 흐름을 기억합니다.

⚡ 빠른 시작

1. 프로젝트 분석

CodeAtlas VS Code 확장 프로그램을 설치한 후 다음을 실행하세요:

Ctrl+Shift+P → CodeAtlas: Analyze Project

이 명령은 프로젝트 루트에 .codeatlas/analysis.json을 생성합니다.

2. MCP 설정 추가

사용 중인 AI 어시스턴트를 선택하고 설정을 추가하세요:

설정(Settings)(Ctrl+,)을 열고 mcp를 검색한 뒤 settings.json에서 편집을 클릭하고 다음을 추가하세요:

{
  "mcp": {
    "servers": {
      "codeatlas": {
        "command": "npx",
        "args": ["-y", "@giauphan/codeatlas-mcp"]
      }
    }
  }
}

또는 프로젝트별 설정을 위해 워크스페이스의 .vscode/settings.json에 추가할 수 있습니다.

.gemini/settings.json에 추가하세요:

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@giauphan/codeatlas-mcp"]
    }
  }
}

claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@giauphan/codeatlas-mcp"]
    }
  }
}

.cursor/mcp.json에 추가하세요:

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@giauphan/codeatlas-mcp"]
    }
  }
}

.windsurf/mcp.json에 추가하세요:

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@giauphan/codeatlas-mcp"]
    }
  }
}

끝입니다! 이제 AI 어시스턴트가 코드베이스 구조, 의존성 및 인사이트를 쿼리할 수 있습니다.

🛠️ 사용 가능한 도구

코드 분석 (6개 도구)

도구	설명
`list_projects`	분석된 모든 프로젝트 나열 (자동으로 `~/` 탐색)
`get_project_structure`	모듈, 클래스, 함수, 변수 가져오기
`get_dependencies`	import / 호출 / 포함 관계 가져오기
`get_insights`	AI가 생성한 코드 품질 인사이트 가져오기
`search_entities`	이름으로 함수, 클래스 검색 (퍼지 매칭)
`get_file_entities`	특정 파일에 정의된 모든 엔티티 가져오기

🧠 AI 시스템 메모리 (3개 도구 — v1.4.0 신규)

도구	설명
`generate_system_flow`	Mermaid 아키텍처 다이어그램 자동 생성. 범위: `modules-only`, `full`, `feature`
`sync_system_memory`	`.agents/memory/` 폴더 생성/업데이트 — AI의 영구적인 장기 기억
`trace_feature_flow`	코드베이스를 통한 기능 흐름 추적. 의존성 순서대로 파일 반환

🧠 AI 시스템 메모리

AI 어시스턴트는 대화 간에 컨텍스트를 잃어버립니다. CodeAtlas MCP는 영구 메모리 파일을 통해 이 문제를 해결합니다.

작동 방식

Conversation 1 → AI writes code → calls sync_system_memory
                                          │
                                   .agents/memory/
                                   ├── system-map.md
                                   ├── modules.json
                                   ├── business-rules.json
                                   ├── conventions.md
                                   ├── feature-flows.json
                                   └── change-log.json
                                          │
Conversation 2 → AI reads .agents/memory/ → knows full system flow instantly

AI 메모리 설정

규칙 템플릿을 프로젝트에 복사하세요:

mkdir -p /path/to/your-project/.agents/rules/

.agents/rules/auto-memory.md를 생성하고 AI에게 다음을 지시하는 규칙을 작성하세요:
- 모든 대화 시작 시 .agents/memory/ 읽기
- 변경 전 trace_feature_flow 사용
- 변경 완료 후 sync_system_memory 호출
sync_system_memory를 한 번 실행하여 초기 메모리 스냅샷을 생성하세요.

📖 전체 설정 가이드 및 규칙 템플릿: CodeAtlas 문서

📦 대안: 전역 설치

npx 대신 전역으로 설치하려면 다음을 사용하세요:

npm install -g @giauphan/codeatlas-mcp

그런 다음 MCP 설정에서 "command": "codeatlas-mcp"를 사용하세요 (args는 필요 없음).

🔧 환경 변수

변수	설명
`CODEATLAS_PROJECT_DIR`	특정 프로젝트 디렉토리 강제 지정

기본적으로 서버는 홈 디렉토리 아래에서 .codeatlas/analysis.json이 있는 모든 프로젝트를 자동으로 탐색합니다.

🌐 지원 언어

언어	기능
TypeScript / JavaScript	전체 AST: import, 클래스, 함수, 변수, 호출
Python	클래스, 함수, 변수, import, 호출
PHP	클래스, 인터페이스, 트레이트, 열거형, 함수, 속성, 상수
Blade Templates	`@extends`, `@include`, `@component`, `<x-component>`

🧑💻 개발

git clone https://github.com/giauphan/codeatlas-mcp.git
cd codeatlas-mcp
npm install
npm run build
npm start

라이선스

MIT

CodeAtlas MCP Server