MCP Server

🚀 Kontent.ai MCP Server

Kontent.ai用のAIパワードツールを使って、コンテンツ運用を変革しましょう。好きなAI対応エディタで自然言語会話を通じて、構造化されたコンテンツを作成、管理、探索します。

Kontent.ai MCP Serverは、Model Context Protocolを実装して、Kontent.aiプロジェクトをClaude、Cursor、VS CodeなどのAIツールに接続します。これにより、AIモデルがコンテンツ構造を理解し、自然言語命令を通じて操作を実行できるようになります。

✨ 主な機能

• 🚀 迅速なプロトタイピング：数秒でダイアグラムを実際のコンテンツモデルに変換します。
• 📈 データ可視化：好きな形式でコンテンツモデルを可視化します。

🚀 クイックスタート

🔑 前提条件

MCPサーバーを使用する前に、以下が必要です。

1. Kontent.aiアカウント - アカウントがない場合は、こちらからサインアップしてください。
2. プロジェクト - 作業するためのプロジェクトを作成してください。
3. 管理APIキー - 適切な権限を持つ管理APIキーを作成してください。
4. 環境ID - 環境IDを取得してください。

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

Kontent.ai MCP Serverは、npxを使って実行できます。

STDIOトランスポート

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

ストリーミング可能なHTTPトランスポート

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

🛠️ 利用可能なツール

パッチ操作ガイド

• get-patch-guide – 🚨 パッチ操作を行う前に必須。エンティティタイプごとにKontent.ai管理APIのパッチ操作ガイドを取得します。

コンテンツタイプ管理

• get-type-mapi – 管理APIから内部IDでKontent.aiコンテンツタイプを取得します。
• list-content-types-mapi – 管理APIからすべてのKontent.aiコンテンツタイプを取得します。
• add-content-type-mapi – 管理APIを介して新しいKontent.aiコンテンツタイプを追加します。
• patch-content-type-mapi – パッチ操作（移動、追加、削除、置換）を使用して、コード名で既存のKontent.aiコンテンツタイプを更新します。
• delete-content-type-mapi – コード名でKontent.aiコンテンツタイプを削除します。

コンテンツタイプスニペット管理

• get-type-snippet-mapi – 管理APIから内部IDでKontent.aiコンテンツタイプスニペットを取得します。
• list-content-type-snippets-mapi – 管理APIからすべてのKontent.aiコンテンツタイプスニペットを取得します。
• add-content-type-snippet-mapi – 管理APIを介して新しいKontent.aiコンテンツタイプスニペットを追加します。
• patch-type-snippet-mapi – パッチ操作（移動、追加、削除、置換）を使用して、内部IDで既存のKontent.aiコンテンツタイプスニペットを更新します。
• delete-type-snippet-mapi – コード名でKontent.aiコンテンツタイプスニペットを削除します。

タクソノミー管理

• get-taxonomy-group-mapi – 管理APIから内部IDでKontent.aiタクソノミーグループを取得します。
• list-taxonomy-groups-mapi – 管理APIからすべてのKontent.aiタクソノミーグループを取得します。
• add-taxonomy-group-mapi – 管理APIを介して新しいKontent.aiタクソノミーグループを追加します。
• patch-taxonomy-group-mapi – パッチ操作（追加、移動、削除、置換）を使用して、管理APIを介してKontent.aiタクソノミーグループを更新します。
• delete-taxonomy-group-mapi – 内部IDでKontent.aiタクソノミーグループを削除します。

コンテンツアイテム管理

• get-item-mapi – 管理APIから内部IDでKontent.aiアイテムを取得します。
• get-latest-variant-mapi – 管理APIからKontent.ai言語バリアントの最新バージョンを取得します。
• get-published-variant-mapi – 管理APIからKontent.ai言語バリアントの公開バージョンを取得します。
• list-variants-item-mapi – 管理APIからコンテンツアイテムのすべてのKontent.ai言語バリアントをリストします。
• list-variants-collection-mapi – 管理APIからコレクションごとにKontent.ai言語バリアントをリストします（ページングあり）。
• list-variants-type-mapi – 管理APIからコンテンツタイプごとにKontent.ai言語バリアントをリストします（ページングあり）。
• list-variants-components-type-mapi – 管理APIから特定のコンテンツタイプのコンポーネントを含むKontent.ai言語バリアントをリストします（ページングあり）。
• list-variants-space-mapi – 管理APIからスペースごとにKontent.ai言語バリアントをリストします（ページングあり）。
• add-content-item-mapi – 管理APIを介して新しいKontent.aiコンテンツアイテムを追加します。これにより、コンテンツアイテムの構造が作成されますが、言語バリアントにコンテンツは追加されません。upsert-language-variant-mapiを使用して、アイテムにコンテンツを追加してください。
• update-content-item-mapi – 管理APIを介して内部IDで既存のKontent.aiコンテンツアイテムを更新します。コンテンツアイテムはすでに存在している必要があります - このツールは新しいアイテムを作成しません。
• delete-content-item-mapi – 管理APIから内部IDでKontent.aiコンテンツアイテムを削除します。
• upsert-language-variant-mapi – 管理APIを介してコンテンツアイテムのKontent.ai言語バリアントを作成または更新します。要素値は、コンテンツタイプで定義された制限とガイドラインを満たす必要があります。更新時には、提供された要素のみが変更されます。
• create-variant-version-mapi – 管理APIを介してKontent.ai言語バリアントの新しいバージョンを作成します。この操作により、既存の言語バリアントの新しいバージョンが作成され、コンテンツのバージョン管理や公開コンテンツからの新しいドラフトの作成に役立ちます。
• delete-language-variant-mapi – 管理APIからKontent.ai言語バリアントを削除します。
• filter-variants-mapi – 管理APIを使用して、コンテンツアイテムのKontent.ai言語バリアントをフィルタリングします。正確なキーワードマッチングやコンテンツ内の特定の用語を検索するために使用します。完全なフィルタリング機能（コンテンツタイプ、ワークフローステップ、タクソノミーなど）をサポートし、必要に応じてバリアントの完全なコンテンツを含めます。続きのページを取得するための継続トークン付きでページングされた結果を返します。
• search-variants-mapi – 特定の言語バリアント内の意味と概念によるコンテンツ検索のためのAIパワードセマンティック検索。正確なキーワードがわからない場合の概念検索に使用します。限られたフィルタリングオプション（バリアントIDのみ）。

アセット管理

• get-asset-mapi – 管理APIから内部IDで特定のKontent.aiアセットを取得します。
• list-assets-mapi – 管理APIからすべてのKontent.aiアセットを取得します。
• update-asset-mapi – 内部IDでKontent.aiアセットを更新します。

アセットフォルダ管理

• list-asset-folders-mapi – すべてのKontent.aiアセットフォルダをリストします。
• patch-asset-folders-mapi – パッチ操作（新しいフォルダを追加するためのaddInto、名前を変更するためのrename、フォルダを削除するためのremove）を使用して、Kontent.aiアセットフォルダを変更します。

言語管理

• list-languages-mapi – 管理APIからすべてのKontent.ai言語を取得します。
• add-language-mapi – 管理APIを介して新しいKontent.ai言語を追加します。
• patch-language-mapi – 置換操作を使用して、管理APIを介してKontent.ai言語を更新します。

コレクション管理

• list-collections-mapi – 管理APIからすべてのKontent.aiコレクションを取得します。コレクションは、環境内のコンテンツアイテムの境界を設定し、チーム、ブランド、またはプロジェクトごとにコンテンツを整理するのに役立ちます。
• patch-collections-mapi – パッチ操作（新しいコレクションを追加するためのaddInto、並べ替えるためのmove、空のコレクションを削除するためのremove、名前を変更するためのreplace）を使用して、Kontent.aiコレクションを更新します。

スペース管理

• list-spaces-mapi – 管理APIからすべてのKontent.aiスペースを取得します。
• add-space-mapi – 環境にKontent.aiスペースを追加します。
• patch-space-mapi – 置換操作を使用して、Kontent.aiスペースをパッチします。
• delete-space-mapi – Kontent.aiスペースを削除します。

ワークフロー管理

• list-workflows-mapi – 管理APIからすべてのKontent.aiワークフローを取得します。ワークフローは、コンテンツのライフサイクル段階とそれらの間の遷移を定義します。
• change-variant-workflow-step-mapi – Kontent.aiで言語バリアントのワークフローステップを変更します。この操作により、言語バリアントがワークフローの別のステップに移動され、ドラフトからレビュー、レビューから公開などのコンテンツライフサイクル管理が可能になります。
• publish-variant-mapi – Kontent.aiでコンテンツアイテムの言語バリアントを公開または公開予定を設定します。この操作により、バリアントを即時公開するか、特定の将来の日付と時刻に（オプションでタイムゾーンを指定して）公開予定を設定できます。
• unpublish-variant-mapi – Kontent.aiでコンテンツアイテムの言語バリアントを非公開または非公開予定を設定します。この操作により、バリアントを即時非公開（配信APIを通じて利用できなくなります）するか、特定の将来の日付と時刻に（オプションでタイムゾーンを指定して）非公開予定を設定できます。

⚙️ 設定

サーバーは2つの設定モードをサポートしています。

シングルテナントモード（デフォルト）

シングルテナントモードの場合、環境変数を設定します。

マルチテナントモード

マルチテナントモード（ストリーミング可能なHTTPのみ）の場合、サーバーは以下を受け入れます。

• 環境IDをURLパスパラメータとして: /{environmentId}/mcp
• APIキーをAuthorizationヘッダーのBearerトークンで: Authorization: Bearer <api-key>

このモードでは、単一のサーバーインスタンスが複数のKontent.ai環境のリクエストを安全に処理でき、環境変数を必要としません。

🔧 レスポンス最適化

MCPサーバーは、AIモデルのコストを削減し、パフォーマンスを向上させるために、自動トークン最適化を実装しています。

トークン削減戦略

サーバーは、レスポンスから空の/デフォルトの値を自動的に削除して、トークンの使用量を削減します。これには以下が含まれます。

• Nullおよび未定義の値
• 空の文字列 ("")
• 空の配列 ([])
• 空のオブジェクト ({})
• リッチテキストのプレースホルダ ("<p><br/></p>")
• 空の値を削除した後にIDのみが残っている要素

AIエージェントへの影響

AI実装に重要: このMCPサーバーからのレスポンスを消費する際には、以下の点に注意してください。

1. 欠落しているプロパティはデフォルト値を示し、欠落しているデータではありません。
2. バリアント内の欠落している要素には、そのタイプ固有のデフォルト値があります。
   • テキスト要素: ""（空の文字列）
   • リッチテキスト: "<p><br/></p>"（空のプレースホルダ）
   • 数値/日付: null
   • カスタム要素: null（値と検索可能な値）
   • 配列（アセット、タクソノミーなど）: []
3. コンテンツを作成/更新する際には、常に完全なデータを送信してください。

🚀 トランスポートオプション

📟 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トランスポートの場合、まずサーバーを起動します。

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

シングルテナントモード

.envファイル内の環境変数、またはプロセスがアクセス可能な他の方法で設定します。

KONTENT_API_KEY=<management-api-key>
KONTENT_ENVIRONMENT_ID=<environment-id>
PORT=3001  # オプション、デフォルトは3001

次に、MCPクライアントを設定します。

{
  "kontent-ai-http": {
    "url": "http://localhost:3001/mcp"
  }
}

マルチテナントモード

環境変数は必要ありません。サーバーは、URLパスパラメータとBearer認証を使用して、複数の環境のリクエストを受け入れます。

{
  "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>をあなたの管理APIキーに置き換えてください。

💻 開発

🛠 ローカルインストール

# リポジトリをクローン
git clone https://github.com/kontent-ai/mcp-server.git
cd mcp-server

# 依存関係をインストール
npm ci

# プロジェクトをビルド
npm run build

# サーバーを起動
npm run start:stdio  # STDIOトランスポートの場合
npm run start:shttp  # ストリーミング可能なHTTPトランスポートの場合

# 自動リロードでサーバーを起動（最初にビルドする必要はありません）
npm run dev:stdio  # STDIOトランスポートの場合
npm run dev:shttp  # ストリーミング可能なHTTPトランスポートの場合

📂 プロジェクト構造

• 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