@salesforce/graphiti 10.10.2

package/src/mcp/tools/sf-gql-raw.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { buildRaw } from "../../intent/build-raw.js";
+import { type PrimeDeps } from "../../lib/prime-schema.js";
+
+export interface SfGqlRawToolOptions {
+	primeDeps?: PrimeDeps;
+}
+
+const inputSchema = {
+	org: z.string().describe("Org alias resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
+	commands: z
+		.array(z.string())
+		.min(1)
+		.describe(
+			"CLI-style commands applied in order to a transient session. Supported verbs:\n" +
+				"  select <path[:alias]>      e.g. select uiapi/query/Case/edges/node/Subject/value\n" +
+				"  set [<path>] <key>=<value> e.g. set uiapi/query/Case first=10  |  set uiapi/query/Case where.Status=New\n" +
+				"  var $name <path> [default] e.g. var $id uiapi/query/Case/@args/where/Id/eq (type inferred from path)\n" +
+				'Each command is tokenized on spaces and a value MUST NOT contain a space — quoting does not help once a token has started (key=\'a b\' still splits). A filter value that contains a space (e.g. "New York", "In Progress") cannot be expressed via set in v1; use sf_gql_list with a JSON filter, or pass the value through a variable bound with var.\n' +
+				"Fails fast: a bad command aborts the whole call. Other CLI verbs (cd, drop, alias, optional, unset) are NOT supported in v1.",
+		),
+	operation: z
+		.enum(["query", "mutation", "aggregate"])
+		.optional()
+		.describe(
+			'Operation root. "query" (default) → uiapi.query; "mutation" → mutation root; "aggregate" → uiapi.aggregate.',
+		),
+	typeName: z
+		.string()
+		.optional()
+		.describe("Codegen type prefix / operation name override. Defaults to Raw<Operation>."),
+};
+
+export function registerSfGqlRawTool(server: McpServer, opts: SfGqlRawToolOptions = {}): void {
+	server.registerTool(
+		"sf_gql_raw",
+		{
+			description:
+				"Low-level escape hatch: build an arbitrary UIAPI query, mutation, or aggregate from CLI-style commands (select/set/var) when the typed tools don't model the case (cross-union selections, custom mutations). Returns rendered GraphQL, declared variables, generated TypeScript types, and validation warnings. Fails fast on a bad command.",
+			inputSchema,
+		},
+		async (args) => {
+			const output = await buildRaw(args, opts.primeDeps);
+			return {
+				content: [{ type: "text", text: JSON.stringify(output) }],
+			};
+		},
+	);
+}

package/src/mcp/tools/sf-gql-update.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { buildUpdate } from "../../intent/build-update.js";
+import { type PrimeDeps } from "../../lib/prime-schema.js";
+
+export interface SfGqlUpdateToolOptions {
+	primeDeps?: PrimeDeps;
+}
+
+const inputSchema = {
+	org: z.string().describe("Org alias resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
+	object: z.string().describe('SObject API name, e.g. "Account", "Order".'),
+	returnFields: z
+		.array(z.string())
+		.optional()
+		.describe(
+			'Scalar field API names to read back on the updated Record. Defaults to ["Id"]. Dot-paths like Owner.Name are not supported in mutation results; passing them produces a warning and the field is skipped.',
+		),
+	inputVariable: z
+		.string()
+		.optional()
+		.describe(
+			'Variable name (without "$") for the update input. Defaults to "input". Declared as $<name>: <Object>UpdateInput!.',
+		),
+	operationName: z
+		.string()
+		.optional()
+		.describe("Override the GraphQL operation name. Defaults to Update<Object>."),
+};
+
+export function registerSfGqlUpdateTool(
+	server: McpServer,
+	opts: SfGqlUpdateToolOptions = {},
+): void {
+	server.registerTool(
+		"sf_gql_update",
+		{
+			description:
+				"Build a UIAPI update mutation against a Salesforce org. Declares a typed input variable ($input: <Object>UpdateInput!) and selects return fields on the updated record. Returns rendered GraphQL, declared variables, generated TypeScript types, and validation warnings.",
+			inputSchema,
+		},
+		async (args) => {
+			const output = await buildUpdate(args, opts.primeDeps);
+			return {
+				content: [{ type: "text", text: JSON.stringify(output) }],
+			};
+		},
+	);
+}

package/src/mcp/tools/shared/zod-schemas.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { z } from "zod";
+import { GRAPHQL_NAME_RE } from "../../../lib/graphql-name.js";
+
+/**
+ * Zod string validator that enforces the GraphQL Name production. Returned
+ * schema is `.describe()`-tagged with the supplied description so it appears
+ * in the MCP tool's advertised JSON Schema.
+ */
+export const graphqlName = (description: string): z.ZodString =>
+	z.string().regex(GRAPHQL_NAME_RE, "must be a valid GraphQL Name").describe(description);
+
+/**
+ * Org alias / username charset + length, matching `auth.ts`'s
+ * `assertValidOrgAlias`. Defense-in-depth at the MCP boundary so the
+ * advertised JSON Schema teaches the LLM the constraint upfront, while
+ * `assertValidOrgAlias` still gates the shell-out path.
+ */
+const ORG_ALIAS_RE = /^[A-Za-z0-9_][A-Za-z0-9_.+@-]{0,252}$/;
+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`).
+ */
+export const orderByObject = z.record(z.unknown());
+
+/**
+ * Build a `childRelationships[]` element schema. The `orderBy` schema is a
+ * parameter because tools differ on whether they advertise the array shape
+ * (`sf_gql_list`: union; `sf_gql_detail`: singleton with array-collapse
+ * preprocess). Everything else — `relationshipName`, `fields`, `first`,
+ * `filter` — is identical across callers.
+ *
+ * `relationshipName` flows into a rendered field-path position in the
+ * resulting query, so it carries the same GraphQL Name constraint as
+ * top-level `object` — same failure mode if it's invalid.
+ */
+export const childRelationshipSchema = (orderBy: z.ZodTypeAny) =>
+	z.object({
+		relationshipName: graphqlName(
+			'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(),
+	});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/**/__tests__/**"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	test: {
+		environment: "node",
+		include: ["src/**/*.spec.ts"],
+		exclude: ["dist/**", "node_modules/**"],
+		setupFiles: ["./src/__tests__/setup.ts"],
+		coverage: {
+			provider: "v8",
+			exclude: ["dist/**", "node_modules/**", "**/*.config.ts", "src/cli.ts", "src/__tests__/**"],
+		},
+	},
+});