@contentful/mcp-server 1.0.4 → 1.1.0

package/README.md

@@ -48,6 +48,10 @@ This MCP server provides a comprehensive set of tools for content management, al
 
 _Note: This requires [Cursor](https://cursor.com/) to be installed. If the link doesn't work, try the manual installation below._
 
+**Claude Desktop:**
+
+Download the .dxt configuration file [here](https://github.com/contentful/contentful-mcp-server/releases) from the latest release and import it into Claude Desktop to automatically configure the MCP server with your environment variables.
+
 #### Install from source
 
 ```bash

package/build/config/env.js

@@ -4,7 +4,7 @@ dotenv.config();
 const EnvSchema = z.object({
     CONTENTFUL_MANAGEMENT_ACCESS_TOKEN: z
         .string()
-        .describe('Contentul CMA token'),
+        .describe('Contentful CMA token'),
     CONTENTFUL_HOST: z
         .string()
         .optional()
@@ -19,7 +19,7 @@ const EnvSchema = z.object({
         .describe('Contentful environment ID'),
 });
 export const env = EnvSchema.safeParse(process.env);
-if (!env.success) {
+if (!env.success && process.env.TEST_TYPE !== 'unit') {
     console.error('Invalid environment variables', env.error.format());
     process.exit(1);
 }

package/build/tools/ai-actions/mockClient.js

@@ -0,0 +1,228 @@
+import { vi } from 'vitest';
+import { createToolClient } from '../../utils/tools.js';
+import { VariableType, OutputFormat } from '../../utils/ai-actions.js';
+/**
+ * Shared mock objects for AI action tests
+ * Provides standardized mock client and AI action objects used across all AI action tests
+ */
+// Create mock functions for the client
+export const mockAiActionGet = vi.fn();
+export const mockAiActionCreate = vi.fn();
+export const mockAiActionUpdate = vi.fn();
+export const mockAiActionDelete = vi.fn();
+export const mockAiActionPublish = vi.fn();
+export const mockAiActionUnpublish = vi.fn();
+export const mockAiActionGetMany = vi.fn();
+export const mockAiActionInvoke = vi.fn();
+export const mockAiActionInvocationGet = vi.fn();
+/**
+ * Standard mock Contentful client with all AI action operations
+ */
+export const mockClient = {
+    aiAction: {
+        get: mockAiActionGet,
+        create: mockAiActionCreate,
+        update: mockAiActionUpdate,
+        delete: mockAiActionDelete,
+        publish: mockAiActionPublish,
+        unpublish: mockAiActionUnpublish,
+        getMany: mockAiActionGetMany,
+        invoke: mockAiActionInvoke,
+    },
+    aiActionInvocation: {
+        get: mockAiActionInvocationGet,
+    },
+};
+/**
+ * Sets up the mock client for tests
+ * Call this in beforeEach to ensure the mock is properly configured
+ */
+export function setupMockClient() {
+    vi.mocked(createToolClient).mockReturnValue(mockClient);
+}
+/**
+ * Standard mock AI action object used across tests
+ */
+export const mockAiAction = {
+    sys: {
+        id: 'test-ai-action-id',
+        type: 'AiAction',
+        version: 1,
+        space: {
+            sys: {
+                type: 'Link',
+                linkType: 'Space',
+                id: 'test-space-id',
+            },
+        },
+        environment: {
+            sys: {
+                type: 'Link',
+                linkType: 'Environment',
+                id: 'test-environment',
+            },
+        },
+        createdAt: '2023-01-01T00:00:00Z',
+        updatedAt: '2023-01-01T00:00:00Z',
+        publishedVersion: undefined,
+    },
+    name: 'Test AI Action',
+    description: 'A test AI action for unit tests',
+    instruction: {
+        template: 'Translate the following text from {{var.sourceLocale}} to {{var.targetLocale}}: {{var.sourceContent}}',
+        variables: [
+            {
+                id: 'sourceContent',
+                name: 'Source Content',
+                type: VariableType.TEXT,
+                description: 'The content to be translated',
+            },
+            {
+                id: 'sourceLocale',
+                name: 'Source Locale',
+                type: VariableType.LOCALE,
+                description: 'The source language locale',
+            },
+            {
+                id: 'targetLocale',
+                name: 'Target Locale',
+                type: VariableType.LOCALE,
+                description: 'The target language locale',
+            },
+        ],
+    },
+    configuration: {
+        modelType: 'gpt-4',
+        modelTemperature: 0.3,
+    },
+    testCases: [],
+};
+/**
+ * Mock AI action with published version
+ */
+export const mockPublishedAiAction = {
+    ...mockAiAction,
+    sys: {
+        ...mockAiAction.sys,
+        publishedVersion: 1,
+    },
+};
+/**
+ * Standard test arguments for AI action operations
+ */
+export const mockArgs = {
+    spaceId: 'test-space-id',
+    environmentId: 'test-environment',
+    aiActionId: 'test-ai-action-id',
+};
+/**
+ * Mock AI action invocation result
+ */
+export const mockAiActionInvocation = {
+    sys: {
+        id: 'test-invocation-id',
+        type: 'AiActionInvocation',
+        status: 'COMPLETED',
+        createdAt: '2023-01-01T00:00:00Z',
+        updatedAt: '2023-01-01T00:00:00Z',
+    },
+    result: {
+        content: 'Translated content result',
+    },
+};
+/**
+ * Mock AI action invocation status response
+ */
+export const mockInvocationStatusResponse = {
+    sys: {
+        id: 'test-invocation-id',
+        status: 'COMPLETED',
+    },
+    result: {
+        content: 'AI action completed successfully',
+    },
+};
+/**
+ * Mock AI actions list response
+ */
+export const mockAiActionsResponse = {
+    total: 2,
+    skip: 0,
+    limit: 3,
+    items: [
+        mockAiAction,
+        {
+            ...mockAiAction,
+            sys: { ...mockAiAction.sys, id: 'another-ai-action' },
+            name: 'Another AI Action',
+            description: 'Another test AI action',
+        },
+    ],
+};
+/**
+ * Mock variable values for AI action invocation
+ */
+export const mockVariables = [
+    {
+        id: 'sourceContent',
+        value: 'Hello, world!',
+    },
+    {
+        id: 'sourceLocale',
+        value: 'en-US',
+    },
+    {
+        id: 'targetLocale',
+        value: 'es-ES',
+    },
+];
+/**
+ * Mock fields for AI action invocation
+ */
+export const mockInvocationFields = [
+    {
+        outputFormat: OutputFormat.PLAIN_TEXT,
+        variables: mockVariables,
+    },
+];
+/**
+ * Mock complex AI action with all field types
+ */
+export const mockComplexAiAction = {
+    ...mockAiAction,
+    name: 'Complex AI Action',
+    description: 'An AI action with complex variable types',
+    instruction: {
+        template: 'Process content from {{var.entryRef}} with context {{var.smartContext}} for {{var.mediaRef}}',
+        variables: [
+            {
+                id: 'entryRef',
+                name: 'Entry Reference',
+                type: VariableType.REFERENCE,
+                description: 'Reference to a content entry',
+            },
+            {
+                id: 'smartContext',
+                name: 'Smart Context',
+                type: VariableType.SMART_CONTEXT,
+                description: 'AI-powered context understanding',
+            },
+            {
+                id: 'mediaRef',
+                name: 'Media Reference',
+                type: VariableType.MEDIA_REFERENCE,
+                description: 'Reference to media assets',
+            },
+        ],
+    },
+    configuration: {
+        modelType: 'gpt-3.5-turbo',
+        modelTemperature: 0.7,
+    },
+    testCases: [
+        {
+            name: 'Test case 1',
+            variables: {},
+        },
+    ],
+};

package/build/tools/content-types/mockClient.js

@@ -0,0 +1,134 @@
+import { vi } from 'vitest';
+import { createToolClient } from '../../utils/tools.js';
+/**
+ * Shared mock objects for content type tests
+ * Provides standardized mock client and content type objects used across all content type tests
+ */
+// Create mock functions for the client
+export const mockContentTypeGet = vi.fn();
+export const mockContentTypeCreate = vi.fn();
+export const mockContentTypeUpdate = vi.fn();
+export const mockContentTypeDelete = vi.fn();
+export const mockContentTypePublish = vi.fn();
+export const mockContentTypeUnpublish = vi.fn();
+export const mockContentTypeGetMany = vi.fn();
+/**
+ * Standard mock Contentful client with all content type operations
+ */
+export const mockClient = {
+    contentType: {
+        get: mockContentTypeGet,
+        create: mockContentTypeCreate,
+        update: mockContentTypeUpdate,
+        delete: mockContentTypeDelete,
+        publish: mockContentTypePublish,
+        unpublish: mockContentTypeUnpublish,
+        getMany: mockContentTypeGetMany,
+    },
+};
+/**
+ * Sets up the mock client for tests
+ * Call this in beforeEach to ensure the mock is properly configured
+ */
+export function setupMockClient() {
+    vi.mocked(createToolClient).mockReturnValue(mockClient);
+}
+/**
+ * Standard mock content type object used across tests
+ */
+export const mockContentType = {
+    sys: {
+        id: 'test-content-type-id',
+        type: 'ContentType',
+        version: 1,
+        space: {
+            sys: {
+                type: 'Link',
+                linkType: 'Space',
+                id: 'test-space-id',
+            },
+        },
+        environment: {
+            sys: {
+                type: 'Link',
+                linkType: 'Environment',
+                id: 'test-environment',
+            },
+        },
+        createdAt: '2023-01-01T00:00:00Z',
+        updatedAt: '2023-01-01T00:00:00Z',
+    },
+    name: 'Test Content Type',
+    description: 'A test content type for unit tests',
+    displayField: 'title',
+    fields: [
+        {
+            id: 'title',
+            name: 'Title',
+            type: 'Symbol',
+            required: true,
+            localized: false,
+            validations: [],
+        },
+        {
+            id: 'description',
+            name: 'Description',
+            type: 'Text',
+            required: false,
+            localized: false,
+            validations: [],
+        },
+    ],
+};
+/**
+ * Standard test arguments for content type operations
+ */
+export const mockArgs = {
+    spaceId: 'test-space-id',
+    environmentId: 'test-environment',
+    contentTypeId: 'test-content-type-id',
+};
+/**
+ * Mock field definitions for testing
+ */
+export const mockField = {
+    id: 'title',
+    name: 'Title',
+    type: 'Symbol',
+    required: true,
+    localized: false,
+    validations: [],
+};
+export const mockTextField = {
+    id: 'description',
+    name: 'Description',
+    type: 'Text',
+    required: false,
+    localized: false,
+    validations: [],
+};
+export const mockLinkField = {
+    id: 'relatedEntry',
+    name: 'Related Entry',
+    type: 'Link',
+    linkType: 'Entry',
+    required: false,
+    localized: false,
+    validations: [],
+};
+/**
+ * Mock content types list response
+ */
+export const mockContentTypesResponse = {
+    total: 2,
+    skip: 0,
+    limit: 10,
+    items: [
+        mockContentType,
+        {
+            ...mockContentType,
+            sys: { ...mockContentType.sys, id: 'another-content-type' },
+            name: 'Another Content Type',
+        },
+    ],
+};

package/build/tools/entries/mockClient.js

@@ -0,0 +1,78 @@
+import { vi } from 'vitest';
+import { createToolClient } from '../../utils/tools.js';
+/**
+ * Shared mock objects for entry tests
+ * Provides standardized mock client and entry objects used across all entry tests
+ */
+// Create mock functions for the client
+export const mockEntryGet = vi.fn();
+export const mockEntryCreate = vi.fn();
+export const mockEntryUpdate = vi.fn();
+export const mockEntryDelete = vi.fn();
+export const mockEntryPublish = vi.fn();
+export const mockEntryUnpublish = vi.fn();
+export const mockEntryGetMany = vi.fn();
+export const mockBulkActionPublish = vi.fn();
+export const mockBulkActionUnpublish = vi.fn();
+/**
+ * Standard mock Contentful client with all entry operations
+ */
+export const mockClient = {
+    entry: {
+        get: mockEntryGet,
+        create: mockEntryCreate,
+        update: mockEntryUpdate,
+        delete: mockEntryDelete,
+        publish: mockEntryPublish,
+        unpublish: mockEntryUnpublish,
+        getMany: mockEntryGetMany,
+    },
+    bulkAction: {
+        publish: mockBulkActionPublish,
+        unpublish: mockBulkActionUnpublish,
+    },
+};
+/**
+ * Sets up the mock client for tests
+ * Call this in beforeEach to ensure the mock is properly configured
+ */
+export function setupMockClient() {
+    vi.mocked(createToolClient).mockReturnValue(mockClient);
+}
+/**
+ * Standard mock entry object used across tests
+ */
+export const mockEntry = {
+    sys: {
+        id: 'test-entry-id',
+        type: 'Entry',
+        contentType: {
+            sys: {
+                id: 'test-content-type',
+                type: 'Link',
+                linkType: 'ContentType',
+            },
+        },
+        version: 1,
+    },
+    fields: {
+        title: { 'en-US': 'Test Entry Title' },
+        description: { 'en-US': 'Test Entry Description' },
+    },
+};
+/**
+ * Standard test arguments for entry operations
+ */
+export const mockArgs = {
+    spaceId: 'test-space-id',
+    environmentId: 'test-environment',
+    entryId: 'test-entry-id',
+};
+/**
+ * Standard test arguments for bulk operations
+ */
+export const mockBulkArgs = {
+    spaceId: 'test-space-id',
+    environmentId: 'test-environment',
+    entryId: ['entry-1', 'entry-2'],
+};

package/build/tools/entries/publishEntry.js

@@ -17,27 +17,19 @@ async function tool(args) {
     const entryIds = Array.isArray(args.entryId) ? args.entryId : [args.entryId];
     // For single entry, use individual publish for simplicity
     if (entryIds.length === 1) {
-        try {
-            const entryId = entryIds[0];
-            const params = {
-                ...baseParams,
-                entryId,
-            };
-            // Get the entry first
-            const entry = await contentfulClient.entry.get(params);
-            // Publish the entry
-            const publishedEntry = await contentfulClient.entry.publish(params, entry);
-            return createSuccessResponse('Entry published successfully', {
-                status: publishedEntry.sys.status,
-                entryId,
-            });
-        }
-        catch (error) {
-            return createSuccessResponse('Entry publish failed', {
-                status: error,
-                entryId: entryIds[0],
-            });
-        }
+        const entryId = entryIds[0];
+        const params = {
+            ...baseParams,
+            entryId,
+        };
+        // Get the entry first
+        const entry = await contentfulClient.entry.get(params);
+        // Publish the entry
+        const publishedEntry = await contentfulClient.entry.publish(params, entry);
+        return createSuccessResponse('Entry published successfully', {
+            status: publishedEntry.sys.status,
+            entryId,
+        });
     }
     // For multiple entries, use bulk action API
     // Get the current version of each entry

package/build/tools/entries/unpublishEntry.js

@@ -15,29 +15,21 @@ async function tool(args) {
     const contentfulClient = createToolClient(args);
     // Normalize input to always be an array
     const entryIds = Array.isArray(args.entryId) ? args.entryId : [args.entryId];
-    // For single entry, use individual publish for simplicity
+    // For single entry, use individual unpublish for simplicity
     if (entryIds.length === 1) {
-        try {
-            const entryId = entryIds[0];
-            const params = {
-                ...baseParams,
-                entryId,
-            };
-            // Get the entry first
-            const entry = await contentfulClient.entry.get(params);
-            // Unpublish the entry
-            const unpublishedEntry = await contentfulClient.entry.unpublish(params, entry);
-            return createSuccessResponse('Entry unpublished successfully', {
-                status: unpublishedEntry.sys.status,
-                entryId,
-            });
-        }
-        catch (error) {
-            return createSuccessResponse('Entry unpublish failed', {
-                status: error,
-                entryId: entryIds[0],
-            });
-        }
+        const entryId = entryIds[0];
+        const params = {
+            ...baseParams,
+            entryId,
+        };
+        // Get the entry first
+        const entry = await contentfulClient.entry.get(params);
+        // Unpublish the entry
+        const unpublishedEntry = await contentfulClient.entry.unpublish(params, entry);
+        return createSuccessResponse('Entry unpublished successfully', {
+            status: unpublishedEntry.sys.status,
+            entryId,
+        });
     }
     // For multiple entries, use bulk action API
     // Get the unversioned links for each entry (unpublish doesn't need version info)

package/build/tools/locales/createLocale.js

@@ -6,7 +6,7 @@ export const CreateLocaleToolParams = BaseToolSchema.extend({
     code: z.string().describe('The locale code (e.g., "en-US")'),
     fallbackCode: z
         .string()
-        .optional()
+        .nullable()
         .describe('The locale code to fallback to when there is no content for the current locale'),
     contentDeliveryApi: z
         .boolean()

package/build/tools/register.js

@@ -1,6 +1,6 @@
 import { registerContextTools } from './context/register.js';
 import { registerEntriesTools } from './entries/register.js';
-import { registerContentTypesTools } from './types/register.js';
+import { registerContentTypesTools } from './content-types/register.js';
 import { registerEnvironmentTools } from './environments/register.js';
 import { registerAssetTools } from './assets/register.js';
 import { registerSpaceTools } from './spaces/register.js';

package/build/types/fieldSchema.js

@@ -5,8 +5,8 @@ export const FieldSchema = z.object({
     type: z
         .string()
         .describe('The field type (e.g., "Symbol", "Text", "Integer", "Boolean", "Date", "Location", "Link", "Array", "Object")'),
-    required: z.boolean().optional().describe('Whether the field is required'),
-    localized: z.boolean().optional().describe('Whether the field is localized'),
+    required: z.boolean().describe('Whether the field is required'),
+    localized: z.boolean().describe('Whether the field is localized'),
     disabled: z.boolean().optional().describe('Whether the field is disabled'),
     omitted: z
         .boolean()
@@ -14,6 +14,7 @@ export const FieldSchema = z.object({
         .describe('Whether the field is omitted from the API response'),
     validations: z.array(z.any()).optional().describe('Field validations'),
     settings: z.record(z.any()).optional().describe('Field-specific settings'),
+    defaultValue: z.any().optional().describe('Default value for the field'),
     linkType: z
         .string()
         .optional()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/mcp-server",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/contentful/contentful-mcp-server"
@@ -18,7 +18,8 @@
     "npm": ">=10.0.0"
   },
   "scripts": {
-    "build": "tsc",
+    "clean": "rimraf build",
+    "build": "npm run clean && tsc",
     "dev": "nodemon --ext ts --ignore build/ --watch src/ --exec 'npm run build && npm start'",
     "format": "prettier --write .",
     "lint": "eslint .",
@@ -43,6 +44,7 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@anthropic-ai/dxt": "^0.2.6",
     "@commitlint/cli": "^19.8.1",
     "@commitlint/config-conventional": "^19.8.1",
     "@modelcontextprotocol/inspector": "0.16.2",
@@ -57,6 +59,7 @@
     "nx": "^21.3.5",
     "prettier": "^3.6.2",
     "pretty-quick": "^4.2.2",
+    "rimraf": "^6.0.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.8.2",
     "vitest": "^3.2.4"