/mcp-toolkit — 앱 속을 직접 조작하는 리모컨#

한마디로#

실행 중인 Flutter 앱의 겉(화면 탭·스크린샷)이 아니라 속(데이터·상태·설정값)을 직접 만지는 리모컨입니다. 연극 무대 뒤에서 소품을 미리 세팅하고 조명 스위치를 직접 켜는 스태프처럼, AI가 앱 내부를 원하는 상태로 바로 바꿔 놓습니다.

누가·언제 쓰나요#

• AI 에이전트가 실행 중인 Flutter 앱의 내부 상태(BLoC, DB, 기능 플래그)를 직접 바꿔야 할 때
• 단순히 버튼을 누르거나 스크린샷을 찍는 것만으로는 재현하기 어려운 상황(예: "데이터가 10개 있는 화면", "네트워크가 끊긴 오류 화면")을 빠르게 만들어 확인하고 싶을 때

무엇을 해주나요#

• 앱에 검사·조작용 도구를 심어 주고(setup), 지금 앱이 어떤 도구를 쓸 수 있는지 목록으로 보여줍니다(list-tools).
• 미리 준비된 더미 데이터를 앱에 채워 넣고 원하는 화면으로 이동시킵니다(seed).
• 특정 상태값(BLoC)이 지금 어떤지 그대로 찍어서 보여줍니다(dump-bloc).
• 여러 동작을 정해진 순서대로 자동 실행하는 시나리오(YAML 파일)를 한 번에 돌립니다(scenario).
• 실행 결과는 .claude/docs/mcp-toolkit/<run_id>/ 폴더에 기록으로 남습니다.

어떻게 쓰나요#

# 처음 한 번: 앱에 도구를 설치·등록
/mcp-toolkit setup

# 지금 앱이 쓸 수 있는 도구 목록 확인
/mcp-toolkit list-tools

# 더미 데이터를 채우고 해당 화면으로 이동
/mcp-toolkit seed --fixture=feed_with_10 --route=feed

# 특정 상태값(FeedBloc)을 그대로 찍어보기
/mcp-toolkit dump-bloc --type=FeedBloc

# 정해진 순서를 담은 시나리오 파일 실행
/mcp-toolkit scenario --file=test/scenarios/feed_offline_error.yaml

• seed는 --fixture(채울 데이터)가 꼭 필요하고, --route(이동할 화면)는 선택입니다.
• dump-bloc는 --type(상태 종류)이 꼭 필요합니다.
• scenario는 --file(시나리오 파일 경로)이 꼭 필요합니다.

안에서 무슨 일이 벌어지나요#

이 명령은 세 개의 층(앱 내부 조작·위젯 트리·실제 화면 캡처)을 한 줄로 엮어 자동으로 굴리는 것이 핵심입니다.

1. 먼저 앱 내부의 데이터를 초기화하고 더미 데이터를 채웁니다.
2. 원하는 화면으로 이동하고, 네트워크를 끊는 등 원하는 조건을 만듭니다.
3. 버튼을 누르거나(marionette) 화면을 캡처(pixel-loop)하는 동작을 순서대로 실행합니다.
4. 마지막에 특정 상태값이 기대한 대로 되었는지(예: "오프라인 오류" 상태인지) 확인합니다.

# Onboarding
/mcp-toolkit setup

# Inspect what ' s registered
/mcp-toolkit list-tools

# Seed and navigate
/mcp-toolkit seed --fixture=feed_with_10 --route=feed

# Dump a BLoC ' s current state
/mcp-toolkit dump-bloc --type=FeedBloc

# Run a YAML scenario
/mcp-toolkit scenario --file=test/scenarios/feed_offline_error.yaml

# test/scenarios/feed_offline_error.yaml
name: feed_offline_error
steps:
  - tool: db.reset
  - tool: db.seed_fixture
    args: { name:  " feed_with_10 "   }
  - tool: nav.go_named
    args: { name:  " feed "   }
  - tool: network.offline
    args: { value: true }
  - external: cc-flutter-marionette:tap
    args: { key:  " refresh_button "   }
  - external: cc-flutter-pixel-loop:capture
    args: { route:  " /feed " , label:  " offline-error "   }
  - tool: network.offline
    args: { value: false }
asserts:
  - tool: bloc.dump_state
    args: { type:  " FeedBloc "   }
    expect: { status:  " offlineError "   }