@contentful/mcp-tools 0.12.8 → 0.12.9

package/dist/index.d.ts

@@ -4233,6 +4233,7 @@ declare class ContentfulMcpTools {
                 spaceId: zod.ZodString;
                 environmentId: zod.ZodString;
             } & {
+                componentId: zod.ZodOptional<zod.ZodString>;
                 name: zod.ZodString;
                 description: zod.ZodString;
                 viewports: zod.ZodArray<zod.ZodObject<{
@@ -4655,6 +4656,7 @@ declare class ContentfulMcpTools {
                         };
                     }[] | undefined;
                 } | undefined;
+                componentId?: string | undefined;
                 slots?: {
                     name: string;
                     required: boolean;
@@ -10310,6 +10312,211 @@ declare class ContentfulMcpTools {
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
     };
+    /**
+     * Get ExO design token tools
+     */
+    getDesignTokenTools(): {
+        getDesignToken: {
+            title: string;
+            description: string;
+            inputParams: {
+                spaceId: zod.ZodString;
+                environmentId: zod.ZodString;
+            } & {
+                designTokenId: zod.ZodString;
+            };
+            annotations: {
+                readOnlyHint: boolean;
+                destructiveHint: boolean;
+                openWorldHint: boolean;
+            };
+            tool: (params: {
+                spaceId: string;
+                environmentId: string;
+                designTokenId: string;
+            }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
+        };
+        listDesignTokens: {
+            title: string;
+            description: string;
+            inputParams: {
+                spaceId: zod.ZodString;
+                environmentId: zod.ZodString;
+            } & {
+                limit: zod.ZodOptional<zod.ZodNumber>;
+                pageNext: zod.ZodOptional<zod.ZodString>;
+                pagePrev: zod.ZodOptional<zod.ZodString>;
+                type: zod.ZodOptional<zod.ZodEnum<["DTCG.Color", "DTCG.Dimension", "DTCG.FontFamily", "DTCG.FontWeight", "DTCG.Duration", "DTCG.CubicBezier", "DTCG.Number", "DTCG.StrokeStyle", "DTCG.Border", "DTCG.Transition", "DTCG.Shadow", "DTCG.Gradient", "DTCG.Typography"]>>;
+            };
+            annotations: {
+                readOnlyHint: boolean;
+                destructiveHint: boolean;
+                openWorldHint: boolean;
+            };
+            tool: (params: {
+                spaceId: string;
+                environmentId: string;
+                type?: "DTCG.Color" | "DTCG.Dimension" | "DTCG.FontFamily" | "DTCG.FontWeight" | "DTCG.Duration" | "DTCG.CubicBezier" | "DTCG.Number" | "DTCG.StrokeStyle" | "DTCG.Border" | "DTCG.Transition" | "DTCG.Shadow" | "DTCG.Gradient" | "DTCG.Typography" | undefined;
+                limit?: number | undefined;
+                pageNext?: string | undefined;
+                pagePrev?: string | undefined;
+            }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
+        };
+        upsertDesignToken: {
+            title: string;
+            description: string;
+            inputParams: {
+                spaceId: zod.ZodString;
+                environmentId: zod.ZodString;
+            } & {
+                designTokenId: zod.ZodString;
+                version: zod.ZodOptional<zod.ZodNumber>;
+                name: zod.ZodOptional<zod.ZodString>;
+                type: zod.ZodOptional<zod.ZodEnum<["DTCG.Color", "DTCG.Dimension", "DTCG.FontFamily", "DTCG.FontWeight", "DTCG.Duration", "DTCG.CubicBezier", "DTCG.Number", "DTCG.StrokeStyle", "DTCG.Border", "DTCG.Transition", "DTCG.Shadow", "DTCG.Gradient", "DTCG.Typography"]>>;
+                metadata: zod.ZodOptional<zod.ZodObject<{
+                    tags: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
+                        sys: zod.ZodObject<{
+                            type: zod.ZodLiteral<"Link">;
+                            linkType: zod.ZodLiteral<"Tag">;
+                            id: zod.ZodString;
+                        }, "strip", zod.ZodTypeAny, {
+                            type: "Link";
+                            id: string;
+                            linkType: "Tag";
+                        }, {
+                            type: "Link";
+                            id: string;
+                            linkType: "Tag";
+                        }>;
+                    }, "strip", zod.ZodTypeAny, {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "Tag";
+                        };
+                    }, {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "Tag";
+                        };
+                    }>, "many">>;
+                    concepts: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
+                        sys: zod.ZodObject<{
+                            type: zod.ZodLiteral<"Link">;
+                            linkType: zod.ZodLiteral<"TaxonomyConcept">;
+                            id: zod.ZodString;
+                        }, "strip", zod.ZodTypeAny, {
+                            type: "Link";
+                            id: string;
+                            linkType: "TaxonomyConcept";
+                        }, {
+                            type: "Link";
+                            id: string;
+                            linkType: "TaxonomyConcept";
+                        }>;
+                    }, "strip", zod.ZodTypeAny, {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "TaxonomyConcept";
+                        };
+                    }, {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "TaxonomyConcept";
+                        };
+                    }>, "many">>;
+                }, "strip", zod.ZodTypeAny, {
+                    tags?: {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "Tag";
+                        };
+                    }[] | undefined;
+                    concepts?: {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "TaxonomyConcept";
+                        };
+                    }[] | undefined;
+                }, {
+                    tags?: {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "Tag";
+                        };
+                    }[] | undefined;
+                    concepts?: {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "TaxonomyConcept";
+                        };
+                    }[] | undefined;
+                }>>;
+            };
+            annotations: {
+                readOnlyHint: boolean;
+                destructiveHint: boolean;
+                idempotentHint: boolean;
+                openWorldHint: boolean;
+            };
+            tool: (params: {
+                spaceId: string;
+                environmentId: string;
+                designTokenId: string;
+                name?: string | undefined;
+                version?: number | undefined;
+                metadata?: {
+                    tags?: {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "Tag";
+                        };
+                    }[] | undefined;
+                    concepts?: {
+                        sys: {
+                            type: "Link";
+                            id: string;
+                            linkType: "TaxonomyConcept";
+                        };
+                    }[] | undefined;
+                } | undefined;
+                type?: "DTCG.Color" | "DTCG.Dimension" | "DTCG.FontFamily" | "DTCG.FontWeight" | "DTCG.Duration" | "DTCG.CubicBezier" | "DTCG.Number" | "DTCG.StrokeStyle" | "DTCG.Border" | "DTCG.Transition" | "DTCG.Shadow" | "DTCG.Gradient" | "DTCG.Typography" | undefined;
+            }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
+        };
+        deleteDesignToken: {
+            title: string;
+            description: string;
+            inputParams: {
+                spaceId: zod.ZodString;
+                environmentId: zod.ZodString;
+            } & {
+                designTokenId: zod.ZodString;
+                confirm: zod.ZodOptional<zod.ZodBoolean>;
+                confirmToken: zod.ZodOptional<zod.ZodString>;
+            };
+            annotations: {
+                readOnlyHint: boolean;
+                destructiveHint: boolean;
+                idempotentHint: boolean;
+                openWorldHint: boolean;
+            };
+            tool: (params: {
+                spaceId: string;
+                environmentId: string;
+                designTokenId: string;
+                confirmToken?: string | undefined;
+                confirm?: boolean | undefined;
+            }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
+        };
+    };
     /**
      * Get job tools (space-to-space migration)
      */

package/dist/index.js

@@ -391,7 +391,8 @@ var RESOURCE_DISPLAY_NAME = {
   experience: "experience",
   experienceFragment: "experience fragment",
   experienceTemplate: "experience template",
-  dataAssembly: "data assembly"
+  dataAssembly: "data assembly",
+  designToken: "design token"
 };
 function buildConfirmationPreview(resource, id, details, confirmToken) {
   const displayName = RESOURCE_DISPLAY_NAME[resource];
@@ -6551,6 +6552,9 @@ var ExperienceSlotNodeSchema = z88.lazy(
 
 // src/tools/exo/components/createComponent.ts
 var CreateComponentToolParams = BaseToolSchema.extend({
+  componentId: z89.string().optional().describe(
+    "Optional ID for the component. If provided, will use upsert (create via PUT) with this ID"
+  ),
   name: z89.string().describe("The name of the component"),
   description: z89.string().describe("Description of the component"),
   viewports: z89.array(ViewportSchema).describe("Viewport definitions for the component (may be empty)"),
@@ -6569,18 +6573,29 @@ function createComponentTool(config) {
       config.protectedEnvironments
     );
     const contentfulClient = createExoToolClient(config, args);
-    const component = await contentfulClient.component.create(
-      { spaceId: args.spaceId, environmentId: args.environmentId },
+    const componentData = {
+      name: args.name,
+      description: args.description,
+      viewports: args.viewports,
+      contentProperties: args.contentProperties,
+      designProperties: args.designProperties,
+      ...args.componentTree && { componentTree: args.componentTree },
+      ...args.slots && { slots: args.slots },
+      ...args.metadata && { metadata: args.metadata }
+    };
+    const component = args.componentId ? await contentfulClient.component.upsert(
       {
-        name: args.name,
-        description: args.description,
-        viewports: args.viewports,
-        contentProperties: args.contentProperties,
-        designProperties: args.designProperties,
-        ...args.componentTree && { componentTree: args.componentTree },
-        ...args.slots && { slots: args.slots },
-        ...args.metadata && { metadata: args.metadata }
+        spaceId: args.spaceId,
+        environmentId: args.environmentId,
+        componentId: args.componentId
+      },
+      {
+        sys: { id: args.componentId, type: "Component" },
+        ...componentData
       }
+    ) : await contentfulClient.component.create(
+      { spaceId: args.spaceId, environmentId: args.environmentId },
+      componentData
     );
     return createSuccessResponse("Component created successfully", {
       component
@@ -8581,6 +8596,231 @@ function createDataAssemblyTools(config) {
   };
 }
 
+// src/tools/exo/design-tokens/getDesignToken.ts
+import { z as z125 } from "zod";
+var GetDesignTokenToolParams = BaseToolSchema.extend({
+  designTokenId: z125.string().describe("The ID of the design token to retrieve details for")
+});
+function getDesignTokenTool(config) {
+  async function tool2(args) {
+    const contentfulClient = createExoToolClient(config, args);
+    const designToken = await contentfulClient.designToken.get({
+      spaceId: args.spaceId,
+      environmentId: args.environmentId,
+      designTokenId: args.designTokenId
+    });
+    return createSuccessResponse("Design token retrieved successfully", {
+      designToken
+    });
+  }
+  return withErrorHandling(tool2, "Error retrieving design token");
+}
+
+// src/tools/exo/design-tokens/listDesignTokens.ts
+import { z as z126 } from "zod";
+var ListDesignTokensToolParams = BaseToolSchema.extend({
+  limit: z126.number().optional().describe("Maximum number of design tokens to return (max 10)"),
+  pageNext: z126.string().optional().describe("Cursor token to fetch the next page of results"),
+  pagePrev: z126.string().optional().describe("Cursor token to fetch the previous page of results"),
+  type: z126.enum(DTCG_DESIGN_PROPERTY_TYPES).optional().describe("Filter to design tokens of this DTCG type (e.g. DTCG.Color)")
+});
+function listDesignTokensTool(config) {
+  async function tool2(args) {
+    const contentfulClient = createExoToolClient(config, args);
+    const cursorParam = args.pageNext ? { pageNext: args.pageNext } : args.pagePrev ? { pagePrev: args.pagePrev } : {};
+    const designTokens = await contentfulClient.designToken.getMany({
+      spaceId: args.spaceId,
+      environmentId: args.environmentId,
+      query: {
+        limit: Math.min(args.limit || 10, 10),
+        ...args.type && { type: args.type },
+        ...cursorParam
+      }
+    });
+    const summarized = summarizeData(designTokens, {
+      maxItems: 10,
+      remainingMessage: "To see more design tokens, ask me to retrieve the next page using the pageNext cursor."
+    });
+    return createSuccessResponse("Design tokens retrieved successfully", {
+      designTokens: summarized,
+      total: designTokens.total,
+      limit: designTokens.limit,
+      pages: designTokens.pages
+    });
+  }
+  return withErrorHandling(tool2, "Error listing design tokens");
+}
+
+// src/tools/exo/design-tokens/upsertDesignToken.ts
+import { z as z127 } from "zod";
+var UpsertDesignTokenToolParams = BaseToolSchema.extend({
+  designTokenId: z127.string().describe("The ID of the design token to create or update"),
+  version: z127.number().optional().describe(
+    "The design token's sys.version, required when updating an existing token. You must call get_design_token first to read the current state and version. The update is rejected if this does not match the current version, which means the token changed since you read it. Omit this entirely to create a new design token with this designTokenId \u2014 in that case name and type are required. Design tokens have no separate publish step: every upsert auto-publishes server-side, which bumps sys.version by 2 (not 1) per call."
+  ),
+  name: z127.string().optional().describe("The name of the design token; required when creating"),
+  type: z127.enum(DTCG_DESIGN_PROPERTY_TYPES).optional().describe("The DTCG type of the design token; required when creating"),
+  metadata: ExoMetadataSchema.optional().describe(
+    "ExO metadata (tags, concepts); replaces existing if provided"
+  )
+});
+function upsertDesignTokenTool(config) {
+  async function tool2(args) {
+    assertEnvironmentNotProtected(
+      args.environmentId,
+      config.protectedEnvironments
+    );
+    const params = {
+      spaceId: args.spaceId,
+      environmentId: args.environmentId,
+      designTokenId: args.designTokenId
+    };
+    const contentfulClient = createExoToolClient(config, args);
+    if (args.version !== void 0) {
+      const current = await contentfulClient.designToken.get(params);
+      if (args.version !== current.sys.version) {
+        throw new Error(
+          `Version conflict: the design token has changed since you read it (your version: ${args.version}, current version: ${current.sys.version}). Re-fetch the design token with get_design_token and retry the update with the latest sys.version.`
+        );
+      }
+      const designToken2 = await contentfulClient.designToken.upsert(params, {
+        sys: {
+          id: current.sys.id,
+          type: "DesignToken",
+          version: current.sys.version
+        },
+        name: args.name ?? current.name,
+        type: args.type ?? current.type,
+        ...(args.metadata ?? current.metadata) && {
+          metadata: args.metadata ?? current.metadata
+        }
+      });
+      return createSuccessResponse("Design token updated successfully", {
+        designToken: designToken2
+      });
+    }
+    if (!args.name || !args.type) {
+      throw new Error(
+        "name and type are required when creating a new design token (no version supplied)."
+      );
+    }
+    const designToken = await contentfulClient.designToken.upsert(params, {
+      sys: { id: args.designTokenId, type: "DesignToken" },
+      name: args.name,
+      type: args.type,
+      ...args.metadata && { metadata: args.metadata }
+    });
+    return createSuccessResponse("Design token created successfully", {
+      designToken
+    });
+  }
+  return withErrorHandling(tool2, "Error upserting design token");
+}
+
+// src/tools/exo/design-tokens/deleteDesignToken.ts
+import { z as z128 } from "zod";
+var DeleteDesignTokenToolParams = BaseToolSchema.extend({
+  designTokenId: z128.string().describe("The ID of the design token to delete"),
+  confirm: z128.boolean().optional().describe(
+    "Set to true on the second call to actually perform the deletion. Required together with confirmToken."
+  ),
+  confirmToken: z128.string().optional().describe(
+    "Token returned by the preview call; must be supplied with confirm: true."
+  )
+});
+function deleteDesignTokenTool(config) {
+  async function tool2(args) {
+    assertEnvironmentNotProtected(
+      args.environmentId,
+      config.protectedEnvironments
+    );
+    const params = {
+      spaceId: args.spaceId,
+      environmentId: args.environmentId,
+      designTokenId: args.designTokenId
+    };
+    const contentfulClient = createExoToolClient(config, args);
+    const designToken = await contentfulClient.designToken.get(params);
+    const expectedToken = buildConfirmToken(
+      "designToken",
+      args.designTokenId,
+      designToken.sys.version
+    );
+    if (args.confirm !== true || args.confirmToken !== expectedToken) {
+      return createSuccessResponse(
+        `${CONFIRMATION_MESSAGE_PREFIX} design token`,
+        buildConfirmationPreview(
+          "designToken",
+          args.designTokenId,
+          { designToken },
+          expectedToken
+        )
+      );
+    }
+    await contentfulClient.designToken.delete(params);
+    return createSuccessResponse("Design token deleted successfully", {
+      designTokenId: args.designTokenId
+    });
+  }
+  return withErrorHandling(tool2, "Error deleting design token");
+}
+
+// src/tools/exo/design-tokens/register.ts
+function createDesignTokenTools(config) {
+  const getDesignToken = getDesignTokenTool(config);
+  const listDesignTokens = listDesignTokensTool(config);
+  const upsertDesignToken = upsertDesignTokenTool(config);
+  const deleteDesignToken = deleteDesignTokenTool(config);
+  return {
+    getDesignToken: {
+      title: "get_design_token",
+      description: "Get details about a specific ExO design token (a named DTCG-typed value, such as a color, dimension, or typography token, referenced by token-backed design properties on components).",
+      inputParams: GetDesignTokenToolParams.shape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false
+      },
+      tool: getDesignToken
+    },
+    listDesignTokens: {
+      title: "list_design_tokens",
+      description: "List ExO design tokens in a space and environment. Returns a maximum of 10 items per request; use the pageNext cursor (returned in pages.next) to paginate.",
+      inputParams: ListDesignTokensToolParams.shape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: false
+      },
+      tool: listDesignTokens
+    },
+    upsertDesignToken: {
+      title: "upsert_design_token",
+      description: "Create or update an ExO design token. To update an existing token, call get_design_token first and pass the returned sys.version as the version parameter; the handler merges your updates with the existing fields, so you only need to provide what changes. If the version is stale, the update is rejected and you must re-fetch with get_design_token. To create a new token, omit version and supply designTokenId, name, and type. Design tokens have no separate publish step: every upsert auto-publishes server-side, bumping sys.version by 2 (not 1) per call.",
+      inputParams: UpsertDesignTokenToolParams.shape,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      },
+      tool: upsertDesignToken
+    },
+    deleteDesignToken: {
+      title: "delete_design_token",
+      description: "Delete an ExO design token. Two-phase: the first call (without confirm/confirmToken) returns a preview and a confirmToken. To complete the deletion, call again with the same designTokenId, confirm: true, and the confirmToken from the preview.",
+      inputParams: DeleteDesignTokenToolParams.shape,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+      },
+      tool: deleteDesignToken
+    }
+  };
+}
+
 // src/ContentfulMcpTools.ts
 var ContentfulMcpTools = class {
   config;
@@ -8713,6 +8953,12 @@ var ContentfulMcpTools = class {
   getDataAssemblyTools() {
     return createDataAssemblyTools(this.config);
   }
+  /**
+   * Get ExO design token tools
+   */
+  getDesignTokenTools() {
+    return createDesignTokenTools(this.config);
+  }
   /**
    * Get job tools (space-to-space migration)
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/mcp-tools",
-  "version": "0.12.8",
+  "version": "0.12.9",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",