codeviewer-mcp

codeviewer-mcp는 상태 유지형 AST 인식 코드 리뷰 워크플로우를 위한 TypeScript MCP 서버입니다.

이 서버는 STDIO를 통해 실행되며, 로컬 MCP 서버를 시작할 수 있는 MCP 클라이언트 및 LLM 하네스를 위해 설계되었습니다.

이 서버가 제공하는 기능

• 반복적인 계획 등록 및 코드 청크 리뷰를 위한 MCP 도구

• SQLite 기반의 리뷰 세션 및 기록

• JS/TS 소스 트리를 위한 AST 인덱싱/컨텍스트 로컬라이제이션

• 사전 검사 (TypeScript 진단 + 보안 패턴 탐지)

• 판정, 분류된 피드백, 선택적 패치 힌트가 포함된 구조화된 리뷰 출력

Related MCP server: lsp-intelligence

MCP 도구

1. register_plan

2. review_code_chunk

3. cleanup_expired_sessions

4. cleanup_session

5. list_sessions

6. list_indexing_errors

7. list_prompt_profiles

8. get_prompt_profile

9. health_check

필수 조건

이 MCP가 올바르게 설치되고 실행되려면 다음 필수 조건이 필요합니다.

OS별 네이티브 빌드 도구 체인:

• Windows: Visual Studio Build Tools 2022 (C++를 사용한 데스크톱 개발) + Python 3

• macOS: Xcode Command Line Tools (xcode-select --install)

• Linux (Debian/Ubuntu): build-essential python3 make g++

네이티브 빌드 도구가 없으면 pnpm install 시 better-sqlite3 컴파일 과정에서 실패할 수 있습니다.

빠른 시작

git clone https://github.com/Master0fFate/codeviewer-mcp.git
cd codeviewer-mcp
pnpm install
pnpm build
pnpm start

개발 모드:

pnpm dev

환경 변수

예시:

MCP_PROJECT_PATH=/absolute/path/to/repo \
MCP_SESSION_TTL_HOURS=24 \
LOG_LEVEL=info \
node dist/index.js

MCP_AUTH_TOKEN이 설정된 경우의 인증 예시:

{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "plan_step": 1,
  "target_file": "src/example.ts",
  "code_chunk": "export const ok = true;",
  "modification_type": "MODIFY",
  "auth_token": "your-shared-secret"
}

프롬프트 프로필 워크플로우 (구획화된 프롬프트)

이 MCP는 이제 prompts 폴더를 통한 세션 수준의 프롬프트 구획화를 지원합니다.

• 프롬프트 디렉토리에 *.md 파일로 프롬프트 파일을 추가합니다.

• 프로필 ID는 확장자를 제외한 파일 이름입니다.

  • 예: prompts/cybersec.md -> prompt_profile: "cybersec"

• register_plan과 선택적 prompt_profile로 세션을 시작합니다.

• 선택된 프로필은 세션에 유지되며 해당 세션 내의 모든 review_code_chunk 호출에 재사용됩니다.

• review_code_chunk 출력에는 다음이 포함됩니다:

  • active_prompt_profile

  • active_prompt_title

  • active_prompt_headings

도우미 도구 사용:

• list_prompt_profiles: 사용 가능한 프로필 확인

• get_prompt_profile: 프로필의 전체 프롬프트 내용 읽기

특화 프로필을 사용한 register_plan 페이로드 예시:

{
  "project_path": "/absolute/path/to/repo",
  "prompt_profile": "cybersec",
  "steps": [
    "Review auth and secrets handling",
    "Check unsafe execution paths"
  ]
}

LLM 자동 설치 가이드

이 섹션은 자율 LLM 설치 프로그램 및 MCP 하네스를 위해 작성되었습니다.

표준 서버 실행

node /absolute/path/to/codeviewer-mcp/dist/index.js

멱등성 설치/업데이트 (bash)

set -euo pipefail
INSTALL_ROOT="${HOME}/mcp-servers"
SERVER_DIR="${INSTALL_ROOT}/codeviewer-mcp"

mkdir -p "${INSTALL_ROOT}"
if [ ! -d "${SERVER_DIR}/.git" ]; then
  git clone https://github.com/Master0fFate/codeviewer-mcp.git "${SERVER_DIR}"
else
  git -C "${SERVER_DIR}" pull --ff-only
fi

cd "${SERVER_DIR}"
pnpm install
pnpm build

멱등성 설치/업데이트 (PowerShell)

$InstallRoot = Join-Path $HOME "mcp-servers"
$ServerDir = Join-Path $InstallRoot "codeviewer-mcp"

New-Item -ItemType Directory -Path $InstallRoot -Force | Out-Null
if (-not (Test-Path (Join-Path $ServerDir ".git"))) {
  git clone https://github.com/Master0fFate/codeviewer-mcp.git $ServerDir
} else {
  git -C $ServerDir pull --ff-only
}

Set-Location $ServerDir
pnpm install
pnpm build

하네스 설치 (Claude Code, VS Code Copilot, OpenCode, 일반 MCP)

모든 하네스에서 동일한 STDIO 실행 값을 사용하십시오.

표준 서버 블록:

{
  "name": "codeviewer-mcp",
  "transport": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/codeviewer-mcp/dist/index.js"],
  "env": {
    "MCP_PROJECT_PATH": "/absolute/path/to/target/repo",
    "MCP_REVIEWER_DB_PATH": "/absolute/path/to/target/repo/.codeviewer-mcp.sqlite",
    "LOG_LEVEL": "info"
  }
}

Claude Code / Claude Desktop

1. Claude MCP 설정을 엽니다.

2. mcpServers 아래에 표준 command/args/env 값을 사용하여 codeviewer-mcp를 추가합니다.

3. Claude를 재시작합니다.

4. 도구가 검색 가능한지 확인합니다.

예시:

{
  "mcpServers": {
    "codeviewer-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/codeviewer-mcp/dist/index.js"],
      "env": {
        "MCP_PROJECT_PATH": "/absolute/path/to/repo"
      }
    }
  }
}

VS Code Copilot (MCP)

1. VS Code MCP 서버 관리(버전에 따라 UI 또는 JSON 설정)를 엽니다.

2. codeviewer-mcp라는 이름의 로컬 STDIO MCP 서버를 등록합니다.

3. node 명령을 설정하고, 인수를 빌드된 dist/index.js로 지정하며, MCP_PROJECT_PATH를 설정합니다.

4. 확장 프로그램 버전에 따라 필요한 경우 VS Code 창을 새로고침합니다.

5. Copilot Chat MCP 도구 목록에서 도구 검색을 확인합니다.

버전이 JSON 설정을 지원하는 경우, 표준 서버 블록을 MCP 설정 스키마에 매핑하십시오.

OpenCode

1. OpenCode MCP 설정을 엽니다.

2. codeviewer-mcp라는 이름의 로컬 STDIO 서버를 추가합니다.

3. node + 빌드된 dist/index.js를 사용합니다.

4. MCP_PROJECT_PATH 및 선택적 DB/로그 환경 변수를 설정합니다.

5. OpenCode를 재시작하고 도구가 나타나는지 확인합니다.

일반 MCP 클라이언트

로컬 STDIO MCP 서버를 지원하는 모든 클라이언트는 위의 표준 블록을 사용할 수 있습니다. 필드 이름이 다른 경우, 동일한 값을 클라이언트 스키마에 매핑하십시오.

검증 체크리스트

• [ ] 서버가 프로세스 오류 없이 시작됨

• [ ] 클라이언트가 MCP 연결 수립을 보고함

• [ ] 도구 표시: register_plan, review_code_chunk, cleanup_expired_sessions, cleanup_session, list_sessions, list_indexing_errors, list_prompt_profiles, get_prompt_profile, health_check

• [ ] register_plan이 유효한 session_id를 반환함

• [ ] review_code_chunk가 구조화된 판정 결과를 반환함

• [ ] health_check가 정상적인 데이터베이스/세션 상태를 보고함

개발 및 검증

pnpm test
pnpm build

보안 참고 사항

• 경로 포함 검사는 심볼릭 링크 기반 탈출을 포함하여 구성된 프로젝트 루트를 벗어나는 것을 방지합니다.

• 인증은 선택 사항(MCP_AUTH_TOKEN)이며 공유 환경에서는 활성화해야 합니다.

• 세션은 MCP_SESSION_TTL_HOURS에 따라 자동으로 만료됩니다.

• SQLite는 WAL 모드 및 외래 키 활성화 상태로 구성됩니다.

저장소 구조

• /src/index.ts - 프로세스 진입점 및 STDIO 전송

• /src/server.ts - MCP 서버 및 도구 등록

• /src/schemas.ts - Zod 도구 계약 스키마

• /src/state.ts - SQLite 상태 저장소 및 세션 수명 주기

• /src/ast.ts - AST 인덱싱 및 컨텍스트 로컬라이제이션

• /src/preflight.ts - 정적 사전 검사

• /src/reviewer.ts - 리뷰 결정 및 출력 형성

• /src/logger.ts - 구조화된 로깅

• /tests - Vitest 테스트 스위트

라이선스

GNU v3