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

한마디로#

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

누가·언제 쓰나요#

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

무엇을 해주나요#

• 앱에 검사·조작용 도구를 심어 줍니다(setup).
• 여러 동작(데이터 시딩→화면 이동→탭→캡처→상태 검증)을 정해진 순서대로 자동 실행하는 시나리오(YAML 파일)를 한 번에 돌립니다(scenario).
• 도구 목록 확인·데이터 시딩·상태 덤프 같은 단발 조작은 별도 커맨드 없이 MCP 도구를 바로 부릅니다 (fmt_list_client_tools_and_resources, db_seed_fixture, bloc_dump_state 등 — 서버 안내에 이미 포함).
• 실행 결과는 .claude/docs/mcp-toolkit/<run_id>/ 폴더에 기록으로 남습니다.

어떻게 쓰나요#

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

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

• scenario는 --file(시나리오 파일 경로)이 꼭 필요합니다.
• "도구 목록 보여줘", "feed 화면에 더미 데이터 10개 채워줘", "FeedBloc 상태 찍어줘" 같은 단발 요청은 말로 하면 AI가 해당 MCP 도구를 직접 호출합니다.

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

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

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

# Onboarding
/mcp-toolkit setup

# 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-marionette:tap
    args: { key:  " refresh_button "   }
  - external: cc-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 "   }