@kentico/management-api-mcp 30.12.3-preview → 31.0.0-preview

package/README.md

@@ -1,12 +1,62 @@
-# Xperience by Kentico - Management API MCP server
+# Xperience by Kentico ManagementApiMcp
 
-This package provides a Model Context Protocol (MCP) server that allows AI tools to work with the Xperience by Kentico management API. Currently, the management API allows interaction with content types and reusable field schemas.
+Model Context Protocol (MCP) server for managing data in Xperience by Kentico.
 
-## Documentation
+## Development
 
-For setup instructions and usage guidelines, refer to the official Xperience by Kentico documentation:
-[Content type management API](https://docs.kentico.com/x/management_api_xp)
+To develop the ManagementApiMcp
 
-## License
+1. Run the `npm install` to install packages
+2. Run the `npm run dev` to start watcher that will rebuild the mcp on any change.
 
-See LICENSE.txt for license information.
+To run the development Management API MCP in cursor/vscode/etc:
+1. Run `npm run dev` or `npm run build` at least once
+2. Add Kentico.Xperience.ManagementApi integration package to the DancingGoat and call `AddKenticoManagementApi()` / `UseKenticoManagementApi()`. Specify 32char length secret.
+3. Run the DancingGoat
+4. Update the `./mcp-config.json` to include correct secret and run `npm run debug`.
+5. Otherwise, you can add the following config to vscode/cursor/etc.:
+
+```json
+{
+    "mcpServers": {
+        "xperience": {
+            "type": "stdio",
+            "command": "node",
+            "args": ["C:\\CMS\\XbK\\CMSSolution\\Integrations\\Kentico.Xperience.ManagementApiMcp\\dist\\index.js"],
+            "env": {
+                "NODE_OPTIONS": "--use-system-ca",
+                "CACHE_OPENAPI": "false",
+                "MANAGEMENT_API_URL": "https://localhost:5001/kentico-api/management",
+                "MANAGEMENT_API_SECRET": "<your-32+char-secret>"
+            }
+        }
+    }
+}
+```
+
+Or prettier one if you execute `npm link`:
+
+```json
+{
+    "mcpServers": {
+        "xperience": {
+            "type": "stdio",
+            "command": "xperience-mcp",
+            "env": {
+                "NODE_OPTIONS": "--use-system-ca",
+                "CACHE_OPENAPI": "false",
+                "MANAGEMENT_API_URL": "https://localhost:5001/kentico-api/management",
+                "MANAGEMENT_API_SECRET": "<your-32+char-secret>"
+            }
+        }
+    }
+}
+```
+
+## Custom environment variables
+
+The following environment variables are used:
+
+- `MANAGEMENT_API_URL` - path to the Management API endpoint
+- `MANAGEMENT_API_SECRET` - required, secret used for Authorization header when calling the Management API (must be at least 32 characters)
+- `CACHE_OPENAPI` - optional, can disable caching of OpenAPI spec for development purposes.

package/dist/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node --use-system-ca
+#!/usr/bin/env node
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -12525,7 +12525,6 @@ function $constructor(name, initializer3, params) {
   Object.defineProperty(_, "name", { value: name });
   return _;
 }
-var $brand = Symbol("zod_brand");
 var $ZodAsyncError = class extends Error {
   constructor() {
     super(`Encountered Promise during synchronous parse. Use .parseAsync() instead.`);
@@ -15029,8 +15028,6 @@ function en_default() {
 }
 
 // node_modules/zod/v4/core/registries.js
-var $output = Symbol("ZodOutput");
-var $input = Symbol("ZodInput");
 var $ZodRegistry = class {
   constructor() {
     this._map = /* @__PURE__ */ new Map();
@@ -16384,10 +16381,10 @@ var ZodType = /* @__PURE__ */ $constructor("ZodType", (inst, def) => {
   };
   inst.clone = (def2, params) => clone(inst, def2, params);
   inst.brand = () => inst;
-  inst.register = (reg, meta) => {
+  inst.register = ((reg, meta) => {
     reg.add(inst, meta);
     return inst;
-  };
+  });
   inst.parse = (data, params) => parse2(inst, data, params, { callee: inst.parse });
   inst.safeParse = (data, params) => safeParse2(inst, data, params);
   inst.parseAsync = async (data, params) => parseAsync2(inst, data, params, { callee: inst.parseAsync });
@@ -18294,11 +18291,13 @@ function assertCompleteRequestPrompt(request) {
   if (request.params.ref.type !== "ref/prompt") {
     throw new TypeError(`Expected CompleteRequestPrompt, but got ${request.params.ref.type}`);
   }
+  void request;
 }
 function assertCompleteRequestResourceTemplate(request) {
   if (request.params.ref.type !== "ref/resource") {
     throw new TypeError(`Expected CompleteRequestResourceTemplate, but got ${request.params.ref.type}`);
   }
+  void request;
 }
 var CompleteResultSchema = ResultSchema.extend({
   completion: looseObject({
@@ -22362,7 +22361,7 @@ ZodNaN.create = (params) => {
     ...processCreateParams(params)
   });
 };
-var BRAND = Symbol("zod_brand");
+var BRAND = /* @__PURE__ */ Symbol("zod_brand");
 var ZodBranded = class extends ZodType2 {
   _parse(input) {
     const { ctx } = this._processInputParams(input);
@@ -22564,14 +22563,14 @@ var ostring = () => stringType().optional();
 var onumber = () => numberType().optional();
 var oboolean = () => booleanType().optional();
 var coerce = {
-  string: (arg) => ZodString2.create({ ...arg, coerce: true }),
-  number: (arg) => ZodNumber2.create({ ...arg, coerce: true }),
-  boolean: (arg) => ZodBoolean2.create({
+  string: ((arg) => ZodString2.create({ ...arg, coerce: true })),
+  number: ((arg) => ZodNumber2.create({ ...arg, coerce: true })),
+  boolean: ((arg) => ZodBoolean2.create({
     ...arg,
     coerce: true
-  }),
-  bigint: (arg) => ZodBigInt.create({ ...arg, coerce: true }),
-  date: (arg) => ZodDate.create({ ...arg, coerce: true })
+  })),
+  bigint: ((arg) => ZodBigInt.create({ ...arg, coerce: true })),
+  date: ((arg) => ZodDate.create({ ...arg, coerce: true }))
 };
 var NEVER2 = INVALID;
 
@@ -22599,10 +22598,10 @@ var ZodMiniType = /* @__PURE__ */ $constructor("ZodMiniType", (inst, def) => {
   };
   inst.clone = (_def, params) => clone(inst, _def, params);
   inst.brand = () => inst;
-  inst.register = (reg, meta) => {
+  inst.register = ((reg, meta) => {
     reg.add(inst, meta);
     return inst;
-  };
+  });
 });
 var ZodMiniObject = /* @__PURE__ */ $constructor("ZodMiniObject", (inst, def) => {
   $ZodObject.init(inst, def);
@@ -22781,7 +22780,7 @@ function isTerminal(status) {
 }
 
 // node_modules/zod-to-json-schema/dist/esm/Options.js
-var ignoreOverride = Symbol("Let zodToJsonSchema decide on which parser to use");
+var ignoreOverride = /* @__PURE__ */ Symbol("Let zodToJsonSchema decide on which parser to use");
 var defaultOptions = {
   name: void 0,
   $refStrategy: "root",
@@ -25631,7 +25630,7 @@ var Server = class extends Protocol {
 };
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/completable.js
-var COMPLETABLE_SYMBOL = Symbol.for("mcp.completable");
+var COMPLETABLE_SYMBOL = /* @__PURE__ */ Symbol.for("mcp.completable");
 function isCompletable(schema) {
   return !!schema && typeof schema === "object" && COMPLETABLE_SYMBOL in schema;
 }
@@ -26502,7 +26501,6 @@ function requestBodyToZod(requestBody, components) {
   } else if ("text/plain" in requestBody.content && requestBody.content["text/plain"].schema) {
     schema = external_exports.string();
   } else {
-    console.error(`Unsupported media type in request body: ${JSON.stringify(requestBody.content, null, 2)}`);
     return external_exports.never();
   }
   if (!requestBody.required) {
@@ -26550,7 +26548,13 @@ function jsonToZodValidation(_schema, components) {
   let combinator;
   if (schema.allOf) {
     const schemas = schema.allOf.map((s) => schemaToZod(s, components));
-    combinator = schemas.length > 0 ? schemas.reduce((acc, s) => external_exports.intersection(acc, s)) : external_exports.unknown();
+    combinator = schemas.length > 0 ? schemas.reduce((acc, s) => zodMerge(acc, s)) : external_exports.unknown();
+    if (combinator && isZodObject(combinator)) {
+      const { discriminatorKey, discriminatorValue } = findDiscriminator(schema, components);
+      if (discriminatorKey && discriminatorValue) {
+        combinator = combinator.extend({ [discriminatorKey]: external_exports.literal(discriminatorValue) });
+      }
+    }
   }
   if (schema.oneOf) {
     const schemas = schema.oneOf.map((s) => schemaToZod(s, components));
@@ -26591,14 +26595,9 @@ function jsonToZodValidation(_schema, components) {
       const shape = {};
       if (schema.properties) {
         for (const [key, property] of Object.entries(schema.properties)) {
-          if ("discriminator" in schema && schema.discriminator?.propertyName === key) {
-            const values = Object.keys(schema.discriminator.mapping ?? {});
-            shape[key] = external_exports.union(values.map((v) => external_exports.literal(v))).describe("Discriminator property for a union.");
-          } else {
-            shape[key] = schemaToZod(property, components);
-            if (!schema.required?.includes(key)) {
-              shape[key] = shape[key].nullish();
-            }
+          shape[key] = schemaToZod(property, components);
+          if (!schema.required?.includes(key)) {
+            shape[key] = shape[key].nullish();
           }
         }
       }
@@ -26606,7 +26605,7 @@ function jsonToZodValidation(_schema, components) {
       if (schema.additionalProperties) {
         return objectSchema.passthrough();
       }
-      return combinator ? external_exports.intersection(combinator, objectSchema) : objectSchema;
+      return combinator ? zodMerge(combinator, objectSchema) : objectSchema;
     }
   }
 }
@@ -26633,7 +26632,7 @@ function resolveRef(ref, components) {
     throw new Error(`Unknown components section: ${section}`);
   }
   const resolved = group[name];
-  if (!resolved) {
+  if (resolved === void 0 || resolved === null) {
     throw new Error(`Reference not found: ${ref}`);
   }
   if (resolved && typeof resolved === "object" && "$ref" in resolved && typeof resolved.$ref === "string") {
@@ -26641,6 +26640,29 @@ function resolveRef(ref, components) {
   }
   return resolved;
 }
+function findDiscriminator(schema, components) {
+  const partWithDiscriminator = schema.allOf?.map((s) => deref(s, components)).find((s) => typeof s === "object" && "discriminator" in s);
+  const discriminator = partWithDiscriminator?.discriminator;
+  if (discriminator?.mapping) {
+    const discriminatorMappingEntry = Object.entries(discriminator.mapping ?? {}).find(
+      ([, discriminatorRef]) => resolveRef(discriminatorRef, components) === schema
+    );
+    if (discriminatorMappingEntry) {
+      const [discriminatorValue] = discriminatorMappingEntry;
+      return { discriminatorKey: discriminator.propertyName, discriminatorValue };
+    }
+  }
+  return {};
+}
+function zodMerge(a, b) {
+  if (isZodObject(a) && isZodObject(b)) {
+    return a.extend(b.shape);
+  }
+  return external_exports.intersection(a, b);
+}
+function isZodObject(obj) {
+  return "shape" in obj && "extend" in obj;
+}
 
 // src/utils.ts
 function info(...parts) {
@@ -26735,17 +26757,17 @@ function generateMcpTool(description, config2) {
         isError: true
       };
     }
+    const isJsonResponse = response.headers.get("Content-Type")?.includes("application/json");
     if (!response.ok) {
       const errorObj = {
         url,
         method,
         body: "data" in params ? params.data : void 0,
-        response: await prettyRead(response)
+        response: isJsonResponse ? await response.json() : await response.text()
       };
       const errorMsg = JSON.stringify(errorObj, null, 2);
-      return { content: [{ type: "text", text: errorMsg }], isError: true };
+      return { content: [{ type: "text", text: "```json\n" + errorMsg + "\n```" }], isError: true };
     }
-    const isJsonResponse = response.headers.get("Content-Type")?.includes("application/json");
     try {
       if (isJsonResponse) {
         const text = JSON.stringify(await response.json(), null, 2);
@@ -26854,18 +26876,13 @@ function write(newStorage) {
 async function lookupOpenApiSpec(managementApiUrl2, secret) {
   const workingDir2 = process.cwd();
   let openApiSpec2 = await fetchOpenApiSpec(managementApiUrl2, secret);
-  if (!openApiSpec2 && workingDir2 && process.env.CACHE_OPENAPI !== "false") {
-    openApiSpec2 = storage.openapiSpecs?.[workingDir2];
-  }
-  if (!openApiSpec2) {
-    openApiSpec2 = await fetchOpenApiSpec(managementApiUrl2, secret);
-    if (!openApiSpec2) {
-      return;
-    }
-    if (workingDir2 && process.env.CACHE_OPENAPI !== "false") {
+  if (workingDir2 && process.env.CACHE_OPENAPI !== "false") {
+    if (openApiSpec2) {
       const openApiSpecs = storage.openapiSpecs ?? {};
       openApiSpecs[workingDir2] = openApiSpec2;
       storage.openapiSpecs = openApiSpecs;
+    } else {
+      openApiSpec2 = storage.openapiSpecs?.[workingDir2];
     }
   }
   return openApiSpec2;
@@ -26901,18 +26918,7 @@ var managementApiUrl = process.env.MANAGEMENT_API_URL;
 if (!managementApiUrl) {
   err(
     "MANAGEMENT_API_URL environment variable is not set.",
-    "Please configure your mcp config to set the MANAGEMENT_API_URL environment variable, example:",
-    {
-      mcpServers: {
-        xperience: {
-          type: "stdio",
-          command: "@kentico/management-api-mcp",
-          env: {
-            MANAGEMENT_API_URL: "https://localhost:12345/kentico-api/management"
-          }
-        }
-      }
-    }
+    "Please configure your mcp config to set the MANAGEMENT_API_URL environment variable."
   );
   process.exit(1);
 }

package/package.json

@@ -1,28 +1,53 @@
-{
-  "name": "@kentico/management-api-mcp",
-  "version": "30.12.3-preview",
-  "description": "Model Context Protocol server for Xperience by Kentico Management API",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "xperience-mcp": "./dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "keywords": [
-    "kentico",
-    "xperience",
-    "mcp",
-    "model-context-protocol",
-    "management-api"
-  ],
-  "author": "Kentico",
-  "license": "SEE LICENSE IN LICENSE.txt",
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
-  },
-  "engines": {
-    "node": ">= 22.0.0"
-  }
-}
+{
+    "name": "@kentico/management-api-mcp",
+    "version": "31.0.0-preview",
+    "description": "Model Context Protocol server for Xperience by Kentico Management API",
+    "type": "module",
+    "main": "dist/index.js",
+    "bin": {
+        "xperience-mcp": "./dist/index.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "start": "node dist/index.js",
+        "debug": "mcp-inspector --config .\\mcp-config.json",
+        "dev": "esbuild src/index.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/index.js --sourcemap --watch",
+        "build": "esbuild src/index.ts --bundle --platform=node --target=node22 --format=esm --outfile=dist/index.js",
+        "lint": "eslint src/**/*.ts",
+        "lint:fix": "eslint src/**/*.ts --fix",
+        "format": "prettier --check \"src/**/*.ts\"",
+        "format:fix": "prettier --write \"src/**/*.ts\"",
+        "version:bump": "npm version",
+        "prepack": "node -e \"require('fs').copyFileSync('PACKAGE_README.md', 'README.md')\"  && clean-pkg-json"
+    },
+    "keywords": [
+        "kentico",
+        "xperience",
+        "mcp",
+        "model-context-protocol",
+        "management-api"
+    ],
+    "author": "Kentico",
+    "license": "SEE LICENSE IN LICENSE.txt",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.23.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.39.1",
+        "@modelcontextprotocol/inspector": "^0.17.2",
+        "@types/node": "22.19.1",
+        "@typescript-eslint/eslint-plugin": "^8.48.0",
+        "@typescript-eslint/parser": "^8.48.0",
+        "esbuild": "^0.27.0",
+        "eslint": "^9.39.1",
+        "prettier": "^3.7.3",
+        "typescript": "5.9.3",
+        "typescript-eslint": "^8.48.0",
+        "clean-pkg-json": "^1.3.0"
+    },
+    "engines": {
+        "node": ">= 22.0.0"
+    }
+}