@fruggr/zendesk-mcp-server 3.0.0 → 3.0.2

package/dist/index.js

@@ -1327,6 +1327,7 @@ const parseSections = (html) => {
 			current = {
 				heading: $(node).text().trim(),
 				headingTag: tagName,
+				headingHtml: $.html(node),
 				level,
 				contentParts: []
 			};
@@ -1344,6 +1345,7 @@ const parseSections = (html) => {
 			index: 0,
 			heading: "intro",
 			headingTag: "",
+			headingHtml: "",
 			level: 0,
 			html: introHtml,
 			wordCount: countWords(textOf(introHtml))
@@ -1355,6 +1357,7 @@ const parseSections = (html) => {
 			index: result.length,
 			heading: s.heading,
 			headingTag: s.headingTag,
+			headingHtml: s.headingHtml,
 			level: s.level,
 			html: sectionHtml,
 			wordCount: countWords(textOf(sectionHtml))
@@ -1365,11 +1368,51 @@ const parseSections = (html) => {
 const replaceSectionContent = (html, sectionIndex, newHtml) => {
 	const sections = parseSections(html);
 	if (sectionIndex < 0 || sectionIndex >= sections.length) throw new Error(`Section index ${sectionIndex} out of range (valid: 0-${Math.max(0, sections.length - 1)})`);
-	return sections.map((section, idx) => {
-		const content = idx === sectionIndex ? newHtml : section.html;
-		if (section.level === 0) return content;
-		return `<${section.headingTag}>${section.heading}</${section.headingTag}>${content}`;
-	}).join("");
+	return sections.map((section, idx) => `${section.headingHtml}${idx === sectionIndex ? newHtml : section.html}`).join("");
+};
+const LEADING_HEADING = /^\s*<(h[1-3])(?:\s[^>]*)?>([\s\S]*?)<\/\1\s*>/i;
+const normalizeText = (text) => text.trim().split(WHITESPACE_RUN).join(" ");
+const stripLeadingDuplicateHeading = (html, target) => {
+	const match = LEADING_HEADING.exec(html);
+	const tag = match?.[1];
+	if (!match || !tag) return {
+		html,
+		stripped: null
+	};
+	const text = normalizeText(textOf(match[2] ?? ""));
+	if (tag.toLowerCase() !== target.headingTag || text !== normalizeText(target.heading)) return {
+		html,
+		stripped: null
+	};
+	return {
+		html: html.slice(match[0].length).trimStart(),
+		stripped: {
+			tag: target.headingTag,
+			text
+		}
+	};
+};
+const introLoss = (target, contentSections) => {
+	if (target?.level !== 0) return null;
+	const first = contentSections[0];
+	if (!first) return "empty";
+	return first.level > 0 ? "heading-led" : null;
+};
+const applySectionUpdate = (html, sectionIndex, newHtml) => {
+	const sections = parseSections(html);
+	const target = sections[sectionIndex];
+	const { html: content, stripped } = target ? stripLeadingDuplicateHeading(newHtml, target) : {
+		html: newHtml,
+		stripped: null
+	};
+	const contentSections = parseSections(content);
+	return {
+		body: replaceSectionContent(html, sectionIndex, content),
+		stripped,
+		contentHeadings: contentSections.filter((s) => s.level > 0).length,
+		introLost: introLoss(target, contentSections),
+		sectionsBefore: sections.length
+	};
 };
 const keepAsHtml = (_state, node) => ({
 	type: "html",
@@ -2361,6 +2404,16 @@ const assertReorderParamsCoherent = (articleId, target, referenceArticleId) => {
 	if (!needsReference && referenceArticleId !== void 0) throw new Error(`reference_article_id must be omitted when target is "${target}" (it only applies to "before"/"after").`);
 	if (referenceArticleId !== void 0 && referenceArticleId === articleId) throw new Error("reference_article_id must differ from article_id.");
 };
+const structureWarning = (r) => {
+	if (r.introLost === "empty") {
+		if (r.sectionsBefore === 1) return ["Warning: content is empty and the intro was the only section, so the article body is now empty."];
+		return [`Warning: content is empty, so the intro no longer exists and every later section index moved down by one (article: ${r.sectionsAfter} sections, was ${r.sectionsBefore}). Call get_article_outline before the next edit.`];
+	}
+	if (r.introLost === "heading-led") return [`Warning: content starts with a heading, so the intro no longer exists and section [${r.sectionIndex}] is now a heading section (article: ${r.sectionsAfter} sections, was ${r.sectionsBefore}). Call get_article_outline before the next edit.`];
+	if (r.contentHeadings > 0) return [`Warning: content contains ${r.contentHeadings} heading(s) (h1-h3), so the article now has ${r.sectionsAfter} sections (was ${r.sectionsBefore}); indexes after [${r.sectionIndex}] shifted. Call get_article_outline before the next edit.`];
+	return [];
+};
+const sectionUpdateNotes = (r) => [...r.stripped ? [`Note: removed a leading <${r.stripped.tag}> "${r.stripped.text}" from content; the section heading is kept automatically and is not part of content.`] : [], ...structureWarning(r)];
 const createHelpCenterTools = (ctx) => {
 	const { subdomain, getToken } = ctx;
 	const fetchSectionOrder = async (sectionId, locale, token) => {
@@ -3207,7 +3260,7 @@ const createHelpCenterTools = (ctx) => {
 			namespace: "help_center",
 			readOnly: true,
 			title: "Get Article Section",
-			description: "Retrieve the content of a single section of an article in a given locale. Use get_article_outline first to discover section indexes. Default format=\"html\" for round-trip safety. Pass format=\"markdown\" only for human review — the Markdown representation is lossy on some structures (<pre> with <br>, tables with multi-<p> cells are kept as raw HTML to limit the damage, but do not round-trip markdown content back through update_article_section).",
+			description: "Retrieve the content of a single section of an article in a given locale. Use get_article_outline first to discover section indexes. Default format=\"html\" for round-trip safety. Pass format=\"markdown\" only for human review — the Markdown representation is lossy on some structures (<pre> with <br>, tables with multi-<p> cells are kept as raw HTML to limit the damage, but do not round-trip markdown content back through update_article_section). The \"## [n] hN: ...\" line at the top is a label, not part of the content.",
 			inputSchema: z.object({
 				article_id: z.number().int().describe(ARTICLE_ID_DESC),
 				locale: z.string().describe("Locale of the body (e.g., \"en-us\", \"fr\")"),
@@ -3245,12 +3298,12 @@ const createHelpCenterTools = (ctx) => {
 			namespace: "help_center",
 			readOnly: false,
 			title: "Update Article Section",
-			description: "Replace the content of a single section of an article in a given locale, keeping the rest of the body intact. The server fetches the current body, replaces the targeted section, and PUTs the full reconstructed body via the Translations API. Default format=\"html\" for fidelity. Use format=\"markdown\" only when you control the input and know it does not rely on structures that round-trip poorly (code blocks with line breaks, tables with multi-paragraph cells). The section heading is preserved and is NOT part of the replaced content.",
+			description: "Replace the body of one article section, heading excluded (the heading is kept as is), in a given locale, leaving the rest of the article intact. The server fetches the current body, replaces the targeted section, and PUTs the full reconstructed body via the Translations API. A leading heading in content that repeats the section heading is removed; any other h1-h3 in content creates new sections and shifts the later indexes (the response warns). section_index 0 is the heading-less intro, which exists only when the body has text before its first heading. Default format=\"html\" for fidelity. Use format=\"markdown\" only when you control the input and know it does not rely on structures that round-trip poorly (code blocks with line breaks, tables with multi-paragraph cells).",
 			inputSchema: z.object({
 				article_id: z.number().int().describe(ARTICLE_ID_DESC),
 				locale: z.string().describe("Locale of the translation to update"),
-				section_index: z.number().int().min(0).describe("0-based index of the section to replace (see get_article_outline)"),
-				content: z.string().describe("New content for the section (heading excluded). HTML by default, Markdown if format=\"markdown\"."),
+				section_index: z.number().int().min(0).describe("0-based index of the section to replace (see get_article_outline). 0 is the heading-less intro when the body has text before its first heading, otherwise the first heading."),
+				content: z.string().describe("New content for the section (heading excluded: send neither the heading nor the \"## [n] hN: ...\" label line that get_article_section prints). HTML by default, Markdown if format=\"markdown\"."),
 				format: z.enum(["html", "markdown"]).default("html").describe("Input format. \"html\" (default) is the safe path. \"markdown\" is converted to HTML server-side but may introduce artifacts on complex content.")
 			}),
 			annotations: {
@@ -3264,13 +3317,26 @@ const createHelpCenterTools = (ctx) => {
 				const token = await getToken();
 				const { translation } = await helpCenterGet(subdomain, token, `/articles/${article_id}/translations/${locale}`);
 				const newSectionHtml = format === "markdown" ? markdownToHtml(content) : content;
-				const newBody = replaceSectionContent(translation.body, section_index, newSectionHtml);
+				const { body: newBody, stripped, contentHeadings, introLost, sectionsBefore } = applySectionUpdate(translation.body, section_index, newSectionHtml);
 				const { translation: updated } = await helpCenterPut(subdomain, token, `/articles/${article_id}/translations/${locale}`, { translation: { body: newBody } });
-				const updatedSection = parseSections(updated.body)[section_index];
-				const newWordCount = updatedSection?.wordCount ?? 0;
+				const updatedSections = parseSections(updated.body);
+				const updatedSection = updatedSections[section_index];
+				const emptied = introLost === "empty";
+				const newWordCount = emptied ? 0 : updatedSection?.wordCount ?? 0;
 				return { content: [{
 					type: "text",
-					text: [`Section [${section_index}] "${updatedSection?.heading ?? "(intro)"}" updated for article #${article_id} (${locale}).`, `New word count: ${newWordCount}.`].join("\n")
+					text: [
+						`Section [${section_index}] "${emptied ? "(intro)" : updatedSection?.heading ?? "(intro)"}" updated for article #${article_id} (${locale}).`,
+						`New word count: ${newWordCount}.`,
+						...sectionUpdateNotes({
+							stripped,
+							contentHeadings,
+							introLost,
+							sectionIndex: section_index,
+							sectionsBefore,
+							sectionsAfter: updatedSections.length
+						})
+					].join("\n")
 				}] };
 			}
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "mcpName": "io.github.fruggr/zendesk-mcp-server",
   "description": "Deep Zendesk MCP server for your AI assistant: search, draft, update and translate Help Center articles and manage Support tickets end to end — comments, triage and image attachments.",
   "type": "module",
@@ -71,9 +71,9 @@
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@12.6.0+sha512.3ef68f951cb111ac204b4a5a16f0b2ddf0da56a96e0413e81d855d9f0b55ef926714709028e1cd00c405c2c5fb7b9e8ec4dc46777c805d0373c2f2ff00fd20ec",
+  "packageManager": "pnpm@12.5.1+sha512.e3f305bc784a2bc89f5ad3b6138889470fae8d2af5f36b61216ec91c2c3d64089775f9de38aac331044ea40f245cb0d5666392dfdf65824e1907ef6a2c62de5f",
   "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0",
+    "@modelcontextprotocol/server": "2.1.0",
     "cheerio": "1.2.0",
     "hast-util-to-html": "9.0.5",
     "hast-util-to-mdast": "10.1.2",
@@ -107,8 +107,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
-    "@modelcontextprotocol/client": "2.0.0",
-    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/client": "2.1.0",
+    "@modelcontextprotocol/node": "2.1.0",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^11.0.0",