@salesforce/graphiti 10.10.2

package/src/mcp/__tests__/server.spec.ts

@@ -0,0 +1,155 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { describe, expect, it } from "vitest";
+import { createServer } from "../server.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Resolves to packages/graphiti/src/mcp/stdio.ts — spawned via tsx so the
+// FR-1.7 test exercises the live source with no build step or dist staleness.
+const STDIO_SRC = resolve(__dirname, "..", "stdio.ts");
+
+async function connect(): Promise<{ client: Client; server: McpServer }> {
+	const server = createServer();
+	const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+	const client = new Client({ name: "graphiti-mcp-test-client", version: "0.0.0" });
+	await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+	return { client, server };
+}
+
+describe("mcp/server", () => {
+	it("initialize round-trips with the expected server identity", async () => {
+		const { client, server } = await connect();
+		try {
+			const info = client.getServerVersion();
+			expect(info?.name).toBe("graphiti-mcp");
+			expect(info?.version).toBeTruthy();
+
+			const capabilities = client.getServerCapabilities();
+			expect(capabilities?.tools).toBeDefined();
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/list returns the registered tools", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.listTools();
+			const names = result.tools.map((t) => t.name).sort();
+			expect(names).toEqual([
+				"echo",
+				"sf_gql_aggregate",
+				"sf_gql_create",
+				"sf_gql_delete",
+				"sf_gql_detail",
+				"sf_gql_discover",
+				"sf_gql_list",
+				"sf_gql_raw",
+				"sf_gql_update",
+			]);
+			const echo = result.tools.find((t) => t.name === "echo");
+			const inputSchema = echo?.inputSchema as
+				| { type?: string; properties?: { message?: unknown } }
+				| undefined;
+			expect(inputSchema?.type).toBe("object");
+			expect(inputSchema?.properties?.message).toBeDefined();
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call echo returns the message verbatim", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "echo",
+				arguments: { message: "hello graphiti-mcp" },
+			});
+			const content = result.content as { type: string; text?: string }[];
+			expect(content[0]?.type).toBe("text");
+			expect(content[0]?.text).toBe("hello graphiti-mcp");
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call unknown tool returns FR-1.6 error envelope", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({ name: "does-not-exist" });
+			expect(result.isError).toBe(true);
+			const content = result.content as { type: string; text?: string }[];
+			expect(content[0]?.type).toBe("text");
+			expect(content[0]?.text ?? "").toMatch(/does-not-exist/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call echo with missing required arg returns zod validation error", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({ name: "echo", arguments: {} });
+			expect(result.isError).toBe(true);
+			const content = result.content as { type: string; text?: string }[];
+			expect(content[0]?.type).toBe("text");
+			const text = content[0]?.text ?? "";
+			expect(text).toMatch(/Input validation error/);
+			expect(text).toMatch(/message/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("FR-1.7: stdio bin exits cleanly on stdin close after handshake", async () => {
+		// End-to-end coverage for FR-1.7: spawn the real bin, complete a
+		// handshake, close stdin, and assert the child exits. This pins that
+		// `main()` actually wires `transport.onclose` to a process-exit path —
+		// regressions like dropping the `await closed` or returning early from
+		// main fail this test. (It does *not* prove the synchronous-close race
+		// fix in isolation; over a real subprocess stdin doesn't close fast
+		// enough to fire onclose inside connect(). That race is guarded by
+		// code review of stdio.ts ordering.)
+		const transport = new StdioClientTransport({
+			command: "npx",
+			args: ["tsx", STDIO_SRC],
+			stderr: "pipe",
+		});
+		const client = new Client({ name: "stdio-bin-test", version: "0.0.0" }, { capabilities: {} });
+
+		// StdioClientTransport fires onclose when the child process exits.
+		const exitPromise = new Promise<void>((resolve) => {
+			transport.onclose = () => resolve();
+		});
+
+		await client.connect(transport);
+		// Confirm the handshake actually completed before we try to drain.
+		expect(client.getServerVersion()?.name).toBe("graphiti-mcp");
+
+		// Closing the client closes its writer, which closes the child's stdin,
+		// which fires StdioServerTransport.onclose on the server side and
+		// resolves runStdio's `closed` promise — so the child exits.
+		await client.close();
+		const result = await Promise.race([
+			exitPromise.then(() => "exited" as const),
+			new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), 5000)),
+		]);
+
+		expect(result).toBe("exited");
+	}, 60_000);
+});

package/src/mcp/server.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerEchoTool } from "./tools/echo.js";
+import { registerSfGqlAggregateTool } from "./tools/sf-gql-aggregate.js";
+import { registerSfGqlCreateTool } from "./tools/sf-gql-create.js";
+import { registerSfGqlDeleteTool } from "./tools/sf-gql-delete.js";
+import { registerSfGqlDetailTool } from "./tools/sf-gql-detail.js";
+import { registerSfGqlDiscoverTool } from "./tools/sf-gql-discover.js";
+import { registerSfGqlListTool } from "./tools/sf-gql-list.js";
+import { registerSfGqlRawTool } from "./tools/sf-gql-raw.js";
+import { registerSfGqlUpdateTool } from "./tools/sf-gql-update.js";
+
+const packageJson = JSON.parse(
+	readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+) as { version: string };
+
+export function createServer(): McpServer {
+	const server = new McpServer({
+		name: "graphiti-mcp",
+		version: packageJson.version,
+	});
+	registerEchoTool(server);
+	registerSfGqlAggregateTool(server);
+	registerSfGqlCreateTool(server);
+	registerSfGqlDeleteTool(server);
+	registerSfGqlDetailTool(server);
+	registerSfGqlDiscoverTool(server);
+	registerSfGqlListTool(server);
+	registerSfGqlRawTool(server);
+	registerSfGqlUpdateTool(server);
+	return server;
+}

package/src/mcp/stdio.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+
+async function main(): Promise<void> {
+	const server = createServer();
+	const transport = new StdioServerTransport();
+	// FR-1.7: register onclose before connect — a synchronous close during
+	// connect() would otherwise be missed and main would hang indefinitely.
+	const closed = new Promise<void>((resolve) => {
+		transport.onclose = () => resolve();
+	});
+	await server.connect(transport);
+	await closed;
+}
+
+main().catch((err) => {
+	// CRITICAL: never write to stdout — that channel is the JSON-RPC frame stream.
+	process.stderr.write(
+		`graphiti-mcp fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`,
+	);
+	process.exit(1);
+});

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

@@ -0,0 +1,173 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { buildSchema, introspectionFromSchema } from "graphql";
+import { describe, expect, it } from "vitest";
+import { atomicWriteJson } from "../../../lib/fs-utils.js";
+import {
+	schemaCacheKeyForInstanceUrl,
+	schemaDir,
+	type SchemaMetadata,
+} from "../../../lib/introspect.js";
+import { type PrimeDeps } from "../../../lib/prime-schema.js";
+import { primeSchemaCache } from "../../../lib/walker.js";
+import { registerSfGqlAggregateTool } from "../sf-gql-aggregate.js";
+
+const ORG = "test-tool-aggregate";
+const ORG_URL = "https://test-tool-aggregate.my.salesforce.com";
+const SCHEMA = buildSchema(`
+	type Query { uiapi: UIAPI! }
+	type UIAPI { aggregate: RecordQueryAggregate! }
+	type RecordQueryAggregate {
+		Account(first: Int, after: String, where: Account_Filter, groupBy: Account_GroupBy): AccountAggregateConnection
+	}
+	input Account_Filter { Industry: PicklistOperators }
+	input Account_GroupBy { Industry: GroupByClause }
+	input PicklistOperators { eq: String }
+	input GroupByClause { group: Boolean }
+
+	type AccountAggregateConnection {
+		edges: [AccountAggregateEdge!]!
+		pageInfo: PageInfo!
+	}
+	type AccountAggregateEdge { node: AccountResult!, cursor: String! }
+	type AccountResult { aggregate: AccountAggregate }
+	type AccountAggregate {
+		Id: IDAggregate
+		Industry: PicklistAggregate
+	}
+	type IDAggregate { value: ID, count: LongValue, countDistinct: LongValue }
+	type PicklistAggregate { value: String, count: LongValue, countDistinct: LongValue }
+	type LongValue { value: Float }
+	type PageInfo { hasNextPage: Boolean!, endCursor: String }
+`);
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+
+const primeDeps: PrimeDeps = {
+	getOrgAuth: async () => ({
+		alias: ORG,
+		username: "u",
+		instanceUrl: ORG_URL,
+		accessToken: "t",
+		orgId: "00D",
+	}),
+	downloadSchema: async (auth) => {
+		const cacheKey = schemaCacheKeyForInstanceUrl(auth.instanceUrl);
+		const filePath = path.join(schemaDir(), `${cacheKey}.json`);
+		atomicWriteJson(filePath, { data: introspectionFromSchema(SCHEMA) });
+		const meta: SchemaMetadata = {
+			cacheKey,
+			instanceUrl: auth.instanceUrl,
+			typeCount: 0,
+			downloadedAt: new Date().toISOString(),
+			filePath,
+		};
+		return meta;
+	},
+};
+
+async function connect(): Promise<{ client: Client; server: McpServer }> {
+	const server = new McpServer({ name: "graphiti-mcp", version: "test" });
+	registerSfGqlAggregateTool(server, { primeDeps });
+	const [c, s] = InMemoryTransport.createLinkedPair();
+	const client = new Client({ name: "test", version: "0.0.0" });
+	await Promise.all([server.connect(s), client.connect(c)]);
+	return { client, server };
+}
+
+describe("mcp/tools/sf-gql-aggregate", () => {
+	it("tools/list advertises sf_gql_aggregate with org/object/groupBy/aggregations properties", async () => {
+		const { client, server } = await connect();
+		try {
+			const list = await client.listTools();
+			const tool = list.tools.find((t) => t.name === "sf_gql_aggregate");
+			expect(tool).toBeDefined();
+			const props =
+				(tool!.inputSchema as { properties?: Record<string, unknown> }).properties ?? {};
+			expect(props.org).toBeDefined();
+			expect(props.object).toBeDefined();
+			expect(props.groupBy).toBeDefined();
+			expect(props.aggregations).toBeDefined();
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_aggregate returns ToolOutput JSON envelope", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_aggregate",
+				arguments: {
+					org: ORG,
+					object: "Account",
+					groupBy: ["Industry"],
+					aggregations: [{ function: "count" }],
+				},
+			});
+			const content = result.content as { type: string; text?: string }[];
+			expect(content[0]?.type).toBe("text");
+			const parsed = JSON.parse(content[0]?.text ?? "{}") as {
+				query: string;
+				variables: unknown[];
+				types: string;
+				warnings: string[];
+			};
+			expect(parsed.query).toMatch(/\bAccountAggregate\b/);
+			expect(parsed.query).toMatch(/countId\s*:\s*Id\s*\{\s*count\s*\{\s*value/s);
+			expect(parsed.query).toMatch(/Industry\s*:\s*\{\s*group\s*:\s*true\s*\}/s);
+			expect(Array.isArray(parsed.variables)).toBe(true);
+			expect(typeof parsed.types).toBe("string");
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_aggregate with no groupBy and no aggregations defaults to count(Id)", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_aggregate",
+				arguments: { org: ORG, object: "Account" },
+			});
+			expect(result.isError).toBeFalsy();
+			const content = result.content as { type: string; text?: string }[];
+			const parsed = JSON.parse(content[0]?.text ?? "{}");
+			expect(parsed.query).toMatch(/countId\s*:\s*Id\s*\{\s*count\s*\{\s*value/s);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_aggregate with sum aggregation missing field returns validation error", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_aggregate",
+				arguments: {
+					org: ORG,
+					object: "Account",
+					groupBy: [],
+					aggregations: [{ function: "sum" }],
+				},
+			});
+			expect(result.isError).toBe(true);
+			const content = result.content as { type: string; text?: string }[];
+			expect(content[0]?.text ?? "").toMatch(/field/i);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+});

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

@@ -0,0 +1,235 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { buildSchema, introspectionFromSchema } from "graphql";
+import { describe, expect, it } from "vitest";
+import { atomicWriteJson } from "../../../lib/fs-utils.js";
+import {
+	schemaCacheKeyForInstanceUrl,
+	schemaDir,
+	type SchemaMetadata,
+} from "../../../lib/introspect.js";
+import { type PrimeDeps } from "../../../lib/prime-schema.js";
+import { primeSchemaCache } from "../../../lib/walker.js";
+import { registerSfGqlCreateTool } from "../sf-gql-create.js";
+
+const ORG = "test-tool-create";
+const ORG_URL = "https://test-tool-create.my.salesforce.com";
+const SCHEMA = buildSchema(`
+	type Query { _placeholder: Boolean }
+	type Mutation { uiapi(input: UIAPIMutationsInput): UIAPIMutations! }
+	input UIAPIMutationsInput { allOrNone: Boolean }
+	type UIAPIMutations {
+		AccountCreate(input: AccountCreateInput!): AccountCreatePayload
+	}
+	input AccountCreateInput { Account: AccountCreateRepresentation! }
+	input AccountCreateRepresentation { Name: String, Industry: String }
+	type AccountCreatePayload { Record: Account }
+	type Account { Id: ID!, Name: StringValue, Industry: StringValue, Owner: User }
+	type StringValue { value: String }
+	type User { Id: ID!, Name: StringValue }
+`);
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+
+const primeDeps: PrimeDeps = {
+	getOrgAuth: async () => ({
+		alias: ORG,
+		username: "u",
+		instanceUrl: ORG_URL,
+		accessToken: "t",
+		orgId: "00D",
+	}),
+	downloadSchema: async (auth) => {
+		const cacheKey = schemaCacheKeyForInstanceUrl(auth.instanceUrl);
+		const filePath = path.join(schemaDir(), `${cacheKey}.json`);
+		atomicWriteJson(filePath, { data: introspectionFromSchema(SCHEMA) });
+		const meta: SchemaMetadata = {
+			cacheKey,
+			instanceUrl: auth.instanceUrl,
+			typeCount: 0,
+			downloadedAt: new Date().toISOString(),
+			filePath,
+		};
+		return meta;
+	},
+};
+
+async function connect(): Promise<{ client: Client; server: McpServer }> {
+	const server = new McpServer({ name: "graphiti-mcp", version: "test" });
+	registerSfGqlCreateTool(server, { primeDeps });
+	const [c, s] = InMemoryTransport.createLinkedPair();
+	const client = new Client({ name: "test", version: "0.0.0" });
+	await Promise.all([server.connect(s), client.connect(c)]);
+	return { client, server };
+}
+
+describe("mcp/tools/sf-gql-create", () => {
+	it("tools/list advertises sf_gql_create with org/object/returnFields properties", async () => {
+		const { client, server } = await connect();
+		try {
+			const list = await client.listTools();
+			const tool = list.tools.find((t) => t.name === "sf_gql_create");
+			expect(tool).toBeDefined();
+			const props =
+				(tool!.inputSchema as { properties?: Record<string, unknown> }).properties ?? {};
+			expect(props.org).toBeDefined();
+			expect(props.object).toBeDefined();
+			expect(props.returnFields).toBeDefined();
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_create returns ToolOutput with mutation keyword and value wrappers", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_create",
+				arguments: {
+					org: ORG,
+					object: "Account",
+					returnFields: ["Id", "Name", "Industry"],
+				},
+			});
+			const content = result.content as { type: string; text?: string }[];
+			expect(content[0]?.type).toBe("text");
+			const parsed = JSON.parse(content[0]?.text ?? "{}") as {
+				query: string;
+				variables: unknown[];
+				types: string;
+			};
+			expect(parsed.query).toMatch(/mutation CreateAccount/);
+			expect(parsed.query).toMatch(/\$input:\s*AccountCreateInput!/);
+			expect(parsed.query).toMatch(/AccountCreate\(input:\s*\$input\)/);
+			expect(parsed.query).toMatch(/Name\s*\{\s*value/s);
+			expect(parsed.query).toMatch(/\bId\b/);
+			expect(parsed.variables).toHaveLength(1);
+			expect(parsed.variables[0]).toEqual({
+				name: "input",
+				type: "AccountCreateInput!",
+				required: true,
+			});
+			expect(typeof parsed.types).toBe("string");
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_create with no returnFields defaults to Id only", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_create",
+				arguments: { org: ORG, object: "Account" },
+			});
+			const content = result.content as { type: string; text?: string }[];
+			const parsed = JSON.parse(content[0]?.text ?? "{}");
+			expect(parsed.query).toMatch(/\bId\b/);
+			expect(parsed.query).not.toMatch(/Name\s*\{/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_create with custom inputVariable declares that variable", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_create",
+				arguments: { org: ORG, object: "Account", inputVariable: "accountInput" },
+			});
+			const content = result.content as { type: string; text?: string }[];
+			const parsed = JSON.parse(content[0]?.text ?? "{}");
+			expect(parsed.query).toMatch(/\$accountInput:\s*AccountCreateInput!/);
+			expect(parsed.query).toMatch(/input:\s*\$accountInput/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_create with custom operationName uses it", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_create",
+				arguments: { org: ORG, object: "Account", operationName: "MakeAccount" },
+			});
+			const content = result.content as { type: string; text?: string }[];
+			const parsed = JSON.parse(content[0]?.text ?? "{}");
+			expect(parsed.query).toMatch(/mutation MakeAccount/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_create strips leading $ from inputVariable", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_create",
+				arguments: { org: ORG, object: "Account", inputVariable: "$myInput" },
+			});
+			expect(result.isError).toBeFalsy();
+			const content = result.content as { type: string; text?: string }[];
+			const parsed = JSON.parse(content[0]?.text ?? "{}");
+			expect(parsed.query).toMatch(/\$myInput:\s*AccountCreateInput!/);
+			expect(parsed.query).toMatch(/input:\s*\$myInput/);
+			expect(parsed.query).not.toMatch(/\$\$myInput/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_create with dotted returnField surfaces walker error as warning", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_create",
+				arguments: { org: ORG, object: "Account", returnFields: ["Id", "Owner.Name"] },
+			});
+			expect(result.isError).toBeFalsy();
+			const content = result.content as { type: string; text?: string }[];
+			const parsed = JSON.parse(content[0]?.text ?? "{}") as {
+				query: string;
+				warnings: string[];
+			};
+			expect(parsed.query).toMatch(/\bId\b/);
+			expect(parsed.warnings.some((w) => w.includes("not available in mutation results"))).toBe(
+				true,
+			);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call sf_gql_create with empty returnFields returns error", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_create",
+				arguments: { org: ORG, object: "Account", returnFields: [] },
+			});
+			expect(result.isError).toBe(true);
+			const content = result.content as { type: string; text?: string }[];
+			expect(content[0]?.text).toMatch(/returnFields must contain at least one field/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+});