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 관련 기능용)
종속성 설치:
npm install
프로젝트를 빌드하세요:
npm run build
구성 파일을 만듭니다.
# 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와 함께 사용하기 전에 서버가 실행 중인지 확인하십시오.

용법

서버 시작

npm start

자동 재시작 기능이 있는 개발 모드의 경우:

npm run dev

구성 옵션

두 가지 방법으로 서버를 구성할 수 있습니다.

.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 패키지 관리자를 사용합니다.
서버의 기능과 견고성을 개선하는 데 도움을 준 모든 기여자에게 특별히 감사드립니다.

Integrations

Xcode MCP 서버

특징

프로젝트 관리

파일 작업

빌드 및 테스트

CocoaPods 통합

Swift 패키지 관리자

iOS 시뮬레이터 도구

Xcode 유틸리티

설치

필수 조건

설정

옵션 1: 자동 설정(권장)

옵션 2: 수동 설정

설정 문제 해결

용법

서버 시작

구성 옵션

주요 구성 매개변수

AI 어시스턴트에 연결

도구 문서

일반적인 워크플로

새 프로젝트 설정

파일 작업

빌딩 및 테스트

프로젝트 구조

작동 원리

핵심 구성 요소

요청 흐름

안전 기능

프로젝트 유형 지원

기여하다

개발 지침

새로운 도구 추가

문제 해결

일반적인 문제

디버깅

특허

감사의 말

Tools

Related Resources

Appeared in Searches