feat: MCP support for json5/yaml/toml/xml/html

Author: benjamine

packages/diff-mcp/package-lock.json

@@ -11,6 +11,7 @@
 	},
 	"scripts": {
 		"build": "tsc",
+		"start": "node build/index.js",
 		"type-check": "tsc --noEmit",
 		"lint": "biome check --error-on-warnings .",
 		"test": "vitest --coverage",
@@ -23,12 +24,17 @@
 	},
 	"keywords": ["mcp", "compare", "diff", "json", "jsondiffpatch"],
 	"dependencies": {
-		"jsondiffpatch": "^0.7.3",
 		"@dmsnell/diff-match-patch": "^1.1.0",
 		"@modelcontextprotocol/sdk": "^1.8.0",
+		"fast-xml-parser": "^5.0.9",
+		"js-yaml": "^4.1.0",
+		"json5": "^2.2.3",
+		"jsondiffpatch": "^0.7.2",
+		"smol-toml": "^1.3.1",
 		"zod": "^3.24.2"
 	},
 	"devDependencies": {
+		"@types/js-yaml": "^4.0.9",
 		"@vitest/coverage-v8": "^3.0.9",
 		"tslib": "^2.6.2",
 		"typescript": "^5.8.2",

packages/diff-mcp/package.json

@@ -3,6 +3,10 @@ import * as consoleFormatter from "jsondiffpatch/formatters/console";
 import * as jsonpatchFormatter from "jsondiffpatch/formatters/jsonpatch";
 import { create } from "jsondiffpatch/with-text-diffs";
 
+import { XMLParser } from "fast-xml-parser";
+import yaml from "js-yaml";
+import json5 from "json5";
+import { parse as tomlParse } from "smol-toml";
 import { z } from "zod";
 
 export const createMcpServer = () => {
@@ -21,26 +25,26 @@ export const createMcpServer = () => {
 		"compare text or data and get a readable diff",
 		{
 			state: z.object({
-				left: z
-					.string()
-					.or(z.record(z.string(), z.unknown()))
-					.or(z.array(z.unknown()))
-					.describe("The left side of the diff."),
-				right: z
-					.string()
-					.or(z.record(z.string(), z.unknown()))
-					.or(z.array(z.unknown()))
-					.describe(
-						"The right side of the diff (to compare with the left side).",
-					),
+				left: inputDataSchema.describe("The left side of the diff."),
+				leftFormat: formatSchema
+					.optional()
+					.describe("format of left side of the diff"),
+				right: inputDataSchema.describe(
+					"The right side of the diff (to compare with the left side).",
+				),
+				rightFormat: formatSchema
+					.optional()
+					.describe("format of right side of the diff"),
 				outputFormat: z
 					.enum(["text", "json", "jsonpatch"])
+					.default("text")
 					.describe(
 						"The output format. " +
-							"text: human readable text diff, " +
+							"text: (default) human readable text diff, " +
 							"json: a compact json diff (jsondiffpatch delta format), " +
 							"jsonpatch: json patch diff (RFC 6902)",
-					),
+					)
+					.optional(),
 			}),
 		},
 		({ state }) => {
@@ -56,23 +60,37 @@ export const createMcpServer = () => {
 					},
 				});
 
-				const delta = jsondiffpatch.diff(state.left, state.right);
-
+				const left = parseData(state.left, state.leftFormat);
+				const right = parseData(state.right, state.rightFormat);
+				const delta = jsondiffpatch.diff(left, right);
 				const output =
 					state.outputFormat === "json"
 						? delta
 						: state.outputFormat === "jsonpatch"
 							? jsonpatchFormatter.format(delta)
-							: consoleFormatter.format(delta);
+							: consoleFormatter.format(delta, left);
+
+				const legend =
+					state.outputFormat === "text"
+						? `\n\nlegend:
+  - lines starting with "+" indicate new property or item array
+  - lines starting with "-" indicate removed property or item array
+  - "value => newvalue" indicate property value changed
+  - "x: ~> y indicate array item moved from index x to y
+  - text diffs are lines that start "line,char" numbers, and have a line below
+    with "+" under added chars, and "-" under removed chars.
+  - you can use this exact representations when showing differences to the user
+  \n`
+						: "";
 
 				return {
 					content: [
 						{
 							type: "text",
 							text:
-								typeof output === "string"
+								(typeof output === "string"
 									? output
-									: JSON.stringify(output, null, 2),
+									: JSON.stringify(output, null, 2)) + legend,
 						},
 					],
 				};
@@ -93,3 +111,63 @@ export const createMcpServer = () => {
 
 	return server;
 };
+
+const inputDataSchema = z
+	.string()
+	.or(z.record(z.string(), z.unknown()))
+	.or(z.array(z.unknown()));
+
+const formatSchema = z
+	.enum(["text", "json", "json5", "yaml", "toml", "xml", "html"])
+	.default("json5");
+
+const parseData = (
+	data: z.infer<typeof inputDataSchema>,
+	format: z.infer<typeof formatSchema> | undefined,
+) => {
+	if (typeof data !== "string") {
+		// already parsed
+		return data;
+	}
+	if (!format || format === "text") {
+		return data;
+	}
+
+	if (format === "json") {
+		try {
+			return JSON.parse(data);
+		} catch {
+			// if json is invalid, try json5
+			return json5.parse(data);
+		}
+	}
+	if (format === "json5") {
+		return json5.parse(data);
+	}
+	if (format === "yaml") {
+		return yaml.load(data);
+	}
+	if (format === "xml") {
+		const parser = new XMLParser({
+			ignoreAttributes: false,
+			preserveOrder: true,
+		});
+		return parser.parse(data);
+	}
+	if (format === "html") {
+		const parser = new XMLParser({
+			ignoreAttributes: false,
+			preserveOrder: true,
+			unpairedTags: ["hr", "br", "link", "meta"],
+			stopNodes: ["*.pre", "*.script"],
+			processEntities: true,
+			htmlEntities: true,
+		});
+		return parser.parse(data);
+	}
+	if (format === "toml") {
+		return tomlParse(data);
+	}
+	format satisfies never;
+	throw new Error(`unsupported format: ${format}`);
+};

packages/diff-mcp/src/server.ts

@@ -10,7 +10,7 @@
 		"esModuleInterop": true,
 		"forceConsistentCasingInFileNames": true,
 		"strict": true,
-		"skipLibCheck": false,
+		"skipLibCheck": true,
 		"noFallthroughCasesInSwitch": true,
 		"noImplicitReturns": true,
 		"noUncheckedIndexedAccess": true,