test(mcp): add tests for jsonPreprocess and extract to module

Extract jsonPreprocess into its own module for testability.
Add vitest with 8 tests covering:
- native objects passed through unchanged
- JSON strings parsed before validation
- "all" literal preserved
- invalid JSON rejected by schema
- nested filter schemas
- sort schemas

Author: bobey

helicone-mcp/package.json

@@ -19,6 +19,7 @@
 		"dev": "tsx src/index.ts",
 		"format": "biome format --write",
 		"lint:fix": "biome lint --fix",
+		"test": "vitest run",
 		"type-check": "tsc --noEmit",
 		"flatten-types": "tsx flatten-types.ts",
 		"generate-zod": "npm run flatten-types && ts-to-zod src/types/flat.ts src/types/generated-zod.ts && npm run build"
@@ -45,8 +46,9 @@
 	"devDependencies": {
 		"@biomejs/biome": "^2.2.5",
 		"@types/node": "^24.9.2",
+		"tsx": "^4.7.0",
 		"typescript": "5.9.3",
-		"tsx": "^4.7.0"
+		"vitest": "^4.0.18"
 	},
 	"publishConfig": {
 		"access": "public"

helicone-mcp/src/__tests__/json-preprocess.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { jsonPreprocess } from "../lib/json-preprocess.js";
+
+describe("jsonPreprocess", () => {
+	const objectSchema = z.object({
+		name: z.string(),
+		value: z.number(),
+	});
+
+	it("passes through native objects unchanged", () => {
+		const schema = jsonPreprocess(objectSchema);
+		const result = schema.parse({ name: "test", value: 42 });
+		expect(result).toEqual({ name: "test", value: 42 });
+	});
+
+	it("parses a JSON string into an object before validation", () => {
+		const schema = jsonPreprocess(objectSchema);
+		const result = schema.parse('{"name": "test", "value": 42}');
+		expect(result).toEqual({ name: "test", value: 42 });
+	});
+
+	it("rejects a parsed JSON string that doesn't match the schema", () => {
+		const schema = jsonPreprocess(objectSchema);
+		expect(() => schema.parse('{"name": 123}')).toThrow();
+	});
+
+	it("preserves the 'all' literal string without parsing", () => {
+		const unionSchema = z.union([objectSchema, z.literal("all")]);
+		const schema = jsonPreprocess(unionSchema);
+		const result = schema.parse("all");
+		expect(result).toBe("all");
+	});
+
+	it("passes through invalid JSON strings for the schema to reject", () => {
+		const schema = jsonPreprocess(objectSchema);
+		expect(() => schema.parse("not valid json")).toThrow();
+	});
+
+	it("passes through non-string values (numbers, booleans, null)", () => {
+		const numberSchema = jsonPreprocess(z.number());
+		expect(numberSchema.parse(42)).toBe(42);
+
+		const boolSchema = jsonPreprocess(z.boolean());
+		expect(boolSchema.parse(true)).toBe(true);
+	});
+
+	it("works with nested filter schemas", () => {
+		const filterSchema = z.union([
+			z.object({
+				request_response_rmt: z.object({
+					request_id: z.object({
+						equals: z.string(),
+					}).optional(),
+				}).optional(),
+			}),
+			z.literal("all"),
+		]);
+
+		const schema = jsonPreprocess(filterSchema);
+
+		// JSON string with nested filter
+		const jsonInput = '{"request_response_rmt": {"request_id": {"equals": "abc-123"}}}';
+		const result = schema.parse(jsonInput);
+		expect(result).toEqual({
+			request_response_rmt: {
+				request_id: { equals: "abc-123" },
+			},
+		});
+
+		// "all" literal still works
+		expect(schema.parse("all")).toBe("all");
+
+		// Native object still works
+		const nativeResult = schema.parse({ request_response_rmt: { request_id: { equals: "xyz" } } });
+		expect(nativeResult).toEqual({ request_response_rmt: { request_id: { equals: "xyz" } } });
+	});
+
+	it("works with sort schemas", () => {
+		const sortSchema = z.object({
+			created_at: z.union([z.literal("asc"), z.literal("desc")]).optional(),
+		});
+
+		const schema = jsonPreprocess(sortSchema);
+		const result = schema.parse('{"created_at": "desc"}');
+		expect(result).toEqual({ created_at: "desc" });
+	});
+});

helicone-mcp/src/index.ts

@@ -4,21 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { fetchRequests, fetchSessions, useAiGateway } from "./lib/helicone-client.js";
 import { requestFilterNodeSchema, sortLeafRequestSchema, sessionFilterNodeSchema } from "./types/generated-zod.js";
-
-/**
- * Wraps a Zod schema with a preprocessing step that parses JSON strings.
- * Some MCP clients (e.g. Claude Code) serialize complex object parameters
- * as JSON strings rather than native objects. This ensures validation
- * still works regardless of how the client sends the data.
- */
-function jsonPreprocess<T extends z.ZodTypeAny>(schema: T) {
-	return z.preprocess((val) => {
-		if (typeof val === "string" && val !== "all") {
-			try { return JSON.parse(val); } catch { return val; }
-		}
-		return val;
-	}, schema);
-}
+import { jsonPreprocess } from "./lib/json-preprocess.js";
 
 const HELICONE_API_KEY = process.env.HELICONE_API_KEY;
 

helicone-mcp/src/lib/json-preprocess.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+
+/**
+ * Wraps a Zod schema with a preprocessing step that parses JSON strings.
+ * Some MCP clients (e.g. Claude Code) serialize complex object parameters
+ * as JSON strings rather than native objects. This ensures validation
+ * still works regardless of how the client sends the data.
+ */
+export function jsonPreprocess<T extends z.ZodTypeAny>(schema: T) {
+	return z.preprocess((val) => {
+		if (typeof val === "string" && val !== "all") {
+			try { return JSON.parse(val); } catch { return val; }
+		}
+		return val;
+	}, schema);
+}