@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 for input validation
• annotations: Semantic hints about tool behavior (readOnly, destructive, idempotent, openWorld)
• tool: The actual tool implementation function

import { entryTools, assetTools, contextTools } from '@contentful/mcp-tools';
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const server = new McpServer();

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

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

Available Tool Collections

import {
  aiActionTools, // AI action management
  assetTools, // Asset operations
  contentTypeTools, // Content type management
  contextTools, // Initial context setup
  entryTools, // Entry operations
  environmentTools, // Environment management
  jobTools, // Long-running jobs
  localeTools, // Locale management
  orgTools, // Organization operations
  spaceTools, // Space operations
  tagTools, // Tag management
  taxonomyTools, // Taxonomy/concept scheme operations
} from '@contentful/mcp-tools';

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

| Category | Tool Name | Description | | ------------------------- | ---------------------------------- | ------------------------------------------------ | | Context & Setup | get_initial_context | Initialize connection and get usage instructions | | Content Types | list_content_types | List content types (max 10 per request) | | | get_content_type | Get detailed content type information | | | create_content_type | Create new content types | | | update_content_type | Modify existing content types | | | publish_content_type | Publish content type changes | | | unpublish_content_type | Unpublish content types | | | delete_content_type | Remove content types | | Entries | search_entries | Search and filter entries in your space | | | get_entry | Retrieve specific entries | | | create_entry | Create new content entries with locale support | | | update_entry | Modify existing entries with locale support | | | publish_entry | Publish entries (single or bulk up to 100) | | | unpublish_entry | Unpublish entries (single or bulk up to 100) | | | delete_entry | Remove entries | | Editor Interfaces | list_editor_interfaces | List all editor interfaces in a space | | | get_editor_interface | Get editor interface for a content type | | | update_editor_interface | Update field controls, sidebars, and layouts | | Assets | upload_asset | Upload new assets | | | list_assets | List and browse assets (max 3 per request) | | | get_asset | Retrieve specific assets | | | update_asset | Modify asset metadata | | | publish_asset | Publish assets (single or bulk up to 100) | | | unpublish_asset | Unpublish assets (single or bulk up to 100) | | | delete_asset | Remove assets | | Spaces & Environments | list_spaces | List available spaces (max 10 per request) | | | get_space | Get space details | | | list_environments | List environments in a space | | | create_environment | Create new environments | | | delete_environment | Remove environments | | Locales | list_locales | List all locales in your environment | | | get_locale | Retrieve specific locale information | | | create_locale | Create new locales for multi-language content | | | update_locale | Modify existing locale settings | | | delete_locale | Remove locales from environment | | Tags | list_tags | List all tags in an environment | | | create_tag | Create new tags with public/private visibility | | Organizations | list_orgs | List organizations user has access to | | | get_org | Get details of a specific organization | | AI Actions | create_ai_action | Create custom AI-powered workflows | | | invoke_ai_action | Invoke AI action with variables (bulk support) | | | get_ai_action_invocation | Get AI action invocation details | | | get_ai_action | Retrieve AI action details and configuration | | | list_ai_actions | List AI actions in a space (max 3 per request) | | | update_ai_action | Update existing AI actions | | | publish_ai_action | Publish AI actions for use | | | unpublish_ai_action | Unpublish AI actions | | | delete_ai_action | Remove AI actions | | Taxonomy Concepts | create_concept | Create new taxonomy concepts with localization | | | get_concept | Retrieve specific taxonomy concept | | | list_concepts | List concepts with filtering and hierarchy | | | update_concept | Update taxonomy concept properties | | | delete_concept | Remove taxonomy concepts | | Taxonomy Schemes | create_concept_scheme | Create new taxonomy concept schemes | | | get_concept_scheme | Retrieve specific concept scheme | | | list_concept_schemes | List concept schemes with pagination | | | update_concept_scheme | Update concept scheme properties | | | delete_concept_scheme | Remove concept schemes | | Space Migration | space_to_space_migration_handler | Enable/disable space migration workflow | | | space_to_space_param_collection | Collect parameters for migration workflow | | | export_space | Export space to file for migration | | | import_space | Import space from exported file |

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