From d0b397c4a9c58bb8b71a9bf390f8aadc49f92b6d Mon Sep 17 00:00:00 2001 From: Ryan Wang Date: Mon, 2 Nov 2026 15:28:19 +0800 Subject: [PATCH 1/2] Guide AI clients to create HTML content by default --- .../run/halo/mcpserver/tools/PostTools.java | 17 ++++++++++------- .../halo/mcpserver/tools/SinglePageTools.java | 17 ++++++++++------- .../run/halo/mcpserver/tools/ToolSupport.java | 3 +++ 3 files changed, 23 insertions(+), 14 deletions(-) diff --git a/src/main/java/run/halo/mcpserver/tools/PostTools.java b/src/main/java/run/halo/mcpserver/tools/PostTools.java index 0a72c01..21bd929 100644 --- a/src/main/java/run/halo/mcpserver/tools/PostTools.java +++ b/src/main/java/run/halo/mcpserver/tools/PostTools.java @@ -277,12 +277,12 @@ private BuiltInTool createTool() { "name", stringSchema("Post metadata.name (a lowercase DNS label)."), "title", stringSchema(), "slug", stringSchema(), - "raw", stringSchema("Editable source content stored in the snapshot."), + "raw", + stringSchema("Editable source content stored in the snapshot." + + " Provide HTML by default so Halo's built-in rich text editor can" + + " preview and edit it."), "content", stringSchema("Rendered content; defaults to raw when omitted."), - "rawType", - described( - stringSchemaWithDefault(DEFAULT_RAW_TYPE), - "Format identifier for raw, such as html or markdown."), + "rawType", described(stringSchemaWithDefault(DEFAULT_RAW_TYPE), RAW_TYPE_DESCRIPTION), "publish", described( booleanSchema(false), @@ -317,12 +317,15 @@ private BuiltInTool updateTool() { "name", stringSchema("Post metadata.name."), "title", stringSchema(), "slug", stringSchema(), - "raw", stringSchema("New editable source; omit for a metadata-only update."), + "raw", + stringSchema("New editable source; omit for a metadata-only update." + + " Provide HTML by default so Halo's built-in rich text editor can" + + " preview and edit it."), "content", stringSchema("Rendered content; valid only when raw is provided."), "rawType", described( stringSchemaWithDefault(DEFAULT_RAW_TYPE), - "Format identifier for raw; valid only when raw is provided."), + RAW_TYPE_DESCRIPTION + " Ignored when raw is omitted."), "visible", enumSchema(Post.VisibleEnum.class), "allowComment", booleanSchema(), "cover", nullableStringSchema(), diff --git a/src/main/java/run/halo/mcpserver/tools/SinglePageTools.java b/src/main/java/run/halo/mcpserver/tools/SinglePageTools.java index 05131c0..ded03d1 100644 --- a/src/main/java/run/halo/mcpserver/tools/SinglePageTools.java +++ b/src/main/java/run/halo/mcpserver/tools/SinglePageTools.java @@ -276,12 +276,12 @@ private BuiltInTool createTool() { "name", stringSchema("SinglePage metadata.name (a lowercase DNS label)."), "title", stringSchema(), "slug", stringSchema(), - "raw", stringSchema("Editable source content stored in the snapshot."), + "raw", + stringSchema("Editable source content stored in the snapshot." + + " Provide HTML by default so Halo's built-in rich text editor can" + + " preview and edit it."), "content", stringSchema("Rendered content; defaults to raw when omitted."), - "rawType", - described( - stringSchemaWithDefault(DEFAULT_RAW_TYPE), - "Format identifier for raw, such as html or markdown."), + "rawType", described(stringSchemaWithDefault(DEFAULT_RAW_TYPE), RAW_TYPE_DESCRIPTION), "publish", described( booleanSchema(false), @@ -307,12 +307,15 @@ private BuiltInTool updateTool() { "name", stringSchema("SinglePage metadata.name."), "title", stringSchema(), "slug", stringSchema(), - "raw", stringSchema("New editable source; omit for a metadata-only update."), + "raw", + stringSchema("New editable source; omit for a metadata-only update." + + " Provide HTML by default so Halo's built-in rich text editor can" + + " preview and edit it."), "content", stringSchema("Rendered content; valid only when raw is provided."), "rawType", described( stringSchemaWithDefault(DEFAULT_RAW_TYPE), - "Format identifier for raw; valid only when raw is provided."), + RAW_TYPE_DESCRIPTION + " Ignored when raw is omitted."), "visible", enumSchema(Post.VisibleEnum.class), "allowComment", booleanSchema()), List.of("name")), diff --git a/src/main/java/run/halo/mcpserver/tools/ToolSupport.java b/src/main/java/run/halo/mcpserver/tools/ToolSupport.java index 245bd51..35e17d8 100644 --- a/src/main/java/run/halo/mcpserver/tools/ToolSupport.java +++ b/src/main/java/run/halo/mcpserver/tools/ToolSupport.java @@ -35,6 +35,9 @@ abstract class ToolSupport { static final int DEFAULT_PAGE_SIZE = 20; static final int MAX_PAGE_SIZE = 100; + static final String RAW_TYPE_DESCRIPTION = + "Format identifier for raw. html (the default) is compatible with Halo's built-in rich text editor;" + + " use markdown only when the user requests Markdown or the site has a Markdown editor plugin."; static final McpSchema.ToolAnnotations READ_ONLY = annotations(true, false, true, false); static final McpSchema.ToolAnnotations CREATE = annotations(false, false, false, false); static final McpSchema.ToolAnnotations UPDATE = annotations(false, true, true, false); From 7bfb8a96de414c981b8efbc512e29572682c79c2 Mon Sep 17 00:00:00 2001 From: Ryan Wang Date: Mon, 2 Nov 2026 15:47:29 +0800 Subject: [PATCH 2/2] Address review feedback on rawType guidance --- .../java/run/halo/mcpserver/tools/PostTools.java | 15 +++++++++------ .../run/halo/mcpserver/tools/SinglePageTools.java | 15 +++++++++------ .../run/halo/mcpserver/tools/ToolSupport.java | 6 ++++-- 3 files changed, 22 insertions(+), 14 deletions(-) diff --git a/src/main/java/run/halo/mcpserver/tools/PostTools.java b/src/main/java/run/halo/mcpserver/tools/PostTools.java index 21bd929..ae43228 100644 --- a/src/main/java/run/halo/mcpserver/tools/PostTools.java +++ b/src/main/java/run/halo/mcpserver/tools/PostTools.java @@ -35,7 +35,6 @@ class PostTools extends ToolSupport implements ToolGroup { static final String RESTORE_POST = "halo_restore_post"; private static final int MAX_CONTENT_CHARS = 65_536; - private static final String DEFAULT_RAW_TYPE = "html"; private final ReactiveExtensionClient client; private final PostContentService contentService; @@ -279,8 +278,9 @@ private BuiltInTool createTool() { "slug", stringSchema(), "raw", stringSchema("Editable source content stored in the snapshot." - + " Provide HTML by default so Halo's built-in rich text editor can" - + " preview and edit it."), + + " Provide an HTML body fragment by default (no , ," + + " ,