/mcp-toolkit setup — 앱과 AI를 잇는 "전선 연결"#

한마디로#

만들고 있는 Flutter 앱과 Claude(AI)를 서로 대화할 수 있게 전선을 연결하고 콘센트를 꽂는 설치 작업입니다. 이게 끝나야 AI가 앱 화면을 직접 들여다보고, 상태를 바꾸고, 동작을 시켜볼 수 있어요.

누가·언제 쓰나요#

• 새 Flutter 앱이나 작업 환경을 처음 세팅할 때 딱 한 번 돌리는 설치 절차입니다.
• AI가 앱 내부(화면 상태, DB, 화면 이동 등)를 직접 다루는 도구(bloc_*, db_*, nav_* 등)를 쓰고 싶을 때.
• 개발자가 새 프로젝트를 받아 "AI 연동 환경"을 갖추는 초기 준비 단계에서 사용합니다.

무엇을 해주나요#

설치가 끝나면 다음이 갖춰집니다.

• MCP 서버(flutter-mcp-toolkit-server)와 CLI(flutter-mcp-toolkit, 별칭 fmtk) 설치 — AI와 앱을 잇는 중계기 역할
• Claude Code에 mcp_flutter 연결 등록 (화면 캡처 fmt_get_screenshots 포함)
• 앱에 mcp_toolkit과 공용 도구 묶음 dev_tooling 패키지 추가
• lib/main.dart에 연결 초기화 코드 삽입
• cocode 표준 도구 세트가 실제로 연결됐는지 확인 (bloc_dump_state, db_reset, nav_go_named, auth_impersonate 등)

어떻게 쓰나요#

# 1. AI-앱 중계 서버 설치 (pub 패키지가 아닌 공식 install.sh)
curl -fsSL https://raw.githubusercontent.com/Arenukvern/mcp_flutter/main/install.sh | bash

# 2. Claude Code에 연결 등록 (--images: 화면 캡처, --dynamics: 앱 등록 동적 도구 노출)
claude mcp add --transport stdio mcp_flutter -- flutter-mcp-toolkit-server --resources --images --dynamics

# 3. 대상 Flutter 앱에 도구 추가 + main.dart 초기화 코드 자동 생성
flutter-mcp-toolkit codegen-init

# 4. 설치 확인: 앱 실행 후 스모크 테스트와 도구 목록 보기
flutter run --debug
flutter-mcp-toolkit validate-runtime
/mcp-toolkit list-tools

설치할 때 켜고 끌 수 있는 선택 옵션도 있습니다.

--resources    # 리소스(visual://...) 노출 켜기
--images       # 화면 캡처(fmt_get_screenshots) 기능 켜기
--dynamics     # 앱이 런타임에 등록한 동적 도구 노출 켜기
--dumps        # 화면 구조 덤프(fmt_debug_dump_*) 기능 켜기 (무거우니 꼭 필요할 때만)

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

설치는 순서대로 6단계를 거칩니다.

1. 중계 서버 설치 — AI와 앱을 잇는 flutter-mcp-toolkit 바이너리들을 install.sh로 설치합니다.
2. 연결 등록 — Claude Code에 mcp_flutter를 등록해 둘을 연결합니다.
3. 앱에 도구 추가 — codegen-init으로 대상 앱에 mcp_toolkit을 추가하고, 공용 도구 묶음 dev_tooling도 함께 추가합니다.
4. 초기화 코드 삽입 — lib/main.dart에 연결을 켜는 코드를 넣습니다. (디버그 모드에서만 작동)
5. 정상 동작 확인 — 앱을 실행하고 validate-runtime 스모크 테스트와 도구 목록으로 표준 도구들이 다 뜨는지 점검합니다.
6. 전체 연결 점검 — 관련 MCP들이 모두 연결됐는지 한 번에 확인합니다.

curl -fsSL https://raw.githubusercontent.com/Arenukvern/mcp_flutter/main/install.sh | bash

claude mcp add --transport stdio mcp_flutter -- flutter-mcp-toolkit-server --resources --images --dynamics

cd path/to/your/flutter/app
flutter-mcp-toolkit codegen-init   # adds mcp_toolkit + emits the main.dart snippet

flutter pub add dev_tooling --path=../packages/dev_tooling

// lib/main.dart
import 'package:dev_tooling/mcp_entries.dart';
import 'package:flutter/foundation.dart';
import 'package:mcp_toolkit/mcp_toolkit.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  if (kDebugMode) {
    await MCPToolkitBinding.instance.bootstrapFlutter(
      additionalEntries: cocodeMcpEntries, // Set<MCPCallEntry>
      runApp: () => runApp(const App()),
    );
  } else {
    runApp(const App());
  }
}

flutter run --debug
flutter-mcp-toolkit validate-runtime   # one-command runtime smoke test
# In Claude Code:
/mcp-toolkit list-tools

# All three MCPs should be connected
claude mcp list | grep -E  " marionette|mcp_flutter|dart|figma "