@salesforce/graphiti 11.13.2 → 11.14.0

package/src/mcp/tools/__tests__/sf-gql-list.spec.ts

@@ -25,12 +25,16 @@ const ORG_URL = "https://test-tool-list.my.salesforce.com";
 const SCHEMA = buildSchema(`
 	type Query { uiapi: UIAPI! }
 	type UIAPI { query: RecordQuery! }
-	type RecordQuery { Account(first: Int, after: String): AccountConnection! }
+	type RecordQuery { Account(first: Int, after: String, where: Account_Filter, orderBy: Account_OrderBy): AccountConnection! }
 	type AccountConnection { edges: [AccountEdge!]!, pageInfo: PageInfo! }
 	type AccountEdge { node: Account! }
 	type PageInfo { hasNextPage: Boolean!, endCursor: String }
 	type Account { Id: ID!, Name: StringValue }
 	type StringValue { value: String }
+	input Account_Filter { Name: StringOperators }
+	input StringOperators { eq: String }
+	input Account_OrderBy { Name: OrderByValue }
+	input OrderByValue { order: String }
 `);
 primeSchemaCache(ORG, SCHEMA);
 primeSchemaCache(ORG_URL, SCHEMA);
@@ -148,4 +152,286 @@ describe("mcp/tools/sf-gql-list", () => {
 			await server.close();
 		}
 	});
+
+	it("accepts a whole-argument $filter string and renders where: $filter", async () => {
+		const { client, server } = await connect();
+		try {
+			const res = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], filter: "$filter" },
+			});
+			const content = res.content as { type: string; text?: string }[];
+			const out = JSON.parse(content[0]?.text ?? "{}") as {
+				query: string;
+				variables: { name: string }[];
+			};
+			expect(out.query).toMatch(/where\s*:\s*\$filter\b/);
+			expect(out.variables.find((v) => v.name === "filter")).toBeDefined();
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("rejects an invalid whole-argument placeholder", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], filter: "$1bad" },
+			});
+			expect(result.isError).toBe(true);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("accepts a whole-argument $first string", async () => {
+		const { client, server } = await connect();
+		try {
+			const res = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], first: "$first" },
+			});
+			const content = res.content as { type: string; text?: string }[];
+			const out = JSON.parse(content[0]?.text ?? "{}") as {
+				query: string;
+				variables: { name: string }[];
+			};
+			expect(out.query).toMatch(/first\s*:\s*\$first\b/);
+			expect(out.variables.find((v) => v.name === "first")).toBeDefined();
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("rejects an invalid $first placeholder", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], first: "$1bad" },
+			});
+			expect(result.isError).toBe(true);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/list advertises orderBy/filter/first $var branch inline (no lost $ref branches)", async () => {
+		const { client, server } = await connect();
+		try {
+			const list = await client.listTools();
+			const tool = list.tools.find((t) => t.name === "sf_gql_list");
+			const props = (tool!.inputSchema as { properties: Record<string, unknown> }).properties;
+
+			// The advertised JSON Schema must be self-contained: the whole serialized
+			// schema string must not rely on $ref to express these unions, because the
+			// MCP SDK's converter resolves $refs in ways that have dropped the string
+			// branch (regressing client-side validation of "$var" inputs).
+			const whole = JSON.stringify(tool!.inputSchema);
+			expect(whole.includes("$ref")).toBe(false);
+
+			// Each of these args must advertise a string branch carrying the $var pattern.
+			for (const key of ["orderBy", "filter", "first"]) {
+				const schema = JSON.stringify(props[key]);
+				expect(schema, `${key} must inline a string $var branch`).toMatch(/"type":"string"/);
+				expect(schema, `${key} must carry the $var regex pattern`).toContain("\\\\$"); // pattern ^\$...
+			}
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("accepts a JSON-stringified filter object (model serialization tolerance)", async () => {
+		const { client, server } = await connect();
+		try {
+			const res = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], filter: '{"Name":{"eq":"$q"}}' },
+			});
+			const content = res.content as { type: string; text?: string }[];
+			const out = JSON.parse(content[0]?.text ?? "{}") as {
+				query: string;
+				variables: { name: string }[];
+			};
+			// coerced to object, leaf $q promoted
+			expect(out.variables.find((v) => v.name === "q")).toBeDefined();
+			expect(out.query).toMatch(/Name\s*:\s*\{\s*eq\s*:\s*\$q/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("accepts a JSON-stringified orderBy object", async () => {
+		const { client, server } = await connect();
+		try {
+			const res = await client.callTool({
+				name: "sf_gql_list",
+				arguments: {
+					org: ORG,
+					object: "Account",
+					fields: ["Id"],
+					orderBy: '{"Name":{"order":"DESC"}}',
+				},
+			});
+			const content = res.content as { type: string; text?: string }[];
+			const out = JSON.parse(content[0]?.text ?? "{}") as { query: string };
+			expect(out.query).toMatch(/orderBy\s*:\s*\{\s*Name/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("accepts a stringified number for first", async () => {
+		const { client, server } = await connect();
+		try {
+			const res = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], first: "25" },
+			});
+			const content = res.content as { type: string; text?: string }[];
+			const out = JSON.parse(content[0]?.text ?? "{}") as { query: string };
+			expect(out.query).toMatch(/first\s*:\s*25\b/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("still promotes a whole-arg $var (coercion leaves $var strings alone)", async () => {
+		const { client, server } = await connect();
+		try {
+			const res = await client.callTool({
+				name: "sf_gql_list",
+				arguments: {
+					org: ORG,
+					object: "Account",
+					fields: ["Id"],
+					orderBy: "$orderBy",
+					filter: "$filter",
+				},
+			});
+			const content = res.content as { type: string; text?: string }[];
+			const out = JSON.parse(content[0]?.text ?? "{}") as { query: string };
+			expect(out.query).toMatch(/orderBy\s*:\s*\$orderBy\b/);
+			expect(out.query).toMatch(/where\s*:\s*\$filter\b/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("rejects a non-JSON garbage string for filter", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], filter: "not json{" },
+			});
+			expect(result.isError).toBe(true);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("rejects pure garbage string for filter (hello)", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], filter: "hello" },
+			});
+			expect(result.isError).toBe(true);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("accepts a double-quoted $var placeholder (model double-stringify)", async () => {
+		const { client, server } = await connect();
+		try {
+			const res = await client.callTool({
+				name: "sf_gql_list",
+				arguments: {
+					org: ORG,
+					object: "Account",
+					fields: ["Id"],
+					filter: '"$filter"',
+					orderBy: '"$orderBy"',
+				},
+			});
+			const content = res.content as { type: string; text?: string }[];
+			const out = JSON.parse(content[0]?.text ?? "{}") as {
+				query: string;
+				variables: { name: string }[];
+			};
+			expect(out.query).toMatch(/where\s*:\s*\$filter\b/);
+			expect(out.query).toMatch(/orderBy\s*:\s*\$orderBy\b/);
+			expect(out.variables.find((v) => v.name === "filter")).toBeDefined();
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("accepts a double-quoted first placeholder and a quoted number", async () => {
+		const { client, server } = await connect();
+		try {
+			const res1 = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], first: '"$first"' },
+			});
+			const content1 = res1.content as { type: string; text?: string }[];
+			const out1 = JSON.parse(content1[0]?.text ?? "{}") as { query: string };
+			expect(out1.query).toMatch(/first\s*:\s*\$first\b/);
+
+			const res2 = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], first: '"25"' },
+			});
+			const content2 = res2.content as { type: string; text?: string }[];
+			const out2 = JSON.parse(content2[0]?.text ?? "{}") as { query: string };
+			expect(out2.query).toMatch(/first\s*:\s*25\b/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("still rejects quoted garbage", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], filter: '"hello"' },
+			});
+			expect(result.isError).toBe(true);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("rejects garbage string for first (abc)", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_list",
+				arguments: { org: ORG, object: "Account", fields: ["Id"], first: "abc" },
+			});
+			expect(result.isError).toBe(true);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
 });

package/src/schemas/fields.ts

@@ -7,6 +7,50 @@
 import { z } from "zod";
 import { GRAPHQL_NAME_RE } from "../lib/graphql-name.js";
 
+/**
+ * Some MCP clients/models JSON-stringify complex tool arguments (e.g. send
+ * `"25"` for a number or `'{"x":1}'` for an object). This coerces such a
+ * string back to its parsed value so the real value validates — lossless,
+ * and scoped to strings that LOOK like JSON (object/array/number) so `$var`
+ * placeholders and enum strings (e.g. scope "MINE") are left untouched.
+ * Same "tolerate predictable client encoding quirks" philosophy as the
+ * detailOrderBy array-collapse shim.
+ */
+export const coerceJsonArg = (v: unknown): unknown => {
+	const once = coerceJsonOnce(v);
+	// Unwrapping a double-quoted string (e.g. '"25"' → "25", '"$first"' → "$first")
+	// can yield another coercible string; coerce one more level so '"25"' → 25.
+	if (typeof once === "string" && once !== v) return coerceJsonOnce(once);
+	return once;
+};
+
+const coerceJsonOnce = (v: unknown): unknown => {
+	if (typeof v !== "string") return v;
+	const t = v.trim();
+	// object/array, bare number, OR a JSON-quoted string literal
+	if (!(t.startsWith("{") || t.startsWith("[") || /^-?\d+(\.\d+)?$/.test(t) || t.startsWith('"')))
+		return v;
+	try {
+		return JSON.parse(t);
+	} catch {
+		return v;
+	}
+};
+
+/** Wrap a schema so a JSON-stringified value is coerced before validation. */
+export const jsonCoercible = (schema: z.ZodTypeAny) => z.preprocess(coerceJsonArg, schema);
+
+/** A string that looks like a JSON object/array literal — used so the advertised
+ *  schema accepts a stringified object/array; coerceJsonArg then parses it. A
+ *  `{`/`[`-prefixed but invalid-JSON string is accepted as a literal (rare; the
+ *  model reliably sends valid JSON) rather than erroring. */
+export const jsonLiteralString = () => z.string().regex(/^\s*[{[]/);
+/** A string of digits — a stringified positive integer for `first`. */
+export const intLiteralString = () => z.string().regex(/^\d+$/);
+/** A JSON-quoted string literal, e.g. "\"$first\"" or "\"25\"" — some models
+ *  double-encode args. coerceJsonArg unwraps it before validation. */
+export const quotedString = () => z.string().regex(/^".*"$/s);
+
 /**
  * Zod string validator that enforces the GraphQL Name production. Returned
  * schema is `.describe()`-tagged with the supplied description so it appears
@@ -26,11 +70,20 @@ export const orgAlias = (description: string): z.ZodString =>
 	z.string().regex(ORG_ALIAS_RE, "must be a valid org alias or username").describe(description);
 
 /**
- * `<Object>_OrderBy` shape. UIAPI accepts a singleton object; tools may
- * additionally accept arrays as a compat shim depending on their advertised
- * schema policy (see `sf-gql-list.ts` vs `sf-gql-detail.ts`).
+ * `<Object>_OrderBy` shape. A FACTORY (not a shared instance): each call returns
+ * a fresh schema so the MCP SDK's zod-to-json-schema converter INLINES it at every
+ * use site instead of collapsing reuse into cross-`$ref`s (which intermittently
+ * dropped union branches in the advertised schema).
+ */
+export const orderByObject = () => z.record(z.unknown());
+
+/**
+ * A bare top-level `$varName` string standing in for an entire `filter` /
+ * `orderBy` / `first` argument. A FACTORY (not a shared instance) so the advertised
+ * JSON Schema inlines it at every use site rather than emitting cross-`$ref`s.
  */
-export const orderByObject = z.record(z.unknown());
+export const varPlaceholder = () =>
+	z.string().regex(/^\$[A-Za-z_]\w*$/, "must be a $variable placeholder, e.g. $filter");
 
 /**
  * Build a `childRelationships[]` element schema. The `orderBy` schema is a
@@ -49,7 +102,13 @@ export const childRelationshipSchema = (orderBy: z.ZodTypeAny) =>
 			'Child relationship API name, e.g. "Contacts", "Opportunities". Must be a valid GraphQL Name.',
 		),
 		fields: z.array(z.string()),
-		first: z.number().int().positive().optional(),
-		filter: z.record(z.unknown()).optional(),
-		orderBy: orderBy.optional(),
+		first: jsonCoercible(
+			z.union([z.number().int().positive(), varPlaceholder(), intLiteralString(), quotedString()]),
+		).optional(),
+		filter: jsonCoercible(
+			z.union([z.record(z.unknown()), varPlaceholder(), jsonLiteralString(), quotedString()]),
+		).optional(),
+		orderBy: jsonCoercible(
+			z.union([orderBy, varPlaceholder(), jsonLiteralString(), quotedString()]),
+		).optional(),
 	});

package/src/schemas/input-schemas.ts

@@ -17,14 +17,32 @@
  */
 
 import { z } from "zod";
-import { childRelationshipSchema, graphqlName, orderByObject, orgAlias } from "./fields.js";
+import {
+	childRelationshipSchema,
+	graphqlName,
+	intLiteralString,
+	jsonCoercible,
+	jsonLiteralString,
+	orderByObject,
+	orgAlias,
+	quotedString,
+	varPlaceholder,
+} from "./fields.js";
 import { GROUP_BY_FUNCTIONS } from "../intent/types.js";
 
 // --- sf_gql_list ------------------------------------------------------------
 
 // `sf_gql_list` advertises both shapes (singleton + array) for backward
 // compatibility with early MCP clients that learned the array form.
-const listOrderBySchema = z.union([orderByObject, z.array(orderByObject)]);
+// Factory function to avoid cross-$ref deduplication.
+const listOrderBySchema = () =>
+	z.union([
+		orderByObject(),
+		z.array(orderByObject()),
+		varPlaceholder(),
+		jsonLiteralString(),
+		quotedString(),
+	]);
 
 export const LIST_INPUT = z.object({
 	org: z.string().describe("Org alias resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
@@ -38,24 +56,26 @@ export const LIST_INPUT = z.object({
 		.array(z.string())
 		.optional()
 		.describe('Dotted parent-relationship paths, e.g. "Account.Name".'),
-	childRelationships: z.array(childRelationshipSchema(listOrderBySchema)).optional(),
-	filter: z
-		.record(z.unknown())
+	childRelationships: z.array(childRelationshipSchema(listOrderBySchema())).optional(),
+	filter: jsonCoercible(
+		z.union([z.record(z.unknown()), varPlaceholder(), jsonLiteralString(), quotedString()]),
+	)
 		.optional()
 		.describe(
-			"<Object>_Filter shape. String leaves matching $varName promote to typed query variables.",
+			'<Object>_Filter shape — pass as a JSON OBJECT (e.g. {"Status":{"eq":"New"}}), not a JSON-stringified string. String leaves matching $varName promote to typed query variables. Pass a single "$varName" string to promote the WHOLE filter to one optional <Object>_Filter variable (bind it to null for "no filter → all rows").',
 		),
-	orderBy: listOrderBySchema
+	orderBy: jsonCoercible(listOrderBySchema())
 		.optional()
 		.describe(
-			"<Object>_OrderBy. Singleton object preferred; arrays are collapsed to the first entry.",
+			'<Object>_OrderBy — pass as a JSON OBJECT (e.g. {"CreatedDate":{"order":"DESC"}}), not a JSON-stringified string. Singleton object preferred; arrays are collapsed to the first entry. Pass a single "$varName" string to promote the whole orderBy to one optional <Object>_OrderBy variable.',
 		),
-	first: z
-		.number()
-		.int()
-		.positive()
+	first: jsonCoercible(
+		z.union([z.number().int().positive(), varPlaceholder(), intLiteralString(), quotedString()]),
+	)
 		.optional()
-		.describe("Top-level connection page size; defaults to 10."),
+		.describe(
+			'Top-level connection page size as a NUMBER (e.g. 25, not "25"); defaults to 10. Pass a single "$varName" string to promote it to an optional Int variable.',
+		),
 	scope: z.string().optional().describe('Scope enum (e.g. "MINE", "EVERYTHING") or $varName.'),
 	operationName: graphqlName(
 		"Override the GraphQL operation name. Defaults to <Object>List.",
@@ -68,7 +88,9 @@ export const LIST_INPUT = z.object({
 // arrays at runtime via `z.preprocess` (FR-6.2 compat shim for early MCP
 // clients that learned the array shape). The transform collapses to the first
 // element before validation, so downstream code sees a singleton.
-const detailOrderBySchema = z.preprocess((v) => (Array.isArray(v) ? v[0] : v), orderByObject);
+// Factory function to avoid cross-$ref deduplication.
+const detailOrderBySchema = () =>
+	z.preprocess((v) => (Array.isArray(v) ? v[0] : v), orderByObject());
 
 // Note: filter/orderBy/scope/first are intentionally absent at the top level —
 // `sf_gql_detail` is single-record-by-Id (FR-5.5). Filtering happens via the
@@ -90,7 +112,7 @@ export const DETAIL_INPUT = z
 			.array(z.string())
 			.optional()
 			.describe('Dotted parent-relationship paths, e.g. "Account.Name".'),
-		childRelationships: z.array(childRelationshipSchema(detailOrderBySchema)).optional(),
+		childRelationships: z.array(childRelationshipSchema(detailOrderBySchema())).optional(),
 		idVariable: graphqlName(
 			'Name (without leading "$") for the ID variable. Defaults to "id". Declared as <name>: ID! and bound via where { Id: { eq: $<name> } } per FR-5.5. Choose a name that does not appear as a $varName in any childRelationships filter/orderBy — collisions are rejected.',
 		).optional(),