Wix Headless API로 Cursor 앱 백엔드 만들기: 공식 문서 미공개 항목과 대체 구성 방안

준비 환경과 파일 위치

조건 1: Cursor 버전이 0.46 미만인 경우, cursor headless --help 명령으로 Headless 모드 설정을 필수적으로 확인해야 합니다. 0.46 이상인 경우 기본 Headless 모드 사용이 가능합니다.

조건 2: Wix Headless API가 공식 문서에 포함되어 있지 않으므로, Wix 개발자 포털(dev.wix.com)에서 API 엔드포인트 존재 여부를 확인해야 합니다. 존재하지 않는 경우 Wix REST API(www.wixapis.com)를 대체로 사용해야 합니다.

수집된 공식 문서에는 Wix Headless API 엔드포인트, 인증 방식, 요청·응답 스펙이 공개되어 있지 않습니다. Cursor 측은 docs.cursor.com/settings/api-keys에서 BYOK 설정을 안내하며, Wix 측은 support.wix.com 도움말 센터에서 일반 계정 관리만 다룹니다. 따라서 실제 연동 전 Wix 개발자 포털(dev.wix.com) 또는 공식 API 레퍼런스 존재 여부를 별도 확인해야 합니다.

Cursor CLI 설치와 환경 변수 명령

# 1. Cursor CLI 설치 및 헤드리스 모드 확인

npm install -g @cursor/cli@latest
cursor --version
cursor headless --help

# 2. 환경 변수 파일 생성 (Git 무시 필수)

cat > .env.local << 'EOF'
CURSOR_API_KEY=sk-cursor-xxxxxxxxxxxxxxxx
WIX_SITE_ID=your-site-id
WIX_API_KEY=your-wix-api-key
EOF

# 3. 기본 연결 테스트 스크립트

cat > test-connection.js << 'EOF'
import { CursorClient } from '@cursor/client';
const client = new CursorClient({ apiKey: process.env.CURSOR_API_KEY });
async function main() {
  const models = await client.models.list();
  console.log('Available models:', models.map(m => m.id));
}
main().catch(console.error);
EOF

위 코드는 Cursor 공식 CLI 설치와 BYOK 환경 변수 설정까지만 검증된 내용입니다. Wix Headless API 호출 부분은 공식 문서 미공개로 구현할 수 없습니다. WIX_API_KEY 발급 경로는 Wix 개발자 콘솔에서 확인해야 합니다.

CLI 설치부터 BYOK 키 확인까지

1. Cursor CLI 최신 버전 설치 후 cursor headless --help 실행하여 Headless/CI 모드 옵션 확인합니다.
2. docs.cursor.com/settings/api-keys에서 BYOK 키 발급 후 .env.local에 CURSOR_API_KEY 저장합니다.
3. Wix 개발자 콘솔 접속하여 Headless API 권한·엔드포인트 존재 여부 확인하고 WIX_API_KEY 발급받습니다.
4. test-connection.js 실행하여 Cursor 모델 목록 조회 성공 시 Available models: ["claude-sonnet-5", "gpt-5.6-sol", ...] 형태 출력 확인합니다.
5. Wix API 테스트 엔드포인트(예: GET /v1/sites/{siteId}) 호출하여 200 응답과 사이트 메타데이터 수신 확인합니다.
6. 양측 인증 성공 시 실제 백엔드 로직 구현 전 샘플 요청·응답 로그를 ./logs/cursor/integration-$(date +%F).log에 저장합니다.

3단계에서 Wix Headless API 문서를 찾지 못하면 연동 작업을 중단하고 Wix 지원 티켓을 통해 API 제공 여부를 문의합니다.

키·개인정보·저장소 권한에서 제외할 값

• CURSOR_API_KEY, WIX_API_KEY는 .env.local에만 저장하고 .gitignore에 추가합니다.
• Wix 사이트 ID, 도메인명, 고객 PII(이메일, 전화번호)는 로그 출력 시 마스킹 처리합니다.
• Cursor 사용량 메트릭(토큰 수, 요청 횟수)은 요금제 과금 기준이므로 외부 로깅 서비스에 전송하지 않습니다.
• .cursor/rules, .cursor/mcp.json 등 로컬 설정 파일은 저장소에 커밋하지 않습니다.

Cursor 공식 문서는 BYOK 키가 조직 외부 유출 시 즉시 폐기·재발급해야 한다고 명시합니다. Wix 측은 도움말 센터에서 계정 보안 설정을 안내하나 API 키 별도 관리 가이드는 공개하지 않습니다.

오류를 구분하는 확인 항목과 복구 경로

Cursor 요금제별 요청 풀 한도는 docs.cursor.com/account/pricing에서 확인 가능하며, 초과 시 자동 차단 후 다음 청구 주기까지 대기해야 합니다. Wix 측 공식 한도 수치는 수집 자료에 없어 공식 문서 미공개로 표기합니다.

대안·상향 경로

Wix Headless API가 공식 제공되지 않는 경우: Wix REST API(www.wixapis.com) 또는 Wix Blocks SDK로 백엔드 기능을 구현하고 Cursor를 코드 생성·리뷰 도구로만 사용합니다. 인증·권한 문제가 지속되면: Cursor 지원(support@cursor.com)과 Wix 지원(support.wix.com 티켓)에 각각 로그 전문 첨부하여 에스컬레이션합니다.

위 대안은 수집된 공식 문서 범위 내에서 검증된 구성만 반영했습니다. Wix Headless API 정식 출시 시 별도 마이그레이션 가이드가 필요합니다.