[KT Tech up] 사이버 보안 2기 TEAM 304

팀장: 이윤재 / 팀원: 김태우, 윤지훈, 최민준

Vulnerability Analyzer MCP — API 엔드포인트 정보를 받아 OWASP Top 10 관점의 취약점 점검을 수행하고, 결과 리포트를 반환하는 Model Context Protocol 서버입니다.

저장소: github.com/KTTechUp-Team304/VA_MCP

Cursor·Claude Desktop 등 MCP를 지원하는 에이전트에 연결해 사용합니다.

제공 기능

• 사람용 분석 보고서: reports/{METHOD}_{path}_{시각}.md (저장소 루트)

• 개발·디버깅 산출물: outputs/runs/<run_id>/, outputs/logs/ (DUMP_ARTIFACTS=true 시)

Related MCP server: MCP-QA

요구 사항

• Git

• uv (Python 패키지·실행 관리)

• Python 3.11+

• MCP 클라이언트: Cursor 또는 Claude Desktop

git --version
uv --version
python3 --version

설치

git clone https://github.com/KTTechUp-Team304/VA_MCP.git
cd VA_MCP
uv sync
uv tool install .

• uv tool install . → ~/.local/bin/va-mcp CLI 등록 (which va-mcp로 확인)

• ~/.local/bin이 PATH에 없으면 셸 설정에 추가한 뒤 MCP 클라이언트를 재시작하세요.

MCP 클라이언트 연동

Cursor

이 저장소에 .cursor/mcp.json이 포함되어 있습니다.

1. Cursor에서 VA-MCP 폴더를 엽니다.

2. Settings → MCP에서 va-mcp 서버가 활성화되어 있는지 확인합니다.

다른 프로젝트(예: broken_regist_frontend)만 연 상태에서 쓰려면, 위 설치 후 전역 ~/.cursor/mcp.json에 동일 설정을 넣거나, 워크스페이스에 VA-MCP 폴더를 추가합니다.

{
  "mcpServers": {
    "va-mcp": {
      "command": "va-mcp"
    }
  }
}

Claude Desktop

macOS 기준 설정 파일: ~/Library/Application Support/Claude/claude_desktop_config.json

mcpServers 블록에 위와 동일하게 추가한 뒤 Claude Desktop을 완전히 종료 후 재실행합니다.

사용 방법

1) 연결 확인

에이전트 채팅에서 MCP 도구 ping을 호출해 응답이 오는지 확인합니다.

2) 엔드포인트 점검 (analyze_endpoint)

점검할 API의 메서드·경로·베이스 URL·(선택) 인증·요청/응답 예시를 전달합니다. 에이전트가 analyze_endpoint 도구를 호출하면 내부적으로 프로필 파싱 → 기능 추출 → 시나리오 계획 → 점검 실행이 이어집니다.

입력 스키마 상세: docs/endpointProfile.md

예시 (개념)

{
  "base_url": "http://localhost:4000",
  "method": "GET",
  "path": "/api/enrollments/me",
  "auth_required": true,
  "headers": { "Authorization": "Bearer <access_token>" }
}

• status: "analyzed" — 점검 완료

• status: "need_more_context" — missing 필드를 보완한 뒤 다시 호출

3) 결과 확인

결과는 두 갈래로 제공됩니다.

A. MCP 응답 (에이전트 → 대화창)

analyze_endpoint가 반환하는 JSON을 Cursor 에이전트가 읽고 채팅으로 요약합니다. 파일을 열지 않아도 동작합니다.

B. 사람용 분석 보고서 (reports/)

저장소 루트의 reports/ 폴더에 Markdown·JSON이 저장됩니다. IDE에서 직접 열어 보거나 팀과 공유할 때 사용합니다.

예: reports/GET_api_admin_2026-05-20T05-42-56_9ddf04.md

MCP 연결 문제는 Cursor Output → MCP Logs, 서버 내부 로그는 outputs/logs/va-mcp.log를 참고하세요.

업데이트

cd VA_MCP
git pull
uv sync
uv tool install --reinstall .

이후 MCP 클라이언트를 재시작합니다.

환경 변수 (선택)

프로젝트 루트 .env 또는 MCP 설정의 env 블록으로 지정할 수 있습니다.

문제 해결

관련 프로젝트

취약점 학습용 수강신청 웹서버와 함께 사용할 수 있습니다. 같은 상위 폴더에 clone한 경우:

• ../broken_regist_backend — NestJS API (기본 http://localhost:4000)

• ../broken_regist_frontend — Next.js UI

개발자용 문서

기능 개발·브랜치 전략·테스트 작성 규칙은 팀 내부 문서를 참고하세요.

• docs/dev_docs/DEV_GUIDE.md — 개발 워크플로우

• docs/dev_docs/OBSERVABILITY.md — 로그·산출물 디버깅

• docs/architecture/ — 아키텍처·구현 가이드

제한 사항

• 현재 배포 형태는 로컬 stdio MCP입니다. Cursor/Claude가 자식 프로세스로 va-mcp를 실행합니다.

• 원격 HTTP MCP·다중 사용자 호스팅은 추후 별도 배포 단계에서 검토 예정입니다.