Kontent.ai

Kontent.ai MCP 서버

Kontent.ai를 위한 AI 기반 도구로 콘텐츠 운영을 혁신하세요. 선호하는 AI 지원 편집기에서 자연어 대화를 통해 구조화된 콘텐츠를 생성, 관리, 탐색할 수 있습니다.

Kontent.ai MCP 서버는 Model Context Protocol을 구현하여 Kontent.ai 프로젝트를 Claude, Cursor, VS Code와 같은 AI 도구와 연결합니다. AI 모델이 콘텐츠 구조를 이해하고 자연어 지시를 통해 작업을 수행할 수 있도록 지원합니다.

✨ 주요 기능

• 🚀 신속한 프로토타이핑: 다이어그램을 몇 초 만에 실제 콘텐츠 모델로 변환
• 📈 데이터 시각화: 원하는 형식으로 콘텐츠 모델 시각화

목차

• ✨ 주요 기능
• 🔌 빠른 시작
• 🛠️ 사용 가능한 도구
• ⚙️ 구성
• 🔒 보안
• 🚀 전송 옵션
• 💻 개발
  • 🛠 로컬 설치
  • 📂 프로젝트 구조
  • 🔍 디버깅
  • 📦 릴리스 프로세스
• 라이선스

🔌 빠른 시작

🔑 사전 요구 사항

MCP 서버를 사용하기 전에 다음이 필요합니다:

1. Kontent.ai 계정 - 계정이 없으면 가입하세요.
2. 프로젝트 - 작업할 프로젝트 생성.
3. Management API 키 - 적절한 권한이 있는 키 생성.
4. 환경 ID - 환경 ID 확인.

🛠 설정 옵션

npx를 사용하여 Kontent.ai MCP 서버를 실행할 수 있습니다:

STDIO 전송

npx @kontent-ai/mcp-server@latest stdio

스트리밍 HTTP 전송

npx @kontent-ai/mcp-server@latest shttp

🛠️ 사용 가능한 도구

패치 작업 가이드

• get-patch-guide – 🚨 모든 패치 작업 전 필수. 엔티티 유형별 Kontent.ai 패치 작업 가이드 조회

콘텐츠 유형 관리

• get-content-type – ID로 Kontent.ai 콘텐츠 유형 조회
• list-content-types – 모든 Kontent.ai 콘텐츠 유형 조회
• create-content-type – 새 Kontent.ai 콘텐츠 유형 생성
• patch-content-type – 패치 작업(move, addInto, remove, replace)을 사용하여 코드명으로 기존 Kontent.ai 콘텐츠 유형 업데이트
• delete-content-type – ID로 Kontent.ai 콘텐츠 유형 삭제

콘텐츠 유형 스니펫 관리

• get-content-type-snippet – ID로 Kontent.ai 콘텐츠 유형 스니펫 조회
• list-content-type-snippets – 모든 Kontent.ai 콘텐츠 유형 스니펫 조회
• create-content-type-snippet – 새 Kontent.ai 콘텐츠 유형 스니펫 생성
• patch-content-type-snippet – 패치 작업(move, addInto, remove, replace)을 사용하여 ID로 기존 Kontent.ai 콘텐츠 유형 스니펫 업데이트
• delete-content-type-snippet – ID로 Kontent.ai 콘텐츠 유형 스니펫 삭제

분류 체계 관리

• get-taxonomy-group – ID로 Kontent.ai 분류 그룹 조회
• list-taxonomy-groups – 모든 Kontent.ai 분류 그룹 조회
• create-taxonomy-group – 새 Kontent.ai 분류 그룹 생성
• patch-taxonomy-group – 패치 작업(addInto, move, remove, replace)을 사용하여 Kontent.ai 분류 그룹 업데이트
• delete-taxonomy-group – ID로 Kontent.ai 분류 그룹 삭제

콘텐츠 항목 관리

• get-content-item – ID로 Kontent.ai 콘텐츠 항목 조회
• get-content-item-variant – Kontent.ai 콘텐츠 항목 변형(언어 버전/번역) 조회. 현재 버전 반환 — 초안이 있으면 초안, 없으면 게시된 버전
• get-published-content-item-variant-version – Kontent.ai 콘텐츠 항목 변형의 게시된 버전 조회. 최신 초안 버전이 있지만 현재 게시된(라이브) 콘텐츠가 필요할 때 사용
• get-content-item-translations – 모든 Kontent.ai 콘텐츠 항목 번역 조회 — 특정 콘텐츠 항목의 모든 언어 버전(변형)
• list-content-item-variants – 콘텐츠 항목 변형(언어 버전/번역)으로 Kontent.ai 콘텐츠 항목 나열, 필터링, 검색
• create-content-item – 새 Kontent.ai 콘텐츠 항목 생성(컨테이너만 생성, 언어 버전/번역 추가는 create-content-item-variant 사용)
• update-content-item – ID로 기존 Kontent.ai 콘텐츠 항목 업데이트. 콘텐츠 항목이 이미 존재해야 함 - 이 도구는 새 항목을 생성하지 않음
• delete-content-item – ID로 Kontent.ai 콘텐츠 항목 삭제
• create-content-item-variant – 현재 사용자를 기여자로 할당하여 Kontent.ai 콘텐츠 항목 변형 생성. 요소 값은 콘텐츠 유형에 정의된 제한 사항 및 지침을 충족해야 함. 설정하려는 요소만 전송; 생략된 요소는 빈 값으로 초기화
• update-content-item-variant – 콘텐츠 항목의 Kontent.ai 콘텐츠 항목 변형 업데이트. 요소 값은 콘텐츠 유형에 정의된 제한 사항 및 지침을 충족해야 함. 변경하려는 요소만 전송 — 생략된 요소는 그대로 유지. 컴포넌트가 있는 리치 텍스트 요소의 경우 전체 요소(값과 전체 컴포넌트 배열, 변경되지 않은 컴포넌트 포함)를 제출
• create-new-content-item-variant-version – Kontent.ai 콘텐츠 항목 변형의 새 버전 생성. 이 작업은 기존 콘텐츠 항목 변형의 새 버전을 생성하며, 콘텐츠 버전 관리 및 게시된 콘텐츠에서 새 초안 생성에 유용
• delete-content-item-variant – Kontent.ai 콘텐츠 항목 변형 삭제
• bulk-get-content-item-variants – 항목 및 언어 참조 쌍으로 Kontent.ai 콘텐츠 항목과 해당 변형을 대량 조회. list-content-item-variants 후 특정 항목+언어 쌍의 전체 콘텐츠 데이터를 검색하는 데 사용. 요청된 언어에 변형이 없는 항목은 변형 속성 없이 반환. 연속 토큰이 있는 페이지네이션 결과 반환
• search-content-item-variants – 특정 콘텐츠 항목 변형에서 의미와 개념으로 콘텐츠를 찾기 위한 AI 기반 시맨틱 검색. 사용 사례: 정확한 키워드를 모를 때 개념적 검색. 제한된 필터링 옵션(변형 ID만)

자산 관리

• get-asset – ID로 특정 Kontent.ai 자산 조회
• list-assets – 모든 Kontent.ai 자산 조회
• update-asset – ID로 Kontent.ai 자산 업데이트

자산 폴더 관리

• list-asset-folders – 모든 Kontent.ai 자산 폴더 나열
• patch-asset-folders – 패치 작업을 사용하여 Kontent.ai 자산 폴더 수정(새 폴더 추가는 addInto, 이름 변경은 rename, 폴더 삭제는 remove)

언어 관리

• list-languages – 모든 Kontent.ai 언어 조회(활성 및 비활성 모두 포함 - is_active 속성 확인)
• create-language – 새 Kontent.ai 언어 생성(언어는 항상 활성 상태로 생성됨)
• patch-language – replace 작업을 사용하여 Kontent.ai 언어 업데이트(활성 언어만 수정 가능 - 활성화/비활성화는 Kontent.ai 웹 UI 사용)

컬렉션 관리

• list-collections – 모든 Kontent.ai 컬렉션 조회. 컬렉션은 환경 내 콘텐츠 항목의 경계를 설정하고 팀, 브랜드, 프로젝트별로 콘텐츠를 구성하는 데 도움
• patch-collections – 패치 작업을 사용하여 Kontent.ai 컬렉션 업데이트(새 컬렉션 추가는 addInto, 재정렬은 move, 빈 컬렉션 삭제는 remove, 이름 변경은 replace)

공간 관리

• list-spaces – 모든 Kontent.ai 공간 조회
• create-space – 웹사이트 또는 채널 관리를 위한 새 Kontent.ai 공간 생성
• patch-space – replace 작업을 사용하여 Kontent.ai 공간 패치
• delete-space – Kontent.ai 공간 삭제

역할 관리

• list-roles – 모든 Kontent.ai 역할 조회. "사용자 지정 역할 관리" 권한이 있는 Enterprise 또는 Flex 플랜 필요

워크플로우 관리

• list-workflows – 모든 Kontent.ai 워크플로우 조회. 워크플로우는 콘텐츠 수명 주기 단계와 그 사이의 전환을 정의
• create-workflow – 사용자 지정 단계, 전환, 범위, 역할 권한으로 새 Kontent.ai 워크플로우 생성
• update-workflow – ID로 기존 Kontent.ai 워크플로우 업데이트. 단계, 전환, 범위, 역할 권한 수정. 사용 중인 단계는 제거할 수 없음
• delete-workflow – ID로 Kontent.ai 워크플로우 삭제. 워크플로우가 어떤 콘텐츠 항목에서도 사용 중이 아니어야 함
• change-content-item-variant-workflow-step – Kontent.ai에서 콘텐츠 항목 변형의 워크플로우 단계 변경. 이 작업은 콘텐츠 항목 변형을 워크플로우의 다른 단계로 이동하여 초안에서 검토, 검토에서 게시 등 콘텐츠 수명 주기 관리 가능
• publish-content-item-variant – Kontent.ai에서 콘텐츠 항목의 콘텐츠 항목 변형 게시 또는 예약. 이 작업은 변형을 즉시 게시하거나 선택적 시간대 지정과 함께 특정 미래 날짜 및 시간에 게시 예약 가능
• unpublish-content-item-variant – Kontent.ai에서 콘텐츠 항목의 콘텐츠 항목 변형 게시 취소 또는 예약. 이 작업은 변형을 즉시 게시 취소(Delivery API를 통해 사용 불가)하거나 선택적 시간대 지정과 함께 특정 미래 날짜 및 시간에 게시 취소 예약 가능

⚙️ 구성

서버는 각 전송 방식에 연결된 두 가지 모드를 지원합니다:

단일 테넌트 모드 (STDIO)

환경 변수를 통해 자격 증명 구성:

다중 테넌트 모드 (스트리밍 HTTP)

스트리밍 HTTP 전송의 경우 요청별로 자격 증명 제공:

• 환경 ID는 URL 경로 매개변수로: /{environmentId}/mcp
• API 키는 Authorization 헤더의 Bearer 토큰으로: Authorization: Bearer <api-key>

이를 통해 단일 서버 인스턴스가 자격 증명 환경 변수 없이 여러 Kontent.ai 환경에 대한 요청을 처리할 수 있습니다.

🔒 보안

간접 프롬프트 인젝션

이 서버에서 반환된 콘텐츠(예: 편집자가 작성한 요소)에는 연결된 LLM이 지시 사항으로 해석할 수 있는 텍스트가 포함될 수 있습니다 — 간접 프롬프트 인젝션. 하이재킹된 에이전트는 파괴적인 도구 호출(삭제/게시 취소/덮어쓰기)이나 게시되지 않은 초안 유출로 이어질 수 있습니다. 이는 업계 전반의 해결되지 않은 문제로, 서버가 반환하는 콘텐츠를 변환하여 안정적으로 해결할 수 없으므로 방어 계층을 구성합니다:

• 최소 권한의 Management API 키를 사용하세요. 서버는 주어진 키의 권한으로 동작합니다. 읽기 전용 키를 사용하면, 탈취된 에이전트의 파괴적인 호출이 API 경계에서 단순히 실패합니다 — 모델 동작과 무관하게 유지되므로 가장 강력한 제어 수단입니다.
• 인간의 개입을 유지하세요. 모든 도구는 MCP 어노테이션을 포함합니다 — 읽기 작업은 readOnlyHint, 생성 전용 도구는 추가적이며, 데이터를 덮어쓰거나 제거하는 도구는 destructiveHint — 이를 준수하는 클라이언트는 읽기를 자동 승인하고 파괴적인 호출 전에 확인 메시지를 표시합니다. 이러한 클라이언트로 서버를 실행하고 쓰기 가능 키에 대해 헤드리스 자동 승인 설정을 피하세요.
• 클라이언트가 지원하는 경우 클라이언트 측 게이트를 추가하세요. 일부 클라이언트(예: Claude Code 훅)는 모델과 독립적으로 파괴적인 도구 실행 전에 결정론적으로 확인 메시지를 표시할 수 있습니다. 이는 로컬에서 구성되며 서버가 강제할 수 없습니다.

이는 보장이 아닌 힌트입니다. 보안 문제는 비공개로 [email protected]로 보고해 주세요.

🚀 전송 옵션

📟 STDIO 전송

STDIO 전송으로 서버를 실행하려면 MCP 클라이언트를 다음과 같이 구성하세요:

{
  "kontent-ai-stdio": {
      "command": "npx",
      "args": ["@kontent-ai/mcp-server@latest", "stdio"],
      "env": {
        "KONTENT_API_KEY": "<management-api-key>",
        "KONTENT_ENVIRONMENT_ID": "<environment-id>"
      }
    }
}

🌊 스트리밍 가능 HTTP 전송 (멀티 테넌트)

스트리밍 가능 HTTP 전송은 단일 서버 인스턴스에서 여러 Kontent.ai 환경을 제공합니다. 각 요청은 URL 경로 매개변수와 Bearer 인증을 통해 자격 증명을 제공합니다.

먼저 서버를 시작하세요:

npx @kontent-ai/mcp-server@latest shttp

{
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/<environment-id>/mcp",
      "headers": {
        "Authorization": "Bearer <management-api-key>"
      }
    }
  }
}

{
  "inputs": [
    {
      "id": "apiKey",
      "type": "password",
      "description": "Kontent.ai API Key"
    },
    {
      "id": "environmentId",
      "type": "text",
      "description": "Environment ID"
    }
  ],
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/${inputs.environmentId}/mcp",
      "headers": {
        "Authorization": "Bearer ${inputs.apiKey}"
      }
    }
  }
}

{
  "mcpServers": {
    "kontent-ai-multi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/<environment-id>/mcp",
        "--header",
        "Authorization: Bearer <management-api-key>"
      ]
    }
  }
}

claude mcp add --transport http kontent-ai-multi \
  "http://localhost:3001/<environment-id>/mcp" \
  --header "Authorization: Bearer <management-api-key>"

[!IMPORTANT] <environment-id>를 귀하의 Kontent.ai 환경 ID(GUID)로, <management-api-key>을 귀하의 키로 교체하세요.

💻 개발

🛠 로컬 설치

# Clone the repository
git clone https://github.com/kontent-ai/mcp-server.git
cd mcp-server

# Install dependencies
npm ci

# Build the project
npm run build

# Start the server
npm run start:stdio  # For STDIO transport
npm run start:shttp  # For Streamable HTTP transport

# Start the server with automatic reloading (no need to build first)
npm run dev:stdio  # For STDIO transport
npm run dev:shttp  # For Streamable HTTP transport

📂 프로젝트 구조

• src/ - 소스 코드
  • tools/ - MCP 도구 구현
  • clients/ - Kontent.ai API 클라이언트 설정
  • schemas/ - 데이터 검증 스키마
  • utils/ - 유틸리티 함수
    • errorHandler.ts - MCP 도구를 위한 표준화된 오류 처리
    • throwError.ts - 일반 오류 발생 유틸리티
  • server.ts - 메인 서버 설정 및 도구 등록
  • bin.ts - 두 전송 유형을 모두 처리하는 단일 진입점

🔍 디버깅

디버깅을 위해 MCP 인스펙터를 사용할 수 있습니다:

npx @modelcontextprotocol/inspector -e KONTENT_API_KEY=<key> -e KONTENT_ENVIRONMENT_ID=<env-id> node path/to/build/bin.js

또는 실행 중인 스트리밍 가능 HTTP 서버에서 MCP 인스펙터를 사용하세요:

npx @modelcontextprotocol/inspector

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

📦 릴리스 프로세스

새 버전을 릴리스하려면:

1. npm version [patch|minor|major]을 사용하여 버전을 올립니다 - 이는 package.json, package-lock.json를 업데이트하고 server.json에 동기화합니다.
2. 브랜치에 커밋을 푸시하고 풀 리퀘스트를 생성합니다.
3. 풀 리퀘스트를 병합합니다.
4. 버전 번호를 이름과 태그로 사용하고 자동 생성된 릴리스 노트와 함께 새 GitHub 릴리스를 생성합니다.
5. 릴리스 게시는 npm 및 GitHub MCP 레지스트리에 게시하는 자동화된 워크플로를 트리거합니다.

라이선스

MIT