contentful-mcp

Contentful MCP Server

Eine MCP-Serverimplementierung, die sich in die Content Management API von Contentful integrieren lässt und umfassende Content-Management-Funktionen bietet.

• Bitte beachten Sie *; wenn Sie nicht am Code interessiert sind und dieses MCP nur in Claude Desktop (oder einem anderen Tool, das MCP-Server verwenden kann) verwenden möchten, müssen Sie dieses Repo nicht klonen, sondern können es einfach in Claude Desktop einrichten. Anweisungen zur Installation finden Sie im Abschnitt „Verwendung mit Claude Desktop“.

Merkmale

• Inhaltsverwaltung : Vollständige CRUD-Operationen für Einträge und Assets
• Raumverwaltung : Erstellen, aktualisieren und verwalten Sie Räume und Umgebungen
• Inhaltstypen : Inhaltstypdefinitionen verwalten
• Lokalisierung : Unterstützung für mehrere Gebietsschemas
• Veröffentlichen : Kontrollieren Sie den Workflow zur Inhaltsveröffentlichung
• Massenvorgänge : Führen Sie Massenveröffentlichungen, -aufhebungen und -validierungen für mehrere Einträge und Assets durch
• Intelligente Paginierung : Listenoperationen geben maximal 3 Elemente pro Anfrage zurück, um einen Überlauf des Kontextfensters zu verhindern, mit integrierter Paginierungsunterstützung

Pagination

Um einen Überlauf des Kontextfensters in LLMs zu verhindern, sind Listenoperationen (wie search_entries und list_assets) auf drei Elemente pro Anfrage begrenzt. Jede Antwort enthält:

• Gesamtzahl der verfügbaren Artikel
• Aktuelle Artikelseite (max. 3)
• Anzahl der verbleibenden Artikel
• Wert für die nächste Seite überspringen
• Meldung, die den LLM auffordert, das Abrufen weiterer Elemente anzubieten

Dieses Paginierungssystem ermöglicht dem LLM die effiziente Verarbeitung großer Datensätze unter Einhaltung der Kontextfenstergrenzen.

Massenvorgänge

Die Funktion für Massenvorgänge ermöglicht die effiziente Verwaltung mehrerer Inhaltselemente gleichzeitig:

• Asynchrone Verarbeitung : Vorgänge werden asynchron ausgeführt und liefern Statusaktualisierungen
• Effizientes Content Management : Verarbeiten Sie mehrere Einträge oder Assets in einem einzigen API-Aufruf
• Statusverfolgung : Überwachen Sie den Fortschritt mit Erfolgs- und Fehlerzählungen
• Ressourcenoptimierung : Reduzieren Sie API-Aufrufe und verbessern Sie die Leistung für Batchvorgänge

Diese Tools für Massenvorgänge eignen sich ideal für Inhaltsmigrationen, Massenaktualisierungen oder Batch-Veröffentlichungs-Workflows.

Werkzeuge

Einlassmanagement

• search_entries : Suche nach Einträgen mithilfe von Abfrageparametern
• create_entry : Neue Einträge erstellen
• get_entry : Vorhandene Einträge abrufen
• update_entry : Eintragsfelder aktualisieren
• delete_entry : Einträge entfernen
• publish_entry : Einträge veröffentlichen
• unpublish_entry : Einträge rückgängig machen

Massenvorgänge

• bulk_publish : Veröffentlichen Sie mehrere Einträge und Assets in einem einzigen Vorgang. Akzeptiert ein Array von Entitäten (Einträge und Assets) und verarbeitet deren Veröffentlichung als Stapel.
• bulk_unpublish : Hebt die Veröffentlichung mehrerer Einträge und Assets in einem einzigen Vorgang auf. Ähnlich wie bulk_publish, entfernt jedoch Inhalte aus der Bereitstellungs-API.
• bulk_validate : Überprüft mehrere Einträge auf Inhaltskonsistenz, Referenzen und Pflichtfelder. Gibt Validierungsergebnisse zurück, ohne den Inhalt zu ändern.

Vermögensverwaltung

• list_assets : Assets mit Seitennummerierung auflisten (3 Elemente pro Seite)
• upload_asset : Neue Assets mit Metadaten hochladen
• get_asset : Assetdetails und -informationen abrufen
• update_asset : Asset-Metadaten und -Dateien aktualisieren
• delete_asset : Assets aus dem Speicherplatz entfernen
• publish_asset : Veröffentlichen Sie Assets in der Bereitstellungs-API
• unpublish_asset : Hebt die Veröffentlichung von Assets aus der Bereitstellungs-API auf

Raum- und Umweltmanagement

• list_spaces : Listet verfügbare Plätze auf
• get_space : Raumdetails abrufen
• list_environments : Umgebungen in einem Bereich auflisten
• create_environment : Neue Umgebung erstellen
• delete_environment : Umgebung entfernen

Inhaltstypverwaltung

• list_content_types : Listet verfügbare Inhaltstypen auf
• get_content_type : Details zum Inhaltstyp abrufen
• create_content_type : Neuen Inhaltstyp erstellen
• update_content_type : Inhaltstyp aktualisieren
• delete_content_type : Inhaltstyp entfernen
• publish_content_type : Einen Inhaltstyp veröffentlichen

Entwicklungstools

MCP-Inspektor

Das Projekt umfasst ein MCP Inspector-Tool, das bei der Entwicklung und beim Debuggen hilft:

• Inspektionsmodus : Führen Sie npm run inspect aus, um den Inspektor zu starten. Sie können den Inspektor öffnen, indem Sie zu http://localhost:5173 gehen.
• Überwachungsmodus : Verwenden Sie npm run inspect:watch , um den Inspektor automatisch neu zu starten, wenn sich Dateien ändern
• Visuelle Schnittstelle : Der Inspector bietet eine Webschnittstelle zum Testen und Debuggen von MCP-Tools
• Echtzeittests : Testen Sie Tools und sehen Sie sich ihre Reaktionen sofort an
• Testen von Massenvorgängen : Testen und überwachen Sie Massenvorgänge mit visuellem Feedback zu Fortschritt und Ergebnissen

Das Projekt enthält außerdem einen npm run dev -Befehl, der den MCP-Server bei jeder Änderung neu erstellt und neu lädt.

Konfiguration

Voraussetzungen

1. Erstellen Sie ein Contentful-Konto bei Contentful
2. Generieren Sie ein Content Management API-Token aus Ihren Kontoeinstellungen

Umgebungsvariablen

Diese Variablen können auch als Argumente gesetzt werden

• CONTENTFUL_HOST / --host : Contentful Management API-Endpunkt (standardmäßig https://api.contentful.com )
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token : Ihr Content Management API-Token
• ENABLE_HTTP_SERVER / --http : Auf „true“ setzen, um den HTTP/SSE-Modus zu aktivieren
• HTTP_PORT / --port : Port für HTTP-Server (Standard: 3000)
• HTTP_HOST / --http-host : Host für HTTP-Server (Standard: localhost)

Raum- und Umweltabgrenzung

Sie können die Space-ID und die Environment-ID festlegen, um sicherzustellen, dass der LLM nur Operationen mit den definierten Space-/Env-IDs durchführt. Dies dient hauptsächlich der Unterstützung von Agenten, die in bestimmten Spaces arbeiten. Wenn sowohl die Umgebungsvariablen SPACE_ID als auch ENVIRONMENT_ID gesetzt sind, melden die Tools diese Werte nicht, und die Handler verwenden die Umgebungsvariablen für CMA-Operationen. Sie verlieren außerdem den Zugriff auf die Tools im Space-Handler, da diese bereichsübergreifend sind. Sie können die SPACE_ID und ENVIRONMENT_ID auch mit den Argumenten --space-id und --environment-id hinzufügen.

Verwenden der App-Identität

Anstatt ein Management-Token bereitzustellen, können Sie auch App Identity für die Authentifizierung nutzen. Dazu müssen Sie eine Contentful App einrichten und installieren und beim Aufruf des MCP-Servers die folgenden Parameter festlegen:

• --app-id = die App-ID, die das Apptoken bereitstellt
• --private-key = der private Schlüssel, den Sie in der Benutzeroberfläche Ihrer App erstellt haben, verknüpft mit app_id
• --space-id = die SpaceId, in der die App installiert ist
• --environment-id = die Umgebungs-ID (innerhalb des Bereichs), in dem die App installiert ist.

Mit diesen Werten fordert der MCP-Server einen temporären AppToken an, um Inhaltsoperationen in der definierten Space/Environment-ID durchzuführen. Dies ist besonders nützlich, wenn dieser MCP-Server in Backend-Systemen verwendet wird, die als MCP-Client fungieren (z. B. Chat-Agenten).

Verwendung mit Claude Desktop

Sie müssen dieses Repo nicht klonen, um dieses MCP zu verwenden. Sie können es einfach zu Ihrer claude_desktop_config.json hinzufügen:

Fügen Sie ~/Library/Application Support/Claude/claude_desktop_config.json hinzu oder bearbeiten Sie es und fügen Sie die folgenden Zeilen hinzu:

Wenn Ihr MCPClient das Festlegen von Umgebungsvariablen nicht unterstützt, können Sie das Verwaltungstoken auch mit einem Argument wie dem folgenden festlegen:

Installation über Smithery

So installieren Sie Contentful Management Server für Claude Desktop automatisch über Smithery :

Entwickeln und Verwenden von Claude Desktop

Wenn Sie mitwirken und testen möchten, was Claude mit Ihren Beiträgen macht;

• Führen Sie npm run dev aus. Dadurch wird der Watcher gestartet, der den MCP-Server bei jeder Änderung neu aufbaut.
• Aktualisieren Sie claude_desktop_config.json um direkt auf das Projekt zu verweisen, d. h.

Dadurch können Sie alle Änderungen am MCP-Server direkt mit Claude testen. Wenn Sie jedoch neue Tools/Ressourcen hinzufügen, müssen Sie Claude Desktop neu starten.

Verkehrsmittel

Der MCP-Server unterstützt zwei Transportmodi:

stdio Transport

Der Standardtransportmodus verwendet Standard-Ein-/Ausgabeströme für die Kommunikation. Dies ist ideal für die Integration mit MCP-Clients, die Standardtransport unterstützen, wie beispielsweise Claude Desktop.

Um den stdio-Modus zu verwenden, führen Sie den Server einfach ohne das Flag --http aus:

StreamableHTTP-Transport

Der Server unterstützt außerdem den im MCP-Protokoll definierten StreamableHTTP-Transport. Dieser Modus ist nützlich für webbasierte Integrationen oder wenn der Server als eigenständiger Dienst ausgeführt wird.

Um den StreamableHTTP-Modus zu verwenden, führen Sie mit dem Flag --http Folgendes aus:

StreamableHTTP-Details

• Verwendet den offiziellen MCP StreamableHTTP-Transport
• Unterstützt Standard-MCP-Protokollvorgänge
• Beinhaltet Sitzungsverwaltung zur Aufrechterhaltung des Status
• Behandelt Initialisierungs-/Benachrichtigungsmuster ordnungsgemäß
• Kompatibel mit Standard-MCP-Clients
• Ersetzt den veralteten SSE-Transport durch den modernen Ansatz

Die Implementierung folgt der Standardspezifikation des MCP-Protokolls und ermöglicht jedem MCP-Client die Verbindung zum Server ohne besondere Behandlung.

Fehlerbehandlung

Der Server implementiert eine umfassende Fehlerbehandlung für:

• Authentifizierungsfehler
• Ratenbegrenzung
• Ungültige Anfragen
• Netzwerkprobleme
• API-spezifische Fehler

Lizenz

MIT-Lizenz

Kleingedrucktes

Dieser MCP-Server ermöglicht es Claude (oder anderen Agenten, die MCP-Ressourcen nutzen können), Inhalte, Bereiche und Inhaltsmodelle zu aktualisieren und zu löschen. Stellen Sie daher sicher, was Sie Claude mit Ihren Contentful-Bereichen erlauben!

Dieser MCP-Server wird von Contentful (noch) nicht offiziell unterstützt