Xcode MCP 서버
AI 어시스턴트를 위한 포괄적인 Xcode 통합을 제공하는 MCP(Model Context Protocol) 서버입니다. 이 서버를 통해 AI 에이전트는 Xcode 프로젝트와 상호 작용하고, iOS 시뮬레이터를 관리하고, 향상된 오류 처리 및 여러 프로젝트 유형을 지원하여 다양한 Xcode 관련 작업을 수행할 수 있습니다.
특징
프로젝트 관리
- 활성 프로젝트를 설정하고 자세한 프로젝트 정보를 얻으세요
- 템플릿(iOS, macOS, watchOS, tvOS)에서 새로운 Xcode 프로젝트 만들기
- 대상 및 그룹 사양을 사용하여 Xcode 프로젝트에 파일 추가
- 연관된 프로젝트를 찾기 위해 작업 공간 문서 구문 분석
- 프로젝트 및 작업 공간에서 사용 가능한 구성표 나열
파일 작업
- 다양한 인코딩을 지원하는 파일 읽기/쓰기
- base64 인코딩/디코딩을 사용하여 바이너리 파일을 처리합니다.
- 패턴과 정규식을 사용하여 파일 내의 텍스트 콘텐츠 검색
- 파일 존재 여부 확인 및 파일 메타데이터 가져오기
- 디렉토리 구조를 자동으로 생성합니다
빌드 및 테스트
- 사용자 정의 가능한 옵션으로 프로젝트 구축
- 자세한 실패 보고와 함께 테스트 실행
- 잠재적인 문제에 대한 코드 분석
- 빌드 디렉토리 정리
- 배포를 위한 아카이브 프로젝트
CocoaPods 통합
- 프로젝트에서 CocoaPods 초기화
- 포드 설치 및 업데이트
- 포드 종속성 추가 및 제거
- 임의의 Pod 명령 실행
Swift 패키지 관리자
- 새로운 Swift 패키지 초기화
- 다양한 버전 요구 사항에 따라 패키지 종속성을 추가하고 제거합니다.
- 패키지 업데이트 및 종속성 해결
- DocC를 사용하여 Swift 패키지에 대한 문서 생성
- 테스트를 실행하고 Swift 패키지를 빌드합니다.
iOS 시뮬레이터 도구
- 자세한 정보와 함께 사용 가능한 시뮬레이터를 나열하세요
- 시뮬레이터 부팅 및 종료
- 시뮬레이터에 앱 설치 및 실행
- 스크린샷을 찍고 비디오를 녹화하세요
- 시뮬레이터 설정 및 상태 관리
Xcode 유틸리티
- xcrun을 통해 Xcode 명령 실행
- 자산 카탈로그를 편집합니다
- 소스 이미지에서 앱 아이콘 세트 생성
- 앱 성능 추적
- App Store 제출을 위한 아카이브 내보내기 및 검증
- 다양한 Xcode 버전 간 전환
설치
필수 조건
- Xcode 14.0 이상이 설치된 macOS
- Node.js 16 이상
- npm 또는 yarn
- Swift 패키지 관리자 기능을 위한 Swift 5.5+
- CocoaPods(CocoaPods 통합을 위한 선택 사항)
설정
옵션 1: 자동 설정(권장)
설치 및 구성 프로세스를 자동화하는 포함된 설정 스크립트를 사용하세요.
지엑스피1
설치 스크립트의 기능:
- 환경 검증 :
- macOS에서 실행 중인지 확인하세요
- Xcode가 설치되었고 접근 가능한지 확인합니다.
- Node.js(v16+) 및 npm이 사용 가능한지 확인합니다.
- Ruby 설치 확인
- CocoaPods 설치를 확인합니다(누락된 경우 설치 제안).
- 종속성 설치 :
npm install 실행하여 필요한 모든 Node.js 패키지를 설치합니다.npm run build 실행하여 TypeScript 코드를 컴파일합니다.
- 구성 설정 :
.env 파일이 없으면 생성합니다.- 프로젝트 기본 디렉토리에 대한 프롬프트
- 디버그 로깅을 활성화할지 묻습니다.
- 구성 기본 설정을 저장합니다.
- Claude Desktop 통합 (선택 사항):
- Claude Desktop용 서버 구성을 제안합니다.
- Claude Desktop 구성 파일을 생성하거나 업데이트합니다.
- 서버를 시작하기 위한 적절한 명령과 인수를 설정합니다.
설치 스크립트를 사용해야 하는 경우:
- 모든 전제 조건이 충족되었는지 확인하기 위한 최초 설치
- 대화형 프롬프트를 통한 가이드 구성이 필요한 경우
- Claude Desktop 통합을 빠르게 설정하려면
- 환경에 필요한 모든 구성 요소가 있는지 확인하려면
스크립트는 명확한 프롬프트와 유용한 피드백을 통해 구성 과정을 안내합니다.
옵션 2: 수동 설정
수동 설정을 사용해야 하는 경우:
- 각 설치 단계에 대한 명시적인 제어를 선호합니다.
- 사용자 정의 환경이나 비표준 구성이 있습니다.
- CI/CD 파이프라인이나 자동화된 환경을 설정하고 있습니다.
- 설치 프로세스의 특정 측면을 사용자 지정하려고 합니다.
- 귀하는 Node.js 프로젝트에 익숙한 숙련된 개발자입니다.
수동 설치를 위해서는 다음 단계를 따르세요.
- 저장소를 복제합니다.
git clone https://github.com/r-huijts/xcode-mcp-server.git
cd xcode-mcp-server
- 필수 구성 요소를 확인하세요(설치되어 있어야 함):
- Xcode 및 Xcode 명령줄 도구
- Node.js v16 이상
- 엔피엠
- Ruby(CocoaPods 지원용)
- CocoaPods(선택 사항, Pod 관련 기능용)
- 종속성 설치:
- 프로젝트를 빌드하세요:
- 구성 파일을 만듭니다.
# Option A: Start with the example configuration
cp .env.example .env
# Option B: Create a minimal configuration
echo "PROJECTS_BASE_DIR=/path/to/your/projects" > .env
echo "DEBUG=false" >> .env
.env 파일을 편집하여 원하는 구성을 설정합니다. - Claude Desktop 통합(선택 사항):
~/Library/Application Support/Claude/claude_desktop_config.json 편집하거나 생성합니다.- 다음 구성을 추가합니다(필요에 따라 경로를 조정): GXP6
설정 문제 해결
일반적인 설정 문제:
- 빌드 오류 :
- 올바른 Node.js 버전(v16+)을 사용하고 있는지 확인하세요.
node_modules 를 삭제하고 npm install 다시 실행해보세요.npx tsc --noEmit 사용하여 TypeScript 오류를 확인하세요.- 코드의 모든 가져오기가 제대로 해결되었는지 확인하세요.
- 종속성 누락 :
- 누락된 모듈에 대한 오류가 표시되면
npm install 다시 실행하세요. - 네이티브 종속성의 경우 Xcode 명령줄 도구가 필요할 수 있습니다:
xcode-select --install
- 권한 문제 :
- 설치 디렉토리에 대한 쓰기 권한이 있는지 확인하세요.
- CocoaPods를 설치하려면
sudo gem install cocoapods 사용해야 할 수 있습니다.
- 구성 문제 :
.env 파일의 형식과 경로가 올바른지 확인하세요.PROJECTS_BASE_DIR 기존 디렉토리를 가리키는지 확인하세요.- 경로에 이스케이프해야 하는 특수 문자가 포함되어 있지 않은지 확인하세요.
- Claude Desktop 통합 :
- Claude 구성의 경로가
index.js 의 올바른 위치를 가리키는지 확인하세요. - 구성 변경 후 Claude Desktop을 다시 시작하세요.
- Claude와 함께 사용하기 전에 서버가 실행 중인지 확인하십시오.
용법
서버 시작
자동 재시작 기능이 있는 개발 모드의 경우:
구성 옵션
두 가지 방법으로 서버를 구성할 수 있습니다.
.env 파일의 환경 변수:PROJECTS_BASE_DIR=/path/to/your/projects
DEBUG=true
ALLOWED_PATHS=/path/to/additional/allowed/directory
PORT=8080
- 명령줄 인수:
npm start -- --projects-dir=/path/to/your/projects --port=8080
주요 구성 매개변수
PROJECTS_BASE_DIR / --projects-dir : 프로젝트의 기본 디렉토리(필수)ALLOWED_PATHS / --allowed-paths : 액세스를 허용할 추가 디렉토리(쉼표로 구분)PORT / --port : 서버를 실행할 포트(기본값: 3000)DEBUG / --debug : 디버그 로깅을 활성화합니다(기본값: false)LOG_LEVEL / --log-level : 로깅 수준을 설정합니다(기본값: info)
AI 어시스턴트에 연결
이 서버는 모델 컨텍스트 프로토콜(MCP)을 구현하여 이 프로토콜을 지원하는 다양한 AI 어시스턴트와 호환됩니다. 연결하려면 다음을 수행하세요.
- Xcode MCP 서버를 시작합니다
- AI 어시스턴트가 서버 URL(일반적으로
http://localhost:3000 )을 사용하도록 구성합니다. - 이제 AI 어시스턴트는 서버에서 제공하는 모든 Xcode 도구에 액세스할 수 있습니다.
도구 문서
사용 가능한 모든 도구와 사용법에 대한 포괄적인 개요는 도구 개요를 참조하세요.
자세한 사용 예와 모범 사례는 사용자 가이드를 참조하세요.
일반적인 워크플로
새 프로젝트 설정
// Create a new iOS app project
await tools.create_xcode_project({
name: "MyAwesomeApp",
template: "ios-app",
outputDirectory: "~/Projects",
organizationName: "My Organization",
organizationIdentifier: "com.myorganization",
language: "swift",
includeTests: true,
setAsActive: true
});
// Add a Swift Package dependency
await tools.add_swift_package({
url: "https://github.com/Alamofire/Alamofire.git",
version: "from: 5.0.0"
});
파일 작업
// Read a file with specific encoding
const fileContent = await tools.read_file({
filePath: "MyAwesomeApp/AppDelegate.swift",
encoding: "utf-8"
});
// Write to a file
await tools.write_file({
path: "MyAwesomeApp/NewFile.swift",
content: "import Foundation\n\nclass NewClass {}\n",
createIfMissing: true
});
// Search for text in files
const searchResults = await tools.search_in_files({
directory: "MyAwesomeApp",
pattern: "*.swift",
searchText: "class",
isRegex: false
});
빌딩 및 테스트
// Build the project
await tools.build_project({
scheme: "MyAwesomeApp",
configuration: "Debug"
});
// Run tests
await tools.test_project({
scheme: "MyAwesomeApp",
testPlan: "MyAwesomeAppTests"
});
프로젝트 구조
xcode-mcp-server/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server implementation
│ ├── types/ # Type definitions
│ │ └── index.ts # Core type definitions
│ ├── utils/ # Utility functions
│ │ ├── errors.js # Error handling classes
│ │ ├── pathManager.ts # Path validation and management
│ │ ├── project.js # Project utilities
│ │ └── simulator.js # Simulator utilities
│ └── tools/ # Tool implementations
│ ├── project/ # Project management tools
│ │ └── index.ts # Project creation, detection, file adding
│ ├── file/ # File operation tools
│ │ └── index.ts # File reading, writing, searching
│ ├── build/ # Build and testing tools
│ │ └── index.ts # Building, testing, analyzing
│ ├── cocoapods/ # CocoaPods integration
│ │ └── index.ts # Pod installation and management
│ ├── spm/ # Swift Package Manager tools
│ │ └── index.ts # Package management and documentation
│ ├── simulator/ # iOS simulator tools
│ │ └── index.ts # Simulator control and interaction
│ └── xcode/ # Xcode utilities
│ └── index.ts # Xcode version management, asset tools
├── docs/ # Documentation
│ ├── tools-overview.md # Comprehensive tool documentation
│ └── user-guide.md # Usage examples and best practices
├── tests/ # Tests
└── dist/ # Compiled code (generated)
작동 원리
Xcode MCP 서버는 모델 컨텍스트 프로토콜(Model Context Protocol)을 사용하여 AI 모델이 Xcode 프로젝트와 상호 작용할 수 있는 표준화된 인터페이스를 제공합니다. 서버 아키텍처는 다음과 같은 몇 가지 핵심 구성 요소로 설계되었습니다.
핵심 구성 요소
- 서버 구현 : 도구 등록 및 요청 처리를 담당하는 주요 MCP 서버입니다.
- 경로 관리 : 허용된 디렉토리에 대한 모든 경로를 검증하여 안전한 파일 액세스를 보장합니다.
- 프로젝트 관리 : 다양한 유형의 Xcode 프로젝트를 감지, 로드 및 관리합니다.
- 표준 Xcode 프로젝트(.xcodeproj)
- Xcode 작업 공간(.xcworkspace)
- Swift 패키지 관리자 프로젝트(Package.swift)
- 디렉토리 상태 : 상대 경로 확인을 위해 활성 디렉토리 컨텍스트를 유지합니다.
- 도구 레지스트리 : 다양한 Xcode 작업에 맞게 도구를 논리적 범주로 구성합니다.
요청 흐름
- AI 어시스턴트가 MCP 서버에 도구 실행 요청을 보냅니다.
- 서버는 요청 매개변수와 권한을 검증합니다.
- 검증된 매개변수를 통해 적절한 도구 핸들러가 호출됩니다.
- 이 도구는 종종 기본 Xcode 명령을 사용하여 요청된 작업을 실행합니다.
- 결과는 포맷되어 AI 어시스턴트에게 반환됩니다.
- 포괄적인 오류 처리를 통해 문제 해결을 위한 의미 있는 피드백을 제공합니다.
안전 기능
- 경로 검증 : 모든 파일 작업은 허용된 디렉토리로 제한됩니다.
- 오류 처리 : 자세한 오류 메시지는 문제를 진단하는 데 도움이 됩니다.
- 매개변수 검증 : 입력 매개변수는 Zod 스키마를 사용하여 검증됩��다.
- 프로세스 관리 : 외부 프로세스는 적절한 오류 처리를 통해 안전하게 실행됩니다.
프로젝트 유형 지원
서버는 다양한 프로젝트 유형을 지능적으로 처리합니다.
- 표준 프로젝트 : .xcodeproj 직접 조작
- 작업 공간 : 작업 공간 내에서 여러 프로젝트를 관리합니다.
- SPM 프로젝트 : Swift 패키지 관리자 특정 작업을 처리합니다.
이 아키텍처를 통해 AI 어시스턴트는 보안을 유지하고 자세한 피드백을 제공하는 동시에 모든 유형의 Xcode 프로젝트에서 원활하게 작업할 수 있습니다.
기여하다
기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.
- 저장소를 포크하세요
- 기능 브랜치를 생성합니다(
git checkout -b feature/amazing-feature ) - 변경 사항을 커밋하세요(
git commit -m 'Add some amazing feature' ) - 브랜치에 푸시(
git push origin feature/amazing-feature ) - 풀 리퀘스트 열기
개발 지침
- 기존 코드 스타일과 구성을 따르세요
- 특정 오류 메시지를 사용하여 포괄적인 오류 처리 추가
- 새로운 기능에 대한 테스트를 작성하세요
- 변경 사항을 반영하도록 문서를 업데이트하세요.
- 다양한 프로젝트 유형(표준, 작업 공간, SPM)과의 호환성을 보장합니다.
새로운 도구 추가
서버에 새로운 도구를 추가하려면:
src/tools/ 디렉토리에서 적절한 카테고리를 식별하세요.- Zod 스키마 검증을 통해 기존 패턴을 사용하여 도구 구현
- 카테고리의
index.ts 파일에 도구를 등록합니다. - 특정 오류 메시지로 오류 처리 추가
- 해당 문서 파일에 도구를 문서화하세요.
문제 해결
일반적인 문제
- 경로 액세스 오류 : 액세스하려는 경로가 허용된 디렉토리 내에 있는지 확인하세요.
- 빌드 실패 : Xcode 명령줄 도구가 설치되어 있고 최신 상태인지 확인하세요.
- 도구를 찾을 수 없음 : 도구 이름이 올바르고 제대로 등록되었는지 확인하세요.
- 매개변수 검증 오류 : 도구 설명서에서 매개변수 유형 및 요구 사항을 확인하세요.
디버깅
- 디버그 로깅을 활성화하여 서버를 시작합니다:
npm start -- --debug - 자세한 오류 메시지는 콘솔 출력을 확인하세요.
- 요청 및 응답 세부 정보를 보려면 서버 로그를 검사하세요.
- 도구별 문제의 경우 터미널에서 직접 동등한 Xcode 명령을 실행해 보세요.
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.
감사의 말
- MCP SDK에 대한 Model Context Protocol 팀에 감사드립니다.
- TypeScript와 Node.js로 구축됨
- Xcode 명령줄 도구와 Swift 패키지 관리자를 사용합니다.
- 서버의 기능과 견고성을 개선하는 데 도움을 준 모든 기여자에게 특별히 감사드립니다.