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 を取得します。

🛠 セットアップオプション

Kontent.ai MCP サーバーは npx で実行できます:

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 Web 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 でコンテンツアイテムバリアントのスケジュール公開をキャンセル。この操作は公開がスケジュールされていたバリアントを以前のワークフローステップに戻し、さらなる編集を可能にします。

⚙️ 設定

サーバーは 2 つのモードをサポートしており、各モードはトランスポートに紐づいています:

シングルテナントモード（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

これにより、利用可能なツールを検査およびテストするためのWebインターフェースが提供されます。

📦 リリースプロセス

新しいバージョンをリリースするには：

1. npm version [patch|minor|major]を使用してバージョンを上げます - これによりpackage.json、package-lock.jsonが更新され、server.jsonに同期されます
2. コミットをブランチにプッシュし、プルリクエストを作成します
3. プルリクエストをマージします
4. バージョン番号を名前とタグの両方として使用し、自動生成されたリリースノートを使用して新しいGitHubリリースを作成します
5. リリースを公開すると、npmおよびGitHub MCPレジストリに公開する自動ワークフローがトリガーされます

ライセンス

MIT