Kontent.ai

Kontent.ai MCP Server

お気に入りのAI対応エディタでの自然言語による会話を通じて、Kontent.aiの構造化コンテンツを作成、管理、探索できるAI搭載ツールで、コンテンツ運用を変革します。

Kontent.ai MCP Serverは、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 Serverを実行できます：

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コンテンツタイプを取得
• 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コンテンツ項目バリアントを更新。要素の値は、コンテンツタイプで定義された制限とガイドラインを満たす必要があります。変更したい要素のみを送信してください。省略した要素は変更されません。コンポーネントを含むリッチテキスト要素の場合は、完全な要素（値と、変更しないコンポーネントを含む完全なcomponents配列）を送信してください
• 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 Web 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ロールを取得。「Manage custom roles」権限を持つ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環境のリクエストを処理できます。

🔒 セキュリティ

間接的なプロンプトインジェクション

このサーバーが返すコンテンツ（例：エディターが書いた要素）には、接続された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 - 汎用エラー送出ユーティリティ
  • 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