Kontent.ai MCP Server

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

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 – パッチ操作を使用して 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 プランと「Manage custom roles」権限が必要です

ワークフロー管理

• 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 のフック）では、モデルに依存せず、破壊的なツールの実行前に確実に確認を求めるよう設定できます。これはローカルで設定するものであり、サーバー側では強制できません。

これらはあくまでヒントであり、保証ではありません。セキュリティ上の問題は [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>"
      }
    }
}

🌊 Streamable HTTP トランスポート（マルチテナント）

Streamable 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>"

重要

<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 - Streamable HTTP トランスポート用の Express アプリファクトリー
  • server.ts - メインサーバーの設定とツールの登録
  • bin.ts - 両方のトランスポートタイプに対応する単一のエントリーポイント

🔍 デバッグ

デバッグには、MCP inspector を使用できます。

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

または、稼働中の streamable HTTP サーバーで MCP inspector を使用します。

npx @modelcontextprotocol/inspector

利用可能なツールを調査およびテストするためのウェブインターフェースが表示されます。

📦 リリースプロセス

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

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

ライセンス

MIT