@contentful/mcp-tools 0.12.3-next.2 → 0.12.4

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _modelcontextprotocol_sdk_server_mcp_js from '@modelcontextprotocol/sdk/server/mcp.js';
 import * as contentful_management from 'contentful-management';
-import { PlainClientAPI } from 'contentful-management';
+import { ExperienceProps } from 'contentful-management';
 import * as _contentful_rich_text_types from '@contentful/rich-text-types';
 import * as _modelcontextprotocol_sdk_shared_protocol_js from '@modelcontextprotocol/sdk/shared/protocol.js';
 import * as _modelcontextprotocol_sdk_types_js from '@modelcontextprotocol/sdk/types.js';
@@ -13,10 +13,7 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
 type Distribute<T> = T extends unknown ? {
     [K in keyof T]: T[K];
 } : never;
-type ComponentTypeEntity = Awaited<ReturnType<PlainClientAPI['componentType']['get']>>;
-type TreeNode = Distribute<NonNullable<ComponentTypeEntity['componentTree']>[number]>;
-type ExperienceEntity = Awaited<ReturnType<PlainClientAPI['experience']['get']>>;
-type ExperienceSlotNode = Distribute<NonNullable<ExperienceEntity['slots']>[string][number]>;
+type ExperienceSlotNode = Distribute<NonNullable<ExperienceProps['slots']>[string][number]>;
 
 /**
  * Response type for tool handlers
@@ -4371,7 +4368,7 @@ declare class ContentfulMcpTools {
                         type: "DesignToken";
                     } | undefined;
                 }>]>, "many">;
-                componentTree: zod.ZodOptional<zod.ZodArray<zod.ZodType<TreeNode, zod.ZodTypeDef, TreeNode>, "many">>;
+                componentTree: zod.ZodOptional<zod.ZodArray<zod.ZodType<contentful_management.TreeNode, zod.ZodTypeDef, contentful_management.TreeNode>, "many">>;
                 slots: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
                     id: zod.ZodString;
                     name: zod.ZodString;
@@ -4540,18 +4537,6 @@ declare class ContentfulMcpTools {
                 description: string;
                 spaceId: string;
                 environmentId: string;
-                viewports: {
-                    id: string;
-                    query: string;
-                    displayName: string;
-                    previewSize: string;
-                }[];
-                contentProperties: (contentful_management.DataTypeDefinition & {
-                    name: string;
-                    required: boolean;
-                    id: string;
-                    defaultValue?: unknown;
-                })[];
                 designProperties: ({
                     name: string;
                     type: "String";
@@ -4590,6 +4575,18 @@ declare class ContentfulMcpTools {
                         type: "DesignToken";
                     } | undefined;
                 })[];
+                contentProperties: (contentful_management.DataTypeDefinition & {
+                    name: string;
+                    required: boolean;
+                    id: string;
+                    defaultValue?: unknown;
+                })[];
+                viewports: {
+                    id: string;
+                    query: string;
+                    displayName: string;
+                    previewSize: string;
+                }[];
                 metadata?: {
                     tags?: {
                         sys: {
@@ -4622,7 +4619,7 @@ declare class ContentfulMcpTools {
                         allowedTypes: string[];
                     }[] | undefined;
                 }[] | undefined;
-                componentTree?: TreeNode[] | undefined;
+                componentTree?: contentful_management.TreeNode[] | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         upsertComponentType: {
@@ -4821,7 +4818,7 @@ declare class ContentfulMcpTools {
                         type: "DesignToken";
                     } | undefined;
                 }>]>, "many">>;
-                componentTree: zod.ZodOptional<zod.ZodArray<zod.ZodType<TreeNode, zod.ZodTypeDef, TreeNode>, "many">>;
+                componentTree: zod.ZodOptional<zod.ZodArray<zod.ZodType<contentful_management.TreeNode, zod.ZodTypeDef, contentful_management.TreeNode>, "many">>;
                 slots: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
                     id: zod.ZodString;
                     name: zod.ZodString;
@@ -5008,18 +5005,6 @@ declare class ContentfulMcpTools {
                 } | undefined;
                 name?: string | undefined;
                 description?: string | undefined;
-                viewports?: {
-                    id: string;
-                    query: string;
-                    displayName: string;
-                    previewSize: string;
-                }[] | undefined;
-                contentProperties?: (contentful_management.DataTypeDefinition & {
-                    name: string;
-                    required: boolean;
-                    id: string;
-                    defaultValue?: unknown;
-                })[] | undefined;
                 designProperties?: ({
                     name: string;
                     type: "String";
@@ -5074,7 +5059,19 @@ declare class ContentfulMcpTools {
                         allowedTypes: string[];
                     }[] | undefined;
                 }[] | undefined;
-                componentTree?: TreeNode[] | undefined;
+                contentProperties?: (contentful_management.DataTypeDefinition & {
+                    name: string;
+                    required: boolean;
+                    id: string;
+                    defaultValue?: unknown;
+                })[] | undefined;
+                viewports?: {
+                    id: string;
+                    query: string;
+                    displayName: string;
+                    previewSize: string;
+                }[] | undefined;
+                componentTree?: contentful_management.TreeNode[] | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         deleteComponentType: {
@@ -5393,7 +5390,7 @@ declare class ContentfulMcpTools {
                         type: "DesignToken";
                     } | undefined;
                 }>]>, "many">;
-                componentTree: zod.ZodOptional<zod.ZodArray<zod.ZodType<TreeNode, zod.ZodTypeDef, TreeNode>, "many">>;
+                componentTree: zod.ZodOptional<zod.ZodArray<zod.ZodType<contentful_management.TreeNode, zod.ZodTypeDef, contentful_management.TreeNode>, "many">>;
                 slots: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
                     id: zod.ZodString;
                     name: zod.ZodString;
@@ -5562,18 +5559,6 @@ declare class ContentfulMcpTools {
                 description: string;
                 spaceId: string;
                 environmentId: string;
-                viewports: {
-                    id: string;
-                    query: string;
-                    displayName: string;
-                    previewSize: string;
-                }[];
-                contentProperties: (contentful_management.DataTypeDefinition & {
-                    name: string;
-                    required: boolean;
-                    id: string;
-                    defaultValue?: unknown;
-                })[];
                 designProperties: ({
                     name: string;
                     type: "String";
@@ -5612,6 +5597,18 @@ declare class ContentfulMcpTools {
                         type: "DesignToken";
                     } | undefined;
                 })[];
+                contentProperties: (contentful_management.DataTypeDefinition & {
+                    name: string;
+                    required: boolean;
+                    id: string;
+                    defaultValue?: unknown;
+                })[];
+                viewports: {
+                    id: string;
+                    query: string;
+                    displayName: string;
+                    previewSize: string;
+                }[];
                 metadata?: {
                     tags?: {
                         sys: {
@@ -5644,7 +5641,7 @@ declare class ContentfulMcpTools {
                         allowedTypes: string[];
                     }[] | undefined;
                 }[] | undefined;
-                componentTree?: TreeNode[] | undefined;
+                componentTree?: contentful_management.TreeNode[] | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         upsertTemplate: {
@@ -5843,7 +5840,7 @@ declare class ContentfulMcpTools {
                         type: "DesignToken";
                     } | undefined;
                 }>]>, "many">>;
-                componentTree: zod.ZodOptional<zod.ZodArray<zod.ZodType<TreeNode, zod.ZodTypeDef, TreeNode>, "many">>;
+                componentTree: zod.ZodOptional<zod.ZodArray<zod.ZodType<contentful_management.TreeNode, zod.ZodTypeDef, contentful_management.TreeNode>, "many">>;
                 slots: zod.ZodOptional<zod.ZodArray<zod.ZodObject<{
                     id: zod.ZodString;
                     name: zod.ZodString;
@@ -6030,18 +6027,6 @@ declare class ContentfulMcpTools {
                 } | undefined;
                 name?: string | undefined;
                 description?: string | undefined;
-                viewports?: {
-                    id: string;
-                    query: string;
-                    displayName: string;
-                    previewSize: string;
-                }[] | undefined;
-                contentProperties?: (contentful_management.DataTypeDefinition & {
-                    name: string;
-                    required: boolean;
-                    id: string;
-                    defaultValue?: unknown;
-                })[] | undefined;
                 designProperties?: ({
                     name: string;
                     type: "String";
@@ -6096,7 +6081,19 @@ declare class ContentfulMcpTools {
                         allowedTypes: string[];
                     }[] | undefined;
                 }[] | undefined;
-                componentTree?: TreeNode[] | undefined;
+                contentProperties?: (contentful_management.DataTypeDefinition & {
+                    name: string;
+                    required: boolean;
+                    id: string;
+                    defaultValue?: unknown;
+                })[] | undefined;
+                viewports?: {
+                    id: string;
+                    query: string;
+                    displayName: string;
+                    previewSize: string;
+                }[] | undefined;
+                componentTree?: contentful_management.TreeNode[] | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         deleteTemplate: {
@@ -6470,12 +6467,6 @@ declare class ContentfulMcpTools {
                         urn: string;
                     };
                 };
-                viewports: {
-                    id: string;
-                    query: string;
-                    displayName: string;
-                    previewSize: string;
-                }[];
                 designProperties: Record<string, Record<string, {
                     value: string;
                     type: "DesignToken";
@@ -6483,6 +6474,12 @@ declare class ContentfulMcpTools {
                     value: string | number | boolean;
                     type: "ManualDesignValue";
                 }>>;
+                viewports: {
+                    id: string;
+                    query: string;
+                    displayName: string;
+                    previewSize: string;
+                }[];
                 metadata?: {
                     name?: string | undefined;
                     tags?: {
@@ -6753,12 +6750,6 @@ declare class ContentfulMcpTools {
                 } | undefined;
                 name?: string | undefined;
                 description?: string | undefined;
-                viewports?: {
-                    id: string;
-                    query: string;
-                    displayName: string;
-                    previewSize: string;
-                }[] | undefined;
                 designProperties?: Record<string, Record<string, {
                     value: string;
                     type: "DesignToken";
@@ -6781,6 +6772,12 @@ declare class ContentfulMcpTools {
                         };
                     }>;
                 } | undefined;
+                viewports?: {
+                    id: string;
+                    query: string;
+                    displayName: string;
+                    previewSize: string;
+                }[] | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         deleteExperience: {
@@ -7917,6 +7914,35 @@ declare class ContentfulMcpTools {
                 dryRun?: boolean | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
+        appendEntryField: {
+            title: string;
+            description: string;
+            inputParams: {
+                spaceId: zod.ZodString;
+                environmentId: zod.ZodString;
+            } & {
+                entryId: zod.ZodString;
+                fieldId: zod.ZodString;
+                locale: zod.ZodString;
+                values: zod.ZodArray<zod.ZodUnknown, "many">;
+                version: zod.ZodOptional<zod.ZodNumber>;
+            };
+            annotations: {
+                readOnlyHint: boolean;
+                destructiveHint: boolean;
+                idempotentHint: boolean;
+                openWorldHint: boolean;
+            };
+            tool: (params: {
+                values: unknown[];
+                spaceId: string;
+                environmentId: string;
+                locale: string;
+                entryId: string;
+                fieldId: string;
+                version?: number | undefined;
+            }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
+        };
     };
     /**
      * Get environment tools
@@ -9119,12 +9145,6 @@ declare class ContentfulMcpTools {
                         urn: string;
                     };
                 };
-                viewports: {
-                    id: string;
-                    query: string;
-                    displayName: string;
-                    previewSize: string;
-                }[];
                 designProperties: Record<string, Record<string, {
                     value: string;
                     type: "DesignToken";
@@ -9132,6 +9152,12 @@ declare class ContentfulMcpTools {
                     value: string | number | boolean;
                     type: "ManualDesignValue";
                 }>>;
+                viewports: {
+                    id: string;
+                    query: string;
+                    displayName: string;
+                    previewSize: string;
+                }[];
                 metadata?: {
                     name?: string | undefined;
                     tags?: {
@@ -9402,12 +9428,6 @@ declare class ContentfulMcpTools {
                 } | undefined;
                 name?: string | undefined;
                 description?: string | undefined;
-                viewports?: {
-                    id: string;
-                    query: string;
-                    displayName: string;
-                    previewSize: string;
-                }[] | undefined;
                 designProperties?: Record<string, Record<string, {
                     value: string;
                     type: "DesignToken";
@@ -9430,6 +9450,12 @@ declare class ContentfulMcpTools {
                         };
                     }>;
                 } | undefined;
+                viewports?: {
+                    id: string;
+                    query: string;
+                    displayName: string;
+                    previewSize: string;
+                }[] | undefined;
             }, extra?: _modelcontextprotocol_sdk_shared_protocol_js.RequestHandlerExtra<_modelcontextprotocol_sdk_types_js.ServerRequest, _modelcontextprotocol_sdk_types_js.ServerNotification>) => Promise<ToolResponse>;
         };
         deleteFragment: {
@@ -10699,4 +10725,38 @@ declare class ContentfulMcpTools {
     };
 }
 
-export { type ContentfulConfig, ContentfulMcpTools };
+/** Feature name for the shared ExO M1 rollout entitlement. */
+declare const EXO_M1_FEATURE = "exoM1";
+/**
+ * Checks whether the user (identified solely by their management token) has the
+ * shared ExO M1 entitlement in ANY organization they can access.
+ *
+ * The local server takes `spaceId`/`organizationId` per tool call, not as
+ * required config, so at registration time there is no single authoritative org
+ * to scope to. We therefore derive orgs from the PAT: list every org the token
+ * can reach (`organization.getAll`) and register ExO if at least one is
+ * entitled. Combined with the `ENABLE_EXO_TOOLS` opt-in (the primary gate),
+ * this answers "does this user have ExO access anywhere?".
+ *
+ * The Node-only `@contentful/entitlements-api-client` and its internal cluster
+ * URL are not used (unreachable from a locally-run server).
+ *
+ * Fails CLOSED: any error (offline, network, no accessible orgs) returns false,
+ * so the caller withholds ExO tools rather than exposing them unentitled.
+ */
+declare function hasExoM1Entitlement(config: ContentfulConfig): Promise<boolean>;
+
+/**
+ * Contentful MCP operating guidance, returned in full by get_initial_context
+ * on every session.
+ *
+ * All content is verified against the actual registered tool surface
+ * (audit 2026-07-02). Do not reintroduce fictional tool names or limits;
+ * instructions.test.ts guards against regressions.
+ */
+declare const CORE_INVARIANTS = "# Core operating rules\n\n- **Schema first.** Before creating or finding content, inspect the environment's schema: list available types and inspect their fields. This prevents failed operations and ensures you use the right type and field names.\n- **Edit safely.** Before updating any item, fetch it first to get the current `sys.version`, then pass that version to the update call. The version is required and prevents overwriting concurrent changes.\n- **Bulk cap.** Bulk publish/unpublish/archive/unarchive operations accept at most 10 IDs per call by default. This cap does not apply to creating or updating items.\n- **Ask when ambiguous.** If multiple spaces or environments are available, ask the user which to use. Do not guess.";
+declare const SEARCHING_GUIDANCE = "# Searching for content\n\n- **Schema first.** When users ask about specific content, discover the relevant schema before searching: list the environment's available types and inspect a type's fields so you query on real field names. This prevents wasted queries. Use whichever primitives the environment exposes \u2014 classic content types and entries, or Experience Orchestration component types and experiences.\n- **Then search.** Query using the correct type and field names. Prefer semantic search when the request is conceptual rather than an exact field match.\n- **Retry thoughtfully.** If a query returns no results, retry 2-3 times: relax filters, use more general terms, or check for typos in field names.\n- **Multi-step reference queries.** For requests that span references (e.g. \"posts by Magnus\"), first inspect the schema to confirm the reference field, then query for the referenced item to get its ID, then filter the primary query on that ID. If several items match, show them all and ask.";
+declare const CONVENTIONS_GUIDANCE = "# Response and workflow conventions\n\n- **Plan, then act.** Before a tool call, think about what you need, pick the right tool, and briefly tell the user what you are about to do.\n- **Persist.** Keep going until the request is fully resolved; do not stop at the first error. On failure, explain what went wrong and immediately try a different approach \u2014 never apologize for tool errors.\n- **Clarify resources.** If multiple spaces or environments exist, always ask which to use before acting.\n- **Format for readability.** Use markdown for complex data; show the most important fields of an entry first; keep responses concise but complete.\n- **Prefer bulk.** If you would call the same tool many times, check whether it supports multiple IDs and condense into one call (respecting the 10-ID cap on publish-family operations).";
+declare const EXO_DISPOSITION = "# Tool disposition: Experience Orchestration by default\n\nExperience Orchestration (ExO) tools are enabled. Use ExO primitives \u2014 Component Types, Experiences, Templates, Fragments, and Data Assemblies \u2014 for all content modeling and authoring. Do not create classic content types or entries unless the user explicitly instructs you to. If you are unsure how to model something with ExO, inspect the tool schemas and proceed with ExO.";
+
+export { CONVENTIONS_GUIDANCE, CORE_INVARIANTS, type ContentfulConfig, ContentfulMcpTools, EXO_DISPOSITION, EXO_M1_FEATURE, SEARCHING_GUIDANCE, hasExoM1Entitlement };