Kontent.ai

Kontent.ai MCP 서버

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

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

✨ 주요 기능

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

목차

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

🔌 빠른 시작

🔑 사전 요구 사항

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

1. Kontent.ai 계정 - 계정이 없다면 가입하세요.
2. 프로젝트 - 작업할 프로젝트 생성.
3. 관리 API 키 - 적절한 권한으로 키 생성.
4. 환경 ID - 환경 ID 가져오기.

🛠 설정 옵션

npx로 Kontent.ai MCP 서버를 실행할 수 있습니다:

STDIO 전송

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

Streamable HTTP 전송

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

🛠️ 사용 가능한 도구

패치 작업 가이드

• get-patch-guide – 🚨 패치 작업 전 필수. 엔티티 유형별 Kontent.ai 패치 작업 가이드 가져오기

콘텐츠 유형 관리

• get-content-type – ID로 Kontent.ai 콘텐츠 유형 가져오기
• list-content-types – 모든 Kontent.ai 콘텐츠 유형 가져오기
• list-content-type-usages – 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 – 패치 작업(addInto로 새 폴더 추가, rename으로 이름 변경, remove로 폴더 삭제)으로 Kontent.ai 자산 폴더 수정

언어 관리

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

컬렉션 관리

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

공간 관리

• 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를 통해 사용 불가능하게)하거나 선택적 시간대 지정과 함께 특정 미래 날짜 및 시간에 게시 취소하도록 예약할 수 있음
• cancel-scheduled-publishing-content-item-variant – Kontent.ai에서 콘텐츠 항목 변형의 예약된 게시 취소. 이 작업은 게시 예약된 변형을 이전 워크플로 단계로 되돌려 추가 편집을 가능하게 함

⚙️ 구성

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

단일 테넌트 모드 (STDIO)

환경 변수로 자격 증명 구성:

다중 테넌트 모드 (Streamable HTTP)

Streamable HTTP 전송의 경우 자격 증명은 요청별로 제공됩니다:

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

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

KONTENT_API_KEY 및 KONTENT_ENVIRONMENT_ID는 서버 환경에 설정되어 있어도 이 전송에서 무시됩니다. 모든 요청은 자체 자격 증명을携带해야 하며, 없는 요청은 서버의 자격 증명으로 처리되지 않고 거부됩니다.

🔒 보안

간접 프롬프트 주입

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

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

이것들은 힌트이지 보장이 아닙니다. 보안 문제는 비공개로 security@kontent.ai에 보고하세요.

🚀 전송 옵션

📟 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 - 일반 오류 발생 유틸리티
  • app.ts - 스트리밍 가능한 HTTP 전송용 Express 앱 팩토리
  • 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