project-graph-mcp: AI 탐색을 위한 그래프

AI 에이전트 코드 탐색을 위한 프로젝트 그래프: MCP 의존성 그래프

다중 에이전트 개발 시스템은 코드베이스를 정확하게 탐색할 수 있어야 합니다. project-graph-mcp 서버는 최소화된 JSON 형식으로 압축된 의존성 그래프를 생성하는 MCP 인터페이스를 제공합니다. 이로써 에이전트는 소스 파일을 파싱하는 데 필요한 토큰을 소비하지 않고도 프로젝트 아키텍처를 이해할 수 있습니다.

서버는 파일을 분석해 클래스, 메서드, 임포트 정보를 추출하고, 10~50배 압축된 구조를 반환합니다. 자바스크립트, 타입스크립트, 파이썬, 고 등 다양한 언어를 지원해 다국적 프로젝트에서도 원활한 작동이 가능합니다.

압축된 형식의 프로젝트 구조체

핵심 기능은 프로젝트의 '구조체'를 생성하는 것입니다. 파서는 소스 파일을 스캔해 도식, 통계, 노드 그래프를 포함한 JSON 출력물을 생성합니다.

예시 출력:

{
  "L": { "SN": "SymNode", "SNG": "SymNodeGraph" },
  "s": { "files": 23, "classes": 10, "functions": 65 },
  "n": { "SN": { "m": 11, "$": 7 }, "SNG": { "m": 16, "$": 5 } },
  "e": 35, "o": 7, "d": 5, "F": 63
}

• L — 약어 이름의 설명서
• s — 통계 (파일, 클래스, 함수 수)
• n — 메서드(m)와 속성($)을 가진 노드
• e, o, d, F — 간선, 객체, 디렉토리, 파일

심층 탐색을 위해 expand 및 deps 메서드를 사용해 그래프를 동적으로 확장할 수 있습니다.

AST 없이 다중 언어 파싱

초기에는 자바스크립트용 Acorn을 기반으로 개발되었습니다. 버전 1.1에서는 정규 표현식을 활용해 타입스크립트, 파이썬, 고에 대한 파서를 추가했습니다. 외부 종속성을 제거하면서도 언어별 특수성은 유지합니다.

공통 유틸리티 stripStringsAndComments는 코드에서 문자열과 주석을 제거합니다:

// 파이썬
stripStringsAndComments(code, { tripleQuote: true, hashComment: true })

// 고
stripStringsAndComments(code, { backtick: true, templateInterpolation: false })

// 타입스크립트 (기본)
stripStringsAndComments(code)

모든 파서는 ParseResult를 통합하여 클래스, 함수, 임포트, 호출을 처리하며, 정규 표현식 패턴은 프로젝트 스타일에 맞게 조정됩니다.

코드 분석 및 건강 점수

서버는 품질 지표를 포함합니다:

• get_dead_code — 미사용 코드 탐지
• get_complexity — 순환 복잡도 측정
• get_large_files — 리팩토링이 필요한 파일 식별
• get_call_chain — 호출 체인 추적 (authMiddleware → validateToken → renderDashboard)

명령어:

# 오래된 패키지 및 의존성 검사
npx project-graph-mcp outdated .

# 복잡도 분석
npx project-graph-mcp complexity src/

결과는 건강 점수(0~100)로 집계되며, 응답 힌트는 복잡한 함수 검토와 같은 다음 단계를 제안합니다.

JSDoc을 통한 테스트 체크리스트

@test 및 @expect 주석을 지원해 테스트를 문서화합니다:

/**
 * API를 통해 새 사용자 생성
 *
 * @test request: POST /api/users with valid data
 * @expect status: 201 Created
 */
async createUser(data) { ... }

• get_pending_tests — 미완료 테스트 목록
• mark_test_passed — 테스트 완료 표시

API, CLI, 통합, 브라우저 테스트 모두 지원합니다.

프레임워크 전용 맞춤 설정

리액트 18/19, 뷰 3, 엑스프레스 5, 타입스크립트 5, 심비오테.js 등에 대한 내장 규칙 세트(11세트, 총 86개 규칙)가 제공됩니다. get_framework_reference를 통해 프로젝트 자동 감지가 가능합니다.

맞춤 규칙을 적용하려면:

• rules/ 폴더에 규칙 추가
• 에이전트에서 set_custom_rule 사용

에이전트 풀과의 통합

프랙탈 오케스트레이션 환경에서 IDE 에이전트는 구조체를 요청하고 작업을 워커(Gemini 등)에게 위임합니다. 각 워커는 로컬 MCP 인스턴스를 실행해 expand/deps를 사용해 탐색합니다.

크기는 단 132KB이며 외부 종속성이 없습니다. VS코드, 커서, 제드용 구성 예시:

{
  "mcpServers": {
    "project-graph": {
      "command": "npx",
      "args": ["-y", "project-graph-mcp"]
    }
  }
}

보안 및 경로 탐색 방지

경로 검증은 resolve + startsWith를 사용해 작업 디렉터리 내부만 접근을 제한합니다. expand, deps, get_skeleton 등의 메서드도 이 보호 기능을 상속받아, ../../etc/passwd와 같은 요청은 오류를 반환합니다.

주요 장점:

• 압축된 의존성 그래프로 AI 에이전트 탐색 속도 향상
• 외부 라이브러리 없이 JS/TS/Python/Go에 대한 정규 표현식 기반 파서
• 대상 리팩토링을 위한 건강 점수 및 호출 체인 분석
• JSDoc 체크리스트로 테스트 문서화 자동화
• 인기 프레임워크용 86개 사전 구축 규칙 제공

— Editorial Team