Developers · Configuration¶

There is no config:/modules/h1-mcp-api. This module is configured in two places only: the registration YAML of each tool (in h1McpTools/ or h1McpPublicTools/, in whichever module owns the tool) and the code of the tool itself. Everything a tool accepts at runtime comes from a third place it does not own: the resolved editor form of the content type, read live from Magnolia's registries with decorations already applied.

The registration YAML¶

One file per tool, in a folder named exactly h1McpTools (admin) or h1McpPublicTools (visitors), at the root of any module's resources. The file name is free; the tool's identity is getName().

Both registries build a definition's id with DefinitionMetadataBuilder.usingModuleAndRelativePathAsId(), so it is derived from the module plus the file's relative path — two modules can each ship a product.yaml without colliding.

GenericContentTypeTool¶

GenericDecoratedFieldsTool¶

Its three actions are get, set (PATCH) and clear (needs fields). The node is addressed by workspace + uuid, or by path. It never creates or deletes content.

BaseMcpTool — the contract¶

AbstractContentTypeTool¶

What a subclass provides¶

The 14 standard actions¶

Every one is dispatched by execute; a name that matches none falls through to executeCustom.

create_folder, rename_folder, delete_folder and publish read folder/path directly rather than through folderPathFor, so those signatures keep working in a tool that overrides its taxonomy. publish deliberately does not fall back to the taxonomy: a publish carrying only marca is ambiguous, and with recursive it would publish the whole brand.

Standard schema parameters¶

Added by buildStandardInputSchema to every content-type tool, next to the content type's own fields:

How the schema is derived from the form¶

FormSchemaBuilder walks the resolved form of the content type's detail subApp and emits one property per field:

Note — a composite whose itemProvider is currentItemProvider is flattened: its sub-fields are properties of the node itself, not of a child, so they appear at the parent's level. This is what makes fields arriving through a decoration inside a composite — the h1seo* that h1-seo-metadata adds to products — visible and writable. The check is against ComplexPropertyDefinition, so it covers a switchable with currentItemProvider too.

The create and update pipeline¶

create runs, in this order:

1. normalizeRelations — a link/reference field with no converter gets its bare UUID prefixed to jcr:<uuid>. A value that is already prefixed, or that is not a UUID, is left alone.
2. resolvePathReferences — a field with JcrNodeToPathConverter accepts a key or slug and is resolved to the node's full path. An absolute path is verified to exist. Zero matches is an error; several matches is an error listing the candidates, because the same key can exist under more than one brand.
3. applyDeclaredDefaults — every form field with a defaultValue that the payload omits is injected, so a defaulted field satisfies required without the caller sending it. Create only.
4. validateInput(data, true) — the single validation pass (below).
5. assertNoForeignFields — refuses fields another tool owns, before the repository is touched.
6. validateTranslations — locales and translatable fields.
7. Switchable objects are lifted out of the payload (the bind→mapper path does not persist their subtree).
8. doCreate → uuidOf → placeInTaxonomyFolder → the switchable subtrees are written → applyTranslations.
9. session.refresh(false) and the response is a re-read of what was persisted.

update is the same with three differences: applyDeclaredDefaults does not run (a PATCH does not re-default), validateInput(data, false) does not enforce required, and the i18n properties are snapshotted before the write and restored afterwards — except for the fields this call rewrote, which the caller owns.

Validation¶

One pass, two phases, recursive into composites (FieldValidator):

Absent, blank, empty-list and empty-object all count as not present for required. The identity field is never required: the tool derives the node name. readOnly, excluded and non-whitelisted fields are validated if sent but never demanded.

An opaque composite — a compositeField with an implementationClass and no declared properties, like the product variants editor — is exempt from the array check: the form says nothing about the shape of its value, so the only declaration is the tool's own schema.

The three guards¶

The schema comes from the form; persistence goes through the module's model. When another module decorates the app, the form becomes a superset of the model and the difference has to go somewhere:

The first guard lives in the flow and not in bind for a specific reason: a tool that persists without a model — GenericContentTypeTool — never calls bind, and used to skip the check. Since every bind/bindOnto call in the project sits inside a doCreate/doUpdate, moving it up covers both paths without duplicating it. Model introspection that fails degrades to "do not classify" rather than refusing everything.

Note — you cannot ask Magnolia whether a field came from a decoration: the form arrives already resolved and EditorPropertyDefinition carries no provenance. So the operative question is not "is it decorated?" but "does another tool claim it?", answered by McpToolRegistry.toolOwning. A prefix map inside this module would answer it too, and would break ADR-010.

Identity resolution¶

resolveTarget(args) tries, in order: resolveCustomIdentifier (a tool's business key) → uuid → path → nodeName. With nodeName and a taxonomy folder it resolves inside that folder and, when it misses, raises an error listing what the folder does contain, so the assistant can correct itself. A bare nodeName is searched across the workspace: several matches is an ambiguity error listing the paths.

Structural nodes are refused: mgnl:folder, mgnl:area, mgnl:page, mgnl:component. The exception is publish/unpublish, which resolve with elementsOnly=false because publishing a folder is legitimate — and has to happen before its children, or they have nothing to hang from on the public instance.

Node names and folder names¶

Two rules, deliberately different:

resolveNodeName(data, source) = explicit nodeName → the tool's domain source → a random UUID. GenericContentTypeTool overrides that last step: with no identity field it fails asking for nodeName, because a content type declared only in YAML may have no human-readable field at all, and a node called 8f3a1b9c-… is indistinguishable in AdminCentral.

Two-step confirmations¶

Without confirm: true, the four destructive or path-changing actions return a preview and touch nothing:

Destination checks (exists, no-op, name conflict) run in the preview too, so a confirmation that looks fine is not going to fail on the second call.

reorder semantics¶

orderBefore among siblings, so reordering never leaves the folder, and the node's name does not change. An out-of-range numeric index is clamped and reported: the answer carries clamped: true, requestedPosition, and a message naming which end it landed on. Already in position answers reordered: false with the current order — never a silent no-op. A parent whose node type does not allow ordered children is an explicit error.

Helper reference¶

All six are stateless; the workspace or the content type name is a parameter.

ContentTypeIntrospector — the form, resolved¶

WorkspaceContentOps — JCR mechanics¶

Warning — nodesOfType walks the tree instead of querying on purpose: a SELECT with no ORDER BY returns Jackrabbit's undefined order, which then disagrees with what Magnolia renders and with the indices reorder uses. listByFolder does use SQL2 — do not swap one for the other where order is part of the contract.

FormDrivenNodeIO — read and write, driven by a form¶

The symmetric pair. The form arrives as List<EditorPropertyDefinition>, so the engine does not know whether it came from a page template's dialog or a content type's detail form — same type, same rules.

Because the JCR type comes from the field definition, this write cannot diverge from the editor: both read the same declaration. A hand-written mapper can (ADR-017). A stray object for a multi-entry field is accepted as a one-item list, rather than creating an entry with no index.

I18nOps — translations¶

Warning — the writer normalises U+2010 and U+2011 (hyphen and non-breaking hyphen) to ASCII -. A U+2011 was silently breaking the persistence of rich-text i18n properties in the store. En dash and em dash are not touched: they are different typography, and if they ever fail the post-save check reports them instead of losing them.

FormSchemaBuilder and FieldValidator¶

Pure, no JCR, unit-testable. FormSchemaBuilder owns buildInputSchema, buildStandardInputSchema, standardActionsHelp, translationsSchema, isRequiredField, validateInput and normalizeRelations. FieldValidator owns the two-phase pass, configured through a Spec (enforceRequired, extraAllowedKeys, excludedNames, includedNames, modelRequiredNames, modelMultipleNames, referenceCheck, identityField) — which is why the same validator serves content-type tools, that have a model, and WebsiteTool, which has only dialogs.

The registries¶

Both extend AbstractRegistry, so the folder observation is Magnolia's own — the same mechanism as virtualUriMappings/. The plural folder name is the convention: a definition type called h1McpTool is looked for in h1McpTools/.

Module components¶

Registered as singletons in META-INF/magnolia/h1-mcp-api.xml, component set main:

McpToolRegistry · McpPublicToolRegistry

H1McpApiModule implements ModuleLifecycle; on start it binds each registry to the configuration source with its definition type, provider builder, metadata builder and reference id resolver. That binding is what makes the two folders live. There is no version handler and no configuration bean.