@contentful/mcp-server 1.0.0 → 1.0.2

package/build/tools/tags/listTags.js

@@ -1,50 +0,0 @@
-import { z } from 'zod';
-import { createSuccessResponse, withErrorHandling, } from '../../utils/response.js';
-import { BaseToolSchema, createToolClient } from '../../utils/tools.js';
-import { summarizeData } from '../../utils/summarizer.js';
-export const ListTagsToolParams = BaseToolSchema.extend({
-    limit: z.number().optional().describe('Maximum number of tags to return'),
-    skip: z.number().optional().describe('Skip this many tags for pagination'),
-    select: z
-        .string()
-        .optional()
-        .describe('Comma-separated list of fields to return'),
-    order: z.string().optional().describe('Order tags by this field'),
-});
-async function tool(args) {
-    const params = {
-        spaceId: args.spaceId,
-        environmentId: args.environmentId,
-    };
-    const contentfulClient = createToolClient(args);
-    const tags = await contentfulClient.tag.getMany({
-        ...params,
-        query: {
-            limit: args.limit || 100,
-            skip: args.skip || 0,
-            ...(args.select && { select: args.select }),
-            ...(args.order && { order: args.order }),
-        },
-    });
-    const summarizedTags = tags.items.map((tag) => ({
-        id: tag.sys.id,
-        name: tag.name,
-        visibility: tag.sys.visibility,
-        createdAt: tag.sys.createdAt,
-        updatedAt: tag.sys.updatedAt,
-    }));
-    const summarized = summarizeData({
-        ...tags,
-        items: summarizedTags,
-    }, {
-        maxItems: 100,
-        remainingMessage: 'To see more tags, please ask me to retrieve the next page using the skip parameter.',
-    });
-    return createSuccessResponse('Tags retrieved successfully', {
-        tags: summarized,
-        total: tags.total,
-        limit: tags.limit,
-        skip: tags.skip,
-    });
-}
-export const listTagsTool = withErrorHandling(tool, 'Error listing tags');

package/build/tools/tags/register.js

@@ -1,6 +0,0 @@
-import { listTagsTool, ListTagsToolParams } from './listTags.js';
-import { createTagTool, CreateTagToolParams } from './createTag.js';
-export function registerTagsTools(server) {
-    server.tool('list_tags', 'List all tags in a space. Returns all tags that exist in a given environment.', ListTagsToolParams.shape, listTagsTool);
-    server.tool('create_tag', 'Creates a new tag and returns it. Both name and ID must be unique to each environment. Tag names can be modified after creation, but the tag ID cannot. The tag visibility can be set to public or private, defaulting to private if not specified.', CreateTagToolParams.shape, createTagTool);
-}

package/build/tools/types/createContentType.js

@@ -1,33 +0,0 @@
-import { z } from 'zod';
-import { createSuccessResponse, withErrorHandling, } from '../../utils/response.js';
-import { BaseToolSchema, createToolClient } from '../../utils/tools.js';
-import { FieldSchema } from '../../types/fieldSchema.js';
-export const CreateContentTypeToolParams = BaseToolSchema.extend({
-    name: z.string().describe('The name of the content type'),
-    displayField: z.string().describe('The field ID to use as the display field'),
-    description: z
-        .string()
-        .optional()
-        .describe('Description of the content type'),
-    fields: z
-        .array(FieldSchema)
-        .describe('Array of field definitions for the content type'),
-});
-async function tool(args) {
-    const params = {
-        spaceId: args.spaceId,
-        environmentId: args.environmentId,
-    };
-    const contentfulClient = createToolClient(args);
-    // Create the content type
-    const contentType = await contentfulClient.contentType.create(params, {
-        name: args.name,
-        displayField: args.displayField,
-        description: args.description,
-        fields: args.fields,
-    });
-    return createSuccessResponse('Content type created successfully', {
-        contentType,
-    });
-}
-export const createContentTypeTool = withErrorHandling(tool, 'Error creating content type');

package/build/tools/types/deleteContentType.js

@@ -1,20 +0,0 @@
-import { z } from 'zod';
-import { createSuccessResponse, withErrorHandling, } from '../../utils/response.js';
-import { BaseToolSchema, createToolClient } from '../../utils/tools.js';
-export const DeleteContentTypeToolParams = BaseToolSchema.extend({
-    contentTypeId: z.string().describe('The ID of the content type to delete'),
-});
-async function tool(args) {
-    const params = {
-        spaceId: args.spaceId,
-        environmentId: args.environmentId,
-        contentTypeId: args.contentTypeId,
-    };
-    const contentfulClient = createToolClient(args);
-    // Delete the content type
-    await contentfulClient.contentType.delete(params);
-    return createSuccessResponse('Content type deleted successfully', {
-        contentTypeId: args.contentTypeId,
-    });
-}
-export const deleteContentTypeTool = withErrorHandling(tool, 'Error deleting content type');

package/build/tools/types/getContentType.js

@@ -1,24 +0,0 @@
-import { z } from 'zod';
-import { createSuccessResponse, withErrorHandling, } from '../../utils/response.js';
-import { BaseToolSchema, createToolClient } from '../../utils/tools.js';
-export const GetContentTypeToolParams = BaseToolSchema.extend({
-    contentTypeId: z
-        .string()
-        .describe('The ID of the content type to retrieve details for'),
-});
-async function tool(args) {
-    const params = {
-        spaceId: args.spaceId,
-        environmentId: args.environmentId,
-    };
-    const contentfulClient = createToolClient(args);
-    // Get the content type details
-    const contentType = await contentfulClient.contentType.get({
-        ...params,
-        contentTypeId: args.contentTypeId,
-    });
-    return createSuccessResponse('Content type retrieved successfully', {
-        contentType,
-    });
-}
-export const getContentTypeTool = withErrorHandling(tool, 'Error retrieving content type');

package/build/tools/types/listContentTypes.js

@@ -1,59 +0,0 @@
-import { z } from 'zod';
-import { createSuccessResponse, withErrorHandling, } from '../../utils/response.js';
-import { BaseToolSchema, createToolClient } from '../../utils/tools.js';
-import { summarizeData } from '../../utils/summarizer.js';
-export const ListContentTypesToolParams = BaseToolSchema.extend({
-    limit: z
-        .number()
-        .optional()
-        .describe('Maximum number of content types to return (max 10)'),
-    skip: z
-        .number()
-        .optional()
-        .describe('Skip this many content types for pagination'),
-    select: z
-        .string()
-        .optional()
-        .describe('Comma-separated list of fields to return'),
-    include: z
-        .number()
-        .optional()
-        .describe('Include this many levels of linked entries'),
-    order: z.string().optional().describe('Order content types by this field'),
-});
-async function tool(args) {
-    const params = {
-        spaceId: args.spaceId,
-        environmentId: args.environmentId,
-    };
-    const contentfulClient = createToolClient(args);
-    const contentTypes = await contentfulClient.contentType.getMany({
-        ...params,
-        query: {
-            limit: Math.min(args.limit || 10, 10),
-            skip: args.skip || 0,
-            ...(args.select && { select: args.select }),
-            ...(args.include && { include: args.include }),
-            ...(args.order && { order: args.order }),
-        },
-    });
-    const summarizedContentTypes = contentTypes.items.map((contentType) => ({
-        ...contentType,
-        id: contentType.sys.id,
-        fieldsCount: contentType.fields.length,
-    }));
-    const summarized = summarizeData({
-        ...contentTypes,
-        items: summarizedContentTypes,
-    }, {
-        maxItems: 10,
-        remainingMessage: 'To see more content types, please ask me to retrieve the next page using the skip parameter.',
-    });
-    return createSuccessResponse('Content types retrieved successfully', {
-        contentTypes: summarized,
-        total: contentTypes.total,
-        limit: contentTypes.limit,
-        skip: contentTypes.skip,
-    });
-}
-export const listContentTypesTool = withErrorHandling(tool, 'Error listing content types');

package/build/tools/types/publishContentType.js

@@ -1,22 +0,0 @@
-import { z } from 'zod';
-import { createSuccessResponse, withErrorHandling, } from '../../utils/response.js';
-import { BaseToolSchema, createToolClient } from '../../utils/tools.js';
-export const PublishContentTypeToolParams = BaseToolSchema.extend({
-    contentTypeId: z.string().describe('The ID of the content type to publish'),
-});
-async function tool(args) {
-    const params = {
-        spaceId: args.spaceId,
-        environmentId: args.environmentId,
-        contentTypeId: args.contentTypeId,
-    };
-    const contentfulClient = createToolClient(args);
-    // Get the content type first
-    const currentContentType = await contentfulClient.contentType.get(params);
-    // Publish the content type
-    const contentType = await contentfulClient.contentType.publish(params, currentContentType);
-    return createSuccessResponse('Content type published successfully', {
-        contentType,
-    });
-}
-export const publishContentTypeTool = withErrorHandling(tool, 'Error publishing content type');

package/build/tools/types/register.js

@@ -1,16 +0,0 @@
-import { getContentTypeTool, GetContentTypeToolParams, } from './getContentType.js';
-import { listContentTypesTool, ListContentTypesToolParams, } from './listContentTypes.js';
-import { createContentTypeTool, CreateContentTypeToolParams, } from './createContentType.js';
-import { updateContentTypeTool, UpdateContentTypeToolParams, } from './updateContentType.js';
-import { deleteContentTypeTool, DeleteContentTypeToolParams, } from './deleteContentType.js';
-import { publishContentTypeTool, PublishContentTypeToolParams, } from './publishContentType.js';
-import { unpublishContentTypeTool, UnpublishContentTypeToolParams, } from './unpublishContentType.js';
-export function registerContentTypesTools(server) {
-    server.tool('get_content_type', 'Get details about a specific Contentful content type', GetContentTypeToolParams.shape, getContentTypeTool);
-    server.tool('list_content_types', 'List content types in a space. Returns a maximum of 10 items per request. Use skip parameter to paginate through results.', ListContentTypesToolParams.shape, listContentTypesTool);
-    server.tool('create_content_type', 'Create a new content type', CreateContentTypeToolParams.shape, createContentTypeTool);
-    server.tool('update_content_type', 'Update an existing content type. The handler will merge your field updates with existing content type data, so you only need to provide the fields and properties you want to change.', UpdateContentTypeToolParams.shape, updateContentTypeTool);
-    server.tool('delete_content_type', 'Delete a content type', DeleteContentTypeToolParams.shape, deleteContentTypeTool);
-    server.tool('publish_content_type', 'Publish a content type', PublishContentTypeToolParams.shape, publishContentTypeTool);
-    server.tool('unpublish_content_type', 'Unpublish a content type', UnpublishContentTypeToolParams.shape, unpublishContentTypeTool);
-}

package/build/tools/types/unpublishContentType.js

@@ -1,20 +0,0 @@
-import { z } from 'zod';
-import { createSuccessResponse, withErrorHandling, } from '../../utils/response.js';
-import { BaseToolSchema, createToolClient } from '../../utils/tools.js';
-export const UnpublishContentTypeToolParams = BaseToolSchema.extend({
-    contentTypeId: z.string().describe('The ID of the content type to unpublish'),
-});
-async function tool(args) {
-    const params = {
-        spaceId: args.spaceId,
-        environmentId: args.environmentId,
-        contentTypeId: args.contentTypeId,
-    };
-    const contentfulClient = createToolClient(args);
-    // Unpublish the content type
-    const contentType = await contentfulClient.contentType.unpublish(params);
-    return createSuccessResponse('Content type unpublished successfully', {
-        contentType,
-    });
-}
-export const unpublishContentTypeTool = withErrorHandling(tool, 'Error unpublishing content type');

package/build/tools/types/updateContentType.js

@@ -1,78 +0,0 @@
-import { z } from 'zod';
-import { createSuccessResponse, withErrorHandling, } from '../../utils/response.js';
-import { BaseToolSchema, createToolClient } from '../../utils/tools.js';
-import { FieldSchema } from '../../types/fieldSchema.js';
-export const UpdateContentTypeToolParams = BaseToolSchema.extend({
-    contentTypeId: z.string().describe('The ID of the content type to update'),
-    name: z.string().optional().describe('The name of the content type'),
-    displayField: z
-        .string()
-        .optional()
-        .describe('The field ID to use as the display field'),
-    description: z
-        .string()
-        .optional()
-        .describe('Description of the content type'),
-    fields: z
-        .array(FieldSchema)
-        .optional()
-        .describe('Array of field definitions for the content type. Will be merged with existing fields.'),
-});
-async function tool(args) {
-    const params = {
-        spaceId: args.spaceId,
-        environmentId: args.environmentId,
-        contentTypeId: args.contentTypeId,
-    };
-    const contentfulClient = createToolClient(args);
-    // Get the current content type
-    const currentContentType = await contentfulClient.contentType.get(params);
-    // Use the new fields if provided, otherwise keep existing fields
-    const fields = args.fields || currentContentType.fields;
-    // If fields are provided, ensure we're not removing any required field metadata
-    if (args.fields) {
-        const existingFieldsMap = currentContentType.fields.reduce((acc, field) => {
-            acc[field.id] = field;
-            return acc;
-        }, {});
-        // Ensure each field has all required metadata
-        fields.forEach((field) => {
-            const existingField = existingFieldsMap[field.id];
-            if (existingField) {
-                // Preserve validations if not explicitly changed
-                field.validations = field.validations || existingField.validations;
-                // Preserve required flag if not explicitly set, default to false
-                field.required =
-                    field.required !== undefined
-                        ? field.required
-                        : existingField.required || false;
-                // Preserve link type for Link fields
-                if (field.type === 'Link' &&
-                    !field.linkType &&
-                    existingField.linkType) {
-                    field.linkType = existingField.linkType;
-                }
-                // Preserve items for Array fields
-                if (field.type === 'Array' && !field.items && existingField.items) {
-                    field.items = existingField.items;
-                }
-            }
-            else {
-                // For new fields, ensure required is a boolean
-                field.required = field.required || false;
-            }
-        });
-    }
-    // Update the content type
-    const contentType = await contentfulClient.contentType.update(params, {
-        ...currentContentType,
-        name: args.name || currentContentType.name,
-        description: args.description || currentContentType.description,
-        displayField: args.displayField || currentContentType.displayField,
-        fields: fields,
-    });
-    return createSuccessResponse('Content type updated successfully', {
-        contentType,
-    });
-}
-export const updateContentTypeTool = withErrorHandling(tool, 'Error updating content type');

package/build/types/fieldSchema.js

@@ -1,29 +0,0 @@
-import { z } from 'zod';
-export const FieldSchema = z.object({
-    id: z.string().describe('The field ID'),
-    name: z.string().describe('The field name'),
-    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'),
-    disabled: z.boolean().optional().describe('Whether the field is disabled'),
-    omitted: z
-        .boolean()
-        .optional()
-        .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'),
-    linkType: z
-        .string()
-        .optional()
-        .describe('Link type for Link fields (e.g., "Entry", "Asset")'),
-    items: z
-        .object({
-        type: z.string(),
-        linkType: z.string().optional(),
-        validations: z.array(z.any()).optional(),
-    })
-        .optional()
-        .describe('Items configuration for Array fields'),
-});

package/build/utils/ai-actions.js

@@ -1,46 +0,0 @@
-import { z } from 'zod';
-export var VariableType;
-(function (VariableType) {
-    VariableType["RESOURCE_LINK"] = "ResourceLink";
-    VariableType["TEXT"] = "Text";
-    VariableType["STANDARD_INPUT"] = "StandardInput";
-    VariableType["LOCALE"] = "Locale";
-    VariableType["MEDIA_REFERENCE"] = "MediaReference";
-    VariableType["REFERENCE"] = "Reference";
-    VariableType["SMART_CONTEXT"] = "SmartContext";
-})(VariableType || (VariableType = {}));
-export var EntityType;
-(function (EntityType) {
-    EntityType["ENTRY"] = "Entry";
-    EntityType["ASSET"] = "Asset";
-    EntityType["RESOURCE_LINK"] = "ResourceLink";
-})(EntityType || (EntityType = {}));
-// Create Zod schema for VariableValue
-export const VariableValue = z.union([
-    z.object({
-        id: z.string(),
-        value: z.string(),
-    }),
-    z.object({
-        id: z.string(),
-        value: z.object({
-            entityType: z.nativeEnum(EntityType),
-            entityId: z.string(),
-            entityPath: z.string(),
-        }),
-    }),
-    z.object({
-        id: z.string(),
-        value: z.object({
-            entityType: z.literal(EntityType.ENTRY),
-            entityId: z.string(),
-            entityPaths: z.array(z.string()),
-        }),
-    }),
-]);
-export var OutputFormat;
-(function (OutputFormat) {
-    OutputFormat["RICH_TEXT"] = "RichText";
-    OutputFormat["MARKDOWN"] = "Markdown";
-    OutputFormat["PLAIN_TEXT"] = "PlainText";
-})(OutputFormat || (OutputFormat = {}));

package/build/utils/bulkOperations.js

@@ -1,94 +0,0 @@
-// Helper function to wait for bulk action completion
-export async function waitForBulkActionCompletion(contentfulClient, baseParams, bulkActionId) {
-    let action = (await contentfulClient.bulkAction.get({
-        ...baseParams,
-        bulkActionId,
-    }));
-    while (action.sys.status === 'inProgress' ||
-        action.sys.status === 'created') {
-        await new Promise((resolve) => setTimeout(resolve, 1000));
-        action = (await contentfulClient.bulkAction.get({
-            ...baseParams,
-            bulkActionId,
-        }));
-    }
-    return action;
-}
-// Helper function to create versioned links for entries
-export async function createEntryVersionedLinks(contentfulClient, baseParams, entryIds) {
-    return Promise.all(entryIds.map(async (entryId) => {
-        const currentEntry = await contentfulClient.entry.get({
-            ...baseParams,
-            entryId,
-        });
-        return {
-            sys: {
-                type: 'Link',
-                linkType: 'Entry',
-                id: entryId,
-                version: currentEntry.sys.version,
-            },
-        };
-    }));
-}
-// Helper function to create unversioned links for entries (used for unpublish operations)
-export async function createEntryUnversionedLinks(contentfulClient, baseParams, entryIds) {
-    // For unpublish operations, we don't need to fetch entries since we only need IDs
-    // But we should validate they exist first
-    await Promise.all(entryIds.map(async (entryId) => {
-        await contentfulClient.entry.get({
-            ...baseParams,
-            entryId,
-        });
-    }));
-    return entryIds.map((entryId) => ({
-        sys: {
-            type: 'Link',
-            linkType: 'Entry',
-            id: entryId,
-        },
-    }));
-}
-// Helper function to create versioned links for assets
-export async function createAssetVersionedLinks(contentfulClient, baseParams, assetIds) {
-    return Promise.all(assetIds.map(async (assetId) => {
-        const currentAsset = await contentfulClient.asset.get({
-            ...baseParams,
-            assetId,
-        });
-        return {
-            sys: {
-                type: 'Link',
-                linkType: 'Asset',
-                id: assetId,
-                version: currentAsset.sys.version,
-            },
-        };
-    }));
-}
-// Helper function to create unversioned links for assets (used for unpublish operations)
-export async function createAssetUnversionedLinks(contentfulClient, baseParams, assetIds) {
-    // For unpublish operations, we don't need to fetch assets since we only need IDs
-    // But we should validate they exist first
-    await Promise.all(assetIds.map(async (assetId) => {
-        await contentfulClient.asset.get({
-            ...baseParams,
-            assetId,
-        });
-    }));
-    return assetIds.map((assetId) => ({
-        sys: {
-            type: 'Link',
-            linkType: 'Asset',
-            id: assetId,
-        },
-    }));
-}
-export function createEntitiesCollection(entities) {
-    return {
-        sys: {
-            type: 'Array',
-        },
-        items: entities,
-    };
-}

package/build/utils/formatters.js

@@ -1,39 +0,0 @@
-import { XMLBuilder } from 'fast-xml-parser';
-/**
- * Formats a response by combining a message with structured data.
- * Converts the provided object to XML format and appends the message.
- */
-export function formatResponse(message, object = {}) {
-    const formattedObject = {};
-    for (const [key, value] of Object.entries(object)) {
-        if (!value)
-            continue;
-        formattedObject[key] = value;
-    }
-    const builder = new XMLBuilder({
-        format: true,
-        indentBy: '  ',
-        suppressEmptyNode: true,
-        ignoreAttributes: false,
-        processEntities: false,
-    });
-    const contextString = builder.build(formattedObject);
-    return `${message}: \n${contextString}\n`;
-}
-/**
- * Ensures that a value is an array.
- */
-export function ensureArray(value) {
-    if (value === null || value === undefined) {
-        return [];
-    }
-    return Array.isArray(value) ? value : [value];
-}
-/**
- * Pluralizes a string based on a count.
- * Returns singular form for count of 1, plural form otherwise.
- */
-export function pluralize(n, singular, plural) {
-    const num = Array.isArray(n) ? n.length : n;
-    return num === 1 ? singular : plural || `${singular}s`;
-}

package/build/utils/getVersion.js

@@ -1,11 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-export const getVersion = () => {
-    const __filename = fileURLToPath(import.meta.url);
-    const __dirname = dirname(__filename);
-    const packageJsonPath = join(__dirname, '../../package.json');
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-    return packageJson.version;
-};

package/build/utils/response.js

@@ -1,37 +0,0 @@
-import { formatResponse } from './formatters.js';
-/**
- * Creates a standardized success response
- */
-export function createSuccessResponse(message, data) {
-    const text = data ? formatResponse(message, data) : message;
-    return {
-        content: [
-            {
-                type: 'text',
-                text,
-            },
-        ],
-    };
-}
-/**
- * Higher-order function that wraps tool handlers with standardized error handling
- */
-export function withErrorHandling(handler, errorPrefix = 'Error') {
-    return async (params, extra) => {
-        try {
-            return await handler(params, extra);
-        }
-        catch (error) {
-            const errorMessage = error instanceof Error ? error.message : String(error);
-            return {
-                isError: true,
-                content: [
-                    {
-                        type: 'text',
-                        text: `${errorPrefix}: ${errorMessage}`,
-                    },
-                ],
-            };
-        }
-    };
-}

package/build/utils/summarizer.js

@@ -1,39 +0,0 @@
-export const summarizeData = (data, options = {}) => {
-    const { maxItems = 3, remainingMessage = 'To see more items, please ask me to retrieve the next page.', } = options;
-    // Handle Contentful-style responses with items and total
-    if (data && typeof data === 'object' && 'items' in data && 'total' in data) {
-        const items = data.items;
-        const total = data.total;
-        // Type guard to ensure items is an array and total is a number
-        if (!Array.isArray(items) || typeof total !== 'number') {
-            return data;
-        }
-        if (items.length <= maxItems) {
-            return data;
-        }
-        return {
-            items: items.slice(0, maxItems),
-            total: total,
-            showing: maxItems,
-            remaining: total - maxItems,
-            message: remainingMessage,
-            skip: maxItems, // Add skip value for next page
-        };
-    }
-    // Handle plain arrays
-    if (Array.isArray(data)) {
-        if (data.length <= maxItems) {
-            return data;
-        }
-        return {
-            items: data.slice(0, maxItems),
-            total: data.length,
-            showing: maxItems,
-            remaining: data.length - maxItems,
-            message: remainingMessage,
-            skip: maxItems, // Add skip value for next page
-        };
-    }
-    // Return non-array data as-is (cast to expected return type)
-    return data;
-};

package/build/utils/tools.js

@@ -1,20 +0,0 @@
-import ctfl from 'contentful-management';
-import { getDefaultClientConfig } from '../config/contentful.js';
-import { z } from 'zod';
-export const BaseToolSchema = z.object({
-    spaceId: z.string().describe('The ID of the Contentful space'),
-    environmentId: z.string().describe('The ID of the Contentful environment'),
-});
-/**
- * Creates a Contentful client with the correct configuration based on resource parameters
- *
- * @param params - Tool parameters that may include a resource
- * @returns Configured Contentful client
- */
-export function createToolClient(params) {
-    const clientConfig = getDefaultClientConfig();
-    if (params.spaceId) {
-        clientConfig.space = params.spaceId;
-    }
-    return ctfl.createClient(clientConfig, { type: 'plain' });
-}