바이브 코딩

IDE Bridge Server 아키텍처

DreamCatcher ^^ 2025. 9. 30. 14:30
반응형

IDE Bridge Server 아키텍처 문서 (보완)

📋 목차

  1. 개요
  2. 전체 아키텍처
  3. 시스템 구성요소
  4. 통신 프로토콜
  5. 데이터 흐름
  6. API 명세
  7. IDE별 연동 방법
  8. 배포 및 운영
  9. 보안 및 성능

개요

목적

본 문서는 다양한 개발 환경(IDE: Cursor AI, Xcode, IntelliJ IDEA, Android Studio) 간의 심리스한 연동을 지원하여 개발 컨텍스트를 공유하고, 효율적인 협업을 가능하게 하는 IDE Bridge Server의 아키텍처를 설명합니다. 이 시스템은 개발 생산성을 향상하고, AI 어시스턴트 및 고급 코드 인텔리전스 기능을 여러 IDE에서 통합적으로 활용할 수 있도록 하는 것을 목표로 합니다.

주요 기능

  • 🔄 IDE 간 실시간 상태 동기화: 현재 작업 중인 파일, 커서 위치, 프로젝트 경로 등 IDE의 핵심 상태를 실시간으로 공유하여 여러 개발자 또는 AI가 동일한 컨텍스트를 이해하도록 합니다.
  • 📁 파일 변경 이벤트 브로드캐스트: 한 IDE에서 발생한 파일 변경 이벤트를 다른 연동된 IDE에 즉시 전파하여, 모든 환경이 최신 파일 상태를 유지하게 합니다.
  • 🏗️ 빌드 상태 공유: 프로젝트의 빌드 시작, 성공, 실패 등의 상태를 중앙 서버를 통해 공유하여, 팀원들이나 AI가 전체 빌드 진행 상황을 파악할 수 있도록 합니다.
  • 🎯 크로스 IDE 코드 네비게이션: 특정 코드 심볼의 정의, 참조 등으로 다른 IDE에서 점프할 수 있는 기능을 제공하여, 여러 IDE를 오가며 작업하는 불편함을 해소합니다.
  • 📊 통합 이벤트 로깅: 모든 IDE에서 발생하는 주요 이벤트를 중앙 집중식으로 로깅하여 시스템 분석, 디버깅 및 사용자 활동 추적에 활용합니다.
  • 🤖 AI 어시스턴트(Cursor AI) 통합: Model Context Protocol(MCP)을 통해 Cursor AI와 연동하여 AI가 IDE의 현재 컨텍스트를 이해하고, 코드 생성, 분석, 질문 응답 등의 고급 기능을 제공할 수 있도록 합니다.
  • 🧠 Xcode 16 Code Intelligence 통합: Xcode 16의 강력한 SourceKit-LSP 기반 코드 인텔리전스 데이터를 Bridge Server를 통해 다른 IDE나 AI가 활용할 수 있도록 합니다.
  • 🔍 SourceKit-LSP 기반 코드 분석 공유: Swift/Objective-C 코드에 대한 심볼 정보, 타입 정보, 진단(에러/경고) 등을 SourceKit-LSP를 통해 분석하고, 이를 통합하여 다른 IDE에서 조회하거나 AI가 활용할 수 있게 합니다.

지원 IDE

  • ✅ Cursor AI: MCP(Model Context Protocol) 및 HTTP API를 통한 통신을 지원하여 AI 어시스턴트 기능을 완벽하게 통합합니다.
  • ✅ Xcode 16: SourceKit-LSP 및 HTTP API를 활용하여 심볼, 타입 정보 등 강력한 코드 인텔리전스 기능을 연동하고, IDE 상태를 공유합니다.
  • ✅ IntelliJ IDEA: 플러그인과 HTTP API를 통해 IDE 상태 동기화, 이벤트 수신 및 전송을 지원합니다.
  • ✅ Android Studio: 플러그인과 HTTP API를 통해 IntelliJ IDEA와 유사하게 IDE 상태 동기화 및 이벤트 처리를 지원합니다.
  • ✅ 기타 IDE: HTTP API를 통한 기본 연동을 제공하여, 향후 다양한 IDE로의 확장성을 확보합니다.

전체 아키텍처

IDE Bridge Server는 다양한 클라이언트 IDE와 중앙 서버, 그리고 선택적인 영구 저장소 계층으로 구성됩니다. 이 아키텍처는 각 IDE의 특성을 고려한 통신 방식을 채택하며, 실시간 동기화 및 고급 코드 인텔리전스 공유를 위한 효율적인 데이터 흐름을 제공합니다.

┌─────────────────────────────────────────────────────────────────────────┐
│                        Client Layer                                      │
├───────────────┬─────────────────┬──────────────┬──────────────────────────┤
│               │                 │              │                          │
│  Cursor AI    │  Xcode 16       │  IntelliJ    │  Android Studio          │
│               │  Code           │     IDEA     │                          │
│   (MCP +      │  Intelligence   │  (Plugin +   │   (Plugin +              │
│    HTTP)      │  (SourceKit-    │   HTTP)      │    HTTP)                 │
│               │   LSP + HTTP)   │              │                          │
│               │                 │              │                          │
└───────┬───────┴────────┬────────┴──────┬───────┴──────┬───────────────────┘
        │                │               │              │
        │ MCP/HTTP       │ SourceKit-LSP │ HTTP         │ HTTP
        │                │ + HTTP        │              │
        │                │               │              │
        └────────────────┴───────────────┴──────────────┘
                                 │
                                 ↓
        ┌──────────────────────────────────────────────────────────┐
        │      Central Bridge Server (Node.js + TypeScript)        │
        │  ┌────────────────────────────────────────────────────┐  │
        │  │     HTTP API Server (Express.js)                   │  │
        │  │  - REST API Endpoints                              │  │
        │  │  - CORS Support                                    │  │
        │  │  - JSON Request/Response                           │  │
        │  │  - SourceKit-LSP Proxy                             │  │
        │  └────────────────────────────────────────────────────┘  │
        │                                                           │
        │  ┌────────────────────────────────────────────────────┐  │
        │  │   WebSocket Server (Socket.io)                     │  │
        │  │  - Real-time Event Broadcasting                    │  │
        │  │  - Client Connection Management                    │  │
        │  │  - Room-based Communication                        │  │
        │  │  - Code Intelligence Events                        │  │
        │  └────────────────────────────────────────────────────┘  │
        │                                                           │
        │  ┌────────────────────────────────────────────────────┐  │
        │  │   MCP Server (Cursor AI용)                         │  │
        │  │  - Tool Definitions                                │  │
        │  │  - Resource Management                             │  │
        │  │  - Stdio Transport                                 │  │
        │  │  - Xcode Intelligence Integration                  │  │
        │  └────────────────────────────────────────────────────┘  │
        │                                                           │
        │  ┌────────────────────────────────────────────────────┐  │
        │  │      State Manager                                 │  │
        │  │  - In-memory State Storage                         │  │
        │  │  - Event History                                   │  │
        │  │  - Client Registry                                 │  │
        │  │  - Code Intelligence Cache                         │  │
        │  └────────────────────────────────────────────────────┘  │
        │                                                           │
        │  ┌────────────────────────────────────────────────────┐  │
        │  │      SourceKit-LSP Adapter                         │  │
        │  │  - LSP Message Translation                         │  │
        │  │  - Symbol Index Management                         │  │
        │  │  - Type Information Cache                          │  │
        │  └────────────────────────────────────────────────────┘  │
        └──────────────────────────────────────────────────────────┘
                                 │
                                 ↓
        ┌──────────────────────────────────────────────────────────┐
        │          Optional Persistence Layer                      │
        │  - Redis (상태 캐싱 + LSP 인덱스)                        │
        │  - PostgreSQL (이벤트 로그)                              │
        │  - File System (설정 저장 + Symbol Index)               │
        └──────────────────────────────────────────────────────────┘

아키텍처 설명:

  • 클라이언트 계층 (Client Layer): Cursor AI, Xcode 16, IntelliJ IDEA, Android Studio 등 다양한 IDE로 구성됩니다. 각 IDE는 자체적인 통신 메커니즘(MCP, SourceKit-LSP, HTTP, IDE Plugin)을 통해 Bridge Server와 상호작용합니다.
  • 중앙 브릿지 서버 (Central Bridge Server): Node.js와 TypeScript로 구현된 핵심 서비스입니다.
    • HTTP API Server (Express.js): RESTful API를 제공하여 IDE의 상태 업데이트, 이벤트 발행, 특정 정보 요청 등을 처리합니다. SourceKit-LSP 프록시 역할을 수행하여 Xcode의 LSP 요청을 중계하기도 합니다.
    • WebSocket Server (Socket.io): 실시간 양방향 통신을 담당하며, 클라이언트 연결 관리, 이벤트 브로드캐스팅, Code Intelligence 이벤트 전파 등의 기능을 수행합니다.
    • MCP Server (@modelcontextprotocol/sdk): Cursor AI와의 MCP 프로토콜 통신을 전담합니다. AI 어시스턴트가 Bridge Server의 기능을 도구(Tools) 형태로 호출할 수 있도록 인터페이스를 제공하며, Xcode Code Intelligence 데이터를 AI에 전달하는 역할을 합니다.
    • State Manager: Bridge Server의 핵심 로직 중 하나로, 모든 연결된 IDE의 현재 상태, 발생한 이벤트 히스토리, 클라이언트 연결 정보, 그리고 Code Intelligence 관련 캐시 데이터를 인메모리로 관리합니다.
    • SourceKit-LSP Adapter: Xcode의 SourceKit-LSP 메시지를 Bridge Server의 내부 데이터 구조로 변환하고, 심볼 인덱싱 및 타입 정보 캐싱을 담당하여 SourceKit-LSP 데이터를 다른 IDE나 AI가 활용할 수 있도록 합니다.
  • 선택적 영구 저장소 계층 (Optional Persistence Layer): Bridge Server의 상태 관리 및 데이터 지속성을 강화하기 위한 선택적 구성요소입니다.
    • Redis: 고성능의 인메모리 데이터 저장소로, 실시간 상태 캐싱 및 SourceKit-LSP 인덱스 데이터 캐싱에 활용될 수 있습니다.
    • PostgreSQL: 관계형 데이터베이스로, 영구적인 이벤트 로그 저장 및 복잡한 쿼리 분석에 적합합니다.
    • File System: 서버 설정 정보, 대용량 Symbol Index 데이터 등 파일 기반 저장이 필요한 경우에 사용됩니다.

시스템 구성요소

1. Central Bridge Server

Central Bridge Server는 Node.js와 TypeScript 기반으로 개발되어 높은 확장성과 비동기 처리 성능을 제공합니다. 다양한 내부 모듈들이 유기적으로 결합하여 IDE 간의 통합 기능을 수행합니다.

1.1 HTTP API Server

기술 스택: Express.js + TypeScript
설명:
Express.js 프레임워크를 기반으로 구축된 HTTP API 서버는 RESTful 원칙을 준수하는 엔드포인트를 제공합니다. 각 IDE는 이 API를 통해 자신의 상태를 서버에 업데이트하거나, 다른 IDE의 상태를 조회하고, 특정 이벤트를 발행할 수 있습니다. 특히, SourceKit-LSP 데이터를 HTTP 요청으로 받아 처리하는 프록시 역할도 수행하여, Xcode와 같은 IDE가 LSP 데이터를 Bridge Server로 전송할 수 있도록 합니다. CORS(Cross-Origin Resource Sharing)를 지원하여 다양한 출처의 클라이언트 IDE와의 통신을 허용하며, 요청/응답은 표준 JSON 형식을 따릅니다.

주요 엔드포인트:

  • GET /health: 서버의 현재 상태 및 활성화된 서비스들의 상태를 확인하는 헬스 체크 엔드포인트입니다.
  • GET /api/states: 현재 Bridge Server에 연결된 모든 IDE 클라이언트들의 상태 정보를 배열 형태로 조회합니다.
  • GET /api/state/:clientId: 특정 clientId에 해당하는 IDE 클라이언트의 상세 상태 정보를 조회합니다.
  • POST /api/state/:clientId: 특정 clientId에 해당하는 IDE 클라이언트의 상태 정보를 업데이트합니다. 이 요청은 State Manager에 의해 처리되며, 변경 사항은 WebSocket을 통해 다른 클라이언트들에게 브로드캐스팅될 수 있습니다.
  • POST /api/event: IDE에서 발생한 특정 이벤트를 서버에 발행합니다. 발행된 이벤트는 이벤트 히스토리에 기록되며, WebSocket을 통해 관련 클라이언트들에게 전파될 수 있습니다.
  • GET /api/events: 서버에 기록된 이벤트 히스토리를 조회합니다. 필터링 및 페이지네이션 기능이 추가될 수 있습니다.
  • POST /api/file-changed: 특정 IDE에서 파일 변경 이벤트가 발생했음을 알립니다. State Manager는 이 정보를 기반으로 캐시를 갱신하거나, 관련 클라이언트들에게 변경 알림을 보냅니다.
  • POST /api/build-status: IDE에서 프로젝트 빌드 상태(시작, 성공, 실패 등)를 업데이트합니다. 이 정보는 다른 IDE 및 AI 어시스턴트에게 실시간으로 공유될 수 있습니다.
  • POST /api/jump-to: 특정 IDE로 코드 점프 요청을 보냅니다. 요청을 받은 대상 IDE는 해당 파일의 특정 라인/컬럼으로 이동하거나, 심볼 정의 위치로 이동하는 동작을 수행합니다.
  • POST /api/sourcekit/analyze: 특정 Swift 코드 파일의 특정 위치에 대한 심볼, 타입, 진단 정보 등의 코드 분석을 SourceKit-LSP Adapter에 요청합니다.
  • GET /api/sourcekit/symbols/:file: 특정 파일 내의 모든 심볼 정보를 조회합니다. query 파라미터를 통해 심볼 이름을 필터링할 수 있습니다.
  • POST /api/sourcekit/index-update: Xcode로부터 SourceKit-LSP 기반으로 추출된 심볼 인덱스 정보를 수신하여 SourceKit-LSP Adapter의 캐시를 업데이트합니다.

1.2 WebSocket Server

기술 스택: Socket.io
설명:
Socket.io 라이브러리를 사용하여 구현된 WebSocket 서버는 IDE 클라이언트들과의 실시간 양방향 통신 채널을 제공합니다. 이는 특히 IDE 간의 즉각적인 상태 동기화, 이벤트 브로드캐스팅, 그리고 Code Intelligence 데이터의 실시간 전파에 필수적입니다. 클라이언트 연결 관리를 용이하게 하며, '방(Room)' 기반 통신을 통해 특정 프로젝트나 그룹에 속한 IDE 클라이언트들에게만 이벤트를 전송하는 기능을 지원합니다.

주요 이벤트:

  • Server → Client:
    • 'state-update': 연결된 IDE 클라이언트의 상태가 변경되었음을 알리는 이벤트입니다. data 페이로드에 변경된 상태 정보가 포함됩니다.
    • 'file-changed': 특정 파일의 내용이 변경되었음을 알리는 이벤트입니다.
    • 'build-status': 프로젝트의 빌드 상태가 변경되었음을 알리는 이벤트입니다 (예: building, success, failed).
    • 'jump-to-request': 다른 IDE로부터 특정 위치로 코드 점프 요청이 왔음을 알리는 이벤트입니다.
    • 'client-joined': 새로운 IDE 클라이언트가 Bridge Server에 연결되었을 때 발생하는 이벤트입니다.
    • 'client-left': 기존 IDE 클라이언트가 Bridge Server와의 연결을 해제했을 때 발생하는 이벤트입니다.
    • 'code-intelligence-update': SourceKit-LSP Adapter로부터 Code Intelligence 데이터(심볼, 타입, 진단 등)가 업데이트되었음을 알리는 이벤트입니다.
    • 'symbol-resolved': 특정 심볼의 정보(위치, 타입 등) 조회가 완료되었음을 알리는 이벤트입니다.
    • 'type-info-available': 특정 타입에 대한 상세 정보 조회가 완료되었음을 알리는 이벤트입니다.
  • Client → Server:
    • 'register': IDE 클라이언트가 서버에 자신을 등록하고 clientId를 부여받거나 기존 clientId를 재사용하는 초기 연결 이벤트입니다.
    • 'message': 클라이언트 간 또는 클라이언트-서버 간의 커스텀 메시지 전송에 사용될 수 있는 범용 이벤트입니다.
    • 'request-analysis': 특정 코드 스니펫이나 파일에 대한 Code Intelligence 분석을 요청하는 이벤트입니다.
    • 'symbol-lookup': 특정 심볼의 상세 정보를 서버에 조회하는 이벤트입니다.

1.3 MCP Server

기술 스택: @modelcontextprotocol/sdk
설명:
MCP(Model Context Protocol) Server는 Cursor AI와 Bridge Server 간의 표준화된 통신 채널을 제공합니다. 이는 Cursor AI가 IDE 컨텍스트를 이해하고 상호작용할 수 있도록 Bridge Server의 다양한 기능을 '도구(Tools)' 형태로 노출합니다. Stdio(표준 입출력) 기반의 JSON-RPC 프로토콜을 사용하여 안정적이고 효율적인 통신을 보장합니다. Xcode Code Intelligence 데이터는 MCP Server를 통해 Cursor AI로 전달되어 AI의 코드 이해도를 높이는 데 사용됩니다.

제공 도구:

  • get_ide_states: 모든 연결된 IDE의 현재 상태를 Cursor AI가 조회할 수 있도록 합니다. AI는 이 정보를 통해 어떤 IDE가 어떤 프로젝트를 열고 어떤 파일에 있는지 파악할 수 있습니다.
  • send_to_ide: 특정 IDE에 명령을 전송합니다 (예: 파일 열기, 코드 삽입 등).
  • jump_to_definition: AI의 지시를 받아 다른 IDE에서 특정 심볼의 정의 위치로 이동하도록 요청합니다.
  • trigger_build: AI가 특정 IDE의 프로젝트 빌드를 트리거할 수 있도록 합니다.
  • get_xcode_symbols: Xcode 프로젝트에 대한 심볼 정보를 AI가 조회할 수 있도록 합니다.
  • analyze_swift_code: Swift 코드 스니펫 또는 파일에 대한 상세 분석 정보를 AI에 제공합니다 (SourceKit-LSP 어댑터 활용).
  • get_type_info: 특정 타입 이름에 대한 상세 정보(상속, 프로토콜, 멤버 등)를 AI에 제공합니다.

1.4 State Manager

역할:
State Manager는 Bridge Server의 핵심적인 상태 관리 모듈입니다. 모든 연결된 IDE 클라이언트들의 현재 작업 컨텍스트(프로젝트 경로, 현재 파일, 커서 위치 등)를 인메모리에 저장하고 관리합니다. 또한, 시스템 내에서 발생하는 모든 이벤트의 히스토리를 유지하여 감사, 디버깅 및 과거 데이터 조회에 활용합니다. 클라이언트 연결 및 등록 정보(Client Registry)를 관리하며, SourceKit-LSP Adapter에서 제공하는 Code Intelligence 데이터를 캐싱하여 빠른 조회를 가능하게 합니다.

데이터 구조:

  • IDEState: 각 IDE 클라이언트의 현재 상태를 나타내는 인터페이스입니다.
    interface IDEState {
  clientId: string; // 클라이언트 고유 ID (예: "xcode-MyApp", "cursor-abc123")
  ide: "cursor" | "xcode" | "intellij" | "android-studio" | "other"; // IDE 종류
  projectPath?: string; // 현재 열려 있는 프로젝트의 절대 경로
  currentFile?: string; // 현재 편집 중인 파일의 절대 경로
  currentLine?: number; // 현재 커서의 라인 번호 (1-based)
  currentColumn?: number; // 현재 커서의 컬럼 번호 (1-based)
  buildStatus?: "idle" | "building" | "success" | "failed" | "cancelled"; // 프로젝트 빌드 상태
  lastActivity?: number; // 마지막 활동 timestamp (epoch milliseconds)
  capabilities?: string[]; // 해당 IDE가 지원하는 기능 목록 (예: ["swift6", "code-intelligence", "sourcekit-lsp", "refactoring"])
  xcodeVersion?: string; // Xcode의 경우, Xcode 버전 정보 (예: "16.0")
  pluginVersion?: string; // IntelliJ/Android Studio 플러그인 버전
  activeClients?: string[]; // 해당 IDE가 현재 연결된 다른 클라이언트 ID 목록 (협업 세션에 유용)
}
  • IDEEvent: 시스템 내에서 발생하는 모든 이벤트를 기록하는 인터페이스입니다.
    interface IDEEvent {
  id: string; // 이벤트 고유 ID
  type: string; // 이벤트 유형 (예: "file_changed", "build_started", "jump_to_definition")
  source: string; // 이벤트를 발생시킨 클라이언트 ID 또는 서버 모듈 (예: "xcode-MyApp", "bridge-server")
  data: any; // 이벤트 관련 페이로드 데이터
  timestamp: number; // 이벤트 발생 시각 (epoch milliseconds)
}
  • CodeIntelligenceData: SourceKit-LSP Adapter에서 생성 및 관리하는 Code Intelligence 데이터의 캐시 구조입니다.
    interface CodeIntelligenceData {
  projectId: string; // 프로젝트 ID (SourceKit-LSP 인덱스는 프로젝트 단위로 관리)
  filePath: string; // 데이터가 특정 파일에 종속될 경우 파일 경로
  symbols: SymbolInfo[]; // 해당 프로젝트 또는 파일에 대한 심볼 정보 목록
  typeInfo: TypeInfo[]; // 타입 정보 목록
  diagnostics: Diagnostic[]; // 진단 정보 (에러, 경고 등) 목록
  indexVersion: number; // Code Intelligence 인덱스 버전 (갱신 여부 판단에 사용)
  lastUpdated: number; // 마지막 업데이트 시각
}
  • SymbolInfo: 코드 내의 개별 심볼(클래스, 함수, 변수 등)에 대한 정보를 나타냅니다.
    interface SymbolInfo {
  name: string; // 심볼 이름 (예: "MyClass", "myMethod")
  kind: string; // 심볼 종류 (예: "class", "instance-method", "variable", "enum")
  location: { file: string; line: number; column: number }; // 심볼 정의 위치
  usr: string; // Unified Symbol Resolution (SourceKit 고유 식별자)
  range?: { start: { line: number; column: number }; end: { line: number; column: number } }; // 심볼의 전체 범위
  containerUsr?: string; // 상위 심볼의 USR (예: 클래스 내 메서드의 경우 클래스의 USR)
  parameters?: string[]; // 함수/메서드의 경우 파라미터 목록
  returnType?: string; // 함수/메서드의 경우 반환 타입
  documentation?: string; // 심볼에 대한 문서화 주석
}
  • TypeInfo: 특정 타입(클래스, 구조체, 열거형 등)에 대한 상세 정보를 나타냅니다.
    interface TypeInfo {
  typeName: string; // 타입 이름
  kind: string; // 타입 종류 (예: "class", "struct", "enum", "protocol")
  module: string; // 소속 모듈 이름
  inheritance?: string[]; // 상속하는 클래스/프로토콜 목록
  properties?: { name: string; type: string; access: string }[]; // 프로퍼티 목록
  methods?: { name: string; signature: string; access: string }[]; // 메서드 목록
  // 기타 타입 관련 상세 정보
}
  • Diagnostic: 코드 내의 에러 또는 경고와 같은 진단 정보를 나타냅니다.
    interface Diagnostic {
  severity: 'error' | 'warning' | 'note'; // 진단 심각도
  message: string; // 진단 메시지
  location: { file: string; line: number; column: number }; // 진단 발생 위치
  range?: { start: { line: number; column: number }; end: { line: number; column: number } }; // 진단 관련 코드 범위
  code?: string; // 진단 코드 (예: Swift Lint rule ID)
}

1.5 SourceKit-LSP Adapter

역할:
SourceKit-LSP Adapter는 Xcode 16의 SourceKit-LSP(Language Server Protocol)와 Bridge Server의 나머지 구성 요소들 사이의 인터페이스 역할을 합니다. Xcode가 생성하는 LSP 메시지(예: 코드 변경, 심볼 업데이트, 진단 정보)를 Bridge Server의 내부 데이터 구조(SymbolInfo, TypeInfo, Diagnostic)로 변환하고 관리합니다. Swift/Objective-C 코드에 대한 심볼 인덱스, 타입 정보 등을 캐싱하여 다른 IDE나 AI가 요청할 때 효율적으로 제공하며, LSP 프로토콜의 복잡성을 추상화하여 HTTP/WebSocket을 통한 간소화된 접근을 가능하게 합니다.

통신 프로토콜

Bridge Server는 다양한 IDE의 특성과 요구사항에 맞춰 최적화된 통신 프로토콜을 사용합니다.

Protocol 1: MCP (Model Context Protocol)

사용처: Cursor AI ↔ Bridge Server
특징:

  • Stdio 기반 JSON-RPC: 표준 입출력(Standard I/O)을 통해 JSON-RPC 2.0 메시지를 교환하는 방식으로, Cursor AI와의 강력한 통합을 가능하게 합니다.
  • 도구(Tools) 호출 방식: Cursor AI가 Bridge Server의 특정 기능을 마치 '도구'처럼 호출하여, IDE 컨텍스트 정보를 얻거나 특정 작업을 지시할 수 있게 합니다. 이는 AI의 지능적인 협업 및 자동화된 작업 수행에 핵심적인 역할을 합니다.
  • 단방향 요청-응답: 각 요청에 대한 응답이 명확하게 정의되어 있으며, 비동기 처리가 가능합니다.
  • Xcode Intelligence 데이터 통합: Bridge Server는 SourceKit-LSP Adapter를 통해 얻은 Xcode의 Code Intelligence 데이터를 MCP 응답에 포함시켜 Cursor AI가 Swift/Objective-C 코드에 대한 깊이 있는 이해를 가질 수 있도록 합니다.

통신 흐름:

Cursor AI → MCP Request (Tools/Call) → Bridge Server
  (예: analyze_swift_code 호출)
Bridge Server → SourceKit-LSP Query (필요시) → Xcode
  (예: SourceKit-LSP Adapter를 통해 Xcode에 코드 분석 요청)
Xcode → SourceKit-LSP Response → Bridge Server
Bridge Server → MCP Response → Cursor AI
  (예: 분석된 코드 정보, 심볼, 타입 정보 등을 포함하여 응답)

예시:

// Cursor에서 Swift 코드 분석 요청 (MCP Tool 호출)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "analyze_swift_code",
    "arguments": {
      "filePath": "/path/to/File.swift",
      "line": 42,
      "column": 10
    }
  }
}

// Bridge Server 응답 (Xcode Intelligence 데이터 포함)
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Symbol at (42, 10): `myFunction(param: Int) -> String`\nType: Function\nModule: MyApp\nFile: /path/to/File.swift:40:1\nDocumentation: \"/// 이 함수는 정수형 파라미터를 받아 문자열을 반환합니다.\"\nInherits: None"
      }
    ],
    "data": { // 추가적인 구조화된 데이터 제공 가능
      "symbolInfo": {
        "name": "myFunction",
        "kind": "function",
        "location": { "file": "/path/to/File.swift", "line": 40, "column": 1 },
        "usr": "s:5MyApp10myFunction_33_"
      },
      "typeInfo": {
        "returnType": "String",
        "parameters": ["Int"]
      }
    }
  }
}

Protocol 2: HTTP REST API

사용처: 모든 IDE ↔ Bridge Server
특징:

  • 표준 HTTP 메서드: GET, POST, PUT, DELETE와 같은 표준 HTTP 메서드를 사용하여 CRUD(Create, Read, Update, Delete) 작업을 수행합니다.
  • JSON 페이로드: 요청 본문 및 응답은 표준 JSON 형식으로 데이터를 교환합니다.
  • 상태 코드 기반 응답: HTTP 상태 코드(예: 200 OK, 201 Created, 400 Bad Request, 500 Internal Server Error)를 사용하여 요청 처리 결과를 명확하게 나타냅니다.
  • SourceKit-LSP 데이터 전송: Xcode와 같은 IDE는 SourceKit-LSP 어댑터로 직접 LSP 메시지를 전송할 수 없는 경우, HTTP API를 통해 LSP 관련 데이터를 Bridge Server로 전송할 수 있습니다. 이는 SourceKit-LSP Adapter가 이러한 데이터를 파싱하고 처리하도록 합니다.

통신 흐름:

Xcode / IntelliJ / Android Studio (Plugin) → HTTP Request → Bridge Server
Bridge Server → HTTP Response → Xcode / IntelliJ / Android Studio (Plugin)
Bridge Server (필요시) → WebSocket Broadcast → 모든 관련 IDE (상태 변경 알림 등)

예시:

# SourceKit-LSP 인덱스 업데이트 (Xcode 플러그인 등에서 HTTP로 전송)
curl -X POST http://localhost:3000/api/sourcekit/index-update \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "xcode-MyApp",
    "projectPath": "/Users/dev/MyApp",
    "symbols": [
      {
        "name": "MyClass",
        "kind": "class",
        "location": { "file": "MyClass.swift", "line": 10, "column": 7 },
        "usr": "s:5MyApp0A5ClassC"
      },
      {
        "name": "init()",
        "kind": "constructor",
        "location": { "file": "MyClass.swift", "line": 12, "column": 10 },
        "usr": "s:5MyApp0A5ClassCACycfc"
      }
    ],
    "indexVersion": 42
  }'

Protocol 3: WebSocket

사용처: Bridge Server ↔ 모든 IDE (실시간 이벤트)
특징:

  • 양방향 실시간 통신: 클라이언트와 서버 간에 지속적인 연결을 유지하며, 언제든지 양방향으로 데이터를 주고받을 수 있습니다. 이는 IDE 간의 실시간 동기화에 필수적입니다.
  • 이벤트 기반: 메시지를 특정 '이벤트' 이름으로 구분하여 전송하고 수신합니다. 클라이언트는 특정 이벤트에 리스너를 등록하여 해당 이벤트 발생 시 콜백 함수를 실행합니다.
  • 자동 재연결: 네트워크 불안정 등으로 연결이 끊겼을 때 자동으로 재연결을 시도하여, 사용자 경험에 미치는 영향을 최소화합니다.
  • Code Intelligence 이벤트 전파: Xcode에서 업데이트된 Code Intelligence 정보(예: 심볼 변경, 진단 발생)를 실시간으로 다른 IDE(예: Cursor AI, IntelliJ)에 전파하여, 모든 환경이 최신 코드 분석 데이터를 공유하도록 합니다.

통신 흐름:

Xcode (Code Intelligence Update 발생) → WebSocket → Bridge Server
  (예: SourceKit-LSP Adapter를 통해 LSP 메시지가 WebSocket 이벤트로 변환)
Bridge Server → WebSocket Broadcast → Cursor AI, IntelliJ, Android Studio 등
  (예: 'code-intelligence-update' 이벤트 전파)

Protocol 4: SourceKit-LSP

사용처: Xcode 16 ↔ Bridge Server (SourceKit-LSP Adapter)
특징:

  • Language Server Protocol 표준: Microsoft가 제안한 LSP 표준을 따르며, 다양한 편집기와 언어 서버 간의 통신을 위한 규약입니다.
  • JSON-RPC 2.0 기반: Stdio 또는 TCP를 통한 JSON-RPC 2.0 메시지 교환을 사용하여 언어별 코드 분석 기능을 제공합니다.
  • Swift 코드 분석 전용: Xcode의 SourceKit-LSP는 Swift/Objective-C 코드에 특화된 풍부한 코드 분석 기능을 제공합니다.
  • 타입 정보, 심볼 탐색, 진단 정보: 코드 완성, 정의 이동, 참조 찾기, 심볼 계층, 타입 정보 조회, 실시간 에러/경고 진단 등 고급 IDE 기능을 지원합니다.

통신 흐름:

Xcode SourceKit-LSP Client → SourceKit-LSP 메시지 → Bridge LSP Adapter
Bridge LSP Adapter → (내부 변환) → State Manager / HTTP API / WebSocket
  (예: LSP `textDocument/didChange`를 받아 `file-changed` 이벤트 발행 또는 인덱스 업데이트)
Bridge Server (다른 IDE) → HTTP/WebSocket Request → Bridge LSP Adapter
Bridge LSP Adapter → (내부 변환) → SourceKit-LSP 요청 → Xcode SourceKit-LSP
  (예: Cursor AI가 `get_xcode_symbols` MCP Tool 호출 시, LSP `workspace/symbol` 요청으로 변환)

주의: Xcode 16은 기본적으로 자체 SourceKit-LSP 서버를 내장하고 있으므로, Bridge Server는 이 SourceKit-LSP 서버와의 직접적인 통신(프록시) 또는 Xcode Bridge 플러그인을 통한 HTTP/WebSocket 방식의 간접적인 데이터 연동 방식을 혼합하여 사용할 수 있습니다. 위 흐름은 SourceKit-LSP Adapter가 Xcode의 SourceKit-LSP 데이터를 직접 처리하는 시나리오를 가정합니다.

데이터 흐름

Bridge Server를 통한 IDE 간의 데이터 흐름 시나리오를 통해 시스템의 동작 방식을 이해합니다.

시나리오 1: Xcode Code Intelligence → Cursor AI 동기화

이 시나리오는 Xcode에서 Swift 코드를 편집할 때 발생하는 코드 인텔리전스 정보를 Cursor AI가 활용하는 과정을 보여줍니다.

sequenceDiagram
    participant Xcode as Xcode 16
    participant Bridge as Bridge Server
    participant Cursor as Cursor AI

    Xcode->>Xcode: 1. 사용자가 코드 편집 (Code Intelligence 실시간 분석)
    Xcode->>Bridge: 2. SourceKit-LSP 인덱스 업데이트 (POST /api/sourcekit/index-update)
    activate Bridge
    Bridge->>Bridge: 3. State Manager 업데이트 및 Code Intelligence 캐시 갱신
    Bridge->>Cursor: 4. WebSocket broadcast ('code-intelligence-update')
    deactivate Bridge
    Cursor->>Cursor: 5. Cursor 컨텍스트 업데이트 (Code Intelligence 데이터 수신)
    Cursor->>Cursor: 6. 사용자: "MyClass가 뭐야?" (AI 어시스턴트에 질문)
    activate Bridge
    Cursor->>Bridge: 7. MCP Tool 호출 (get_xcode_symbols)
    Bridge->>Xcode: 8. SourceKit-LSP 심볼 정보 요청 (GET /api/sourcekit/symbols/MyClass.swift) (Bridge Adapter 경유)
    Xcode->>Bridge: 9. SourceKit-LSP 심볼 정보 응답
    Bridge->>Cursor: 10. MCP Response (심볼 정보 + 타입 정보)
    deactivate Bridge
    Cursor->>Cursor: 11. AI가 사용자에게 설명 제공 ("MyClass는...")

설명:

  1. 사용자 코드 편집: Xcode에서 개발자가 Swift 코드를 편집하면, Xcode의 내장 SourceKit-LSP는 실시간으로 코드를 분석하여 심볼 테이블, 타입 정보, 진단(에러/경고) 등을 업데이트합니다.
  2. Xcode 인덱스 업데이트 요청: Xcode Bridge 플러그인 또는 직접 연동된 SourceKit-LSP 어댑터를 통해, Xcode는 변경된 코드 인텔리전스 정보를 POST /api/sourcekit/index-update HTTP API를 통해 Bridge Server로 전송합니다.
  3. Bridge Server 상태 갱신: Bridge Server의 SourceKit-LSP Adapter와 State Manager는 수신된 데이터를 파싱하고 내부 Code Intelligence 캐시를 최신 상태로 갱신합니다.
  4. Code Intelligence 이벤트 브로드캐스트: Bridge Server는 WebSocket을 통해 모든 연결된 클라이언트(Cursor AI 포함)에게 code-intelligence-update 이벤트를 브로드캐스팅하여 Code Intelligence 데이터가 갱신되었음을 알립니다.
  5. Cursor AI 컨텍스트 업데이트: Cursor AI는 이 이벤트를 수신하여 자체적인 코드 컨텍스트를 업데이트하고, 최신 Xcode Code Intelligence 정보를 인지하게 됩니다.
  6. 사용자 AI 질의: 개발자가 Cursor AI에 "MyClass가 뭐야?"와 같은 질문을 던져 특정 심볼에 대한 정보를 요청합니다.
  7. MCP Tool 호출: Cursor AI는 Bridge Server의 get_xcode_symbols MCP Tool을 호출하여 MyClass에 대한 상세 정보를 요청합니다.
  8. 심볼 정보 요청: Bridge Server는 SourceKit-LSP Adapter를 통해 Xcode에 GET /api/sourcekit/symbols/MyClass.swift?query=MyClass HTTP 요청 또는 SourceKit-LSP textDocument/symbol 요청을 보내 MyClass의 상세 심볼 정보를 조회합니다.
  9. Xcode 심볼 정보 응답: Xcode는 요청된 심볼 정보를 Bridge Server에 응답합니다.
  10. MCP 응답: Bridge Server는 수신된 심볼 및 타입 정보를 Cursor AI에 MCP 응답으로 전달합니다.
  11. AI 설명 제공: Cursor AI는 전달받은 정보를 바탕으로 "MyClass는 MyApp 모듈에 정의된 클래스이며, UIViewController를 상속합니다..."와 같이 사용자에게 상세한 설명을 제공합니다.

시나리오 2: Cursor에서 Xcode로 코드 점프

이 시나리오는 Cursor AI가 특정 코드 심볼의 정의로 이동하기 위해 Xcode에 코드 점프를 요청하는 과정을 보여줍니다.

sequenceDiagram
    participant Cursor as Cursor AI
    participant Bridge as Bridge Server
    participant Xcode as Xcode 16

    Cursor->>Cursor: 1. 사용자: "MyClass의 정의로 가줘"
    activate Bridge
    Cursor->>Bridge: 2. MCP Tool 호출 (jump_to_definition)
    Bridge->>Xcode: 3. HTTP POST /api/jump-to (targetIDE: "xcode", symbol: "MyClass")
    activate Xcode
    Xcode->>Xcode: 4. Xcode Bridge App (Plugin) 이벤트 수신
    Xcode->>Xcode: 5. AppleScript / 내부 API 실행하여 Xcode 활성화
    Xcode->>Xcode: 6. SourceKit-LSP 심볼 위치 조회 (MyClass의 정의 위치)
    Xcode->>Xcode: 7. 파일 열고 해당 라인으로 이동
    Xcode->>Bridge: 8. HTTP POST /api/state/xcode (currentFile: "MyClass.swift", line: 15 등)
    deactivate Xcode
    deactivate Bridge
    Bridge->>Cursor: 9. WebSocket 'state-update' broadcast
    Cursor->>Cursor: 10. Cursor AI에 Xcode의 현재 위치 업데이트 알림

설명:

  1. 사용자 AI 질의: Cursor AI에서 개발자가 "MyClass의 정의로 가줘"와 같은 명령을 내립니다.
  2. MCP Tool 호출: Cursor AI는 Bridge Server의 jump_to_definition MCP Tool을 호출하며, 대상 IDE를 Xcode로 지정하고 이동할 심볼 정보를 함께 전달합니다.
  3. HTTP 점프 요청: Bridge Server는 POST /api/jump-to HTTP API를 통해 Xcode로 코드 점프 요청을 보냅니다. 이 요청에는 대상 IDE(xcode), 파일 경로, 라인/컬럼 또는 심볼 이름이 포함됩니다.
  4. Xcode Bridge 앱/플러그인 이벤트 수신: Xcode에 설치된 Bridge 앱 또는 플러그인은 이 HTTP 요청을 수신합니다.
  5. Xcode 활성화: Xcode Bridge 앱/플러그인은 macOS의 AppleScript 또는 Xcode 내부 API를 사용하여 Xcode 애플리케이션을 활성화하고 전면으로 가져옵니다.
  6. 심볼 위치 조회: Xcode는 요청받은 심볼 이름(MyClass)을 바탕으로 SourceKit-LSP를 사용하여 해당 심볼의 정의 위치(파일 경로, 라인 번호)를 조회합니다.
  7. 파일 열기 및 이동: Xcode는 조회된 파일(MyClass.swift)을 열고 커서를 해당 정의 위치(예: 15라인)로 이동시킵니다.
  8. Xcode 상태 업데이트: Xcode Bridge 앱/플러그인은 현재 IDE의 상태(현재 파일, 커서 위치)가 변경되었음을 POST /api/state/xcode HTTP API를 통해 Bridge Server에 업데이트합니다.
  9. 상태 업데이트 브로드캐스트: Bridge Server는 수신된 Xcode의 상태 변경 정보를 state-update WebSocket 이벤트를 통해 Cursor AI를 포함한 모든 연결된 클라이언트에게 브로드캐스팅합니다.
  10. Cursor AI 알림: Cursor AI는 이 이벤트를 수신하여 Xcode의 현재 작업 컨텍스트가 MyClass.swift 파일의 특정 라인으로 이동했음을 인지하고, 사용자에게 이를 알리거나 UI에 반영할 수 있습니다.

시나리오 3: 멀티 IDE 빌드 오케스트레이션

이 시나리오는 Cursor AI가 여러 IDE(Xcode, Android Studio)에 동시에 빌드를 지시하고, 각 IDE의 빌드 상태를 통합하여 관리하는 과정을 보여줍니다.

sequenceDiagram
    participant Cursor as Cursor AI
    participant Bridge as Bridge Server
    participant Xcode as Xcode 16
    participant Android as Android Studio

    Cursor->>Cursor: 1. 사용자: "전체 빌드 실행" (AI에 명령)
    activate Bridge
    Cursor->>Bridge: 2. MCP Tool 호출 (trigger_build, targets: ["xcode", "android-studio"])
    Bridge->>Bridge: 3. 빌드 요청을 각 대상 IDE에 전파
    Bridge->>Xcode: 4. WebSocket 'build-trigger' 이벤트 전송
    Bridge->>Android: 5. WebSocket 'build-trigger' 이벤트 전송
    activate Xcode
    activate Android
    Xcode->>Xcode: 6. xcodebuild 시작
    Android->>Android: 7. Gradle build 시작
    Xcode->>Bridge: 8. HTTP POST /api/build-status (clientId: "xcode-1", status: "building")
    Android->>Bridge: 9. HTTP POST /api/build-status (clientId: "android-1", status: "building")
    Bridge->>Cursor: 10. WebSocket 'build-status' broadcast (각 IDE의 빌드 진행 상태)
    Xcode->>Xcode: 11. iOS 빌드 완료 (성공 또는 실패)
    Xcode->>Bridge: 12. HTTP POST /api/build-status (clientId: "xcode-1", status: "success")
    Bridge->>Cursor: 13. WebSocket 'build-status' broadcast (iOS 빌드 성공 알림)
    Android->>Android: 14. Android 빌드 완료 (성공 또는 실패)
    Android->>Bridge: 15. HTTP POST /api/build-status (clientId: "android-1", status: "success")
    Bridge->>Cursor: 16. WebSocket 'build-status' broadcast (Android 빌드 성공 알림)
    deactivate Xcode
    deactivate Android
    deactivate Bridge
    Cursor->>Cursor: 17. AI가 최종 빌드 결과 요약 및 사용자에게 알림

설명:

  1. 사용자 AI 명령: 개발자가 Cursor AI에게 "전체 빌드 실행"과 같이 멀티 플랫폼 빌드를 지시합니다.
  2. MCP Tool 호출: Cursor AI는 Bridge Server의 trigger_build MCP Tool을 호출하며, 빌드 대상 IDE 목록(xcode, android-studio)을 지정합니다.
  3. 빌드 요청 전파: Bridge Server는 수신된 trigger_build 요청을 파싱하고, 각 대상 IDE에 빌드 시작을 알리는 이벤트를 전파할 준비를 합니다.
  4. Xcode 빌드 트리거: Bridge Server는 build-trigger WebSocket 이벤트를 Xcode Bridge 앱/플러그인에 전송합니다.
  5. Android Studio 빌드 트리거: Bridge Server는 build-trigger WebSocket 이벤트를 Android Studio 플러그인에 전송합니다.
  6. Xcode 빌드 시작: Xcode Bridge 플러그인은 이 이벤트를 수신하여 xcodebuild 명령어를 실행하여 iOS 프로젝트 빌드를 시작합니다.
  7. Android Studio 빌드 시작: Android Studio 플러그인은 이 이벤트를 수신하여 Gradle 빌드를 시작합니다.
  8. Xcode 빌드 상태 업데이트: Xcode 플러그인은 빌드 시작 직후 HTTP POST /api/build-status를 통해 Bridge Server에 자신의 빌드 상태가 "building"임을 알립니다.
  9. Android Studio 빌드 상태 업데이트: Android Studio 플러그인도 빌드 시작 직후 HTTP POST /api/build-status를 통해 Bridge Server에 자신의 빌드 상태가 "building"임을 알립니다.
  10. 빌드 진행 상태 브로드캐스트: Bridge Server는 이 상태 업데이트를 수신하여 모든 연결된 클라이언트(Cursor AI 포함)에게 build-status WebSocket 이벤트를 브로드캐스팅하여 각 IDE의 빌드 진행 상황을 실시간으로 공유합니다.
  11. iOS 빌드 완료: Xcode의 빌드가 성공 또는 실패로 완료됩니다.
  12. Xcode 최종 빌드 상태 업데이트: Xcode 플러그인은 빌드 완료 후 HTTP POST /api/build-status를 통해 Bridge Server에 최종 빌드 상태(예: "success")를 알립니다.
  13. iOS 빌드 결과 알림: Bridge Server는 이 최종 상태를 build-status WebSocket 이벤트를 통해 Cursor AI에 브로드캐스팅합니다.
  14. Android 빌드 완료: Android Studio의 빌드가 성공 또는 실패로 완료됩니다.
  15. Android 최종 빌드 상태 업데이트: Android Studio 플러그인도 빌드 완료 후 HTTP POST /api/build-status를 통해 Bridge Server에 최종 빌드 상태(예: "success")를 알립니다.
  16. Android 빌드 결과 알림: Bridge Server는 이 최종 상태를 build-status WebSocket 이벤트를 통해 Cursor AI에 브로드캐스팅합니다.
  17. AI 최종 결과 요약: Cursor AI는 두 플랫폼의 빌드 완료 이벤트를 모두 수신하여, "iOS 및 Android 빌드가 모두 성공적으로 완료되었습니다."와 같이 사용자에게 통합된 빌드 결과를 요약하여 제공합니다.

API 명세

Bridge Server의 HTTP REST API, WebSocket Events, 그리고 MCP Tools에 대한 상세 명세입니다.

REST API

1. Health Check

서버의 가용성과 주요 서비스들의 상태를 확인합니다.

  • Method: GET
  • Path: /health
  • 응답 (200 OK):
    {
  "status": "ok",
  "timestamp": 1234567890123, // epoch milliseconds
  "version": "1.0.0",
  "services": {
    "http": "running",
    "websocket": "running",
    "mcp": "running",
    "sourcekit-adapter": "running",
    "state-manager": "running"
  },
  "uptime": "1h 2m 3s" // 서버 가동 시간
}

2. SourceKit 코드 분석

특정 Swift/Objective-C 코드 파일의 특정 위치에 대한 상세 분석 정보를 요청합니다.

  • Method: POST
  • Path: /api/sourcekit/analyze
  • Request Body:
    {
  "clientId": "xcode-MyApp", // 요청을 시작한 클라이언트 ID
  "projectPath": "/Users/dev/MyProject", // 대상 프로젝트 경로
  "filePath": "/path/to/File.swift",
  "line": 42, // 분석할 코드의 라인 번호 (1-based)
  "column": 10 // 분석할 코드의 컬럼 번호 (1-based)
}
  • 응답 (200 OK):
    {
  "success": true,
  "symbol": { // 발견된 심볼 정보
    "name": "MyClass",
    "kind": "class",
    "usr": "s:5MyApp0A5ClassC",
    "location": {
      "file": "/path/to/MyClass.swift",
      "line": 15,
      "column": 7
    },
    "range": {
      "start": { "line": 15, "column": 7 },
      "end": { "line": 15, "column": 14 }
    }
  },
  "typeInfo": { // 심볼의 타입 정보
    "typeName": "MyClass",
    "kind": "class",
    "module": "MyApp",
    "inheritance": ["UIViewController"],
    "protocols": ["Codable"]
  },
  "documentation": "/// MyClass는 메인 뷰 컨트롤러입니다." // 관련 문서화 주석
}
  • 오류 응답 (404 Not Found 또는 500 Internal Server Error): {"success": false, "message": "Symbol not found"}

3. 심볼 정보 조회

특정 파일 내 또는 프로젝트 전체의 심볼 정보를 조회합니다. query 파라미터로 필터링할 수 있습니다.

  • Method: GET
  • Path: /api/sourcekit/symbols/:file (특정 파일 내 심볼) 또는 /api/sourcekit/symbols (프로젝트 전체 심볼)
  • Query Parameters:
    • query: (Optional) 심볼 이름으로 필터링할 문자열 (부분 일치)
    • projectPath: (Required for project-wide lookup) 대상 프로젝트의 경로
    • clientId: (Optional) 요청을 시작한 클라이언트 ID
  • 응답 (200 OK):
    {
  "projectId": "/Users/dev/MyProject",
  "file": "/path/to/MyClass.swift", // 특정 파일 조회 시
  "symbols": [
    {
      "name": "MyClass",
      "kind": "class",
      "location": { "file": "/path/to/MyClass.swift", "line": 15, "column": 7 },
      "usr": "s:5MyApp0A5ClassC",
      "documentation": "/// MyClass definition."
    },
    {
      "name": "myMethod()",
      "kind": "instance-method",
      "location": { "file": "/path/to/MyClass.swift", "line": 20, "column": 10 },
      "usr": "s:5MyApp0A5ClassC8myMethod33_",
      "returnType": "Void"
    }
  ]
}
  • 오류 응답 (400 Bad Request 또는 500 Internal Server Error): {"success": false, "message": "Error fetching symbols"}

4. SourceKit 인덱스 업데이트

Xcode Bridge 플러그인 등이 SourceKit-LSP에서 추출한 심볼 인덱스 데이터를 Bridge Server로 전송하여 캐시를 업데이트합니다.

  • Method: POST
  • Path: /api/sourcekit/index-update
  • Request Body:
    {
  "clientId": "xcode-MyApp",
  "projectPath": "/Users/dev/MyProject",
  "symbols": [ // 업데이트할 심볼 정보 목록
    {
      "name": "MyClass",
      "kind": "class",
      "location": {
        "file": "/path/to/MyClass.swift",
        "line": 15,
        "column": 7
      },
      "usr": "s:5MyApp0A5ClassC"
    }
  ],
  "diagnostics": [ // 업데이트할 진단 정보 목록
    {
      "severity": "error",
      "message": "Missing return in a function expected to return 'String'",
      "location": { "file": "/path/to/File.swift", "line": 30, "column": 5 }
    }
  ],
  "indexVersion": 42 // 현재 인덱스 버전 (증가하는 숫자)
}
  • 응답 (200 OK):
    {
  "success": true,
  "indexVersion": 42,
  "symbolsIndexed": 1,
  "diagnosticsUpdated": 1,
  "message": "SourceKit index updated successfully."
}
  • 오류 응답 (400 Bad Request 또는 500 Internal Server Error): {"success": false, "message": "Failed to update index"}

5. 모든 IDE 상태 조회

현재 Bridge Server에 연결된 모든 IDE 클라이언트들의 상태 정보를 조회합니다.

  • Method: GET
  • Path: /api/states
  • 응답 (200 OK):
    [
  {
    "clientId": "cursor-abc123",
    "ide": "cursor",
    "projectPath": "/path/to/project/web-app",
    "currentFile": "/path/to/project/web-app/src/index.ts",
    "currentLine": 42,
    "currentColumn": 10,
    "buildStatus": "idle",
    "lastActivity": 1234567890123,
    "capabilities": ["typescript", "ai-assistant"]
  },
  {
    "clientId": "xcode-def456",
    "ide": "xcode",
    "projectPath": "/path/to/project/ios-app.xcodeproj",
    "currentFile": "/path/to/project/ios-app/ViewController.swift",
    "currentLine": 10,
    "currentColumn": 5,
    "buildStatus": "success",
    "lastActivity": 1234567891234,
    "capabilities": ["swift6", "code-intelligence", "sourcekit-lsp"],
    "xcodeVersion": "16.0"
  },
  {
    "clientId": "intellij-ghi789",
    "ide": "intellij",
    "projectPath": "/path/to/project/java-backend",
    "currentFile": "/path/to/project/java-backend/src/main/java/MyService.java",
    "currentLine": 25,
    "currentColumn": 12,
    "buildStatus": "building",
    "lastActivity": 1234567892345,
    "capabilities": ["java", "gradle", "plugin"],
    "pluginVersion": "1.0.0"
  }
]

6. IDE 상태 업데이트

특정 clientId에 해당하는 IDE 클라이언트의 상태 정보를 업데이트합니다.

  • Method: POST
  • Path: /api/state/:clientId
  • Request Body:
    {
  "ide": "xcode", // 필수
  "projectPath": "/path/to/project/ios-app.xcodeproj", // 업데이트할 필드만 포함
  "currentFile": "/path/to/file.swift",
  "currentLine": 42,
  "currentColumn": 10,
  "buildStatus": "building",
  "capabilities": ["swift6", "code-intelligence"]
}
  • 응답 (200 OK): {"success": true, "message": "IDE state updated."}
  • 오류 응답 (400 Bad Request 또는 404 Not Found): {"success": false, "message": "Client not found or invalid data."}

7. 코드 점프 요청

다른 IDE로 특정 코드 위치 또는 심볼로 점프하도록 요청합니다.

  • Method: POST
  • Path: /api/jump-to
  • Request Body:
    {
  "sourceClientId": "cursor-abc123", // 요청을 시작한 클라이언트 ID
  "targetIDE": "xcode", // 대상 IDE의 종류 (예: "xcode", "intellij")
  "targetClientId": "xcode-def456", // (Optional) 특정 클라이언트 인스턴스에만 요청 시
  "filePath": "/path/to/File.swift", // 점프할 파일 경로
  "line": 42, // (Optional) 점프할 라인 번호
  "column": 10, // (Optional) 점프할 컬럼 번호
  "symbol": "MyClass", // (Optional) 점프할 심볼 이름 (심볼 정의로 이동)
  "projectPath": "/Users/dev/MyProject" // (Optional) 대상 프로젝트 경로 (심볼 조회에 사용)
}
  • 응답 (200 OK): {"success": true, "message": "Jump-to request sent."}
  • 오류 응답 (400 Bad Request 또는 404 Not Found): {"success": false, "message": "Target IDE not found or invalid request."}

WebSocket Events

Code Intelligence 관련 이벤트

1. code-intelligence-update

SourceKit-LSP Adapter에서 코드 인텔리전스 데이터(심볼, 타입 정보, 진단)가 업데이트되었을 때 브로드캐스팅됩니다.

socket.on('code-intelligence-update', (data) => {
  console.log('Code Intelligence Updated:', data);
  // data: {
  //   clientId: 'xcode-MyApp', // 업데이트를 발생시킨 IDE
  //   projectPath: '/Users/dev/MyProject',
  //   filePath: '/path/to/File.swift', // (Optional) 특정 파일에 대한 업데이트인 경우
  //   symbols: [...], // SymbolInfo[] (변경 또는 추가된 심볼)
  //   typeInfo: [...], // TypeInfo[] (변경 또는 추가된 타입 정보)
  //   diagnostics: [...], // Diagnostic[] (새로운 진단 또는 변경된 진단)
  //   indexVersion: 42, // 현재 인덱스 버전
  //   timestamp: 1234567890123
  // }
});
2. symbol-resolved

클라이언트가 요청한 특정 심볼에 대한 정보 조회가 완료되었을 때 전송됩니다.

socket.on('symbol-resolved', (data) => {
  console.log('Symbol Resolved:', data);
  // data: {
  //   requestId: 'some-uuid', // 요청에 대한 고유 ID (클라이언트가 요청 시 생성)
  //   symbolName: 'MyClass',
  //   location: { file: '/path/to/MyClass.swift', line: 15, column: 7 },
  //   typeInfo: { ... }, // TypeInfo 객체
  //   documentation: '/// MyClass description'
  // }
});
3. diagnostics-update

코드 내의 진단 정보(에러, 경고)가 업데이트되었을 때 브로드캐스팅됩니다.

socket.on('diagnostics-update', (data) => {
  console.log('Diagnostics Updated:', data);
  // data: {
  //   clientId: 'xcode-MyApp',
  //   projectPath: '/Users/dev/MyProject',
  //   filePath: '/path/to/file.swift',
  //   diagnostics: [ // 해당 파일의 현재 모든 진단 목록
  //     { severity: 'error', line: 10, column: 5, message: 'Missing return in a function...' },
  //     { severity: 'warning', line: 25, column: 12, message: 'Variable 'x' was never used.' }
  //   ],
  //   timestamp: 1234567890123
  // }
});

일반 IDE 상태 및 이벤트 관련 이벤트

4. state-update

연결된 IDE 클라이언트의 상태(예: 현재 파일, 커서 위치, 빌드 상태)가 변경되었을 때 브로드캐스팅됩니다.

socket.on('state-update', (data) => {
  console.log('IDE State Updated:', data);
  // data: {
  //   clientId: 'xcode-def456',
  //   changes: { // 변경된 필드만 포함
  //     currentFile: '/path/to/new-file.swift',
  //     currentLine: 1,
  //     currentColumn: 1,
  //     lastActivity: 1234567890123
  //   },
  //   fullState: { ... } // 변경 후의 전체 IDEState 객체
  // }
});
5. file-changed

한 IDE에서 파일 변경 이벤트가 발생했을 때 브로드캐스팅됩니다.

socket.on('file-changed', (data) => {
  console.log('File Changed:', data);
  // data: {
  //   clientId: 'intellij-ghi789',
  //   filePath: '/path/to/project/src/main.ts',
  //   eventType: 'contentChanged' | 'renamed' | 'deleted' | 'created',
  //   timestamp: 1234567890123
  // }
});
6. build-status

프로젝트의 빌드 상태가 변경되었을 때 브로드캐스팅됩니다.

socket.on('build-status', (data) => {
  console.log('Build Status Changed:', data);
  // data: {
  //   clientId: 'xcode-def456',
  //   projectPath: '/path/to/project/ios-app.xcodeproj',
  //   status: 'building' | 'success' | 'failed' | 'cancelled',
  //   timestamp: 1234567890123,
  //   message: 'Build successful for iOS-App.' // (Optional) 상세 메시지
  // }
});
7. jump-to-request

다른 IDE로부터 코드 점프 요청이 수신되었을 때 특정 대상 IDE에만 전송됩니다.

socket.on('jump-to-request', (data) => {
  console.log('Jump-to Request Received:', data);
  // data: {
  //   sourceClientId: 'cursor-abc123',
  //   filePath: '/path/to/File.swift',
  //   line: 42,
  //   column: 10,
  //   symbol: 'MyClass',
  //   timestamp: 1234567890123
  // }
  // 이 이벤트를 받은 IDE는 내부적으로 파일 열기/커서 이동 로직을 수행해야 합니다.
});

MCP Tools

Cursor AI가 Bridge Server의 기능을 활용하기 위해 호출할 수 있는 도구(Tools) 목록입니다.

Xcode Intelligence 관련 도구

1. get_xcode_symbols

Xcode 프로젝트 내의 심볼 정보를 조회합니다.

  • 설명: Cursor AI가 Xcode 프로젝트의 특정 심볼 목록(예: 클래스, 함수)을 질의할 때 사용됩니다.
  • Arguments:
    {
  "projectPath": "/path/to/xcode/project", // (필수) 대상 Xcode 프로젝트의 절대 경로
  "filter": "class" | "function" | "variable" | "all", // (선택) 조회할 심볼 종류 (기본값: "all")
  "nameContains": "My", // (선택) 심볼 이름에 포함될 문자열 필터
  "filePath": "/path/to/specific/file.swift" // (선택) 특정 파일 내 심볼만 조회
}
  • Result (예시):
    Classes in project '/path/to/xcode/project':
- MyClass (MyClass.swift:15) // location: { file: "MyClass.swift", line: 15, column: 7 }
- AnotherClass (AnotherClass.swift:20)
Functions in MyClass:
- init() (MyClass.swift:18)
- doSomething(param: String) (MyClass.swift:25)
    Note: Result는 AI가 처리하기 용이한 텍스트 또는 구조화된 JSON 형태로 반환될 수 있습니다.
2. analyze_swift_code

특정 Swift 코드 조각 또는 파일 위치에 대한 심볼, 타입, 문서화 등 상세 분석 정보를 제공합니다.

  • 설명: Cursor AI가 특정 코드에 대한 심층적인 이해가 필요할 때 사용됩니다.
  • Arguments:
    {
  "filePath": "/path/to/File.swift", // (필수) 분석할 파일 경로
  "line": 42, // (필수) 분석할 코드의 라인 번호 (1-based)
  "column": 10 // (필수) 분석할 코드의 컬럼 번호 (1-based)
}
  • Result (예시):
    Symbol at /path/to/File.swift:42:10: `myMethod(value: Int) -> String`
Kind: Instance Method
Type Signature: (Int) -> String
Defined in: MyClass (s:5MyApp0A5ClassC)
Module: MyApp
Documentation: "/// 이 메서드는 정수 값을 받아 문자열로 변환합니다."
Diagnostics: None
3. get_type_info

특정 타입 이름에 대한 상세 정보를 조회합니다.

  • 설명: Cursor AI가 클래스, 구조체, 열거형, 프로토콜 등의 정의 및 멤버 구성에 대한 정보를 파악할 때 사용됩니다.
  • Arguments:
    {
  "typeName": "MyClass", // (필수) 조회할 타입 이름
  "projectPath": "/path/to/xcode/project" // (선택) 특정 프로젝트 내에서 조회
}
  • Result (예시):
    Type: MyClass
Kind: class
Module: MyApp
Inherits: UIViewController, Codable // 상속하는 클래스 및 채택하는 프로토콜
Properties:
- name: String (public)
- age: Int (private)
Methods:
- init()
- viewDidLoad()
- encode(to encoder: Encoder) throws
- decode(from decoder: Decoder) throws
반응형
저작자표시 비영리 변경금지 (새창열림)

'바이브 코딩' 카테고리의 다른 글

사주 운세  (0) 2025.10.04
LunaTarot  (0) 2025.10.03
DiviTrack — 배당 수익을 한 눈에 관리하는 도구  (1) 2025.09.29
Echo — 익명 커뮤니티 게시판  (0) 2025.09.29
FormatKit — 파일 변환, 이렇게 활용해보세요!  (1) 2025.09.28

'바이브 코딩'의 다른글

  • 현재글IDE Bridge Server 아키텍처

관련글

티스토리툴바