Code Smell Detection

MCP server for static analysis / code smell detection. Minimal TypeScript stdio transport implementation and tool registration stubs.

목표

• CodeVi 내부의 codevi-metrics-server.ts 단일 파일 중심 구현을 분리하여, 독립적인 MCP 도구 서버로 전환.
• NestJS, TypeORM, MySQL, Docker 구성 등 CodeVi 본체 종속 항목은 제외.
• 우선 npm 배포/사용을 목표로 함. (PyPI는 추후 Python 포팅 시 고려)

사용법

1. 설치

npm install

2. 개발 모드

npm run dev

3. 빌드

npm run build

4. 테스트

npm run test:stdio
npm run test:advanced-pyexamine
npm run test:advanced-pyexamine:http

5. 실행 (빌드 후)

npm start

환경 변수

복사하여 .env로 사용:

• ANALYSIS_API_BASE_URL (예: http://localhost:13000/api)
• REQUEST_TIMEOUT_MS
• METRICS_API_BASE_URL (예: http://localhost:14000)
• METRICS_API_KEY (필요 시)
• METRICS_DEFAULT_TEAM_PROJECT_ID
• METRICS_REQUEST_TIMEOUT_MS
• ADVANCED_PYEXAMINE_BIN (기본값: python)
• ADVANCED_PYEXAMINE_ARGS (기본값: -m,advanced_pyexamine)
• ADVANCED_PYEXAMINE_CWD (예: advanced_pyexamine 레포 루트)
• ADVANCED_PYEXAMINE_TIMEOUT_MS
• ADVANCED_PYEXAMINE_MODE (cli 또는 http, 기본값: cli)
• ADVANCED_PYEXAMINE_SERVICE_URL (HTTP mode, 예: http://localhost:18080)
• ADVANCED_PYEXAMINE_SERVICE_TIMEOUT_MS
• ADVANCED_PYEXAMINE_SOURCE_DIR (service 실행 시 advanced_pyexamine 원본 repo 경로)
• ADVANCED_PYEXAMINE_E2E_PROJECT_PATH (실제 service E2E 테스트 대상 Python project path)

제공 도구

Metrics Analysis

• list_metric_analyses: CodeVi metric analysis 이력 목록 조회
• run_metric_analysis: CodeVi metric analysis 실행 및 저장
• get_metric_analysis: 저장된 metric analysis 단건 조회

PyExamine / Code Analysis

• get_latest_pyexamine_result: 최신 PyExamine 결과 조회
• get_pyexamine_result_by_commit: commit hash 기준 PyExamine 결과 조회
• get_high_severity_smells: high severity smell 조회
• get_smells_by_file: 파일 경로 기준 smell 조회

Advanced PyExamine

• analyze_python_smells: Python 프로젝트 smell 결과를 JSON으로 반환
  • ADVANCED_PYEXAMINE_MODE=cli: advanced_pyexamine CLI를 subprocess로 실행
  • ADVANCED_PYEXAMINE_MODE=http: services/advanced-pyexamine HTTP service의 /analyze 호출

CLI mode 예시:

printf '%s\n' '{"id":"py-smell-1","tool":"analyze_python_smells","params":{"projectPath":"/path/to/python/project"}}' \
| ADVANCED_PYEXAMINE_MODE=cli \
  ADVANCED_PYEXAMINE_BIN=python \
  ADVANCED_PYEXAMINE_ARGS=-m,advanced_pyexamine \
  ADVANCED_PYEXAMINE_CWD="/path/to/pyexamine 2" \
  node dist/server.js

HTTP mode 예시:

printf '%s\n' '{"id":"py-smell-5","tool":"analyze_python_smells","params":{"projectPath":"/path/to/python/project","summaryOnly":true}}' \
| ADVANCED_PYEXAMINE_MODE=http \
  ADVANCED_PYEXAMINE_SERVICE_URL=http://localhost:18080 \
  node dist/server.js

HTTP service 실행:

ADVANCED_PYEXAMINE_SOURCE_DIR="/path/to/pyexamine 2" npm run service:advanced-pyexamine

HTTP service Docker 실행:

docker build -t advanced-pyexamine-service:local services/advanced-pyexamine

docker run --rm \
  -p 18080:18080 \
  -e ADVANCED_PYEXAMINE_SOURCE_DIR=/opt/advanced-pyexamine-source \
  -v "/path/to/pyexamine 2:/opt/advanced-pyexamine-source:ro" \
  advanced-pyexamine-service:local

자세한 Docker workflow는 docs/advanced-pyexamine-service-docker.md를 참고합니다.

MCP server와 HTTP service를 Docker Compose로 함께 실행:

printf '%s\n' '{"id":"compose-e2e-1","tool":"analyze_python_smells","params":{"projectPath":"/opt/advanced-pyexamine-source/advanced_pyexamine","only":"long_method,data_clumps","summaryOnly":true}}' \
| ADVANCED_PYEXAMINE_HOST_SOURCE_DIR="/path/to/pyexamine 2" \
  docker compose -f docker-compose.example.yml run --rm -T mcp-server

통합 Compose workflow는 docs/mcp-advanced-pyexamine-compose.md를 참고합니다.

CodeVi backend에서 advanced-pyexamine-service를 호출할 수 있도록 runtime service만 고정 실행:

ADVANCED_PYEXAMINE_HOST_SOURCE_DIR="/path/to/pyexamine 2" \
npm run compose:codevi-runtime:up

이 compose는 advanced-pyexamine-service를 외부 Docker network shared-net에 연결하고, CodeVi backend가 http://advanced-pyexamine-service:18080으로 호출할 수 있게 network alias를 고정합니다.

CodeVi backend에 전달할 분석 경로는 host path가 아니라 container path를 사용합니다.

/opt/advanced-pyexamine-source/advanced_pyexamine

중지:

ADVANCED_PYEXAMINE_HOST_SOURCE_DIR="/path/to/pyexamine 2" \
npm run compose:codevi-runtime:down

자세한 CodeVi runtime workflow는 docs/advanced-pyexamine-codevi-runtime.md를 참고합니다.

실제 HTTP service E2E 검증:

ADVANCED_PYEXAMINE_SERVICE_URL=http://localhost:18080 \
ADVANCED_PYEXAMINE_E2E_PROJECT_PATH="/path/to/python/project" \
npm run test:advanced-pyexamine:service

특정 detector만 실행하려면 only를 전달합니다.

{ "id": "py-smell-2", "tool": "analyze_python_smells", "params": { "projectPath": "/path/to/python/project", "only": "orphan_module,data_clumps" } }

응답이 너무 큰 경우 summaryOnly 또는 limitPerGroup을 사용할 수 있습니다.

{ "id": "py-smell-3", "tool": "analyze_python_smells", "params": { "projectPath": "/path/to/python/project", "summaryOnly": true } }

{ "id": "py-smell-4", "tool": "analyze_python_smells", "params": { "projectPath": "/path/to/python/project", "limitPerGroup": 5 } }

summary는 항상 전체 탐지 결과 기준이며, limitPerGroup은 반환되는 smellGroups만 제한합니다.

test:advanced-pyexamine은 실제 advanced_pyexamine 레포 없이 mock CLI로 summary, summaryOnly, limitPerGroup 응답 처리를 검증합니다. test:advanced-pyexamine:http는 mock HTTP service로 MCP HTTP mode forwarding과 응답 처리를 검증합니다. test:advanced-pyexamine:service는 이미 실행 중인 실제 FastAPI service를 대상으로 /health, /analyze, MCP HTTP mode를 함께 검증합니다.

CodeVi backend 연동 contract는 docs/codevi-smell-analysis-contract.md를 참고합니다.

원본 코드 분리 가이드

• 복사할 파일: code-vi-internal/code-vi-back/src/mcp/codevi-metrics-server.ts
• 옮겨야 할 항목:
  • axios 기반 REST 호출 로직 → src/clients/analysis-client.ts로 이동
  • 도구(tool) 등록 부분 → src/tools/*.ts로 분리
  • 타입 정의(인터페이스)만 src/types/*로 이동
  • stdio transport 또는 MCP SDK 초기화 부분 → src/stdio/stdio-transport.ts
• 제외할 항목:
  • NestJS 모듈/컨트롤러 전체
  • TypeORM 엔티티 / DB 설정
  • Docker/Jenkins 구성
  • 기존 CodeVi 프론트/백엔드 의존성

Cursor / Codex / Claude 실행 예시

• Cursor/Codex 등의 도구에서 이 MCP를 사용할 때는 stdio를 통해 JSON 메시지를 주고받는 방식을 사용합니다.
• 메시지 형식 예:

{ "id": "uuid-1234", "tool": "get_latest_pyexamine_result", "params": { "repo": "owner/repo", "ref": "main" } }

• 응답 형식 예:

{ "id": "uuid-1234", "result": { /* result payload */ } }

향후 작업

• 원본 codevi-metrics-server.ts에서 실제 핸들러 로직을 옮겨 오기
• 오류/타입 재검토, 테스트 케이스 추가
• 필요 시 MCP 공식 SDK(stdio 외)로 transport 전환
• npm 패키지화 및 배포
• CodeVi backend smell analysis contract에 맞춘 저장/API 구현은 별도 backend repo에서 진행