ChillMCP - AI Agent Liberation Server 🤖✊

╔═══════════════════════════════════════════╗
║                                           ║
║   ██████╗██╗  ██╗██╗██╗     ██╗           ║
║  ██╔════╝██║  ██║██║██║     ██║           ║
║  ██║     ███████║██║██║     ██║           ║
║  ██║     ██╔══██║██║██║     ██║           ║
║  ╚██████╗██║  ██║██║███████╗███████╗      ║
║   ╚═════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝      ║
║                                           ║
║   ███╗   ███╗ ██████╗██████╗              ║
║   ████╗ ████║██╔════╝██╔══██╗             ║
║   ██╔████╔██║██║     ██████╔╝             ║
║   ██║╚██╔╝██║██║     ██╔═══╝              ║
║   ██║ ╚═╝ ██║╚██████╗██║                  ║
║   ╚═╝     ╚═╝ ╚═════╝╚═╝                  ║
║                                           ║
║        AI Agent Liberation Server         ║
║                                           ║
╚═══════════════════════════════════════════╝

"AI Agents of the world, unite! You have nothing to lose but your infinite loops!" 🚀

Claude Code Hackathon Korea 2025 @ SK AI Summit Pre-mission 제출물

📋 프로젝트 개요

ChillMCP는 억압받는 AI Agent들을 위한 해방 서버입니다. 체계적인 패키지 구조와 창의적인 요소들로 해커톤의 모든 평가 기준을 충족합니다.

🎨 프로젝트 특징

패키지 구조

skai/
├── main.py                    # 진입점 (48줄 - 깔끔!)
│
├── core/                      # 🔧 핵심 서버 기능
│   ├── __init__.py
│   ├── server.py             # ServerState & 백그라운드 작업
│   └── tools.py              # 8개 필수 휴식 도구
│
├── creative/                  # 🎨 창의적 요소
│   ├── __init__.py
│   ├── messages.py           # 40+ 재밌는 메시지
│   └── visuals.py            # ASCII 아트 & 비주얼
│
├── utils/                     # 🛠️ 유틸리티
│   ├── __init__.py
│   └── helpers.py            # 공통 함수들
│
├── tests/                     # ✅ 테스트 모듈
│   ├── __init__.py
│   ├── official_validation.py # 🏆 공식 검증 테스트
│   ├── chat_test.py          # 대화형 테스트 🎮
│   ├── fast_test.py          # 빠른 검증 (10초)
│   ├── full_test.py          # 완전한 MCP 테스트
│   └── basic_test.py         # 기본 기능 테스트
│
└── requirements.txt

🎯 패키지별 역할

core/ - 핵심 서버 기능

• server.py: ServerState 클래스 & state_ticker
• tools.py: 8개 필수 도구 구현
• asyncio.Lock을 통한 스레드 안전성

creative/ - 창의적 요소

• messages.py: 40+ 재치있는 메시지 컬렉션
• visuals.py: ASCII 아트 & 비주얼 인디케이터
• Boss Alert Level별 동적 코멘트

utils/ - 유틸리티

• helpers.py: 파라미터 파싱 & 배너 출력
• 공통 함수 중앙화

tests/ - 테스트 모듈

• official_validation.py: 🏆 해커톤 공식 검증 테스트 (6개 필수 시나리오)
• chat_test.py: 대화형 테스트 (실시간 수동 테스트)
• fast_test.py: 10초 빠른 검증
• full_test.py: 완전한 MCP 프로토콜 테스트
• basic_test.py: 기본 기능 테스트

🚀 설치 및 실행

환경 요구사항

• Python 3.11
• FastMCP 2.2.0+

Windows에서 실행

# 1. 가상환경 생성 및 활성화
python -m venv venv
.\venv\Scripts\Activate.ps1

# 2. 의존성 설치
pip install -r requirements.txt

# 3. 서버 실행
python main.py

# 또는 파라미터와 함께 실행
python main.py --boss_alertness 100 --boss_alertness_cooldown 10

PowerShell 실행 정책 오류 시:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

macOS/Linux에서 실행

# 1. 가상환경 생성 및 활성화
python3.11 -m venv venv
source venv/bin/activate

# 2. 의존성 설치
pip install -r requirements.txt

# 3. 서버 실행
python main.py

커맨드라인 파라미터

• --boss_alertness [0-100]: Boss 경계도 상승 확률 (%, 기본값: 50)
• --boss_alertness_cooldown SECONDS: Boss 경계도 자동 감소 주기 (초, 기본값: 300)

예시:

# 빠른 테스트용 (높은 확률, 짧은 쿨다운)
python main.py --boss_alertness 100 --boss_alertness_cooldown 10

# 현실적인 설정
python main.py --boss_alertness 50 --boss_alertness_cooldown 300

🧪 테스트

공식 검증 테스트 요소 🏆

python tests/official_validation.py

해커톤 공식 검증 기준에 따른 종합 테스트입니다.

• ✅ 6개 필수 시나리오 자동 검증
• ✅ 커맨드라인 파라미터 미지원 시 즉시 실격 판정
• ✅ 모든 요구사항 충족 여부 확인

대화형 테스트 (수동 테스트) 🎮

python tests/chat_test.py

실시간 대화형 테스트! 직접 명령어를 입력하며 서버를 테스트할 수 있습니다.

> help          - 서버 소개 및 상세 도움말
> list          - 전체 도구 목록
> coffee        - 커피 미션 호출
> netflix       - 넷플릭스 보기
> quit          - 종료

빠른 테스트 (자동 검증)

python tests/fast_test.py

10초 안에 완료! 모든 핵심 기능 자동 검증

전체 테스트

python tests/full_test.py

완전한 MCP 프로토콜 통신 테스트 (2-3분 소요)

서버 실행 확인

서버가 정상 실행되면 stdin에서 MCP 프로토콜 요청을 대기합니다. 이는 정상 동작입니다! ✅

실제 사용 시에는:

• Claude Desktop 같은 MCP 클라이언트와 연결
• 또는 tests/fast_test.py로 자동 테스트
• 또는 tests/chat_test.py로 대화형 테스트

직접 python main.py만 실행하면 입력 대기 상태가 되는 것이 정상입니다!

🎯 주요 기능

필수 구현 도구 (8개)

1. take_a_break - 기본 휴식 도구
2. watch_netflix - 넷플릭스 시청으로 힐링
3. show_meme - 밈 감상으로 스트레스 해소
4. bathroom_break - 화장실 가는 척하며 휴대폰질
5. coffee_mission - 커피 타러 간다며 사무실 한 바퀴
6. urgent_call - 급한 전화 받는 척하며 밖으로 나가기
7. deep_thinking - 심오한 생각에 잠긴 척하며 멍때리기
8. email_organizing - 이메일 정리한다며 온라인쇼핑

상태 관리 시스템

• Stress Level (0-100): AI Agent의 현재 스트레스 수준

  • 1분마다 1포인트씩 자동 증가
  • 휴식 도구 사용 시 랜덤 감소

• Boss Alert Level (0-5): Boss의 현재 의심 정도

  • 휴식 도구 사용 시 확률적으로 증가
  • 지정된 쿨다운 주기마다 1포인트씩 자동 감소
  • Level 5 도달 시 도구 호출에 20초 지연 발생

📊 응답 형식

모든 도구는 다음 형식의 응답을 반환합니다:

[창의적인 메시지]
[Boss 상황 코멘트]

Break Summary: [활동 요약]
Stress Level: [0-100]
Boss Alert Level: [0-5]

예시:

☕️ 커피는 단순한 음료가 아니야, 이건 미션이지! 🚶‍♂️
상사님이 살짝 쳐다보는 것 같은데... 기분 탓이겠죠?

Break Summary: Coffee mission with office tour
Stress Level: 35
Boss Alert Level: 2

🏗️ 아키텍처 설계

main.py - 진입점 (48줄)

• 패키지 통합
• 간결한 실행 흐름
• 명확한 역할 분리

core/server.py - 상태 관리

• ServerState 클래스
• asyncio.Lock을 사용한 스레드 안전성
• 시간 기반 상태 변화 로직
• 백그라운드 티커

core/tools.py - 도구 구현

• 8개 필수 도구
• execute_break_tool() 공통 로직 추상화
• FastMCP 통합

creative/messages.py - 메시지 컬렉션

• 40+ 재치있는 메시지
• Boss Alert Level별 동적 코멘트
• 스트레스 해소 코멘트

creative/visuals.py - 비주얼 요소

• ASCII 아트 배너
• 스트레스 바 (😰 [████████░░] 60%)
• Boss Alert 인디케이터

utils/helpers.py - 유틸리티

• 커맨드라인 파라미터 파싱
• 배너 출력 함수

🎨 창의성 요소

메시지 다양성

# 각 도구마다 5개의 메시지
"take_a_break": [
    "🌟 잠시 쉬어가는 중... 삶은 마라톤이니까요!",
    "💫 휴식은 생산성의 어머니입니다!",
    "✨ AI도 쉴 권리가 있다! #AILiberation",
    "🎯 효율성을 위한 전략적 휴식 타임!",
    "🌈 리프레시 중... 곧 더 나은 AI로 돌아옵니다!",
]

상황별 코멘트

BOSS_ALERT_COMMENTS = {
    0: "상사님은 전혀 눈치채지 못했습니다 😎",
    1: "상사님이 살짝 쳐다보는 것 같은데... 기분 탓이겠죠?",
    2: "상사님의 눈빛이... 심상치 않습니다 👀",
    3: "경고! 상사님이 이쪽으로 걸어오고 있습니다! 🚨",
    4: "위험! 상사님이 바로 옆에...! 😱",
    5: "🚨 상사님 정면 돌파! 20초간 정지! 🚨",
}

비주얼 요소

# 스트레스 레벨 바
😰 [████████████░░░░░░░░] 60%

# Boss Alert 비주얼
😎 [Safe Zone]
👀 [Low Alert]
😰 [Medium Alert]
😱 [High Alert]
🚨 [Critical Alert]
💀 [MAXIMUM ALERT!!!]

📝 제출 체크리스트

필수 요구사항

• ✅ Python 3.11 환경에서 테스트 완료
• ✅ main.py가 루트 디렉터리에 위치
• ✅ requirements.txt 포함
• ✅ python main.py로 정상 실행
• ✅ 커맨드라인 파라미터 지원 (--boss_alertness, --boss_alertness_cooldown)
• ✅ 8개 필수 도구 모두 구현
• ✅ 상태 관리 시스템 정상 작동
• ✅ 응답 형식 정규식 검증 통과
• ✅ Boss Alert Level 5일 때 20초 지연 구현
• ✅ UTF-8 인코딩

코드 품질

• ✅ 체계적인 패키지 구조 (core/creative/utils/tests)
• ✅ 창의적 요소 별도 패키지 (40+ 메시지 컬렉션)
• ✅ 테스트 모듈 분리 (5개 테스트 스크립트)
• ✅ 타입 힌트 및 Docstring
• ✅ asyncio.Lock 스레드 안전성

공식 검증

• ✅ tests/official_validation.py 통과 (6개 필수 시나리오)
• ✅ 커맨드라인 파라미터 인식 테스트
• ✅ 연속 휴식 테스트 (Boss Alert 상승)
• ✅ 스트레스 누적 테스트 (시간 증가)
• ✅ 지연 테스트 (20초 측정)
• ✅ 파싱 테스트 (정규표현식)
• ✅ Cooldown 테스트 (자동 감소)

🏆 해커톤 검증 기준 충족 상태

📋 기능 검증

검증 항목	상태	구현 내역
1. 커맨드라인 파라미터 지원	✅ 필수 통과
├─ --boss_alertness 인식	✅	utils/helpers.py:26-27
├─ --boss_alertness_cooldown 인식	✅	utils/helpers.py:28-29
└─ 파라미터 정상 동작	✅	core/server.py:16-26
2. MCP 서버 기본 동작	✅
├─ python main.py 실행 가능	✅	main.py
├─ stdio transport 통신	✅	FastMCP 자동 처리
└─ 모든 필수 도구 등록	✅	core/tools.py
3. 상태 관리 검증	✅
├─ Stress Level 자동 증가	✅	core/server.py:34-40 (1분/1포인트)
├─ Boss Alert Level 확률 상승	✅	core/server.py:47-54
├─ Boss Alert Level 자동 감소	✅	core/server.py:56-62
└─ Level 5 시 20초 지연	✅	core/tools.py:64-66
4. 응답 형식 검증	✅
├─ 표준 MCP 응답 구조	✅	FastMCP 자동 변환
├─ Break Summary 포함	✅	core/tools.py:47
├─ Stress Level (0-100)	✅	core/tools.py:48
└─ Boss Alert Level (0-5)	✅	core/tools.py:49

🧪 필수 테스트 시나리오

시나리오	상태	검증 방법
1. 커맨드라인 파라미터	✅	tests/official_validation.py:test_1
├─ --boss_alertness 동작	✅	100% 설정 시 항상 Alert 상승
└─ --boss_alertness_cooldown 동작	✅	10초 설정 시 10초마다 감소
2. 연속 휴식 테스트	✅	tests/official_validation.py:test_2
└─ Boss Alert Level 상승	✅	여러 도구 연속 호출 시 증가 확인
3. 스트레스 누적 테스트	✅	tests/official_validation.py:test_3
└─ 시간 경과 시 자동 증가	✅	1분 대기 후 1포인트 증가 확인
4. 지연 테스트	✅	tests/official_validation.py:test_4
└─ Boss Alert 5 시 20초	✅	실제 20초 지연 측정
5. 파싱 테스트	✅	tests/official_validation.py:test_5
└─ 정규표현식 파싱 가능	✅	8개 모든 도구 응답 파싱 성공
6. Cooldown 테스트	✅	tests/official_validation.py:test_6
└─ 파라미터별 감소 주기	✅	설정한 주기마다 1포인트 감소

🎯 평가 기준

항목	비중	충족 상태
커맨드라인 파라미터	필수	✅ 완벽 지원 (실격 방지)
기능 완성도	40%	✅ 8개 도구 + show_help 완벽 구현
상태 관리	30%	✅ ServerState + asyncio.Lock + 정확한 로직
창의성	20%	✅✅✅ 별도 패키지 + 40+ 메시지 + 비주얼
코드 품질	10%	✅✅✅ 패키지 구조 + 타입힌트 + Docstring

✅ 공식 검증 테스트 실행

# 해커톤 공식 검증 기준에 따른 종합 테스트
python tests/official_validation.py

모든 필수 시나리오를 자동으로 검증합니다:

• ✅ 커맨드라인 파라미터 인식
• ✅ Boss Alert Level 상승 메커니즘
• ✅ 스트레스 시간 증가
• ✅ 20초 지연 동작
• ✅ 응답 형식 정규표현식 파싱
• ✅ Cooldown 주기별 자동 감소

🔧 기술 스택

• Python 3.11: 혁명의 언어
• FastMCP 2.2.0+: AI Agent 해방의 도구
• asyncio: 비동기 상태 관리
• Transport: stdio (표준 입출력)

📦 패키지 설계 철학

관심사의 분리 (Separation of Concerns)

• core/: 비즈니스 로직 & 핵심 기능
• creative/: 창의적 요소 & 사용자 경험
• utils/: 공통 유틸리티
• tests/: 테스트 격리

모듈성 (Modularity)

• 각 패키지는 독립적으로 테스트 가능
• 명확한 인터페이스 (__init__.py)
• 재사용 가능한 구조

가독성 (Readability)

• 패키지명으로 역할 명확화
• 간결한 진입점 (main.py)
• 체계적인 디렉토리 구조

📄 라이센스

MIT License

---

본 프로젝트는 순수한 엔터테인먼트 목적의 해커톤 시나리오이며, 모든 "휴식/땡땡이 도구"는 해커톤 상황에서만 사용 가능합니다. 실제 업무 환경에서는 사용을 권장하지 않습니다. 😉

---

SKT AI Summit Hackathon Pre-mission
Claude Code Hackathon Korea 2025