@contentful/mcp-tools

A toolkit package containing reusable MCP (Model Context Protocol) tools for Contentful. This package provides structured tool collections with complete metadata including descriptions, input schemas, semantic annotations, and tool implementations.

Installation

npm install @contentful/mcp-tools

Usage

Using Tool Collections

The package exports tool collections organized by category. Each tool in a collection includes:

• title: The tool name
• description: What the tool does
• inputParams: Zod schema or raw shape for input validation
• annotations: Semantic hints about tool behavior (readOnly, destructive, idempotent, openWorld)
• tool: The actual tool implementation function

import { ContentfulMcpTools } from '@contentful/mcp-tools';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const server = new McpServer({ name: 'my-contentful-mcp', version: '1.0.0' });
const tools = new ContentfulMcpTools({
  accessToken: '<management-token>',
  mcpVersion: '1.0.0',
});

// Register a specific tool
const { searchEntries } = tools.getEntryTools();
server.registerTool(
  searchEntries.title,
  {
    description: searchEntries.description,
    inputSchema: searchEntries.inputParams,
    annotations: searchEntries.annotations,
  },
  searchEntries.tool,
);

// Register all tools from a collection
Object.values(tools.getAssetTools()).forEach((toolConfig) => {
  server.registerTool(
    toolConfig.title,
    {
      description: toolConfig.description,
      inputSchema: toolConfig.inputParams,
      annotations: toolConfig.annotations,
    },
    toolConfig.tool,
  );
});

Data Assembly write inputs

create_data_assembly takes editable configuration without sys, dataType, or variant. The API generates sys.id and infers sys.dataType from return. parameters is an ordered array of declarations with stable id and explicit boolean required. Updates that omit parameters require a canonical array from the current GET response and retain server metadata. Coordinate canonical GET coverage and tool distribution before releasing this array-only contract. This is a breaking input change: callers still passing top-level sys, dataType, or variant receive a validation error. Remove those arguments when upgrading. Nested ResourceLink sys objects remain part of the configuration.

ContentfulMcpTools.getDataAssemblyTools() exposes these tools to MCP hosts. The local server registers ExO tools only when ENABLE_EXO_TOOLS is enabled and the organization has the exoM1 entitlement. The remote server also requires the exoM1 entitlement.

{
  "spaceId": "my-space",
  "environmentId": "master",
  "name": "Page title",
  "description": "A static page title",
  "parameters": [{ "id": "title", "type": "String", "required": false }],
  "resolvers": {},
  "return": { "$object": { "title": { "$literal": "Hello" } } }
}

update_data_assembly takes the assembly ID and the current sys.version from get_data_assembly. Omitted editable fields retain their current values.

{
  "spaceId": "my-space",
  "environmentId": "master",
  "dataAssemblyId": "the-created-sys-id",
  "version": 3,
  "name": "Updated page title"
}

Available Tool Collections

Collections come from ContentfulMcpTools getters such as getEntryTools(), getAssetTools(), getContentTypeTools(), getReleaseTools(), and getDataAssemblyTools(). ExO collections are registered by each server only when its access gates pass.

Tool Annotations

Each tool includes semantic annotations to help MCP clients understand tool behavior:

• readOnlyHint: true if the tool only reads data without modifications
• destructiveHint: true if the tool permanently deletes or removes data
• idempotentHint: true if calling the tool multiple times with the same input produces the same result
• openWorldHint: true if the tool interacts with external services or systems beyond Contentful

🛠️ Available Tools

Configuration

The tools require environment variables to be configured:

CONTENTFUL_MANAGEMENT_ACCESS_TOKEN=your_token_here
CONTENTFUL_HOST=api.contentful.com
SPACE_ID=your_space_id
ENVIRONMENT_ID=master

Testing

All tools include comprehensive unit tests. Run tests with:

npm test

License

MIT