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. Management API キー - 適切な権限を持つキーを作成します。
4. 環境 ID - 環境 ID を取得します。

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

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

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 – パッチ操作 (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 – Web サイトやチャネルを管理するための新しい 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 経由で利用不可にする)、オプションのタイムゾーン指定で特定の将来の日時に非公開をスケジュールできます

⚙️ 設定

サーバーは 2 つのモードをサポートし、それぞれトランスポートに関連付けられています:

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

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

📦 リリースプロセス

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

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

ライセンス

MIT