contentful-mcp

コンテンツフル MCP サーバー

Contentful のコンテンツ管理 API と統合し、包括的なコンテンツ管理機能を提供する MCP サーバー実装。

• ご注意ください *; コードに興味がなく、この MCP を Claude Desktop (または MCP サーバーを使用できるその他のツール) で使用したいだけの場合は、このリポジトリを複製する必要はなく、Claude Desktop でセットアップするだけで済みます。インストール方法については、「Claude Desktop での使用」セクションを参照してください。

特徴

• コンテンツ管理: エントリとアセットの完全なCRUD操作
• スペース管理: スペースと環境を作成、更新、管理します
• コンテンツタイプ: コンテンツタイプの定義を管理する
• ローカライズ: 複数のロケールのサポート
• 公開: コンテンツ公開ワークフローを制御する
• 一括操作: 複数のエントリとアセットにわたって一括公開、非公開、検証を実行します。
• スマートページネーション: リスト操作は、コンテキストウィンドウのオーバーフローを防ぐために、組み込みのページネーションサポートを使用して、リクエストごとに最大3つのアイテムを返します。

ページネーション

LLMにおけるコンテキストウィンドウのオーバーフローを防ぐため、リスト操作（search_entriesやlist_assetsなど）はリクエストごとに3項目までに制限されています。各レスポンスには以下が含まれます。

• 利用可能なアイテムの合計数
• 現在のアイテムページ（最大 3 件）
• 残りのアイテム数
• 次のページのスキップ値
• LLMにさらなるアイテムの取得を提案するよう促すメッセージ

このページ区切りシステムにより、LLM はコンテキスト ウィンドウの制限を維持しながら大規模なデータセットを効率的に処理できます。

一括操作

一括操作機能により、複数のコンテンツ項目を同時に効率的に管理できます。

• 非同期処理: 操作は非同期的に実行され、ステータスの更新が提供されます
• 効率的なコンテンツ管理: 1回のAPI呼び出しで複数のエントリまたはアセットを処理
• ステータス追跡: 成功と失敗の数で進捗状況を監視
• リソースの最適化: API呼び出しを減らし、バッチ操作のパフォーマンスを向上

これらの一括操作ツールは、コンテンツの移行、大量更新、バッチ公開ワークフローに最適です。

ツール

入場管理

• search_entries : クエリパラメータを使用してエントリを検索する
• create_entry : 新しいエントリを作成する
• get_entry : 既存のエントリを取得する
• update_entry : エントリフィールドを更新する
• delete_entry : エントリを削除する
• publish_entry : エントリを公開する
• unpublish_entry : エントリを非公開にする

一括操作

• bulk_publish : 複数のエントリとアセットを1回の操作で公開します。エンティティ（エントリとアセット）の配列を受け取り、それらの公開を一括処理します。
• bulk_unpublish : 複数のエントリとアセットを1回の操作で非公開にします。bulk_publish と似ていますが、配信APIからコンテンツを削除します。
• bulk_validate : 複数のエントリのコンテンツの一貫性、参照、必須フィールドを検証します。コンテンツを変更せずに検証結果を返します。

資産運用管理

• list_assets : ページ区切りでアセットを一覧表示します（1 ページあたり 3 項目）
• upload_asset : メタデータを含む新しいアセットをアップロードする
• get_asset : 資産の詳細と情報を取得する
• update_asset : アセットのメタデータとファイルを更新する
• delete_asset : スペースからアセットを削除する
• publish_asset : アセットを配信APIに公開する
• unpublish_asset : 配信 API からアセットを非公開にする

宇宙と環境管理

• list_spaces : 利用可能なスペースを一覧表示する
• get_space : スペースの詳細を取得する
• list_environments : スペース内の環境を一覧表示する
• create_environment : 新しい環境を作成する
• delete_environment : 環境を削除する

コンテンツタイプ管理

• list_content_types : 利用可能なコンテンツタイプを一覧表示する
• get_content_type : コンテンツタイプの詳細を取得する
• create_content_type : 新しいコンテンツタイプを作成する
• update_content_type : コンテンツタイプの更新
• delete_content_type : コンテンツタイプを削除する
• publish_content_type : コンテンツタイプを公開する

開発ツール

MCP検査官

このプロジェクトには、開発とデバッグに役立つ MCP Inspector ツールが含まれています。

• インスペクターモード: npm run inspectを実行してインスペクターを起動します。http ://localhost:5173にアクセスしてインスペクターを開くことができます。
• ウォッチモード: npm run inspect:watchを使用すると、ファイルが変更されたときにインスペクターが自動的に再起動されます。
• ビジュアルインターフェース: インスペクターは、MCPツールをテストおよびデバッグするためのWebインターフェースを提供します。
• リアルタイムテスト: ツールを試して、その反応をすぐに確認します
• 一括操作のテスト: 進捗状況と結果の視覚的なフィードバックを使用して一括操作をテストおよび監視します。

このプロジェクトには、変更のたびに MCP サーバーを再構築して再ロードするnpm run devコマンドも含まれています。

構成

前提条件

1. ContentfulでContentfulアカウントを作成する
2. アカウント設定からコンテンツ管理APIトークンを生成する

環境変数

これらの変数は引数として設定することもできる

• CONTENTFUL_HOST / --host : Contentful 管理 API エンドポイント (デフォルトはhttps://api.contentful.com )
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token : コンテンツ管理APIトークン
• ENABLE_HTTP_SERVER / --http : HTTP/SSEモードを有効にするには「true」に設定します
• HTTP_PORT / --port : HTTPサーバーのポート（デフォルト: 3000）
• HTTP_HOST / --http-host : HTTPサーバーのホスト（デフォルト: localhost）

宇宙と環境のスコープ

spaceIdとEnvironmentIdのスコープを設定することで、LLMが定義された空間/環境IDに対してのみ操作SPACE_ID実行するようにすることができます。これは主に、特定の空間内で動作するエージェントをサポートするためです。SPACE_IDとENVIRONMENT_ID両方の環境変数が設定されている場合、ツールはこれらの値が必要であることを報告せず、ハンドラーは環境変数を使用してCMA操作を実行します。また、これらのツールは複数の空間にまたがるため、空間ハンドラー内のツールへのアクセスも失われます。-- --space-idおよび--environment-id引数を使用して、 SPACE_IDとENVIRONMENT_IDを追加することもできます。

アプリIDの使用

管理トークンを提供する代わりに、 App Identityを利用して認証を処理することもできます。Contentfulアプリをセットアップしてインストールし、MCPサーバーを呼び出す際に以下のパラメータを設定する必要があります。

• --app-id = Apptokenを提供しているアプリID
• --private-key = アプリのユーザーインターフェースで作成した、 app_idに紐付けられた秘密鍵
• --space-id = アプリがインストールされているスペースID
• --environment-id = アプリがインストールされている環境 ID (スペース内)。

これらの値により、MCPサーバーは定義された空間/環境IDでコンテンツ操作を行うために一時的なAppTokenを要求します。これは、MCPクライアント（チャットエージェントなど）として機能するバックエンドシステムでこのMCPサーバーを使用する場合に特に便利です。

Claude Desktopでの使用

この MCP を使用するためにこのリポジトリをクローンする必要はありませんclaude_desktop_config.jsonに追加するだけです。

~/Library/Application Support/Claude/claude_desktop_config.jsonを追加または編集し、次の行を追加します。

MCPClient が環境変数の設定をサポートしていない場合は、次のような引数を使用して管理トークンを設定することもできます。

Smithery経由でインストール

Smithery経由で Claude Desktop 用の Contentful Management Server を自動的にインストールするには:

Claudeデスクトップの開発と使用

あなたが貢献して、Claude があなたの貢献によって何を行うかをテストしたい場合;

• npm run devを実行すると、変更ごとに MCP サーバーを再構築するウォッチャーが起動します。
• プロジェクトを直接参照するようにclaude_desktop_config.jsonを更新します。

これにより、MCPサーバーの変更をClaudeで直接テストできるようになります。ただし、新しいツール/リソースを追加する場合は、Claude Desktopを再起動する必要があります。

輸送モード

MCP サーバーは、次の 2 つのトランスポート モードをサポートしています。

stdioトランスポート

デフォルトのトランスポートモードでは、通信に標準入出力ストリームを使用します。これは、Claude Desktop などの標準入出力トランスポートをサポートする MCP クライアントとの統合に最適です。

stdio モードを使用するには、 --httpフラグなしでサーバーを実行するだけです。

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

サーバーは、MCPプロトコルで定義されているStreamableHTTPトランスポートもサポートしています。このモードは、Webベースの統合や、サーバーをスタンドアロンサービスとして実行する場合に役立ちます。

StreamableHTTP モードを使用するには、 --httpフラグを付けて実行します。

StreamableHTTPの詳細

• 公式MCP StreamableHTTPトランスポートを使用
• 標準MCPプロトコル操作をサポート
• 状態を維持するためのセッション管理が含まれています
• 初期化/通知パターンを適切に処理します
• 標準MCPクライアントと互換性あり
• 廃止されたSSEトランスポートを最新のアプローチに置き換えます

実装は標準の MCP プロトコル仕様に準拠しており、特別な処理なしで任意の MCP クライアントがサーバーに接続できます。

エラー処理

サーバーは、以下に対する包括的なエラー処理を実装します。

• 認証失敗
• レート制限
• 無効なリクエスト
• ネットワークの問題
• API固有のエラー

ライセンス

MITライセンス

細則

このMCPサーバーは、Claude（またはMCPリソースを消費できる他のエージェント）がコンテンツ、スペース、コンテンツモデルを更新、削除できるようにします。そのため、ContentfulスペースでClaudeにどのような操作を許可するかは慎重に検討してください。

このMCPサーバーはContentfulによって公式にサポートされていません（まだ）