Xcode MCP 사용 지침: AI 에이전트용

name: xcode-mcp-for-pi-agent description: mcporter CLI를 통한 효율적인 Xcode MCP 도구 사용 지침. 이 스킬은 Xcode MCP 도구를 사용해야 하는 시점과 표준 도구를 사용해야 하는 시점을 이해하는 데 사용됩니다. Xcode MCP는 많은 토큰을 소비하므로 빌드, 테스트, 시뮬레이터, 미리보기 및 SourceKit 진단에만 사용하세요. 파일 읽기/쓰기/grep 작업에는 절대 사용하지 마세요. Xcode 프로젝트, iOS/macOS 빌드, SwiftUI 미리보기 또는 Apple 플랫폼 개발 작업 시 이 스킬을 사용하세요. # Xcode MCP 사용 지침 Xcode MCP 도구는 MCP 서버를 표준 명령줄 도구에 연결하는 `mcporter` CLI를 통해 접근합니다. 이 스킬은 Xcode MCP를 사용해야 하는 시점과 표준 도구를 선호해야 하는 시점을 정의합니다. ## 설정 Xcode MCP는 `~/.mcporter/mcporter.json`에 구성되어야 합니다: ```json { "mcpServers": { "xcode": { "command": "xcrun", "args": ["mcpbridge"], "env": {} } } } ``` 연결 확인: ```bash mcporter list xcode ``` --- ## 도구 호출 모든 Xcode MCP 도구는 mcporter를 통해 호출됩니다: ```bash # 사용 가능한 도구 목록 mcporter list xcode # key:value 인수로 도구 호출 mcporter call xcode.<tool_name> param1:value1 param2:value2 # 함수 호출 구문으로 호출 mcporter call 'xcode.<tool_name>(param1: "value1", param2: "value2")' ``` --- ## Xcode MCP 도구 전체 참조 ### 창 및 프로젝트 관리 | 도구 | mcporter 호출 | 토큰 비용 | |------|---------------|------------| | 열린 Xcode 창 목록 (tabIdentifier 가져오기) | `mcporter call xcode.XcodeListWindows` | 낮음 | ### 빌드 작업 | 도구 | mcporter 호출 | 토큰 비용 | |------|---------------|------------| | Xcode 프로젝트 빌드 | `mcporter call xcode.BuildProject` | 중간 | | 오류/경고가 포함된 빌드 로그 가져오기 | `mcporter call xcode.GetBuildLog` | 중간 | | Issue Navigator의 문제 목록 | `mcporter call xcode.XcodeListNavigatorIssues` | 낮음 | ### 테스트 | 도구 | mcporter 호출 | 토큰 비용 | |------|---------------|------------| | 테스트 플랜에서 사용 가능한 테스트 가져오기 | `mcporter call xcode.GetTestList` | 낮음 | | 모든 테스트 실행 | `mcporter call xcode.RunAllTests` | 중간 | | 특정 테스트 실행 (권장) | `mcporter call xcode.RunSomeTests` | 중간 | ### 미리보기 및 실행 | 도구 | mcporter 호출 | 토큰 비용 | |------|---------------|------------| | SwiftUI 미리보기 스냅샷 렌더링 | `mcporter call xcode.RenderPreview` | 중간 | | 파일 컨텍스트에서 코드 스니펫 실행 | `mcporter call xcode.ExecuteSnippet` | 중간 | ### 진단 | 도구 | mcporter 호출 | 토큰 비용 | |------|---------------|------------| | 특정 파일의 컴파일러 진단 가져오기 | `mcporter call xcode.XcodeRefreshCodeIssuesInFile` | 낮음 | | SourceKit 진단 가져오기 (열린 모든 파일) | `mcporter call xcode.getDiagnostics` | 낮음 | ### 문서 | 도구 | mcporter 호출 | 토큰 비용 | |------|---------------|------------| | Apple Developer 문서 검색 | `mcporter call xcode.DocumentationSearch` | 낮음 | ### 파일 작업 (높은 토큰 - 절대 사용 금지) | MCP 도구 | 대신 사용 | 이유 | |----------|-------------|-----| | `xcode.XcodeRead` | `Read` 도구 / `cat` | 높은 토큰 소비 | | `xcode.XcodeWrite` | `Write` 도구 | 높은 토큰 소비 | | `xcode.XcodeUpdate` | `Edit` 도구 | 높은 토큰 소비 | | `xcode.XcodeGrep` | `rg` / `grep` | 높은 토큰 소비 | | `xcode.XcodeGlob` | `find` / `glob` | 높은 토큰 소비 | | `xcode.XcodeLS` | `ls` 명령 | 높은 토큰 소비 | | `xcode.XcodeRM` | `rm` 명령 | 높은 토큰 소비 | | `xcode.XcodeMakeDir` | `mkdir` 명령 | 높은 토큰 소비 | | `xcode.XcodeMV` | `mv` 명령 | 높은 토큰 소비 | --- ## 권장 워크플로우 ### 1. 코드 변경 및 빌드 흐름 ``` 1. 코드 검색 -> rg "pattern" --type swift 2. 파일 읽기 -> Read 도구 / cat 3. 파일 편집 -> Edit 도구 4. 구문 확인 -> mcporter call xcode.getDiagnostics 5. 빌드 -> mcporter call xcode.BuildProject 6. 오류 확인 -> mcporter call xcode.GetBuildLog (빌드 실패 시) ``` ### 2. 테스트 작성 및 실행 흐름 ``` 1. 테스트 파일 읽기 -> Read 도구 / cat 2. 테스트 작성/편집 -> Edit 도구 3. 테스트 목록 가져오기 -> mcporter call xcode.GetTestList 4. 테스트 실행 -> mcporter call xcode.RunSomeTests (특정 테스트) 5. 결과 확인 -> 테스트 출력 검토 ``` ### 3. SwiftUI 미리보기 흐름 ``` 1. 뷰 편집 -> Edit 도구 2. 미리보기 렌더링 -> mcporter call xcode.RenderPreview 3. 반복 -> 필요에 따라 반복 ``` ### 4. 디버그 흐름 ``` 1. 진단 확인 -> mcporter call xcode.getDiagnostics 2. 프로젝트 빌드 -> mcporter call xcode.BuildProject 3. 빌드 로그 가져오기 -> mcporter call xcode.GetBuildLog severity:error 4. 문제 수정 -> Edit 도구 5. 재빌드 -> mcporter call xcode.BuildProject ``` ### 5. 문서 검색 ``` 1. 문서 검색 -> mcporter call xcode.DocumentationSearch query:"SwiftUI NavigationStack" 2. 결과 검토 -> 구현에 정보 사용 ``` --- ## 대체 명령 (MCP 또는 mcporter 사용 불가 시) Xcode MCP가 연결 해제되었거나, mcporter가 설치되지 않았거나, 연결이 실패한 경우 다음 xcodebuild 명령을 직접 사용하세요: ### 빌드 명령 ```bash # 디버그 빌드 (시뮬레이터) - <SchemeName>을 프로젝트의 스킴으로 교체 xcodebuild -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # 릴리스 빌드 (기기) xcodebuild -scheme <SchemeName> -configuration Release -sdk iphoneos build # 워크스페이스로 빌드 (CocoaPods 프로젝트용) xcodebuild -workspace <ProjectName>.xcworkspace -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # 프로젝트 파일로 빌드 xcodebuild -project <ProjectName>.xcodeproj -scheme <SchemeName> -configuration Debug -sdk iphonesimulator build # 사용 가능한 스킴 목록 xcodebuild -list ``` ### 테스트 명령 ```bash # 모든 테스트 실행 xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -configuration Debug # 특정 테스트 클래스 실행 xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing:<TestTarget>/<TestClassName> # 특정 테스트 메서드 실행 xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -destination "platform=iOS Simulator,name=iPhone 16" \ -only-testing:<TestTarget>/<TestClassName>/<testMethodName> # 코드 커버리지로 실행 xcodebuild test -scheme <SchemeName> -sdk iphonesimulator \ -configuration Debug -enableCodeCoverage YES # 사용 가능한 시뮬레이터 목록 xcrun simctl list devices available ``` ### 클린 빌드 ```bash xcodebuild clean -scheme <SchemeName> ``` --- ## 빠른 참조 ### mcporter + Xcode MCP 사용 대상: - `xcode.BuildProject` - 빌드 - `xcode.GetBuildLog` - 빌드 오류 - `xcode.RunSomeTests` - 특정 테스트 실행 - `xcode.GetTestList` - 테스트 목록 - `xcode.RenderPreview` - SwiftUI 미리보기 - `xcode.ExecuteSnippet` - 코드 실행 - `xcode.DocumentationSearch` - Apple 문서 - `xcode.XcodeListWindows` - tabIdentifier 가져오기 - `xcode.getDiagnostics` - SourceKit 오류 ### Xcode MCP 절대 사용 금지 대상: - `xcode.XcodeRead` -> `Read` 도구 / `cat` 사용 - `xcode.XcodeWrite` -> `Write` 도구 사용 - `xcode.XcodeUpdate` -> `Edit` 도구 사용 - `xcode.XcodeGrep` -> `rg` 또는 `grep` 사용 - `xcode.XcodeGlob` -> `find` / `glob` 사용 - `xcode.XcodeLS` -> `ls` 명령 사용 - 파일 작업 -> 표준 도구 사용 --- ## 토큰 효율성 요약 | 작업 | 최선의 선택 | 토큰 영향 | |-----------|--------------|--------------| | 빠른 구문 확인 | `mcporter call xcode.getDiagnostics` | 낮음 | | 전체 빌드 | `mcporter call xcode.BuildProject` | 중간 | | 특정 테스트 실행 | `mcporter call xcode.RunSomeTests` | 중간 | | 모든 테스트 실행 | `mcporter call xcode.RunAllTests` | 높음 | | 파일 읽기 | `Read` 도구 / `cat` | 낮음 | | 파일 편집 | `Edit` 도구 | 낮음 | | 코드 검색 | `rg` / `grep` | 낮음 | | 파일 목록 | `ls` / `find` | 낮음 |