@salesforce/graphiti 10.10.3 → 10.11.0

package/src/lib/prime-schema.ts

@@ -9,11 +9,14 @@ import path from "node:path";
 import { getOrgAuth as realGetOrgAuth, type OrgAuth } from "./auth.js";
 import {
 	downloadSchema as realDownloadSchema,
+	getSchemaMetadata,
 	normalizeInstanceUrl,
 	schemaCacheKeyForInstanceUrl,
 	schemaDir,
 	type SchemaMetadata,
 } from "./introspect.js";
+import { clearObjectInfoCache } from "./object-info.js";
+import { clearSchemaCacheByUrl } from "./walker.js";
 
 // FR-13.7 originally suggested a 10-30s introspection budget. Empirical
 // smoke testing against real Salesforce UIAPI schemas measures ~135s for
@@ -33,23 +36,29 @@ const MAX_WAIT_MS = 7 * 60_000;
  * since `mkdir` is atomic on POSIX), run `work`, then release the lock.
  *
  * If another process holds the lock, this polls every 100ms for the lock
- * to be released. On release, if `finalPath` now exists, the work function
- * is skipped (the other process already did it). If `finalPath` still does
- * not exist (the other process aborted without writing), this acquires the
- * lock and runs `work`.
+ * to be released. On release, if the work is already satisfied (per `skipIf`),
+ * the work function is skipped (the other process already did it). Otherwise
+ * this acquires the lock and runs `work`.
  *
- * Contract: `work` will NOT run when `finalPath` exists at any point during
+ * Contract: `work` will NOT run when `skipIf()` is true at any point during
  * the lock dance — including immediately after we acquire the lock (a holder
  * may have finished and released the lock between our last EEXIST poll and
  * our successful `mkdir`). In that case the lock is released and the
  * function returns `undefined`.
  *
+ * `skipIf` defaults to "`finalPath` exists" — the lazy-prime contract (any
+ * cached schema is good enough). A forced refresh passes a predicate that is
+ * true only once the file has been *replaced* since the refresh was requested,
+ * which coalesces concurrent refreshes onto a single introspection.
+ *
  * Stale locks (older than STALE_LOCK_MS) are reclaimed.
  */
 export async function withSchemaLock<T>(
 	finalPath: string,
 	work: () => Promise<T>,
+	opts: { skipIf?: () => boolean } = {},
 ): Promise<T | undefined> {
+	const skip = opts.skipIf ?? (() => fs.existsSync(finalPath));
 	const lockPath = `${finalPath}.lock`;
 	fs.mkdirSync(path.dirname(finalPath), { recursive: true });
 
@@ -62,8 +71,8 @@ export async function withSchemaLock<T>(
 			const err = e as NodeJS.ErrnoException;
 			if (err.code !== "EEXIST") throw e;
 
-			// If the cache exists now, another holder finished — short-circuit.
-			if (fs.existsSync(finalPath)) return undefined;
+			// If the work is already satisfied, another holder finished — short-circuit.
+			if (skip()) return undefined;
 
 			// Stale-lock reclaim. Known TOCTOU: between this `statSync` and
 			// the `rmSync` below, another process may have already reclaimed
@@ -94,10 +103,10 @@ export async function withSchemaLock<T>(
 		}
 	}
 
-	// We now hold the lock. Re-check for the cache: a holder that finished
-	// between our last EEXIST poll and our successful mkdir may have just
-	// primed it. Avoid running `work` redundantly.
-	if (fs.existsSync(finalPath)) {
+	// We now hold the lock. Re-check `skip`: a holder that finished between our
+	// last EEXIST poll and our successful mkdir may have just satisfied it.
+	// Avoid running `work` redundantly.
+	if (skip()) {
 		try {
 			fs.rmSync(lockPath, { recursive: true });
 		} catch {
@@ -122,10 +131,61 @@ export async function withSchemaLock<T>(
 
 export interface PrimeResult {
 	cached: boolean;
+	/** True only when this call performed a forced re-download (forceRefresh). */
+	refreshed: boolean;
 	filePath: string;
 	durationMs: number;
 	/** Resolved instance URL (already auth-resolved). */
 	instanceUrl: string;
+	/**
+	 * Non-`__` type count from the just-downloaded schema. Present only when this
+	 * call performed a download (`cached: false`); a cache hit or coalesced
+	 * refresh leaves it undefined to avoid re-parsing the (large) introspection
+	 * JSON just to count types.
+	 */
+	typeCount?: number;
+}
+
+/**
+ * Thrown when a forced refresh fails to download a new schema. The previously
+ * cached schema (if any) is left intact on disk and in memory — we only clear
+ * the caches *after* a successful download. `staleSince` is the surviving
+ * cache's download timestamp (ISO) so callers can render a staleness-aware
+ * message; it is undefined when no prior cache existed (a true hard failure) —
+ * or when a cache file is present but unparseable, since `getSchemaMetadata`
+ * returns null for a corrupt file, which correctly degrades to a hard failure
+ * (a corrupt cache is not usable). `instanceUrl` is always the resolved org URL
+ * (known before the download).
+ */
+export class SchemaRefreshError extends Error {
+	staleSince?: string;
+	instanceUrl: string;
+	constructor(
+		message: string,
+		opts: { instanceUrl: string; staleSince?: string; cause?: unknown },
+	) {
+		super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+		this.name = "SchemaRefreshError";
+		this.staleSince = opts.staleSince;
+		this.instanceUrl = opts.instanceUrl;
+	}
+}
+
+function formatAge(ms: number): string {
+	const min = Math.floor(ms / 60_000);
+	if (min < 1) return "just now";
+	if (min < 60) return `${min}m ago`;
+	const hr = Math.floor(min / 60);
+	if (hr < 24) return `${hr}h ago`;
+	return `${Math.floor(hr / 24)}d ago`;
+}
+
+function buildStaleMessage(orgAlias: string, surviving: SchemaMetadata | null): string {
+	if (!surviving) {
+		return `Schema refresh for "${orgAlias}" failed and no cached schema exists yet. Resolve connectivity/auth and run \`graphiti connect ${orgAlias}\` again.`;
+	}
+	const age = formatAge(Date.now() - new Date(surviving.downloadedAt).getTime());
+	return `Schema refresh for "${orgAlias}" failed; keeping the previously cached schema (downloaded ${age}). The cached schema is still usable — try refreshing again shortly.`;
 }
 
 /**
@@ -143,25 +203,43 @@ const REAL_DEPS: PrimeDeps = {
 };
 
 /**
- * Lazily prime the on-disk schema cache for `orgAlias`.
+ * Lazily prime — or, with `forceRefresh`, re-download — the on-disk schema
+ * cache for `orgAlias`.
  *
+ * Lazy prime (`forceRefresh` falsy):
  * - If `<HOME>/.graphiti/schemas/<hash>.json` already exists, returns
- *   `{cached: true}` immediately.
+ *   `{cached: true, refreshed: false}` immediately.
  * - Otherwise: resolves auth via `deps.getOrgAuth` (throws verbatim if the
  *   alias is not authenticated, per FR-13.5), acquires the schema lock via
  *   `withSchemaLock`, calls `deps.downloadSchema(auth)` (which writes the
- *   cache atomically via `downloadSchema`'s internal use of
- *   `atomicWriteJson`), releases the lock, and returns
- *   `{cached: false, durationMs}`. Per FR-13.6, partial caches never reach
- *   disk because writes are atomic.
+ *   cache atomically), releases the lock, and returns `{cached: false}`. Per
+ *   FR-13.6, partial caches never reach disk because writes are atomic.
+ *   `downloadSchema` bounds the request with a timeout and retries transient
+ *   failures (network / 5xx) once at the connection layer; deterministic
+ *   failures (4xx, GraphQL errors in a 200 body, missing `__schema`) and missing
+ *   auth surface immediately. Unlike a forced refresh, a lazy-prime failure is
+ *   re-thrown verbatim (there is no prior cache to keep, so no `SchemaRefreshError`).
+ *
+ * Forced refresh (`forceRefresh: true`) — W-22845606:
+ * - Re-downloads even though the file exists, then clears all three caches
+ *   coherently: the on-disk introspection JSON (overwritten atomically), this
+ *   process's in-memory parsed-schema cache, and the ObjectInfo cache (memory
+ *   + disk). Clearing happens only AFTER a successful download, so a failed
+ *   refresh leaves every cache intact.
+ * - Coalesces concurrent refreshes (CLI + MCP) into a single introspection via
+ *   a request-time mtime snapshot: a peer that replaced the file since this
+ *   refresh was requested satisfies us, and we skip the redundant download.
+ * - The download retries transient failures (network / 5xx) once at the
+ *   connection layer. On terminal failure throws {@link SchemaRefreshError}
+ *   carrying the surviving cache's age; the old caches are kept.
  *
- * Concurrent callers in the same or different processes serialize on the
- * lock dir; only one performs introspection. Subsequent waiters observe
- * the primed cache and short-circuit (FR-13.4).
+ * Concurrent callers in the same or different processes serialize on the lock
+ * dir; only one performs introspection.
  */
 export async function primeSchemaWithLock(
 	orgAlias: string,
 	deps: PrimeDeps = REAL_DEPS,
+	opts: { forceRefresh?: boolean } = {},
 ): Promise<PrimeResult> {
 	// We must call `deps.getOrgAuth` first because it is the only injected
 	// source of the org's `instanceUrl`, which the cache key is derived from.
@@ -173,23 +251,97 @@ export async function primeSchemaWithLock(
 	const cacheKey = schemaCacheKeyForInstanceUrl(instanceUrl);
 	const filePath = path.join(schemaDir(), `${cacheKey}.json`);
 
-	if (fs.existsSync(filePath)) {
-		return { cached: true, filePath, durationMs: 0, instanceUrl };
+	const forceRefresh = !!opts.forceRefresh;
+
+	// Snapshot the cached file's mtime before we (might) overwrite it.
+	// `atomicWriteJson` installs the new JSON via rename, so a successful
+	// download bumps mtime forward. The refresh skip-predicate compares
+	// against this snapshot (mtime-to-mtime, immune to wall-clock skew) so a
+	// peer that replaced the file since we were asked coalesces us out.
+	// Best-effort: on filesystems with coarse mtime resolution two refreshes in
+	// the same tick may each download (redundant, never incorrect — strict `>`
+	// can only cause an extra download, never an erroneous skip of a real refresh).
+	const mtimeAtRequest = fs.existsSync(filePath) ? fs.statSync(filePath).mtimeMs : -1;
+
+	if (fs.existsSync(filePath) && !forceRefresh) {
+		return { cached: true, refreshed: false, filePath, durationMs: 0, instanceUrl };
 	}
 
 	const start = Date.now();
 	let primed = false;
-	await withSchemaLock(filePath, async () => {
-		// withSchemaLock re-checks `finalPath` after acquire and short-
-		// circuits if it now exists, so when our work runs we know we
-		// must do the introspection.
-		await deps.downloadSchema(auth);
-		primed = true;
-	});
+	let typeCount: number | undefined;
+	await withSchemaLock(
+		filePath,
+		async () => {
+			let meta: SchemaMetadata;
+			try {
+				// `downloadSchema` bounds the request with a timeout and retries
+				// transient (network/5xx) failures once with backoff at the
+				// connection layer (jsforce); deterministic failures throw straight
+				// through.
+				meta = await deps.downloadSchema(auth);
+			} catch (cause) {
+				// Lazy prime (no existing cache): surface the raw error verbatim
+				// (FR-13.5/13.6) — there is no stale cache to keep.
+				if (!forceRefresh) throw cause;
+				// Forced refresh: atomic writes mean the old JSON is still on
+				// disk, so surface a staleness-aware error and leave every cache
+				// untouched.
+				const surviving = getSchemaMetadata(instanceUrl);
+				throw new SchemaRefreshError(buildStaleMessage(orgAlias, surviving), {
+					staleSince: surviving?.downloadedAt,
+					instanceUrl,
+					cause,
+				});
+			}
+			typeCount = meta.typeCount;
+			// On a forced refresh, drop this process's in-memory copies so the
+			// next read rebuilds from the freshly-downloaded JSON. A lazy prime
+			// has nothing stale to clear (this org wasn't cached before).
+			//
+			// `clearObjectInfoCache` takes the raw alias. Its on-disk path guard
+			// (object-info.ts ORG_ALIAS_PATH_RE) is intentionally stricter than the
+			// `org` charset `connect` accepts — it gates a filesystem path, so it
+			// must reject `.`/`@`/`+` to stay traversal-safe. For an email-shaped
+			// alias the disk clear no-ops, but that is safe: the ObjectInfo disk
+			// *write* uses the same strict guard, so no on-disk entry can exist for
+			// such an alias; the in-memory clear (no guard) always runs. Do NOT
+			// loosen the path guard to "align" the two regexes.
+			if (forceRefresh) {
+				clearSchemaCacheByUrl(instanceUrl);
+				clearObjectInfoCache(orgAlias);
+			}
+			primed = true;
+		},
+		forceRefresh
+			? { skipIf: () => fs.existsSync(filePath) && fs.statSync(filePath).mtimeMs > mtimeAtRequest }
+			: undefined,
+	);
 
 	if (!primed) {
-		// Another process primed while we were waiting.
-		return { cached: true, filePath, durationMs: Date.now() - start, instanceUrl };
+		// Either a lazy prime found the file already present, or a concurrent
+		// refresh produced the new schema while we waited (coalesced). In the
+		// coalesced-refresh case a long-lived process (the MCP server) may still
+		// hold stale in-memory copies of the OLD schema, so drop them now that
+		// disk is fresh — the next read rebuilds from the peer's download.
+		if (forceRefresh && fs.existsSync(filePath) && fs.statSync(filePath).mtimeMs > mtimeAtRequest) {
+			clearSchemaCacheByUrl(instanceUrl);
+			clearObjectInfoCache(orgAlias);
+		}
+		return {
+			cached: true,
+			refreshed: false,
+			filePath,
+			durationMs: Date.now() - start,
+			instanceUrl,
+		};
 	}
-	return { cached: false, filePath, durationMs: Date.now() - start, instanceUrl };
+	return {
+		cached: false,
+		refreshed: forceRefresh,
+		filePath,
+		durationMs: Date.now() - start,
+		instanceUrl,
+		typeCount,
+	};
 }

package/src/lib/walker.ts

@@ -28,6 +28,7 @@ import {
 	type GraphQLOutputType,
 	type GraphQLType,
 } from "graphql";
+import { atomicWriteText } from "./fs-utils.js";
 import { loadIntrospectionResult, getSchemaFilePath, normalizeInstanceUrl } from "./introspect.js";
 import { type OperationType } from "./session.js";
 
@@ -122,9 +123,13 @@ function buildSchemaWithSdlCache(introspectionFilePath: string): GraphQLSchema {
 	patchEmptyInputObjects(data);
 	const schema = buildClientSchema(data);
 
-	// Persist SDL for the next invocation.
+	// Persist SDL for the next invocation. Atomic temp+rename (not a bare
+	// writeFileSync) so a crash mid-write or a concurrent CLI+MCP writer can't
+	// leave a torn `.graphql` — readers see either the old or the fully-written
+	// file. (The read path also self-heals from the atomic JSON, but this avoids
+	// the wasted rebuild.)
 	try {
-		fs.writeFileSync(sdlPath, printSchema(schema), "utf-8");
+		atomicWriteText(sdlPath, printSchema(schema));
 	} catch {
 		// Non-critical — writable filesystem is not guaranteed.
 	}
@@ -170,6 +175,25 @@ export function clearSchemaCache(instanceUrl?: string): void {
 	}
 }
 
+/**
+ * Evict the parsed schema for an instance URL AND its derived on-disk SDL
+ * side-file (`<cacheKey>.graphql`). Extends {@link clearSchemaCache} (in-memory
+ * only) with the SDL removal the refresh path needs: after a forced refresh
+ * rewrites the introspection JSON, `buildSchemaWithSdlCache` would otherwise
+ * prefer a stale SDL whenever `sdlMtime >= introspMtime` — true on a
+ * same-mtime-tick edge — resurrecting the old schema on the next cold read and
+ * defeating the refresh's coherence guarantee. SDL removal is best-effort.
+ */
+export function clearSchemaCacheByUrl(instanceUrl: string): void {
+	clearSchemaCache(instanceUrl);
+	try {
+		const sdlPath = getSchemaFilePath(instanceUrl).replace(/\.json$/, ".graphql");
+		fs.rmSync(sdlPath, { force: true });
+	} catch {
+		// best-effort; a stale SDL only matters on the rare same-mtime-tick edge.
+	}
+}
+
 export function primeSchemaCache(alias: string, schema: GraphQLSchema): void {
 	schemaCache.set(alias, schema);
 }

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

@@ -50,6 +50,7 @@ describe("mcp/server", () => {
 			expect(names).toEqual([
 				"echo",
 				"sf_gql_aggregate",
+				"sf_gql_connect",
 				"sf_gql_create",
 				"sf_gql_delete",
 				"sf_gql_detail",

package/src/mcp/server.ts

@@ -8,6 +8,7 @@ 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 { registerSfGqlConnectTool } from "./tools/sf-gql-connect.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";
@@ -27,6 +28,7 @@ export function createServer(): McpServer {
 	});
 	registerEchoTool(server);
 	registerSfGqlAggregateTool(server);
+	registerSfGqlConnectTool(server);
 	registerSfGqlCreateTool(server);
 	registerSfGqlDeleteTool(server);
 	registerSfGqlDetailTool(server);

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

@@ -0,0 +1,202 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+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 } from "graphql";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { makeNoopPrimeDeps } from "../../../__tests__/helpers/prime-deps.js";
+import { type PrimeDeps } from "../../../lib/prime-schema.js";
+import { registerSfGqlConnectTool } from "../sf-gql-connect.js";
+
+const ORG = "test-tool-connect";
+const ORG_URL = "https://test-tool-connect.my.salesforce.com";
+const SCHEMA = buildSchema(`type Query { x: Int }`);
+
+// Succeeds on the first download (prime), then fails every subsequent one — lets
+// a single server prime a real cache and then fail a refresh over it.
+function flakyPrimeDeps(): PrimeDeps {
+	const noop = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+	let n = 0;
+	return {
+		getOrgAuth: noop.getOrgAuth,
+		downloadSchema: async (auth) => {
+			n++;
+			if (n === 1) return noop.downloadSchema(auth);
+			throw new Error("introspection failed");
+		},
+	};
+}
+
+function failingPrimeDeps(): PrimeDeps {
+	const noop = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+	return {
+		getOrgAuth: noop.getOrgAuth,
+		downloadSchema: async () => {
+			throw new Error("introspection failed");
+		},
+	};
+}
+
+interface ParsedConnect {
+	org: string;
+	instanceUrl: string;
+	refreshed: boolean;
+	cached: boolean;
+	durationMs: number;
+	warnings?: string[];
+}
+
+async function connect(
+	primeDeps: PrimeDeps = makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA),
+): Promise<{ client: Client; server: McpServer }> {
+	const server = new McpServer({ name: "graphiti-mcp", version: "test" });
+	registerSfGqlConnectTool(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 };
+}
+
+function parse(result: Awaited<ReturnType<Client["callTool"]>>): ParsedConnect {
+	const content = result.content as { type: string; text?: string }[];
+	return JSON.parse(content[0]?.text ?? "{}") as ParsedConnect;
+}
+
+describe("mcp/tools/sf-gql-connect", () => {
+	let tmpRoot: string;
+
+	beforeEach(() => {
+		tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "graphiti-tool-connect-"));
+		process.env.GRAPHITI_HOME = tmpRoot;
+	});
+
+	afterEach(() => {
+		delete process.env.GRAPHITI_HOME;
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+	});
+
+	it("tools/list advertises sf_gql_connect with org/forceRefresh properties", async () => {
+		const { client, server } = await connect();
+		try {
+			const list = await client.listTools();
+			const tool = list.tools.find((t) => t.name === "sf_gql_connect");
+			expect(tool).toBeDefined();
+			const props =
+				(tool!.inputSchema as { properties?: Record<string, unknown> }).properties ?? {};
+			expect(props.org).toBeDefined();
+			expect(props.forceRefresh).toBeDefined();
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("primes on first connect and reports cached on the second (forceRefresh defaults to false)", async () => {
+		const { client, server } = await connect();
+		try {
+			const first = parse(
+				await client.callTool({ name: "sf_gql_connect", arguments: { org: ORG } }),
+			);
+			expect(first.cached).toBe(false);
+			expect(first.refreshed).toBe(false);
+			expect(first.instanceUrl).toBe(ORG_URL);
+
+			const second = parse(
+				await client.callTool({ name: "sf_gql_connect", arguments: { org: ORG } }),
+			);
+			expect(second.cached).toBe(true);
+			expect(second.refreshed).toBe(false);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("forceRefresh:true re-downloads and reports refreshed:true", async () => {
+		const { client, server } = await connect();
+		try {
+			await client.callTool({ name: "sf_gql_connect", arguments: { org: ORG } }); // prime
+			const refreshed = parse(
+				await client.callTool({
+					name: "sf_gql_connect",
+					arguments: { org: ORG, forceRefresh: true },
+				}),
+			);
+			expect(refreshed.refreshed).toBe(true);
+			expect(refreshed.cached).toBe(false);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("refresh failure over a surviving cache returns a soft staleness warning (not isError)", async () => {
+		const { client, server } = await connect(flakyPrimeDeps());
+		try {
+			await client.callTool({ name: "sf_gql_connect", arguments: { org: ORG } }); // prime (ok)
+			const result = await client.callTool({
+				name: "sf_gql_connect",
+				arguments: { org: ORG, forceRefresh: true }, // download now fails
+			});
+			expect(result.isError).toBeFalsy();
+			const out = parse(result);
+			expect(out.refreshed).toBe(false);
+			expect(out.cached).toBe(true);
+			expect(out.warnings?.[0]).toMatch(/keeping the previously cached schema/i);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("refresh failure with no prior cache surfaces an isError envelope", async () => {
+		const { client, server } = await connect(failingPrimeDeps());
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_connect",
+				arguments: { org: ORG, forceRefresh: true },
+			});
+			expect(result.isError).toBe(true);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("tools/call with missing org returns a validation error", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({ name: "sf_gql_connect", arguments: {} });
+			expect(result.isError).toBe(true);
+			const content = result.content as { type: string; text?: string }[];
+			expect(content[0]?.text ?? "").toMatch(/org/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it("rejects an org alias containing shell metacharacters", async () => {
+		const { client, server } = await connect();
+		try {
+			const result = await client.callTool({
+				name: "sf_gql_connect",
+				arguments: { org: "evil; rm -rf /" },
+			});
+			expect(result.isError).toBe(true);
+			const content = result.content as { type: string; text?: string }[];
+			expect(content[0]?.text ?? "").toMatch(/org/);
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+});

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

@@ -0,0 +1,42 @@
+/**
+ * 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 { orgAlias } from "./shared/zod-schemas.js";
+import { buildConnect, type ConnectDeps } from "../../intent/build-connect.js";
+
+export type SfGqlConnectToolOptions = ConnectDeps;
+
+const inputSchema = {
+	org: orgAlias("Org alias or username resolved via local Salesforce CLI auth (~/.sf, ~/.sfdx)."),
+	forceRefresh: z
+		.boolean()
+		.optional()
+		.describe(
+			"Re-download the schema even if it is already cached, clearing the on-disk introspection JSON, the in-memory parsed schema, and the ObjectInfo cache. Use after deploying new metadata (fields, picklist values, objects) so subsequent tools see the changes. Defaults to false.",
+		),
+};
+
+export function registerSfGqlConnectTool(
+	server: McpServer,
+	opts: SfGqlConnectToolOptions = {},
+): void {
+	server.registerTool(
+		"sf_gql_connect",
+		{
+			description:
+				"Connect to a Salesforce org and prime its GraphQL schema cache. With forceRefresh, re-download the schema and coherently clear all caches so subsequent tools see freshly-deployed metadata. Concurrent refreshes coalesce into a single introspection. Returns { org, instanceUrl, refreshed, cached, durationMs, warnings? } — not the standard ToolOutput envelope. If a refresh fails but a usable cached schema survives, returns refreshed:false with a staleness warning instead of erroring.",
+			inputSchema,
+		},
+		async (args) => {
+			const output = await buildConnect(args, opts);
+			return {
+				content: [{ type: "text", text: JSON.stringify(output) }],
+			};
+		},
+	);
+}