🩺 Server Doctor: Spring Boot Server Diagnosis MCP

LLM을 통한 안전하고 간편한 Spring Boot 서버 진단 및 모니터링 도구 "복잡한 설정(Datadog, Prometheus) 없이, docker-compose, application.yml, .env 설정을 통해 내 서버의 상태를 LLM에게 물어보세요."

🎉 카카오 PlayMCP 공식 승인 · 배포 완료

자세한 설명 블로그

Spring 서버 진단 MCP 개발

📖 프로젝트 소개 (Overview)

Server Doctor는 MCP(Model Context Protocol) 를 활용하여, LLM(ChatGPT, Claude 등)이 개발자의 로컬 또는 배포된 Spring Boot 서버의 상태(Health)와 에러 로그(Logs) 를 실시간으로 분석하고 진단해주는 도구입니다.

기존 모니터링 도구(Datadog, ELK)의 높은 비용과 복잡한 설정 문제를 해결하기 위해, 초기 스타트업 및 사이드 프로젝트에 최적화된 MVP 형태의 진단 솔루션을 개발했습니다.

• 기존: 서버 접속 → 로그 조회 → 복사 → LLM 프롬프트 입력
• 개선: LLM 진단 요청 → MCP Tool 자동 호출 → 분석 결과 반환

🎯 핵심 목표

• Zero-Config: docker-compose.yml, application.yml, .env 파일 수정으로 즉시 적용 가능.
• Security First: 외부 포트 노출 없이, Sidecar Pattern을 통해 내부망에서 안전하게 데이터를 수집.
• AI Diagnosis: 단순 로그 수집을 넘어, LLM이 문맥을 파악하여 에러 원인을 설명.

시연

서버를 직접 등록하기 전에 데모서버를 시연하며 어떤 MCP인지 테스트 가능합니다.

1. 데모 서버의 상태를 확인

   

2. 에러 여부 확인

   

3. 에러 분석

   

사용자 서버 등록 과정

1. Application.yml

logging:
  file:
    name: /app/logs/application.log

management:
  server:
    port: 9090
  endpoints:
    web:
      exposure:
        include: "health,metrics"
  endpoint:
    health:
      show-details: always

2. build.gradle 의존성 추가

implementation 'org.springframework.boot:spring-boot-starter-actuator'

3. .env 추가

SERVER_NAME=test003
INGEST_TOKEN=c13600a7-0f90-4373-879a-b62c3d1389da // 서버 등록 시 생성되는 Token
MCP_DOMAIN=http://168.107.53.175
FORWARDER_IMAGE=ghcr.io/takch02/mcp-forwarder:latest

4. docker-compose.yml 추가

services:
  target:
    container_name: my-app-target
    image: my-app-image:latest
    volumes:
      - logs:/app/logs
    ports:
      - "8080:8080"

  forwarder:
    image: ${FORWARDER_IMAGE}
    container_name: mcp-forwarder
    depends_on: [target]
    volumes:
      - logs:/logs:ro
    environment:
      MCP_LOG_INGEST_URL: "${MCP_DOMAIN}/api/servers/${SERVER_NAME}/ingest/logs"
      MCP_METRIC_INGEST_URL: "${MCP_DOMAIN}/api/servers/${SERVER_NAME}/ingest/metrics"
      MCP_HEALTH_INGEST_URL: "${MCP_DOMAIN}/api/servers/${SERVER_NAME}/ingest/health"
      HEALTH_URL: "http://target:9090/actuator/health"
      MCP_TOKEN: "${INGEST_TOKEN}"
      LOG_PATH: "/logs/application.log"
      ACTUATOR_URL: "http://target:9090/actuator/metrics"
    restart: unless-stopped

volumes:
  logs:

🏗️ 아키텍처 (Architecture)

본 프로젝트는 보안과 확장성을 위해 사이드카 패턴(Sidecar Pattern) 을 채택했습니다.

🤔 설계 결정: 왜 Pull이 아닌 Push인가? (Pull → Push 전환)

• 기존 Pull 방식의 한계: 수집 서버가 대상 서버의 Actuator 포트(9090)를 외부에서 직접 호출해야 해 외부 포트 개방이 필수였습니다. 구현은 단순하지만 모니터링 포트가 외부에 노출되는 보안 위험이 컸습니다.
• Push 방식으로 전환: 구조 복잡도를 감수하고, 사용자 서버 내부에 Forwarder를 Sidecar로 배치해 수집을 내부에서 수행하고 결과만 Push하도록 변경. 이를 통해 모니터링 목적의 외부 접근 포트를 제거(앱 서비스 포트는 별개 유지)하고, 설정 파일만으로 기존 서버와 독립적인 로그 수집 구조를 확보했습니다.

🔄 작동 원리 (Forwarder System)

1. User Target (Spring Boot): 사용자의 애플리케이션입니다. 로그 파일만 생성하며 외부로 데이터를 보내지 않습니다.
2. **Forwarder (Sidecar

... View full README on GitHub