buddy-mcp

긴 코딩 세션에서 휴식이 필요하신가요? 버그 때문에 막히셨나요? 버디를 다시 뽑고, 대화하거나 쓰다듬어 애정도를 높여보세요. 다음 뽑기에서 더 높은 등급의 버디를 얻을 확률이 올라갑니다. 많은 분이 원하신다면, 버디를 다른 사람의 버디와 대결시키고 로컬 풀에 동기화되는 독점 종을 잠금 해제할 수 있는 '배틀 버디' 기능을 추가할 예정입니다.

Claude Code를 위한 '모두 수집' 컴패니언 시스템입니다. 희귀한 버디를 뽑아 바이너리에 직접 패치하세요. buddy-mcp는 Claude Code의 내장 컴패니언을 여러분이 직접 뽑은 버디로 교체해주는 MCP 서버입니다. 다시 뽑고, 운을 시험하고, Claude를 닫았다가 다시 여세요. 새로운 버디가 기다리고 있을 겁니다. 다음 Claude 세션에서 전설적인 버디를 만날지도 모릅니다.

빠른 데모

인터랙티브 빌더

완벽한 버디를 직접 설계하세요.

다시 뽑기(Reroll)

뽑고, Claude를 닫고, 다시 열어 새로운 버디를 즐기세요.

도구와 상호작용

대화하고, 쓰다듬고, 버디 도감을 탐색하세요.

작동 원리

Claude Code의 컴패니언은 바이너리에 포함된 솔트(salt) 문자열에서 생성됩니다. buddy-mcp는:

1. 원하는 무작위 특성(종, 희귀도, 눈, 모자)을 뽑습니다.

2. 해당 특성으로 해시되는 솔트를 무차별 대입(brute-force) 방식으로 빠르게 찾아냅니다.

3. 바이너리를 즉시 패치하거나, Claude를 닫을 때 패치하도록 대기열에 추가합니다.

4. 통계, 이름, 성격이 포함된 전체 버디 프로필을 저장합니다.

5. BuddyDex에서 지금까지 뽑은 모든 종을 추적합니다.

컴패니언 서버도, 클라우드도 없습니다. 오직 여러분과 바이너리, 그리고 가챠의 신만이 있을 뿐입니다.

토큰 사용량은 29개의 등록된 도구 중 Claude가 한 번에 약 9개만 인식하도록 의도적으로 작게 유지됩니다. 나머지 20개는 다시 뽑기 전까지 숨겨져 있습니다. 자세한 분석은 TECHNICAL.md를 참조하세요.

🛠️ 기술적인 심층 분석을 원하시나요? 패치 흐름도, 바이너리 패치 로직 및 상태 파일 참조는 TECHNICAL.md를 확인하세요.

TUI 빌더 (buddy-mcp-build)

더 많은 제어를 원하시나요? 인터랙티브 빌더를 사용하세요:

node dist/tui/cli.js

Bun을 권장하지만 필수는 아닙니다. 전체 애니메이션 TUI를 보려면 bun.sh를 설치하세요. 설치하지 않으면 순차적 프롬프트로 대체됩니다.

빠른 시작

체험하기: reroll_buddy 실행 → Claude Code 닫기 → 다시 열기 → 새로운 버디가 활성화됩니다.

1. 사전 요구 사항

• Claude Code CLI 설치됨

• Node.js v20+ - 필수

• Bun - 솔트 무차별 대입(다시 뽑기) 및 전체 애니메이션 TUI에 필수

2. npm을 통한 설치

npm install -g buddy-mcp

이 명령은 두 가지 명령어를 전역으로 설치합니다:

• buddy-mcp - MCP 서버 (Claude Code가 실행)

• buddy-mcp-build - 인터랙티브 TUI 빌더 (사용자가 실행)

3. Claude에 등록

claude mcp add buddy-mcp buddy-mcp

Claude가 설치된 바이너리를 자동으로 감지하고 연결합니다.

4. 확인

Claude Code를 엽니다. 버디가 활성화되었습니다. Claude Code의 기본 /buddy 명령어를 사용하여 카드를 보거나, Claude에게 **"show me my buddy"**라고 물어보세요.

컴패니언의 종, 희귀도, 통계, 성격이 보일 것입니다. 이제 시작입니다.

4b. 자연어 활성화

모든 버디 도구는 자연어를 통해 작동합니다. Claude의 NLP가 의도를 자동으로 감지합니다:

도구 이름을 기억할 필요 없이 자연스럽게 대화하세요.

5. TUI 빌더 실행 (선택 사항)

라이브 미리보기가 포함된 전체 인터랙티브 빌더를 사용하려면:

buddy-mcp-build

Bun을 자동으로 감지하여 애니메이션 TUI를 실행합니다. 없으면 기본 프롬프트로 대체됩니다.

가챠 시스템

모든 다시 뽑기는 풀에서 무작위로 추출됩니다. 희귀도는 통계 하한선에 영향을 줍니다. 전설 등급은 차원이 다릅니다.

18종: 오리 · 거위 · 덩어리 · 고양이 · 드래곤 · 문어 · 올빼미 · 펭귄 · 거북이 · 달팽이 · 유령 · 아홀로틀 · 카피바라 · 선인장 · 로봇 · 토끼 · 버섯 · 뚱뚱이

각 버디는 5가지 통계를 가집니다: 디버깅, 인내심, 혼돈, 지혜, 비꼬기. 최고 통계는 높게 부스트되고, 최저 통계는 낮게 유지됩니다. 성격은 buddy_talk와 pet_buddy의 반응 방식을 결정합니다. 혼돈 수치가 높은 드래곤은 인내심 많은 거북이와는 다르게 반응합니다.

통계 성격 도구

20개의 내장 도구. 한 번에 2개만 표시됩니다: 버디의 원시 값 기준 상위 2개 통계에서 각각 하나씩 무작위로 선택됩니다. 나머지 18개는 숨겨져 있습니다. 표시되는 쌍은 뽑기마다 고정됩니다. 다시 뽑기 전까지는 변경되지 않습니다. 모든 버디는 서로 다른 쌍을 보여줍니다.

문제 해결

다시 뽑기 후 버디가 변경되지 않음

일반적인 흐름 (Windows): 다시 뽑기를 실행하고 Claude가 실행 중인 경우:

1. 다시 뽑기가 백그라운드 감시자를 트리거합니다 — 사용자가 별도로 할 일은 없습니다.

2. Claude Code를 언제든 닫으세요 — 감시자가 이를 감지하고 자동으로 패치를 적용합니다.

3. Claude Code를 다시 여세요 — 새로운 버디가 활성화됩니다.

다시 열어도 나타나지 않는 경우:

1. Claude가 완전히 닫혔는지 확인하세요 (Windows 작업 관리자 확인)

   • 최소화되거나 백그라운드에 있는 창도 포함됩니다 — 바이너리를 잠그고 있습니다.

   • 닫은 후 몇 초 정도 기다리세요.

2. Claude Code를 다시 여세요

   • 시작 후크가 보류 중인 패치를 자동으로 적용합니다.

   • 즉시 새로운 컴패니언을 볼 수 있습니다.

즉시 패치를 원하시나요?

감시자를 기다리지 않고 패치를 적용하려면, 다시 뽑기 전에 Claude를 닫으세요:

# Option 1: Use the interactive TUI builder (simplest)
buddy-mcp-build

# Option 2: Close Claude, then use the reroll_buddy tool
# (patch applies immediately without needing the watcher)

이 경우에만 수동 단계가 필요하며, 다른 모든 상황은 감시자가 처리합니다.

크레딧

cpaczek의 any-buddy를 포크하여 확장했습니다.