@umbraco-cms/mcp-editor 17.6.0-beta.8 → 17.6.0-beta.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,6 +4,8 @@ MCP server template for Umbraco add-ons using the @umbraco-cms/mcp-server-sdk.
4
4
 
5
5
  ## Getting Started
6
6
 
7
+ **Requirements:** Node.js 22.23.4+, 24.22.1+ or 26.12.1+. Earlier releases are affected by [CVE-2026-111497](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases) (Brotli decoder out-of-bounds write), which Node's built-in `fetch` reaches when it decompresses a Brotli response from Umbraco. Upgrading Node.js is the only fix. Check your version with `node --version`.
8
+
7
9
  ### 1. Install Dependencies
8
10
 
9
11
  ```bash
@@ -1,11 +1,12 @@
1
1
  import { z } from 'zod';
2
- import { createMcpClientManager, withStandardDecorators, baseSliceNames, createToolResult, createToolResultError, extractChainedResult, requestApproval, UmbracoManagementClient, encodeCursor } from '@umbraco-cms/mcp-server-sdk';
2
+ import { createMcpClientManager, withStandardDecorators, baseSliceNames, createToolResult, createToolResultError, extractChainedResult, requestApproval, UmbracoManagementClient, encodeCursor, isLoopbackUrl } from '@umbraco-cms/mcp-server-sdk';
3
3
  import { statSync, readFileSync } from 'fs';
4
4
  import { resolve } from 'path';
5
5
 
6
6
  // src/umbraco-api/tools/content/get/search-content.ts
7
-
8
- // src/config/mcp-servers.ts
7
+ function chainedTlsEnv(baseUrl) {
8
+ return isLoopbackUrl(baseUrl) ? { NODE_TLS_REJECT_UNAUTHORIZED: "0" } : {};
9
+ }
9
10
  async function buildServers() {
10
11
  const isWorkersRuntime = typeof navigator !== "undefined" && navigator.userAgent === "Cloudflare-Workers";
11
12
  if (isWorkersRuntime || typeof process === "undefined" || !process.env) return [];
@@ -30,13 +31,14 @@ async function buildServers() {
30
31
  const binEntry = typeof cmsDevPkg.bin === "string" ? cmsDevPkg.bin : cmsDevPkg.bin ? Object.values(cmsDevPkg.bin)[0] : void 0;
31
32
  if (!binEntry) throw new Error("@umbraco-cms/mcp-dev has no bin entry");
32
33
  const binAbs = path.resolve(path.dirname(pkgPath), binEntry);
34
+ const baseUrl = process.env.UMBRACO_BASE_URL || "http://localhost:44391";
33
35
  return [{
34
36
  name: "cms",
35
37
  command: process.execPath,
36
38
  args: [binAbs],
37
39
  env: {
38
- NODE_TLS_REJECT_UNAUTHORIZED: "0",
39
- UMBRACO_BASE_URL: process.env.UMBRACO_BASE_URL || "http://localhost:44391",
40
+ ...chainedTlsEnv(baseUrl),
41
+ UMBRACO_BASE_URL: baseUrl,
40
42
  UMBRACO_CLIENT_ID: process.env.UMBRACO_CLIENT_ID || "",
41
43
  UMBRACO_CLIENT_SECRET: process.env.UMBRACO_CLIENT_SECRET || "",
42
44
  // Clear tool filters so our editor tool names (search-content etc.) don't
@@ -649,10 +651,15 @@ var tool4 = {
649
651
  var list_document_types_default = withStandardDecorators(tool4);
650
652
 
651
653
  // src/umbraco-api/tools/content/helpers/resolve-document-type-properties.ts
652
- async function resolveDocumentTypeProperties(documentTypeId) {
653
- const docTypeResult = await chainCms("get-document-type-by-id", { id: documentTypeId });
654
- if (!docTypeResult.ok) return { ok: false, errorResult: docTypeResult.errorResult };
655
- const data = docTypeResult.data;
654
+ async function resolveDocumentTypeProperties(documentTypeId, documentType) {
655
+ let data;
656
+ if (documentType) {
657
+ data = documentType;
658
+ } else {
659
+ const docTypeResult = await chainCms("get-document-type-by-id", { id: documentTypeId });
660
+ if (!docTypeResult.ok) return { ok: false, errorResult: docTypeResult.errorResult };
661
+ data = docTypeResult.data;
662
+ }
656
663
  const collected = /* @__PURE__ */ new Map();
657
664
  function addProperties(props) {
658
665
  for (const p of props) {
@@ -1391,11 +1398,11 @@ ${aliases.join("\n")}`
1391
1398
  }
1392
1399
  };
1393
1400
  var get_property_value_template_default = withStandardDecorators(tool10);
1394
- async function resolveEditorAliases(documentTypeId, values) {
1401
+ async function resolveEditorAliases(documentTypeId, values, { defaultCulture = null, documentType, siteCultures } = {}) {
1395
1402
  if (!values || values.length === 0) {
1396
1403
  return { ok: true, values: [] };
1397
1404
  }
1398
- const docTypeResult = await resolveDocumentTypeProperties(documentTypeId);
1405
+ const docTypeResult = await resolveDocumentTypeProperties(documentTypeId, documentType);
1399
1406
  if (!docTypeResult.ok) return docTypeResult;
1400
1407
  const dataTypeIds = Array.from(
1401
1408
  new Set(
@@ -1414,22 +1421,32 @@ async function resolveEditorAliases(documentTypeId, values) {
1414
1421
  docTypeResult.properties.map((p) => p.alias).filter((alias) => typeof alias === "string")
1415
1422
  );
1416
1423
  const editorAliasByPropertyAlias = /* @__PURE__ */ new Map();
1424
+ const cultureVariantAliases = /* @__PURE__ */ new Set();
1417
1425
  for (const prop of docTypeResult.properties) {
1418
1426
  const editorAlias = prop.dataType?.id ? editorAliasByDataTypeId.get(prop.dataType.id) : void 0;
1419
1427
  if (prop.alias && editorAlias) editorAliasByPropertyAlias.set(prop.alias, editorAlias);
1428
+ if (prop.alias && prop.variesByCulture) cultureVariantAliases.add(prop.alias);
1420
1429
  }
1421
1430
  const notAProperty = /* @__PURE__ */ new Set();
1422
1431
  const missingEditorAlias = /* @__PURE__ */ new Set();
1432
+ const unknownCultures = /* @__PURE__ */ new Set();
1423
1433
  const resolved = values.map((v) => {
1424
1434
  const editorAlias = editorAliasByPropertyAlias.get(v.alias);
1425
1435
  if (!editorAlias) {
1426
1436
  if (propertyAliases.has(v.alias)) missingEditorAlias.add(v.alias);
1427
1437
  else notAProperty.add(v.alias);
1428
1438
  }
1439
+ let culture = v.culture ?? (cultureVariantAliases.has(v.alias) ? defaultCulture : null);
1440
+ if (v.culture && siteCultures) {
1441
+ const requested = v.culture.toLowerCase();
1442
+ const match = siteCultures.find((c) => c.toLowerCase() === requested);
1443
+ if (match) culture = match;
1444
+ else unknownCultures.add(v.culture);
1445
+ }
1429
1446
  return {
1430
1447
  alias: v.alias,
1431
1448
  value: v.value,
1432
- culture: v.culture ?? null,
1449
+ culture,
1433
1450
  segment: v.segment ?? null,
1434
1451
  editorAlias: editorAlias ?? ""
1435
1452
  };
@@ -1460,14 +1477,74 @@ async function resolveEditorAliases(documentTypeId, values) {
1460
1477
  )
1461
1478
  };
1462
1479
  }
1480
+ if (unknownCultures.size > 0 && siteCultures) {
1481
+ return {
1482
+ ok: false,
1483
+ errorResult: createToolResultError(
1484
+ `The following value culture(s) are not languages on this site: ${Array.from(unknownCultures).join(", ")}. Available cultures: ${siteCultures.join(", ")}.`
1485
+ )
1486
+ };
1487
+ }
1463
1488
  return { ok: true, values: resolved };
1464
1489
  }
1490
+ var LANGUAGE_PAGE_SIZE = 100;
1491
+ async function resolvePageCulture(documentTypeId, culture, { forPublish = false } = {}) {
1492
+ const docTypeResult = await chainCms("get-document-type-by-id", { id: documentTypeId });
1493
+ if (!docTypeResult.ok) return { ok: false, errorResult: docTypeResult.errorResult };
1494
+ const documentType = docTypeResult.data;
1495
+ if (!documentType.variesByCulture) {
1496
+ return { ok: true, culture: null, documentType };
1497
+ }
1498
+ const langResult = await chainCms("get-language", { cursor: encodeCursor({ s: 0, t: LANGUAGE_PAGE_SIZE }) });
1499
+ if (!langResult.ok) return { ok: false, errorResult: langResult.errorResult };
1500
+ const languages = langResult.data.items ?? [];
1501
+ const complete = (langResult.data.total ?? languages.length) <= languages.length;
1502
+ const siteCultures = languages.map((l) => l.isoCode);
1503
+ let pageCulture;
1504
+ if (culture) {
1505
+ const match = siteCultures.find((c) => c.toLowerCase() === culture.toLowerCase());
1506
+ if (!match && complete) {
1507
+ return {
1508
+ ok: false,
1509
+ errorResult: createToolResultError(
1510
+ `Culture "${culture}" is not a language on this site. Available cultures: ${siteCultures.join(", ")}.`
1511
+ )
1512
+ };
1513
+ }
1514
+ pageCulture = match ?? culture;
1515
+ } else {
1516
+ const defaultLanguage = languages.find((l) => l.isDefault);
1517
+ if (!defaultLanguage?.isoCode) {
1518
+ return {
1519
+ ok: false,
1520
+ errorResult: createToolResultError(
1521
+ "This document type varies by culture, but no default language could be determined. Call list-languages and pass `culture` explicitly."
1522
+ )
1523
+ };
1524
+ }
1525
+ pageCulture = defaultLanguage.isoCode;
1526
+ }
1527
+ if (forPublish) {
1528
+ const missingMandatory = languages.filter((l) => l.isMandatory && l.isoCode !== pageCulture).map((l) => l.isoCode);
1529
+ if (missingMandatory.length > 0) {
1530
+ const one = missingMandatory.length === 1;
1531
+ return {
1532
+ ok: false,
1533
+ errorResult: createToolResultError(
1534
+ `Cannot create and publish this page in ${pageCulture} alone: ${missingMandatory.join(", ")} ${one ? "is a mandatory language" : "are mandatory languages"} on this site, and a page can only be published once it exists in every mandatory language. Nothing was created. ${one ? `Either pass culture "${missingMandatory[0]}", or use` : "Use"} create-page, add the other language(s) with create-variant, then publish.`
1535
+ )
1536
+ };
1537
+ }
1538
+ }
1539
+ return { ok: true, culture: pageCulture, documentType, siteCultures: complete ? siteCultures : void 0 };
1540
+ }
1465
1541
 
1466
1542
  // src/umbraco-api/tools/content/post/create-page.ts
1467
1543
  var inputSchema11 = {
1468
1544
  name: z.string().describe("The name of the page to create"),
1469
1545
  documentTypeId: z.string().uuid().describe("The ID of the document type to use. Call list-document-types first to find available types."),
1470
1546
  parentId: z.string().uuid().optional().describe("The ID of the parent page. If omitted, the page is created at the root"),
1547
+ culture: z.string().optional().describe("Culture (ISO code, e.g. en-US) to create the page in. Only used when the document type varies by culture; defaults to the site's default language. Call list-languages for the available cultures. Add further languages afterwards with create-variant or copy-variant."),
1471
1548
  values: z.array(z.object({
1472
1549
  alias: z.string().describe("The property alias"),
1473
1550
  value: z.any().describe("The property value"),
@@ -1479,23 +1556,28 @@ var outputSchema11 = z.object({
1479
1556
  message: z.string(),
1480
1557
  id: z.string(),
1481
1558
  name: z.string(),
1559
+ culture: z.string().nullable().describe("The culture the page was created in \u2014 the requested `culture`, or the site's default language when none was given. Null when the document type does not vary by culture."),
1482
1560
  previewUrl: previewUrlSchema,
1483
1561
  validation: validationResultSchema
1484
1562
  });
1485
1563
  var tool11 = {
1486
1564
  name: "create-page",
1487
- description: "Create a new content page as a draft \u2014 the page will NOT be published automatically. Call list-document-types first to find a valid documentTypeId. Use this as a starting point: pass `name`, `documentTypeId`, optional `parentId`, and at most a small number of simple initial values (strings, numbers, booleans). For everything else, follow up with the dedicated tools after creation \u2014 they're shorter, safer, and avoid the JSON-payload errors that come from cramming a full page into one call: edit-page for property updates, add-blocklist-block / add-blockgrid-block / add-rte-block for block content, edit-block for block-property edits, and get-property-value-template for the value shape of structured non-block editors (media pickers, image cropper, etc.).",
1565
+ description: "Create a new content page as a draft \u2014 the page will NOT be published automatically. Call list-document-types first to find a valid documentTypeId. Use this as a starting point: pass `name`, `documentTypeId`, optional `parentId`, and at most a small number of simple initial values (strings, numbers, booleans). For everything else, follow up with the dedicated tools after creation \u2014 they're shorter, safer, and avoid the JSON-payload errors that come from cramming a full page into one call: edit-page for property updates, add-blocklist-block / add-blockgrid-block / add-rte-block for block content, edit-block for block-property edits, and get-property-value-template for the value shape of structured non-block editors (media pickers, image cropper, etc.). On a multilingual site, a document type that varies by culture is created in `culture` (default: the site's default language); values without a culture on culture-variant properties are stored in that culture too.",
1488
1566
  inputSchema: inputSchema11,
1489
1567
  outputSchema: outputSchema11,
1490
1568
  slices: ["create"],
1491
1569
  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
1492
- handler: async ({ name, documentTypeId, parentId, values }) => {
1493
- const resolved = await resolveEditorAliases(documentTypeId, values);
1570
+ handler: async ({ name, documentTypeId, parentId, culture, values }) => {
1571
+ const cultureResult = await resolvePageCulture(documentTypeId, culture);
1572
+ if (!cultureResult.ok) return cultureResult.errorResult;
1573
+ const { culture: pageCulture, documentType, siteCultures } = cultureResult;
1574
+ const resolved = await resolveEditorAliases(documentTypeId, values, { defaultCulture: pageCulture, documentType, siteCultures });
1494
1575
  if (!resolved.ok) return resolved.errorResult;
1495
1576
  const createResult = await chainCms("create-document", {
1496
1577
  documentTypeId,
1497
1578
  name,
1498
1579
  values: resolved.values,
1580
+ ...pageCulture ? { cultures: [pageCulture] } : {},
1499
1581
  ...parentId ? { parentId } : {}
1500
1582
  });
1501
1583
  if (!createResult.ok) return createResult.errorResult;
@@ -1507,6 +1589,7 @@ var tool11 = {
1507
1589
  message,
1508
1590
  id: createdId,
1509
1591
  name,
1592
+ culture: pageCulture,
1510
1593
  previewUrl: createdId ? await fetchPreviewUrl(createdId) : null,
1511
1594
  validation
1512
1595
  });
@@ -1517,6 +1600,7 @@ var inputSchema12 = {
1517
1600
  name: z.string().describe("The name of the page to create"),
1518
1601
  documentTypeId: z.string().uuid().describe("The ID of the document type to use. Call list-document-types first to find available types."),
1519
1602
  parentId: z.string().uuid().optional().describe("The ID of the parent page. If omitted, the page is created at the root"),
1603
+ culture: z.string().optional().describe("Culture (ISO code, e.g. en-US) to create the page in. Only used when the document type varies by culture; defaults to the site's default language. Call list-languages for the available cultures. Add further languages afterwards with create-variant or copy-variant."),
1520
1604
  values: z.array(z.object({
1521
1605
  alias: z.string().describe("The property alias"),
1522
1606
  value: z.any().describe("The property value"),
@@ -1528,23 +1612,28 @@ var outputSchema12 = z.object({
1528
1612
  message: z.string(),
1529
1613
  id: z.string(),
1530
1614
  name: z.string(),
1615
+ culture: z.string().nullable().describe("The culture the page was created in \u2014 the requested `culture`, or the site's default language when none was given. Null when the document type does not vary by culture."),
1531
1616
  publishedUrls: publishedUrlsSchema
1532
1617
  });
1533
1618
  var tool12 = {
1534
1619
  name: "create-and-publish-page",
1535
- description: "Create a new content page and publish it \u2014 mirrors clicking 'Save and publish' (instead of 'Save') on the create screen in the Umbraco backoffice. This is a single atomic operation when the connected Umbraco instance supports it (17.6+); otherwise a two-call create-then-publish sequence is used. Call list-document-types first to find a valid documentTypeId. Use this as a starting point: pass `name`, `documentTypeId`, optional `parentId`, and at most a small number of simple initial values. Required-property validation runs at publish time, not create time: on the atomic path a validation failure leaves no page behind, but on the fallback path the draft can already have been created before publish fails, leaving an unpublished draft. Either way, check the response `message` before retrying \u2014 don't retry blindly, or you may pile up duplicate drafts. Use create-page followed by save-and-publish instead when you need to build up content across multiple calls before publishing.",
1620
+ description: "Create a new content page and publish it \u2014 mirrors clicking 'Save and publish' (instead of 'Save') on the create screen in the Umbraco backoffice. This is a single atomic operation when the connected Umbraco instance supports it (17.6+); otherwise a two-call create-then-publish sequence is used. Call list-document-types first to find a valid documentTypeId. Use this as a starting point: pass `name`, `documentTypeId`, optional `parentId`, and at most a small number of simple initial values. Required-property validation runs at publish time, not create time: on the atomic path a validation failure leaves no page behind, but on the fallback path the draft can already have been created before publish fails, leaving an unpublished draft. Either way, check the response `message` before retrying \u2014 don't retry blindly, or you may pile up duplicate drafts. Use create-page followed by save-and-publish instead when you need to build up content across multiple calls before publishing. On a multilingual site, a document type that varies by culture is created in `culture` (default: the site's default language); values without a culture on culture-variant properties are stored in that culture too. If the site has a mandatory language other than that culture, the page can't be published from a single call \u2014 the tool says so and creates nothing; use create-page, create-variant, then publish instead.",
1536
1621
  inputSchema: inputSchema12,
1537
1622
  outputSchema: outputSchema12,
1538
1623
  slices: ["create", "publish"],
1539
1624
  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
1540
- handler: async ({ name, documentTypeId, parentId, values }) => {
1541
- const resolved = await resolveEditorAliases(documentTypeId, values);
1625
+ handler: async ({ name, documentTypeId, parentId, culture, values }) => {
1626
+ const cultureResult = await resolvePageCulture(documentTypeId, culture, { forPublish: true });
1627
+ if (!cultureResult.ok) return cultureResult.errorResult;
1628
+ const { culture: pageCulture, documentType, siteCultures } = cultureResult;
1629
+ const resolved = await resolveEditorAliases(documentTypeId, values, { defaultCulture: pageCulture, documentType, siteCultures });
1542
1630
  if (!resolved.ok) return resolved.errorResult;
1543
1631
  if (await isCmsToolAvailable("create-and-publish-document")) {
1544
1632
  const createResult = await chainCms("create-and-publish-document", {
1545
1633
  documentTypeId,
1546
1634
  name,
1547
1635
  values: resolved.values,
1636
+ ...pageCulture ? { cultures: [pageCulture] } : {},
1548
1637
  ...parentId ? { parentId } : {}
1549
1638
  });
1550
1639
  if (!createResult.ok) return createResult.errorResult;
@@ -1553,6 +1642,7 @@ var tool12 = {
1553
1642
  message: `Created and published "${name}"`,
1554
1643
  id: createdId2,
1555
1644
  name,
1645
+ culture: pageCulture,
1556
1646
  publishedUrls: createdId2 ? await fetchPublishedUrls(createdId2) : []
1557
1647
  });
1558
1648
  }
@@ -1560,19 +1650,21 @@ var tool12 = {
1560
1650
  documentTypeId,
1561
1651
  name,
1562
1652
  values: resolved.values,
1653
+ ...pageCulture ? { cultures: [pageCulture] } : {},
1563
1654
  ...parentId ? { parentId } : {}
1564
1655
  });
1565
1656
  if (!createDocumentResult.ok) return createDocumentResult.errorResult;
1566
1657
  const createdId = createDocumentResult.data.id;
1567
1658
  const publishResult = await chainCms("publish-document", {
1568
1659
  id: createdId,
1569
- data: { publishSchedules: [{ culture: null }] }
1660
+ data: { publishSchedules: [{ culture: pageCulture }] }
1570
1661
  });
1571
1662
  if (!publishResult.ok) {
1572
1663
  return createToolResult({
1573
1664
  message: `Created "${name}" as a draft but publish failed: ${publishResult.errorResult.content?.[0]?.text ?? "unknown error"}`,
1574
1665
  id: createdId,
1575
1666
  name,
1667
+ culture: pageCulture,
1576
1668
  publishedUrls: []
1577
1669
  });
1578
1670
  }
@@ -1580,6 +1672,7 @@ var tool12 = {
1580
1672
  message: `Created and published "${name}"`,
1581
1673
  id: createdId,
1582
1674
  name,
1675
+ culture: pageCulture,
1583
1676
  publishedUrls: createdId ? await fetchPublishedUrls(createdId) : []
1584
1677
  });
1585
1678
  }