H1 MCP Server

Previous Next

H1 MCP Server

Version 2.0.0-SNAPSHOT · Magnolia 6.4 · Java 21

H1 MCP Server puts an AI assistant inside AdminCentral — a chat panel one click away from wherever the manager is working — and gives it real hands: it creates pages, adds components, uploads assets, fixes metadata and publishes, through the same rules the editing form applies to a person. The same set of tools is published as a Model Context Protocol server, so an external client (Claude Desktop, MCP Inspector, your own agent) works against the same instance without a line of glue code.

It is the transport half of the pair: h1-mcp-api defines the tool contract and discovers every module's tools; this module exposes them over HTTP and drives a conversation against Claude or OpenAI. It also ships the five tools that are not tied to a domain module.

Feature What it solves Where it lives
AI Chat in AdminCentral A manager describes the change in words instead of clicking through forms — and the assistant knows which app they are in. Top-bar button + [H1] AI › AI Chat app
MCP server Any MCP client operates the instance: the tool list, its schemas and its guardrails come from the same registry the chat uses. /.rest/v1/mcp/admin
Public MCP surface A visitor-facing assistant that can read the site without being able to change it — the allowed actions are declared per registration. /.rest/v1/mcp
Two providers, one interface Claude or OpenAI, chosen with an environment variable. The tool loop, the history and the prompts are the module's, not the vendor's. HABITO_AI_PROVIDER
The website tool Pages, areas and nested components — created, updated, reordered and published, with component availability checked against the template. WebsiteTool
The asset tool Upload by URL or base64 into the DAM, plus folders, metadata and publishing. AssetTool
The content_type tool Discover what content types exist and what fields they really have, and publish or delete a node in any workspace. ContentTypeTool
The marketing_tag tool Analytics and marketing scripts (GA, Meta Pixel) managed as content, including which pages they apply to. MarketingTagTool
The keywords guide The keywords a human wants a piece of content to work, stored where an AI writer can read them — and rendered nowhere. [H1] AI tab · h1mcp_keywords

Why use H1 MCP Server?

  • The assistant is where the work is. A button in the AdminCentral top bar opens the chat over whatever app the manager has open, and every message carries that context — the assistant does not have to be told where it is.
  • It acts, it does not advise. The chat runs a tool loop of up to ten steps per message, so "create the landing page, add the hero and publish it" is one instruction, not a checklist. Every step goes through the same validation as the form.
  • One tool set, three doors. The chat, the MCP server and the public surface all read the same registry, so a tool a module publishes is immediately available in all of them, with the same schema and the same refusals.
  • Not locked to a vendor. Switching between Claude and OpenAI is one environment variable; the conversation, the tool definitions and the system prompt stay identical, because the provider sits behind a two-method interface.
  • The keywords a human chose are not lost. Primary and secondary keywords live on the content itself, ordered, for the writing agent to read — and they are emitted nowhere, because meta keywords has been dead since 2009.

Documentation

  • Authors — where the chat is, what it can do for you, what it remembers, and the [H1] AI tab with its keyword lists field by field.
  • Developers · Installation — what the JAR contains, Maven coordinates, the API key and provider variables, how the chat panel gets injected, permissions and verification.
  • Developers · Configuration — every environment variable, the MCP protocol surface, the three endpoints, the five tools and their actions, the conversation limits and the properties reference.
  • Troubleshooting — symptom to cause, silent failures first.

Requirements
Magnolia 6.4 (built against bundle 6.4.0; DX Core or Community)
Java 21
Magnolia modules core, rest-integration, rest-services (declared in the module descriptor)
H1 modules h1-mcp-api (mandatory — the tool contract and both registries) · h1-helpers (mandatory, used by the marketing_tag tool)
An LLM account Mandatory for the chat. An OPENAI_API_KEY or an ANTHROPIC_API_KEY in the instance's environment. The MCP server itself works without one
Optional integrations The DX Core marketing-tags module — when absent, the marketing_tag tool hides itself instead of failing
Magnolia platform APIs used magnolia-rendering, magnolia-ui-framework, magnolia-ui-framework-compatibility, magnolia-content-types, magnolia-content-types-jcr, vaadin-server-mpr-jakarta, jakarta.servlet-api (all provided — supplied by the bundle)
Repository README Authors