@tac0de/code-explainer-mcp

코드 저장소를 사람이 이해하기 쉬운 말로 설명해주는 MCP 서버입니다.
LLM/에이전트가 프로젝트 구조, 핵심 파일, 각 파일의 역할을 빠르게 파악할 수 있게 도와줍니다.

✨ 무엇을 해주나요?

이 서버는 아래 같은 질문에 잘 맞습니다.

• "이 레포 구조를 초보자도 알기 쉽게 설명해줘"
• "이 파일은 왜 있는 거야?"
• "먼저 읽어야 할 핵심 파일만 뽑아줘"
• "이 프로젝트가 어떤 스택인지 요약해줘"

제공 도구

| Tool | 설명 | 언제 쓰면 좋은가 | | --- | --- | --- | | explain_repo_map | 레포 전체 구조를 스캔해서 큰 그림을 설명 | 처음 프로젝트를 열었을 때 | | list_key_files | 먼저 읽어야 할 핵심 파일 목록을 보여줌 | 빠른 온보딩이 필요할 때 | | explain_file_role | 특정 파일의 역할, 개념, import, 심볼을 설명 | 파일 하나를 이해하고 싶을 때 |

✅ 요구사항

• Node.js >= 20
• npm >= 9

확인:

node -v
npm -v

🚀 가장 쉬운 로컬 실행법

1) 설치

npm install

2) 빌드

npm run build

3) Inspector로 테스트

npm run inspect

정상이라면 브라우저/Inspector에서 MCP 서버를 연결해 도구 목록을 확인할 수 있습니다.

🧪 개발 모드

소스 그대로 실행:

npm run dev

배포용 빌드 실행:

npm run build
npm start

📦 npm 패키지로 사용할 때

배포 후에는 보통 아래처럼 실행합니다.

npx -y @tac0de/code-explainer-mcp --root /ABSOLUTE/PATH/TO/YOUR/REPO

옵션

| 옵션 | 설명 | | --- | --- | | --root, -r | 분석 허용 루트 경로 지정 | | --help, -h | 도움말 출력 | | --version, -v | 버전 출력 |

환경 변수

| 환경 변수 | 설명 | | --- | --- | | WORKSPACE_ROOT | 기본 분석 루트 경로 | | MCP_IGNORE_NAMES | 무시할 디렉터리 이름을 쉼표로 추가 지정 |

예시:

MCP_IGNORE_NAMES="node_modules,dist,.git,coverage" \
npx -y @tac0de/code-explainer-mcp --root /ABSOLUTE/PATH/TO/YOUR/REPO

🖥️ MCP 클라이언트에 붙이는 법

아래 JSON 패턴을 대부분의 MCP 클라이언트(Claude Desktop, Cursor, 일부 VS Code 설정)에서 응용할 수 있습니다.

{
  "mcpServers": {
    "code-explainer": {
      "command": "npx",
      "args": [
        "-y",
        "@tac0de/code-explainer-mcp",
        "--root",
        "/ABSOLUTE/PATH/TO/YOUR/REPO"
      ],
      "env": {
        "MCP_IGNORE_NAMES": "node_modules,dist,.git,coverage"
      }
    }
  }
}

Claude Desktop 예시

macOS 설정 파일 위치:

~/Library/Application Support/Claude/claude_desktop_config.json

예시:

{
  "mcpServers": {
    "code-explainer": {
      "command": "npx",
      "args": [
        "-y",
        "@tac0de/code-explainer-mcp",
        "--root",
        "/Users/you/projects/my-repo"
      ]
    }
  }
}

저장 후 Claude Desktop을 완전히 종료했다가 다시 실행하세요.

💬 사용 예시 프롬프트

클라이언트에서 이런 식으로 물어보면 됩니다.

1. 이 프로젝트 구조를 초보자도 이해하게 설명해줘
2. 먼저 읽어야 할 핵심 파일만 뽑아줘
3. src/index.ts 파일의 역할을 설명해줘
4. 이 레포의 주요 기술 스택과 엔트리포인트를 알려줘

🔍 동작 방식

explain_repo_map

입력 예시:

{
  "rootPath": "/Users/you/projects/my-repo",
  "maxEntries": 250,
  "maxDepth": 8
}

list_key_files

입력 예시:

{
  "rootPath": "/Users/you/projects/my-repo",
  "maxEntries": 200
}

explain_file_role

입력 예시:

{
  "rootPath": "/Users/you/projects/my-repo",
  "filePath": "src/index.ts",
  "maxChars": 12000
}

1) 클라이언트에서 도구가 안 보임

확인할 것:

• 클라이언트를 재시작했는지
• npx 실행이 가능한지
• --root 경로가 절대 경로인지
• Node 버전이 20 이상인지

2) 너무 많은 파일을 읽어서 느림

• maxEntries를 줄이세요
• maxDepth를 줄이세요
• MCP_IGNORE_NAMES에 큰 디렉터리를 더 넣으세요

예시:

MCP_IGNORE_NAMES="node_modules,dist,.git,coverage,.next" \
npx -y @tac0de/code-explainer-mcp --root /ABSOLUTE/PATH/TO/YOUR/REPO

📁 프로젝트 구조

src/
  index.ts   # MCP 서버 엔트리포인트, tool 등록
  utils.ts   # 파일 스캔/분석 유틸리티
dist/        # 빌드 결과물 (배포 시 포함)

🔐 안전성 메모

• 지정한 루트 밖 파일은 읽지 않도록 제한합니다.
• STDIO MCP 서버 특성상 stdout에 로그를 찍지 않도록 주의해야 합니다.
• 큰 저장소에서는 maxEntries, maxDepth, MCP_IGNORE_NAMES를 함께 쓰는 것이 좋습니다.

License

MIT