퍼즐박스

상태 머신과 에이전트 조정

클라이언트가 구독하고 상태가 변경될 때 업데이트할 수 있는 동적 리소스로 유한 상태 머신을 호스팅하는 MCP 서버 입니다.

퍼즐박스는 어떤 문제를 해결하나요?

팀에는 조정이 필요합니다

여러 에이전트를 하나의 큰 목표를 향해 이끌어내는 일은 요청을 작업으로 나누고, 이를 사용 가능한 에이전트에게 할당하고, 에이전트 간의 협업을 가능하게 하는 것 보다 더 어렵습니다.

몇몇 에이전트가 소규모 프로젝트를 완료하기 위해 협업할 수 있는 것처럼, 프로세스를 인식하는 에이전트로 구성된 여러 팀이 장기적인 노력을 처리하기 위해 서로 다른 프로젝트 단계 내에서 운영되어야 합니다.

기업 수준의 소프트웨어 개발 프로세스를 고려해 보세요.

• 대규모 소프트웨어 프로젝트는 일반적으로 여러 단계를 거치며, 때로는 시작부터 설계, 구축, 테스트, 문서화, 마케팅, 생산까지 후퇴하는 경로를 거칩니다.
• 시간이 지남에 따라 다양한 팀이 서로 다른 측면에 집중하며, 과거의 사건을 통해 정보를 얻고, 배운 교훈에 따라 개선되는 끊임없이 변화하는 목표를 지향합니다.
• 한 단계 내에서도 팀은 애자일 스프린트처럼 자체 단계를 순환할 수 있습니다. 스프린트에는 일정량의 작업 범위가 정해지고, 팀은 각자 맡은 부분을 수행하며, 스프린트가 끝나면 다음 단계를 결정합니다. 각 스프린트가 향후 개발 방향을 바꿀 수 있다는 점을 인정하는 것입니다. 이러한 주기는 퍼즐처럼 표현될 수도 있습니다.

퍼즐박스를 사용하면 에이전트 팀 구성원이 프로세스를 인식할 수 있지만 프로세스 자체는 환각의 대상이 되지 않습니다.

시나리오: 횃불을 전달하는 팀

세 명의 요원이 작업 중입니다. 그들이 공유하는 퍼즐의 현재 상태는 "사양"입니다.

• 에이전트 1은 도메인 언어를 지정합니다.
• 에이전트 2는 프로젝트 범위를 정의하고 있습니다.
• 에이전트 3이 사양 문서를 작성하고 있습니다.
• 각 대리인은 협력하여 최종 사양 문서를 도출합니다.
• 사양이 완성되면 에이전트 3은 "디자인" 상태로 전환을 시작합니다.
  • 먼저, 사양은 완전성을 위해 종료 가드(즉, LLM 샘플링)에 의해 검사됩니다.
    • 문제가 발견되면 상태 전환이 취소되고 팀은 계속 진행됩니다.
    • 허용 가능한 경우 상태가 "디자인"으로 변경됩니다.
      • "사양" 에이전트가 퍼즐을 모니터링하고 있으며 지금 퇴근해야 합니다.
        • 오랜 (비용이 많이 드는) 맥락이 사양에 압축되어 들어갔습니다.
        • "디자인" 팀은 사양을 리소스로 삼고 자신의 역할에 맞는 새로운 맥락을 고려하여 여기에서 선택합니다.

퍼즐이란 무엇인가요?

당신이 행동할 수 있는 상태가 있는 것

루빅 큐브 퍼즐을 상상해 보세요. 43경(quintillion) 개의 상태가 있는데, 각 상태 사이를 전환하려면 장치의 교차면을 회전시키면 됩니다.

퍼즐의 속성

• "시리즈 컨셉 및 분위기", "세계 구축", "아크 플로팅", "에피소드 계획", "줄거리 혼합", "에피소드 개요", "대본 작성" 등과 같은 유한한 수의 개별 상태입니다.
• 각 상태는 다른 상태로의 전환을 시작하는 여러 개의 동작(0 포함)을 가질 수 있습니다.
• 초기 상태가 있습니다.
• 퍼즐에 대한 작업이 수행된 후에는 현재 상태가 달라질 수 있습니다.
• 전환은 상태 종료 및 진입 가드(예: 클라이언트 샘플링 요청을 통해 LLM에 문의)를 통해 취소될 수 있습니다.

간단한 예

지엑스피1

퍼즐박스란 무엇인가요?

동적 리소스를 공유하는 많은 클라이언트

Puzzlebox는 다음을 위한 MCP 서버 구현입니다.

• 공유된 동적 리소스를 생성하고 모니터링할 수 있는 여러 클라이언트 연결을 지원합니다.
• 퍼즐 인스턴스를 관리합니다
• 다음을 위한 도구를 공개합니다.
  • 퍼즐 추가
  • 상자에 있는 주어진 퍼즐에 대한 상태와 사용 가능한 작업의 스냅샷을 얻습니다.
  • 상자 안의 주어진 퍼즐에 대해 상태 전환을 트리거하는 작업 수행
• 등록된 퍼즐을 리소스로 노출합니다.
  • 클라이언트는 Puzzle Snapshot 리소스 템플릿을 사용하여 ID로 리소스를 가져올 수 있습니다.
  • 리소스 URI는 puzzlebox:/puzzle/{puzzleId} 입니다.
  • 클라이언트는 개별 리소스 URI를 구독/구독 취소할 수 있습니다.

작동 원리

1. 클라이언트는 퍼즐박스 SSE 서버에 연결합니다.
2. 클라이언트는 서버에 퍼즐을 등록합니다.
3. 클라이언트는 퍼즐을 구독하여 상태가 변경될 때 업데이트를 받을 수 있습니다.
4. 클라이언트는 퍼즐에 대한 작업을 수행하며, 이로 인해 상태와 사용 가능한 작업이 변경될 수 있습니다.
5. 퍼즐박스 서버는 시도된 모든 동작이 주어진 퍼즐의 현재 상태에서 유효한지 확인합니다.
6. 동작이 유효하면 대상 상태로의 전환이 시작됩니다.
7. 전환 중에 선택적 출입 경비원이 클라이언트에게 샘플링 요청을 보낼 수 있으며, 그 결과에 따라 전환이 취소될 수 있습니다(이해 관계자의 수락 테스트 참조).
8. 경비원이 지나가면 국가 전환이 완료됩니다.
9. 클라이언트가 리소스 업데이트 알림을 받으면 리소스를 읽거나 get_puzzle_snapshot 도구를 사용하여 현재 상태와 사용 가능한 작업을 가져올 수 있습니다.
10. 클라이언트는 새로운 상태에 따라 UI를 업데이트합니다.

MCP 도구

⚙️ add_puzzle

퍼즐의 새로운 인스턴스를 추가합니다(유한 상태 머신).

• 입력: 없음
• 반환: 부울 success 및 puzzleId 포함된 JSON 객체

⚙️ get_puzzle_snapshot

퍼즐의 스냅샷(현재 상태와 사용 가능한 작업)을 가져옵니다.

• 입력: puzzleId
• 반환: currentState 및 availableActions 배열이 포함된 JSON 객체
• 참고: 리소스 구독을 지원하지 않는 MCP 클라이언트는 이 도구를 폴링하여 상태 변경을 감시할 수 있습니다.

⚙️ perform_action_on_puzzle

퍼즐에 대한 작업을 수행합니다(상태 전환을 시도합니다).

• 입력: puzzleId 및 actionName
• 반환: currentState 및 availableActions 배열이 포함된 JSON 객체

⚙️ count_puzzles

등록된 퍼즐의 개수를 알아보세요

• 입력: 없음
• 반환: 등록된 퍼즐의 현재 count 포함하는 JSON 객체

로컬 설정

종속성 설치

• cd /path/to/puzzlebox/
• npm install

짓다

• npm run build
• /dist/index.js 에 MCP 서버 런타임을 빌드합니다.

시작

• npm run start
• 포트 :3001 에서 엔드포인트 /sse 사용하여 SSE 기반/MCP 서버를 시작합니다.
• INSPECTOR를 실행하기 전에 시작해야 합니다.

검사관

• npm run inspector
• 모델 컨텍스트 프로토콜 검사기를 실행합니다.
• Inspector UI는 http://localhost:5173 에서 사용할 수 있습니다.
• 검사기 UI에서:
  • Transport Type``SSE 로 설정되어 있는지 확인하세요.
  • URLhttp://localhost:3001/sse 로 설정되어 있는지 확인하세요.
  • "연결" 버튼을 클릭하면 퍼즐박스 서버에 연결됩니다.
    • 녹색 표시등 🟢과 "연결됨" 메시지가 표시됩니다.
  • 목록 도구 버튼을 클릭하세요

체재

• npm run format
• 코드에서 prettier 실행되고 서식이 조정됩니다.

타입체크

• npm run typecheck
• 인수를 사용하여 tsc 실행하여 유형 문제를 확인하고 보고합니다.

린트

• npm run lint
• 비파괴적으로 구문 문제를 검사하고 보고하기 위해 eslint 실행합니다.

린트픽스

• npm run lint:fix
• eslint 실행하여 구문 문제를 확인하고 수정합니다.

시험

• npm run test
• 단위 테스트 실행

스크린샷

서버 테스트는 공식 참조 클라이언트인 MCP Inspector를 사용하여 수행되었습니다.

0 - 목록 도구

1 - 퍼즐 추가

2 - 퍼즐 스냅샷 가져오기(초기 상태)

3 - 퍼즐에 대한 작업 수행

4 - 퍼즐 스냅샷 받기(새로운 상태)

5 - 퍼즐에 대한 작업 수행

6 - 퍼즐 스냅샷 받기(또 다른 새로운 상태)

7 - 리소스 목록

8 - 리소스 템플릿

9 - 구독 취소된 리소스

10 - 구독 리소스

11 - 리소스 업데이트 알림