Sanity MCP Server

Sanity MCP 서버

Sanity의 AI 기반 도구로 콘텐츠 운영을 혁신하세요. 선호하는 AI 기반 편집기에서 자연어 대화를 통해 콘텐츠를 제작, 관리 및 탐색하세요.

Sanity MCP 서버는 모델 컨텍스트 프로토콜을 구현하여 Sanity 프로젝트를 Claude, Cursor, VS Code와 같은 AI 도구와 연결합니다. 이를 통해 AI 모델이 콘텐츠 구조를 이해하고 자연어 명령을 통해 작업을 수행할 수 있습니다.

✨ 주요 특징

• 🤖 콘텐츠 인텔리전스 : AI가 콘텐츠 라이브러리를 탐색하고 이해하도록 하세요
• 🔄 콘텐츠 운영 : 자연어 지침을 통해 작업 자동화
• 📊 스키마 인식 : AI는 콘텐츠 구조 및 검증 규칙을 존중합니다.
• 🚀 릴리스 관리 : 콘텐츠 릴리스를 손쉽게 계획하고 구성하세요
• 🔍 의미 검색 : 키워드가 아닌 의미에 따라 콘텐츠를 검색합니다.

목차

• 🔌 빠른 시작
  • 필수 조건
  • Sanity MCP 서버에 대한 구성 추가
• 🛠️ 사용 가능한 도구
• ⚙️ 구성
  • 🔑 API 토큰 및 권한
  • 👥 사용자 역할
• 📦 Node.js 환경 설정
  • 🛠 Node Version Manager 사용자를 위한 빠른 설정
  • 🤔 왜 이것이 필요한가요?
  • 🔍 문제 해결
• 💻 개발
  • 디버깅

🔌 빠른 시작

필수 조건

MCP 서버를 사용하려면 다음이 필요합니다.

1. 스키마 매니페스트를 사용하여 Sanity Studio 배포MCP 서버가 효과적으로 작동하려면 콘텐츠 구조에 액세스해야 합니다. 다음 방법 중 하나를 사용하여 스키마 매니페스트를 배포하세요.지엑스피1Sanity 로그인 없이 CI 환경에서 실행하는 경우 인증 토큰을 제공해야 합니다.
   SANITY_AUTH_TOKEN=<token> sanity schema deploy

   [!NOTE] 스키마 배포에는 Sanity CLI 버전 3.88.1 이상이 필요합니다.

2. API 자격 증명을 받으세요
   • 프로젝트 ID
   • 데이터 세트 이름
   • 적절한 권한이 있는 API 토큰

이 MCP 서버는 모델 컨텍스트 프로토콜(MCP)을 지원하는 모든 애플리케이션에서 사용할 수 있습니다. 다음은 몇 가지 일반적인 예입니다.

• 클로드 데스크탑
• 커서 IDE
• 비주얼 스튜디오 코드
• 맞춤형 MCP 호환 애플리케이션

Sanity MCP 서버에 대한 구성 추가

Sanity MCP 서버를 사용하려면 애플리케이션의 MCP 설정에 다음 구성을 추가하세요.

필수 및 선택 환경 변수의 전체 목록은 구성 섹션을 참조하세요.

이 구성의 정확한 위치는 응용 프로그램에 따라 달라집니다.

작동하지 않나요? Node.js 구성 섹션을 참조하세요.

🛠️ 사용 가능한 도구

컨텍스트 및 설정

• get_initial_context – 중요: 컨텍스트를 초기화하고 사용 지침을 얻으려면 다른 도구를 사용하기 전에 호출해야 합니다.
• get_sanity_config – 현재 Sanity 구성(projectId, dataset, apiVersion 등)을 검색합니다.

문서 작업

• create_document – 지침에 따라 AI가 생성한 콘텐츠로 새 문서를 만듭니다.
• update_document – 지침에 따라 AI가 생성한 콘텐츠로 기존 문서 업데이트
• patch_document - AI 생성을 사용하지 않고 문서의 특정 부분을 수정하기 위해 직접 패치 작업을 적용합니다.
• transform_document – 서식과 구조를 유지하면서 문서 내용을 변환합니다. 텍스트 교체 및 스타일 수정에 이상적입니다.
• translate_document – 서식과 구조를 유지하면서 문서 내용을 다른 언어로 번역합니다.
• query_documents – GROQ 쿼리를 실행하여 콘텐츠를 검색하고 검색합니다.
• document_action – 문서 게시, 게시 취소 또는 삭제와 같은 문서 작업 수행

릴리스 관리

• list_releases – 선택적으로 상태별로 필터링된 콘텐츠 릴리스 목록
• create_release – 새로운 콘텐츠 릴리스를 만듭니다.
• edit_release – 기존 릴리스에 대한 메타데이터 업데이트
• schedule_release – 특정 시간에 게시할 릴리스를 예약합니다.
• release_action – 릴리스에 대한 작업 수행(게시, 보관, 보관 취소, 예약 취소, 삭제)

버전 관리

• create_version – 특정 릴리스에 대한 문서 버전을 만듭니다.
• discard_version – 릴리스에서 특정 버전 문서를 삭제합니다.
• mark_for_unpublish – 특정 릴리스가 게시되면 문서를 게시 취소로 표시합니다.

데이터 세트 관리

• get_datasets – 프로젝트의 모든 데이터세트 나열
• create_dataset – 새 데이터 세트 만들기
• update_dataset – 데이터 세트 설정 수정

스키마 정보

• get_schema – 전체 스키마 또는 특정 유형에 대한 스키마 세부 정보를 가져옵니다.
• list_workspace_schemas – 사용 가능한 모든 작업 공간 스키마 이름 목록을 가져옵니다.

GROQ 지원

• get_groq_specification – GROQ 언어 사양 요약을 가져옵니다.

임베딩 및 의미 검색

• list_embeddings_indices – 사용 가능한 모든 임베딩 인덱스를 나열합니다.
• semantic_search – 임베딩 인덱스에 대한 의미 검색 수행

프로젝트 정보

• list_projects – 계정과 관련된 모든 Sanity 프로젝트를 나열합니다.
• get_project_studios – 특정 프로젝트에 연결된 스튜디오 애플리케이션 가져오기

⚙️ 구성

서버는 다음과 같은 환경 변수를 사용합니다.

[!경고] > 프로덕션 데이터세트에 AI 사용 프로덕션 데이터세트에 대한 쓰기 권한이 있는 토큰으로 MCP 서버를 구성하는 경우, AI가 콘텐츠 생성, 업데이트 또는 삭제와 같은 파괴적인 작업을 수행할 수 있다는 점에 유의하십시오. 읽기 전용 토큰을 사용하는 경우에는 문제가 되지 않습니다. 현재 가드레일을 적극적으로 개발하고 있지만, 쓰기 권한이 필요한 AI 작업을 테스트할 때는 개발/스테이징 데이터세트를 사용하는 것이 좋습니다.

🔑 API 토큰 및 권한

MCP 서버가 제대로 작동하려면 적절한 API 토큰과 권한이 필요합니다. 다음 사항을 숙지하세요.

1. 로봇 토큰 생성 :
   • 프로젝트 관리 콘솔로 이동하세요: 설정 > API > 토큰
   • "새 토큰 추가"를 클릭하세요
   • MCP 서버 사용을 위한 전용 토큰을 생성하세요
   • 토큰을 안전하게 보관하세요. 토큰은 한 번만 표시됩니다!
2. 필요한 권한 :
   • 토큰에는 사용에 따라 적절한 권한이 필요합니다.
   • 기본 읽기 작업의 경우: viewer 역할이면 충분합니다.
   • 콘텐츠 관리의 경우 editor 또는 developer 역할 권장
   • 고급 작업(데이터 세트 관리 등)의 경우 administrator 역할이 필요할 수 있습니다.
3. 데이터 세트 접근 :
   • 공개 데이터 세트: 인증되지 않은 사용자가 콘텐츠를 읽을 수 있습니다.
   • 개인 데이터 세트: 적절한 토큰 인증이 필요합니다.
   • 초안 및 버전 관리된 콘텐츠: 적절한 권한이 있는 인증된 사용자만 액세스할 수 있습니다.
4. 보안 모범 사례 :
   • 다양한 환경(개발, 스테이징, 프로덕션)에 대해 별도의 토큰을 사용하세요.
   • 토큰을 버전 제어에 커밋하지 마십시오.
   • 토큰 관리를 위해 환경 변수 사용을 고려하세요
   • 보안을 위해 정기적으로 토큰을 회전하세요

👥 사용자 역할

서버는 두 가지 사용자 역할을 지원합니다.

• 개발자 : 모든 도구에 액세스
• 편집기 : 프로젝트 관리 없이 콘텐츠 중심 도구

📦 Node.js 환경 설정

Node Version Manager 사용자 여러분께 중요 : nvm , mise , fnm , nvm-windows 또는 이와 유사한 도구를 사용하는 경우, MCP 서버가 Node.js에 액세스할 수 있도록 아래 설정 단계를 따라야 합니다. 이는 일회성 설정으로, 나중에 문제 해결 시간을 절약할 수 있습니다. 이는 MCP 서버에서 지속적으로 발생하는 문제 입니다.

🛠 Node Version Manager 사용자를 위한 빠른 설정

1. 먼저, 원하는 Node.js 버전을 활성화하세요.
   # Using nvm nvm use 20 # or your preferred version # Using mise mise use node@20 # Using fnm fnm use 20
2. 그런 다음 필요한 심볼릭 링크를 만듭니다(OS 선택):macOS/Linux의 경우:
   sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx

   [!NOTE] sudo 사용할 때는 일반적으로 주의가 필요하지만 이 컨텍스트에서는 다음과 같은 이유로 안전합니다.

   • 우리는 기존 Node.js 바이너리에 대한 심볼릭 링크만 생성합니다.
   • 대상 디렉토리( /usr/local/bin )는 사용자가 설치한 프로그램에 대한 표준 시스템 위치입니다.
   • 심볼릭 링크는 이미 설치하고 신뢰하는 바이너리만 가리킵니다.
   • 나중에 sudo rm 사용하여 이러한 심볼릭 링크를 쉽게 제거할 수 있습니다.

   Windows(관리자 권한으로 PowerShell 사용):
   New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\node.exe" -Target (Get-Command node).Source -Force New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\npx.cmd" -Target (Get-Command npx).Source -Force
3. 설정을 확인하세요:
   # Should show your chosen Node version /usr/local/bin/node --version # macOS/Linux "C:\Program Files\nodejs\node.exe" --version # Windows

🤔 왜 이것이 필요한가요?

MCP 서버는 node 및 npx 바이너리를 직접 호출하여 시작됩니다. Node 버전 관리자를 사용하는 경우, 이러한 바이너리는 시스템 애플리케이션에서 자동으로 액세스할 수 없는 격리된 환경에서 관리됩니다. 위의 심볼릭 링크는 버전 관리자와 MCP 서버가 사용하는 시스템 경로 사이에 브리지를 생성합니다.

🔍 문제 해결

Node 버전을 자주 전환하는 경우:

• Node 버전을 변경할 때는 심볼릭 링크를 업데이트하는 것을 잊지 마세요.
• 이를 자동화하려면 셸 별칭이나 스크립트를 만들 수 있습니다.
  # Example alias for your .bashrc or .zshrc alias update-node-symlinks='sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx'

나중에 심볼릭 링크를 제거하려면:

💻 개발

종속성 설치:

개발 모드에서 빌드하고 실행:

서버를 빌드하세요:

빌드된 서버를 실행합니다.

디버깅

디버깅을 위해 MCP 검사기를 사용할 수 있습니다.

이를 통해 사용 가능한 도구를 검사하고 테스트할 수 있는 웹 인터페이스가 제공됩니다.