Cursor

사전 요구 사항

설정 -> 기능 -> MCP 또는 마켓플레이스 지원이 포함된 Cursor IDE를 사용하세요. 인터페이스 및 사전 요구 사항:

• 구체적인 인터페이스: Cursor IDE (~/.cursor/mcp.json 또는 설정 -> 기능 -> MCP).
• 엔드포인트: https://xmemo.dev/mcp.
• 선호하는 인증 모드: Browser OAuth.
• 대체 인증 모드: 헤드리스 및 컨테이너 환경을 위한 직접 베어러 토큰.
• 계정: https://xmemo.dev 의 유효한 XMemo 계정.

설치 / 설정

Cursor 설정 -> 기능 -> MCP 를 열거나 ~/.cursor/mcp.json 을 구성합니다. 헤드리스 작업의 경우 브라우저 흐름 대신 환경 토큰 참조가 포함된 직접 구성 블록을 사용하세요:

• OAuth 경로: 호스팅된 URL만 구성하고 첫 번째 사용 시 브라우저 동의가 트리거되도록 합니다.
• 직접 폴백: 토큰을 설정 파일에 직접 넣지 말고 항상 XMEMO_KEY 에 유지하세요.
• 동일한 항목에 OAuth URL 구성과 Authorization 헤더를 함께 사용하지 마세요.

자격 증명 설정

OAuth 경로에는 키가 필요하지 않습니다 — 첫 번째 프롬프트에서 Browser OAuth를 완료하세요. 직접 헤드리스 폴백의 경우 셸 환경에서 XMEMO_KEY 를 설정하고 Cursor 설정에 토큰 값을 붙여넣지 마세요:

# OAuth path: no XMEMO_KEY needed (browser prompt)
# Direct fallback:
export XMEMO_KEY='<your-xmemo-token>'

XMEMO_AGENT_INSTANCE_ID 생성 / 확인

검토된 Cursor OAuth 및 직접 스니펫에는 클라이언트 측 인스턴스 헤더가 필요하지 않습니다. 헤드리스 래퍼가 XMEMO_AGENT_INSTANCE_ID 를 제공하는 경우 로컬 프로필당 한 번 생성하고 재사용하세요.

기존 구성 블록 유지

선호하는 OAuth 경로: 브라우저 기반 OAuth 인증을 위해 ~/.cursor/mcp.json 에서 검토된 URL 전용 Cursor 구성을 사용하세요:

{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp"
    }
  }
}

직접 대체 구성 블록

직접 헤드리스 대체: 헤드리스 또는 비대화형 환경에서 Cursor를 실행할 때 로컬 환경의 ${env:XMEMO_KEY} 를 참조하는 Authorization 헤더를 구성하세요:

{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}"
      }
    }
  }
}

클라이언트 다시 시작

구성을 편집한 후 변경 사항이 적용되도록 Cursor를 다시 시작하거나 설정 -> 기능 -> MCP 에서 MCP 서버를 껐다가 켜세요.

실제 recall 호출로 테스트

첫 번째 MCP 호출을 읽기 전용으로 설정합니다. 이는 상태 확인 플레이스홀더가 아니라 실제 리콜 호출이며 메모리에 쓰지 않습니다.

recall({ query: "connection check", limit: 1 })

예상 응답(리터럴 형태)

성공적인 호출은 아래의 공개 순위 텍스트 형식을 반환합니다. 참조 및 콘텐츠는 승인된 메모리 공간의 실제 값입니다.

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

첫 번째 유용한 작업: 합성 메모리 수명 주기

Cursor Composer 또는 Agent 모드 내에서 완전한 합성 메모리 작업을 연습합니다:

• 1. 합성 사실 저장: 규칙("Demo project timestamps use UTC.")을 "projects/demo-onboarding/conventions" 에 기억하도록 Cursor에 요청합니다.
• 2. 상태 비저장 전환: 새 Cursor Composer 채팅을 시작하거나 프로젝트 작업 공간을 다시 엽니다.
• 3. 출처 귀속 리콜: "demo project timestamp format" 을 쿼리합니다. 반환된 Reference 및 Location 을 확인합니다.
• 4. 메모리 수정: 타임스탬프를 ISO 8601 로 서식 지정하기 위해 활성 ID로 update_memory 를 호출합니다.
• 5. 선택적 정리: 온보딩 테스트가 완료되면 메모리 ID로 forget 을 호출합니다.

기능 및 프로필 도구

Cursor는 cursor-plugin 프로필에 대한 MCP 문서 계약에 정의된 프로필 한정 도구에 액세스할 수 있습니다:

• 핵심 메모리 도구: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context, search_knowledge.
• 스냅샷 및 충돌 도구: create_restart_snapshot, restore_restart_snapshot, list_memory_versions, list_memory_conflicts, resolve_memory_conflict.
• 프로젝트 및 계획 도구: get_mcp_identity, get_project_context, get_timeline, list_memory_todos, complete_memory_todo, create_memory_todo, update_project_decision, update_project_todo, update_state.
• 클라우드 스킬 및 거버넌스: recall_cloud_skill, save_cloud_skill, propose_write, propose_todo_mutation, propose_profile_mutation, query_audit, record_event, memory_stats.

제한 사항 및 경계

Cursor의 운영 경계 및 제약 조건:

• 구성 순수성: 동일한 서버 블록에 OAuth URL 전용 구성과 Authorization 헤더를 혼합하지 마세요.
• 작업 공간 경계: 메모리 접근은 인증된 사용자의 작업 공간으로 엄격히 제한됩니다.
• 헤드리스 토큰 요구 사항: 직접 MCP 폴백에는 명시적인 환경 토큰 프로비저닝이 필요합니다.

일반적인 오류

Cursor는 OAuth 경로 또는 직접 헤드리스 폴백 모두에서 실패할 수 있습니다:

• invalid_grant — OAuth 인증 코드가 유효하지 않거나 만료되었거나 이미 사용되었습니다: Cursor를 다시 연결하고 다시 인증하세요.
• 401 invalid_token — 직접 폴백 토큰이 누락되었거나 만료되었거나 유효하지 않습니다: 헤드리스 환경에서 XMEMO_KEY 를 확인하세요.
• 403 insufficient_scope — 자격 증명이 memory:read 를 부여하지 않습니다: 필요한 범위를 승인하거나 해당 범위가 포함된 토큰을 발급하세요.

업데이트 및 제거

Cursor 유지 관리 절차:

• 업데이트: 스키마를 다시 로드하려면 Cursor MCP 설정에서 서버를 껐다가 켜세요.
• 제거: ~/.cursor/mcp.json 에서 xmemo 항목을 삭제하거나 Cursor MCP 설정에서 제거하세요.