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개)

take_a_break - 기본 휴식 도구
watch_netflix - 넷플릭스 시청으로 힐링
show_meme - 밈 감상으로 스트레스 해소
bathroom_break - 화장실 가는 척하며 휴대폰질
coffee_mission - 커피 타러 간다며 사무실 한 바퀴
urgent_call - 급한 전화 받는 척하며 밖으로 나가기
deep_thinking - 심오한 생각에 잠긴 척하며 멍때리기
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