MCP 서버 코드베이스 분석기

TypeScript 코드베이스를 분석하고, 코드 상태 문제를 감지하며, 시스템 인시던트를 가져오고, 실행 가능한 수정 계획을 생성하는 프로덕션급 MCP(Model Context Protocol) 서버입니다. 이중 전송(로컬 개발용 STDIO, 클라우드 배포용 SSE)을 지원합니다. ts-morph, Express 및 Zod 유효성 검사를 사용하여 구축되었습니다.

🚀 주요 기능

세 가지 핵심 도구:

1. analyze_codebase_health — TypeScript 저장소를 스캔하여 다음을 확인합니다:

   • 대용량 파일 (리팩토링 후보)

   • 명시적 함수 타입 누락 (약한 타이핑)

   • 순환 참조 (아키텍처 문제)

   • AST 수준 분석을 위해 ts-morph 사용

2. fetch_system_incidents — 구조화된 인시던트 데이터를 반환합니다:

   • 모의 인시던트 데이터 (테스트/데모용으로 적합)

   • 구성 가능한 지연 및 실패 모드

   • LLM 친화적인 JSON 응답

3. generate_remediation_plan — 실행 가능한 수정 계획을 생성합니다:

   • 스택 트레이스를 통한 근본 원인 분석

   • 단계별 수정 절차

   • 코드 제안 및 모범 사례

   • 위험 수준 평가

모든 도구는 LLM이 소비할 수 있도록 설계된 구조화된 성공/오류 봉투(envelope)를 반환합니다.

아키텍처 개요

flowchart LR
    Client[McpClient] --> Runtime[RuntimeSelector]
    Runtime -->|stdio| Stdio[StdioTransportAdapter]
    Runtime -->|sse| Sse[SseTransportAdapter]
    Stdio --> Server[McpServer]
    Sse --> Server
    Server --> Registry[ToolRegistry]
    Registry --> ToolA[analyze_codebase_health]
    Registry --> ToolB[fetch_system_incidents]
    Registry --> ToolC[generate_remediation_plan]

로컬 실행 (STDIO)

1. 의존성 설치:

   • npm install

2. 서버 시작:

   • npm run dev:stdio

3. 서버가 stdin/stdout을 통해 시작되며 로컬 MCP 클라이언트를 사용할 준비가 됩니다.

SSE로 실행 (Express)

1. 환경 설정:

   • TRANSPORT=sse

   • 선택 사항: AUTH_TOKEN=your-secret-token

2. 서버 시작:

   • npm run dev:sse

3. 엔드포인트:

   • SSE 스트림용 GET /events

   • MCP JSON-RPC 메시지용 POST /messages?sessionId=...

Cursor에서 연결

로컬 사용을 위해 Nexus-Core를 stdio MCP 서버로 등록합니다:

• command: node

• args: dist/index.js (빌드 후) 또는 tsx src/index.ts (개발)

• env: TRANSPORT=stdio

호스팅된 사용을 위해 MCP 클라이언트가 SSE 엔드포인트를 사용하도록 구성합니다:

• stream URL: https://<host>/events

• message URL: https://<host>/messages?sessionId=<session-id>

• 토큰 인증이 활성화된 경우 Authorization: Bearer <AUTH_TOKEN>을 추가합니다.

예시 프롬프트

• "내 저장소 분석해줘"

• "인시던트 가져와"

• "이 오류 수정해줘"

환경 변수

지원되는 모든 설정은 .env.example을 참조하세요. 중요한 제어 항목:

• TRANSPORT: stdio 또는 sse

• TOOL_TIMEOUT_MS: 각 도구 호출에 대한 하드 타임아웃

• TS_MORPH_MAX_FILES, TS_MORPH_MAX_DEPTH: 분석 가드레일

• INCIDENT_API_TIMEOUT_MS, INCIDENT_API_RETRIES: 외부 의존성 제어

• SSE_HEARTBEAT_MS, SSE_SESSION_TTL_MS: SSE 세션 수명 주기

프로덕션 배포

Docker

• 이미지 빌드: docker build -t nexus-core .

• 컨테이너 실행:

  • docker run -e TRANSPORT=sse -e PORT=8080 -p 8080:8080 nexus-core

Cloud Run

deploy.sh를 사용하세요:

PROJECT_ID=<gcp-project> REGION=<region> SERVICE=nexus-core ./deploy.sh

이 스크립트의 기능:

1. 컨테이너 이미지 빌드

2. GCR로 푸시

3. Cloud Run에 배포

신뢰성 및 오류 모델

• 모든 도구 요청은 Zod로 유효성이 검사됩니다.

• 도구 실행 시 처리되지 않은 예외가 반환되지 않습니다.

• 오류는 다음을 포함하는 표준 봉투를 사용합니다:

  • code

  • message

  • retryable

  • suggestedAction

  • meta (requestId, toolName, 타이밍)