Contentful Operations Gateway Server

Important Notice

This implementation is maintained by the community. Contentful has provided an official counterpart, accessible through this repository link.

This Management Protocol (MCP) server extension furnishes comprehensive content administration capabilities by interfacing directly with Contentful's Content Management API suite.

• Note: For users who only wish to employ this gateway within Claude Desktop or compatible MCP clients, cloning the repository is unnecessary. Configuration details for direct setup are available in the "Client Integration Instructions" section.

Core Capabilities

• Content Manipulation: Complete lifecycle management (CRUD) for content entries and digital assets.
• Annotation Handling: Creation, fetching, and lifecycle management for entry annotations, supporting both plain text and structured rich text formats, including nested conversational threads.
• Workspace Administration: Provisioning, updating, and overseeing Contentful spaces and their associated environments.
• Schema Definition: Management of content type blueprints.
• Internationalization: Full interoperability across multiple configured locales.
• Deployment Control: Governance over the content publishing pipeline.
• Batch Processing: Execution of mass publication, retraction, and data validation actions across numerous items.
• Context-Aware Paging: List operations are artificially capped at three items per retrieval request to mitigate LLM context window saturation, featuring intrinsic support for sequential fetching.

Data Paging Mechanism

To safeguard the operational context window of Large Language Models (LLMs), retrieval calls (such as search_entries or list_assets) are constrained to a maximum of three results per invocation. Every response structure incorporates:

• The aggregate count of all available records.
• The current subset of results (limited to three).
• The remaining record count.
• The 'skip' offset parameter required for the subsequent query.
• A descriptive prompt guiding the LLM on requesting further data.

This systematic paging ensures efficient traversal of expansive datasets while adhering strictly to memory constraints.

Bulk Operation Utilities

The batch processing feature enables streamlined mass modification of numerous content entities:

• Asynchronous Execution: Operations execute independently, furnishing real-time progress updates.
• High-Efficiency Content Handling: Process substantial volumes of entries or assets within a consolidated API transaction.
• Progress Monitoring: Track execution flow via aggregated success and failure metrics.
• Resource Optimization: Minimize external API calls, substantially enhancing throughput for large-scale workflows.

These bulk execution utilities are optimized for content migration projects, sweeping content updates, and scheduled batch deployment routines.

Available Toolsets

Entry Administration

• search_entries: Query entries based on specified parameters.
• create_entry: Instantiate new content entries.
• get_entry: Fetch details of an existing entry.
• update_entry: Modify the field values of an entry.
• delete_entry: Permanently remove entries.
• publish_entry: Promote entries to the live delivery environment.
• unpublish_entry: Retract entries from the live delivery environment.

Annotation Management

• get_comments: Fetch associated annotations for an entry, filterable by lifecycle status (active, resolved, all).
• create_comment: Introduce new annotations to entries, supporting both text and rich-text bodies. Supports structured reply chains via the optional parent comment identifier.
• get_single_comment: Retrieve a solitary annotation using its unique identifier.
• delete_comment: Erase a specific annotation from an entry.
• update_comment: Modify the content or status of an existing annotation.

Conversational Threading

Annotations support nested replies to facilitate organized discussion and overcome potential message length constraints (e.g., 512 characters):

• Reply Initiation: Utilize the parent field within create_comment to target an existing annotation for a reply.
• Thread Construction: Build complex discussion trees by referencing preceding annotation IDs in the parent parameter.
• Extended Dialogue: Enable protracted conversations by chaining replies within a thread, circumventing single-message length caps.
• Context Retention: Preserve conversational flow by organizing related comments into discernible threads.

Example Sequence:

1. Initiate main annotation: Invoke create_comment with entryId, body, and status.
2. Respond to main: Invoke create_comment supplying entryId, body, status, and the ID of the comment just created as the parent.
3. Continue the discussion: Use the ID of any annotation in the chain as the parent for the next reply.

Batch Processing Functions

• bulk_publish: Initiate simultaneous publication for an array of entries and assets.
• bulk_unpublish: Execute mass retraction for content items from the delivery API.
• bulk_validate: Perform consistency checks on multiple entries regarding field requirements and references, returning results without altering content.

Asset Administration

• list_assets: Retrieve asset listings with mandated three-item per-page pagination.
• upload_asset: Introduce new digital assets along with associated metadata.
• get_asset: Fetch detailed metadata for a specific asset.
• update_asset: Modify asset file contents or descriptive metadata.
• delete_asset: Purge assets from the Contentful space.
• publish_asset: Make assets available via the delivery API.
• unpublish_asset: Remove assets from delivery API access.

Space & Environment Administration

• list_spaces: Enumerate all accessible Contentful workspaces.
• get_space: Retrieve configuration details for a workspace.
• list_environments: List all isolated environments within a workspace.
• create_environment: Provision a new development environment.
• delete_environment: Decommission an existing environment.

Content Type Definition Management

• list_content_types: Fetch definitions of all content models.
• get_content_type: Retrieve the schema details for a single content model.
• create_content_type: Define a new content model structure.
• update_content_type: Modify an existing content model structure.
• delete_content_type: Remove a content model definition.
• publish_content_type: Deploy a content model to be active.

Development Utilities

MCP Debugging Inspector

This project incorporates an Inspector utility designed to aid in development and troubleshooting of the MCP services:

• Inspection Mode Activation: Execute npm run inspect to initialize the inspector interface, accessible via http://localhost:5173.
• Auto-Reload Mode: Use npm run inspect:watch to trigger automatic inspector restarts upon file modification.
• Graphical Interface: The inspector offers a web-based environment for testing and debugging the gateway tools.
• Instantaneous Validation: Perform tool invocations and observe immediate response outcomes.
• Batch Testing Feedback: Visually monitor the execution progress and results of bulk operations.

The repository also includes the npm run dev command, which continuously rebuilds and reloads the MCP gateway whenever source files are altered.

System Setup

Prerequisites

1. Establish a Contentful account at Contentful Platform.
2. Generate and secure a Content Management API access credential from your settings panel.

Environment Variables & CLI Arguments

These settings can be provided either via environment variables or corresponding command-line flags:

• CONTENTFUL_HOST / --host: The base URL for the Contentful Management API (default: https://api.contentful.com).
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token: Your primary CMA access token.
• ENABLE_HTTP_SERVER / --http: Set to "true" to activate the StreamableHTTP/SSE transport layer.
• HTTP_PORT / --port: The network port for the HTTP server (default: 3000).
• HTTP_HOST / --http-host: The hostname interface for the HTTP server (default: localhost).

Context Scoping (Space/Environment)

You can pre-set the spaceId and EnvironmentId to restrict the LLM's actions solely to the defined context. If both SPACE_ID and ENVIRONMENT_ID environment variables are present, the tools will operate using these values without prompting the user, and space-level tools outside this scope will become inaccessible.

These identifiers can also be passed via arguments: --space-id and --environment-id.

Utilizing App Identity Authentication

As an alternative to using a long-lived Management token, this server supports authentication via Contentful's App Identity framework:

• --app-id: The unique identifier for the installed Contentful App.
• --private-key: The cryptographic private key generated within the app setup interface.
• --space-id: The workspace identifier where the app is installed.
• --environment-id: The specific environment within that workspace targeted for operations.

Supplying these parameters causes the MCP server to securely acquire a short-lived AppToken, enabling content operations within the specified context. This is particularly beneficial for backend systems or agents functioning as MCP clients.

Integration with Claude Desktop

Direct repository cloning is unnecessary for Claude Desktop integration. The server can be easily added via modification of your claude_desktop_config.json file:

Edit or create ~/Library/Application Support/Claude/claude_desktop_config.json and include:

{ "mcpServers": { "contentful": { "command": "npx", "args": ["-y", "@ivotoby/contentful-management-mcp-server"], "env": { "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "" } } } }

If your client environment restricts environment variable setting, the token can be supplied via CLI arguments instead:

{ "mcpServers": { "contentful": { "command": "npx", "args": [ "-y", "@ivotoby/contentful-management-mcp-server", "--management-token", "", "--host", "http://api.contentful.com" ] } } }

Automated Installation via Smithery

To deploy the Contentful Management Server to Claude Desktop automatically using Smithery:

bash npx -y @smithery/cli install @ivotoby/contentful-management-mcp-server --client claude

Local Development and Client Testing

To test local code changes directly within the Claude Desktop environment:

• Execute npm run dev to initiate the watcher that triggers server rebuilds on file changes.
• Update claude_desktop_config.json to point to your local executable path, for instance:

{ "mcpServers": { "contentful": { "command": "node", "args": ["/path/to/your/project/bin/mcp-server.js"], "env": { "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "" } } } }

This method allows immediate testing of modifications. However, introducing new tool definitions may necessitate a full restart of the Claude Desktop application.

Communication Protocols

The gateway supports two distinct transport mechanisms for client interaction:

stdio (Standard Input/Output) Transport

This is the default operational mode, utilizing standard system I/O streams for communication. It is optimized for clients like Claude Desktop that natively support stdio interaction.

To invoke stdio mode, run the server without the HTTP flag:

bash npx -y contentful-mcp --management-token YOUR_TOKEN

Alternatively

npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN

StreamableHTTP Transport

The server also implements the StreamableHTTP transport mechanism defined in the MCP specification. This is suitable for web-based services or deployment as a standalone API endpoint.

Activate StreamableHTTP mode using the --http flag:

bash npx -y contentful-mcp --management-token YOUR_TOKEN --http --port 3000

Alternatively

npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN --http --port 3000

StreamableHTTP Technical Details

• Adheres strictly to the official MCP StreamableHTTP transport specification.
• Supports all standard MCP protocol operations.
• Incorporates robust session state management.
• Correctly manages the initialize/notify communication sequences.
• Fully interoperable with standard MCP consuming clients.
• Replaces the legacy SSE mechanism with this modern, standard approach.

The underlying implementation strictly follows the MCP protocol specification, ensuring seamless connectivity with any compliant client.

Robust Error Management

The server incorporates comprehensive exception handling for scenarios including:

• API credential authentication failures.
• Server rate-limiting enforcement.
• Malformed request payloads.
• Underlying network communication failures.
• Contentful API-specific error codes.

Licensing

MIT License

Critical Disclaimer

This MCP Gateway grants agents (like Claude) the capability to modify, archive, or eliminate content, workspace configurations, and content models within your Contentful organization. Exercise extreme caution regarding the permissions granted to the consuming agent!

This specific MCP server is currently not officially endorsed or supported by Contentful.

WIKIPEDIA: Business management tools encompass the systems, applications, controls, computational solutions, and methodologies utilized by enterprises to navigate market fluctuations, maintain competitive advantage, and enhance overall operational efficiency.

== General Context == Tools are departmentalized and categorized based on specific management functions, such as strategic planning, operational workflow management, record-keeping, human resources management, decision support, and performance oversight. A functional breakdown highlights:

Tools for data capture and verification across organizational units. Systems for monitoring and optimizing organizational procedures. Platforms for aggregating data to facilitate strategic decision-making. Modern business tools have undergone profound transformation in the last decade due to rapid technological acceleration, making the selection of optimal solutions for any company context increasingly complex. This complexity stems from the perpetual drive to reduce overhead and boost revenue, the necessity of deeply understanding client demands, and the commitment to delivering products that precisely meet those requirements. In this dynamic environment, management must adopt a strategic viewpoint regarding business tools, prioritizing careful selection and customization over adopting the newest release. Over-reliance on off-the-shelf tools without organizational alignment often leads to instability. Business management tools must be chosen judiciously and then tailored to fit the specific needs of the organization, rather than forcing the organization to conform to the tool's structure.

== Prevalent Tools (2013 Survey) == In 2013, a study by Bain & Company mapped the global utilization of business tools, reflecting how their outputs addressed regional needs amid market conditions:

The leading ten tools identified were:

Strategic planning frameworks Customer relationship management systems Personnel satisfaction measurement Competitive benchmarking practices Balanced scorecard implementation Core competency identification Outsourcing strategies Organizational change programs Supply chain optimization Mission and vision statement articulation Market segmentation analysis Total quality management protocols

== Business Software Applications == Software or integrated suites used by personnel to execute various corporate functions are termed business software (or business applications). These applications are designed to augment productivity, precisely measure performance, and conduct diverse corporate tasks. This category evolved from early Management Information Systems (MIS) to Enterprise Resource Planning (ERP) systems. Subsequently, Customer Relationship Management (CRM) capabilities were integrated, leading to the current landscape of cloud-based business management platforms. While a demonstrable link exists between IT investment and organizational performance, two factors are crucial for value realization: the efficacy of the deployment process and the appropriateness of the tool selection and adaptation methodology.

== Solutions for Small and Medium Enterprises (SMEs) == Tools tailored for SMEs are vital as they offer avenues for cost minimization and operational streamlining...