H1 MCP API¶

Version 1.0.0-SNAPSHOT · Magnolia 6.4 · Java 21

H1 MCP API is the SDK that lets any Magnolia module expose its content to an AI assistant. A module drops one YAML file into a folder and its tool is live: no dependency on the MCP server, no registration list to maintain, no transport code. And because every tool derives what it accepts from the resolved editor form — the same definition AdminCentral renders, decorations included — an assistant writing through it is held to the same rules as a person typing in the dialog: required fields, option lists, regular expressions, referential integrity, languages.

It ships as a single JAR with no light module and no content of its own. What it gives you is a contract, two registries and a set of bases and helpers that already solve the expensive parts.

Why use H1 MCP API?¶

• A tool costs one YAML file. class: plus a name and a content type is a working CRUD tool with fourteen actions. Three of the twenty-four tools registered in the H1 platform have no Java at all.
• The editor is the contract, not a second schema you maintain. Field types, option lists, required, readOnly, regexp validators, defaultValue and i18n flags are read from the form at runtime, with decorations already applied. When someone adds a field to a dialog, the tool accepts it the same day — and when a field is readOnly, the tool ignores it even if the caller sends it.
• Nothing is written by accident. Every destructive or path-changing action — delete, delete_folder, move, rename_folder — needs two calls: the first returns a preview of what would happen, including how many descendants are affected, and only confirm: true executes.
• A field always has exactly one owner. Properties on a node are a shared namespace, so a module can decorate another module's content type. The tool that owns those fields declares them, the registry answers "who owns this?", and the other tool refuses them naming the tool to use — the alternative, which this replaced, was Jackson dropping the value with no error at all.
• Inversion of dependencies, enforced. A domain module depends on this API, never on the MCP server, and this API depends on no domain module. There is no prefix map, no tool list, nothing here that names a module — which is what makes each module deployable on its own.

Documentation¶

• Authors — what the assistant that edits your content is allowed to do, what it asks before doing it, and what it refuses.
• Developers · Installation — what the JAR contains, Maven coordinates, how to register a tool, how to write one, and why a tool stays inert without a transport.
• Developers · Configuration — every YAML key, the fourteen standard actions and their parameters, the validation pipeline, the guards, and the full helper reference.
• Troubleshooting — symptom to cause, silent failures first.

Requirements¶