경로

Windows 예시

macOS 예시

WeChat 개발자 도구 CLI

C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat

/Applications/wechatwebdevtools.app/Contents/MacOS/cli

미니프로그램 프로젝트 루트 디렉터리

D:\MyProjects\mini-app

/Users/<you>/Projects/mini-app

도구

기능

지원 action

wechat_ide

IDE 수명 주기 관리

open login is_login close quit status

wechat_build

빌드 및 배포

compile preview upload build_npm cache_clean

wechat_automator

자동화 상호작용

start tap input element_info set_data call_method call_wx mock_wx evaluate page_stack page_data system_info storage

wechat_inspector

런타임 로그 수집

console cdp

wechat_screenshot

화면 스크린샷(긴 이미지 이어붙이기)

—

wechat_navigate

페이지 이동 및 CDP 로그 수집

—

wechat_file

프로젝트 파일 읽기

project_info list_pages read_page read_file

사용자 발화

AI 실행 프로세스

"모든 페이지에 오류가 있는지 확인해줘"

SOP D — 전체 페이지 순찰

"로그인 버튼을 클릭하고 스크린샷으로 결과를 봐줘"

SOP B — UI 디버깅

"페이지가 하얀 화면인데, 원인을 찾아줘"

SOP C — 이상 원인 조사

"결제 API를 Mock하고 결제 프로세스를 테스트해줘"

SOP E — Mock 통합 테스트

"상세 페이지를 테스트할 건데, 파라미터 이름이 뭐야?"

SOP G — 하위 페이지 테스트

"각 페이지의 포인트가 일치하는지 비교해줘"

SOP I — 페이지 간 데이터 검증

변수명

설명

기본값

필수

WECHAT_DEVTOOLS_CLI

WeChat 개발자 도구 CLI 경로

—

예

WECHAT_PROJECT_PATH

기본 미니프로그램 프로젝트 절대 경로

—

예

WECHAT_CLI_TIMEOUT

CLI 명령 제한 시간(초)

30

아니요

NODE_PATH

Node.js 실행 파일 경로

node

아니요

版本

说明

0.9.15

개발자 도구 2.x(Electron) 적응 + CDP 수집 장기 무효화 수정: 개발자 도구 2.x는 Electron으로 전환(1.06.x Stable은 여전히 NW.js, 이중 트랙 호환, 교체 없음). macOS 시작 경로는 Resources/package.nw 존재 여부로 런타임을 자동 판별하고, 진입점은 Info.plist의 CFBundleExecutable을 읽으며, kill 모드는 .app 패키지 경로를 사용——기존 모드는 Electron 프로세스를 매칭하지 못해 macOS에서 기본 매개변수의 wechat_ide(action='open')이 완전히 사용 불가능했음; 2.x는 더 이상 명령줄 --project를 인식하지 않으므로, 먼저 CDP로 프로세스를 시작한 후 CLI로 프로젝트를 열고, CDP와 IDE 서비스 포트가 모두 준비될 때까지 기다린 후 계속 진행(그렇지 않으면 CLI가 CDP 없는 인스턴스를 별도로 실행하여 '프로젝트는 열렸지만 CDP에 연결할 수 없음'이라는 가짜 성공이 발생). wechat_inspector(action='cdp')가 v0.9.0부터 항상 0건을 반환하는 문제 수정——daemon은 결과를 data에 넣지만 inspector는 존재하지 않는 logs를 읽어, 가장 많이 사용되는 오류 진단 도구가 8개 마이너 버전 동안 조용히 작동하지 않았음. daemon 스트림 상한을 asyncio 기본 64 KiB에서 16 MiB로 상향(2.x에서 6초 수집 시 실제 634 KiB, 초과 시 모든 결과가 조용히 폐기됨). CDP 노이즈 필터링을 2.x target 구조에 맞게 조정, 추가된 IDE 셸 페이지와 type=webview로 누락된 devtools:// 제거(실측 734건 → 206건). IDE 포트 탐지는 IDE가 디스크에 기록하는 .ide 파일을 읽도록 변경(하드코딩된 후보 포트는 2.x에서 전혀 맞지 않음); status에 service_port_enabled(CLI_TIMEOUT의 1순위 원인, 이제 자가 진단 가능)와 ide_port 추가; wechat_ide / wechat_build에 cdp_port 매개변수 추가(9222는 Chrome에 자주 점유됨)

0.9.14

파일 읽기 경로 수정 + 매개변수 무효화 수정: wechat_file의 read_page/read_file을 list_pages와 동일한 기준으로 변경(먼저 project.config.json의 miniprogramRoot로 해석, 그다음 프로젝트 루트로 폴백)——이전에는 클라우드 개발 프로젝트에서 list_pages가 반환한 pages/xxx/index를 read_page에 전달하면 반드시 '페이지 파일을 찾을 수 없음' 오류가 발생하여 SOP G 1단계가 바로 영향받음; 동일 이름의 파일이 두 루트에 모두 존재할 때 also_found_at을 추가하여 정확히 알리고, project.config.json은 프로젝트 루트의 권위 있는 사본을 고정 사용; read_page는 resolved_base를, read_file은 resolved_path를 반환. wechat_inspector(action='cdp')에 cdp_port 전달 추가(이전에는 이 매개변수가 무의미하여 항상 9222에 연결됨). subprocess.CREATE_NO_WINDOW를 모두 getattr 폴백으로 변경하여 비 Windows 플랫폼의 AttributeError 위험 제거

0.9.13

--version 조기 종료 + 문서 대조 수정: wechat-devtools-mcp --version / -V가 의존성 없이 설치 버전을 출력한 후 바로 종료(uvx가 설치된 환경을 재사용하여 최신 버전을 자동으로 가져오지 않으므로 한 줄 명령으로 실제 버전 확인 가능); 문서 수정: navigate 매개변수 표 5열 오류, 설정 -> 보안 설정 메뉴 이름, mcp_version 예시 버전 제거; wechat_ide의 result_output과 wechat_navigate의 timeout 추가 기록(이전에는 v0.6.0부터 문서에 없었음); SKILL.md Step 1에 skill/MCP 버전 일치 자가 점검 줄 추가

0.9.12

핸드셰이크 반환 패키지 버전 + 의존성 상한: mcp 2.x에서 initialize의 serverInfo.version을 빈 문자열에서 본 패키지 버전으로 변경(1.x에서는 여전히 SDK 버전 보고, SDK에 덮어쓸 매개변수 없음); 의존성에 상한 mcp[cli]>=1.9,<3 추가하여 mcp 향후 메이저 버전 파괴 방지; 이중 버전 import를 _compat.py로 통일(#9 #10)

0.9.11

mcp 2.0.0 호환: 공식 MCP Python SDK 2.0(2026-07-28 출시)이 mcp.server.fastmcp를 제거(이름이 MCPServer로 변경)하여 새 설치 사용자가 시작 즉시 충돌, 모든 import를 1.x/2.x 이중 버전 호환으로 변경; 의존성을 mcp[cli]>=1.9로 명시(#8)

0.9.10

page_path 조용한 실패 수정: screenshot.js가 내비게이션 후 페이지 경로가 일치하는지 검증, /index 접미사가 없거나 페이지가 없으면 조용히 이전 페이지를 촬영하는 대신 명확한 오류 반환; node_bridge.py에서 daemon handler 오류 정보 유실 수정(#5)

0.9.9

스크린샷으로 인한 미니프로그램 재시작 수정: screenshot.js가 비 TabBar 페이지의 내비게이션 방식을 reLaunch(전체 페이지 스택 파괴)에서 navigateTo(비파괴적 푸시)로 변경, macOS에서 스크린샷 후 시뮬레이터 초기화 문제 수정(#4)

0.9.8

automator 연결 안정성 수정: daemon.js currentPage() 건강 검사를 폴링 재시도로 변경(새 연결 5회 × 3s+1.5s), 페이지 로딩이 느려도 이미 설정된 WebSocket 연결을 버리지 않음; _action_start는 _run_cli를 사용하여 CLI 반환 코드를 동기적으로 감지, CLI 실패를 즉시 인지(#3)

0.9.7

daemon 고아 프로세스 잔존 수정: daemon.js에 부모 프로세스 watchdog 추가, 5초마다 process.kill(ppid, 0)로 생존 감지, 부모 프로세스가 종료되면 WS 연결을 자동 정리하고 종료(#2)

0.9.6

macOS 적응: cdp_enabled=true 모드 크로스 플랫폼 시작(NW.js 메인 프로그램 wechatdevtools + package.nw 진입점 + pkill 정리); 기본 CLI 경로를 플랫폼별로 반환; Node.js 감지에 Homebrew/nvm 후보 경로 추가; README에 macOS 경로 예시 추가

0.9.5

compile 건강 검사가 영구히 실패하는 잠복 버그 수정(ui_debug.js에 page_stack action이 없어 v0.9.0 이후 automator_verified가 계속 false로 오보); compile이 EACCES/EADDRINUSE/#initialize-error 등 치명적 패턴에 대해 fail로 강등, '가짜 성공으로 이전 bundle 게시' 방지; preview가 상대 경로 자동 해석 + mtime 신선도 감지; wechat_automator(action='start')를 TCP+WS 이중 검증 + retry_after_ms 정밀 대기로 업그레이드; compile 전 miniprogram_npm 만료 감지 시 warning 발행; inspector 짧은 duration에서 예외 포착 시 warning 발행; wechat_cloud 도구 비활성화(CloudBase MCP로 대체)

0.9.4

switchTab 점프가 적용되지 않는 문제 수정(miniProgram.switchTab()로 callWxMethod 대체); compile 후 재연결 안정성(중복 프로세스 제거 + 3s 지연 + WS 건강 검사); README 5가지 agent 친화성 개선

버전

설명

0.9.3

status에 mcp_version 필드 추가로 버전 확인; 시작 시 버전 번호를 stderr로 출력; README에 pip/uv 버전 충돌 해결 가이드 추가

0.9.2

compile 후 navigate 타임아웃 수정: daemon 연결 상태 확인에 3초 타임아웃 보호 추가; compile 후 이전 캐시 연결을 자동으로 무효화하고 재연결; navigate currentPage 폴링 시 각 호출에 2초 독립 타임아웃 추가; HEALTH_CHECK_TIMEOUT과 CONNECTION_ERROR 오류 코드 구분

0.9.1

cdp_enabled=true 시 AttributeError 크래시 수정; WXML 런타임 오류 수집 추가(compile 후 CDP가 template not found 등 경고 자동 포착)

0.9.0

영구 Node daemon 아키텍처: 단일 daemon 프로세스 상주, NDJSON 프로토콜 통신, WS 연결을 포트별로 재사용; 8개 개별 bundle을 단일 daemon.bundle.js로 대체; 도구 호출 지연 시간이 500ms+에서 ~3ms로 감소; compile 후 daemon이 자동으로 연결을 재구축하여 연결 끊김 없음

0.8.0

compile 후 automator 자동 재연결; navigate가 TabBar 페이지를 자동 인식하여 switchTab 사용; screenshot에 full_page/scroll_top/page_path 파라미터 및 뷰포트 스크린샷 모드 추가; page_data에 expected_path 폴링 추가로 이전 데이터 방지; 긴 이미지 이어붙이기 동적 스텝으로 내용 누락 수정; node_bridge 연결 끊김 시 재시도 통일 + 500ms 호출 간격; start 포트 검증을 20회로 증가

0.7.0

navigate 변수 스코프 수정(currentPageTimeout); evaluate가 선언문 지원(const/let/var fallback); call_method가 현재 페이지 경로 반환; automator start 시 포트 폴링 검증으로 맹목적 대기 대체; SKILL.md에 효율 원칙, 복구 등급, 페이지 이동 방법, 6개 장애 항목 추가

0.6.0

navigate가 query 파라미터 지원(reLaunch 타임아웃 fallback); CDP 시작 노이즈 필터링(console.assert/__route__/ide:// 노이즈 감소 + WXML 오류 보호); compile 반환값 3분류 + automator 무효 안내; navigate currentPage 폴링 재시도; 타임아웃 설정 가능

0.5.1

wechat_ide(action='open')에 CDP 시작 상태 확인 추가: 5초간 CDP 로그를 자동 수집하여 시작 단계 치명적 오류 감지, 오류 발생 시 바로 실패 반환하여 후속 작업 차단

0.5.0

Skill SOP 전면 최적화: SOP I/J 추가; AppID 확인 및 path 검증 추가; CDP 노이즈 필터링; 스크린샷 이어붙이기 퍼지 매칭 수정

0.4.1

스크린샷 긴 페이지 이어붙이기 재작성: 고정 영역 감지, DPR 적응, 동적 겹침 계산

0.4.0

CDP 로그 강화, 클라우드 함수 배포 자동 검증, navigate 지능형 진단, SOP G/H 추가

0.3.0

대규모 리팩토링: 44개 도구를 8개 API로 통합; CDP 로그 v2; SKILL.md 지식 베이스 추가

0.2.6

README에 OpenAI Codex 설정 설명 추가

0.2.5

Kiro 편집기 설정 설명 추가

0.2.4

스크린샷 스크롤 이어붙이기 수정: sharp → jimp

0.2.3

배포 패키지 최적화: scripts/ 소스 제외, dist/ 빌드 산출물만 유지

0.2.2

Node.js 스크립트를 bundle-only 모드로 변경

0.2.1

버전 업데이트 및 문서 보완

0.2.0

navigate가 CDP 고화질 로그 수집으로 변경

0.1.9

UTF-8 인코딩 깨짐 수정

0.1.8

Windows 중국어 경로 UnicodeDecodeError 수정

0.1.7

core/full 도구 세트 프리셋 추가; MCP_DOC.md 추가

0.1.6

wechat_open(cdp_enabled=true)가 기존 프로세스 자동 종료

0.1.5

Windows stdio 차단 문제 수정

0.1.4

CDP 로그, 스크린샷, 자동화 등 기능 추가

0.1.3

초기 버전