@alfe.ai/salesforce-mcp 0.0.17 → 0.0.19

package/README.md

@@ -10,6 +10,17 @@ Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: buil
 npm install @alfe.ai/salesforce-mcp
 ```
 
+The server is normally launched by the Alfe Salesforce integration. Call
+`salesforce_list_orgs` first and pass its exact `orgId` to every data tool.
+Queries and reads are bounded, write payloads accept JSON-only Salesforce field
+maps, and permanent deletion requires `confirmRecordId` to exactly match the
+record being deleted.
+
+Credentials are fetched through Alfe Connect. Access tokens are sent only to a
+canonical HTTPS `*.salesforce.com` or `*.salesforce.mil` instance origin; REST
+requests use a 30-second deadline, disable redirects, and cap responses at
+5 MiB.
+
 ## Links
 
 - 🌐 Website: <https://alfe.ai>

package/dist/server.js

@@ -1,95 +1,306 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
 import { resolveConfig } from "@alfe.ai/config";
 import { AgentApiClient } from "@alfe.ai/agent-api-client";
+import { z } from "zod";
+//#region src/validation.ts
+const MAX_QUERY_CHARS = 1e5;
+const MAX_REQUEST_BODY_BYTES = 1024 * 1024;
+const MAX_JSON_DEPTH = 8;
+const MAX_JSON_NODES = 1e4;
+const MAX_JSON_ARRAY_ITEMS = 1e3;
+const MAX_JSON_STRING_CHARS = 1e5;
+const SOBJECT_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,79}$/u;
+const FIELD_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,79}$/u;
+const RECORD_ID_PATTERN = /^(?:[A-Za-z0-9]{15}|[A-Za-z0-9]{18})$/u;
+const UNSAFE_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+function validateOrgId(value) {
+	const normalized = boundedTrimmedString("orgId", value, 18);
+	if (!RECORD_ID_PATTERN.test(normalized)) throw new Error("orgId must contain 15 or 18 alphanumeric characters");
+	return normalized;
+}
+function validateSObject(value) {
+	const normalized = boundedTrimmedString("sObject", value, 80);
+	if (!SOBJECT_PATTERN.test(normalized)) throw new Error("sObject must be a Salesforce API object name");
+	return normalized;
+}
+function validateRecordId(value) {
+	const normalized = boundedTrimmedString("record id", value, 18);
+	if (!RECORD_ID_PATTERN.test(normalized)) throw new Error("record id must contain 15 or 18 alphanumeric characters");
+	return normalized;
+}
+function validateQuery(label, value) {
+	return boundedTrimmedString(label, value, MAX_QUERY_CHARS);
+}
+function validateFieldNames(fields) {
+	if (fields === void 0) return void 0;
+	if (!Array.isArray(fields) || fields.length < 1 || fields.length > 200) throw new Error(`fields must contain 1 to ${String(200)} API names`);
+	const normalized = fields.map((field) => validateFieldName(field));
+	if (new Set(normalized).size !== normalized.length) throw new Error("fields must not contain duplicates");
+	return normalized;
+}
+function validateRecordFields(fields) {
+	if (!isRecord$1(fields)) throw new Error("record fields must be an object");
+	const entries = Object.entries(fields);
+	if (entries.length < 1 || entries.length > 200) throw new Error(`record fields must contain 1 to ${String(200)} entries`);
+	const budget = { nodes: 0 };
+	const result = Object.create(null);
+	for (const [key, value] of entries) result[validateFieldName(key)] = cloneJson(value, 0, budget);
+	const encoded = JSON.stringify(result);
+	if (Buffer.byteLength(encoded, "utf-8") > 1048576) throw new Error(`record fields exceed the ${String(MAX_REQUEST_BODY_BYTES)} byte request limit`);
+	return result;
+}
+function validateFieldName(value) {
+	const normalized = boundedTrimmedString("field name", value, 80);
+	if (UNSAFE_KEYS.has(normalized) || !FIELD_PATTERN.test(normalized)) throw new Error("field name must be a safe Salesforce API field name");
+	return normalized;
+}
+function boundedTrimmedString(label, value, maxLength) {
+	if (typeof value !== "string") throw new Error(`${label} must be a string`);
+	const normalized = value.trim();
+	if (normalized.length < 1 || normalized.length > maxLength) throw new Error(`${label} must contain 1 to ${String(maxLength)} characters`);
+	return normalized;
+}
+function cloneJson(value, depth, budget) {
+	budget.nodes += 1;
+	if (budget.nodes > MAX_JSON_NODES) throw new Error("record fields contain too many JSON values");
+	if (depth > MAX_JSON_DEPTH) throw new Error("record fields exceed the JSON depth limit");
+	if (value === null || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error("record fields contain a non-finite number");
+		return value;
+	}
+	if (typeof value === "string") {
+		if (value.length > MAX_JSON_STRING_CHARS) throw new Error("record fields contain an oversized string");
+		return value;
+	}
+	if (Array.isArray(value)) {
+		if (value.length > MAX_JSON_ARRAY_ITEMS) throw new Error("record fields contain an oversized array");
+		return value.map((item) => cloneJson(item, depth + 1, budget));
+	}
+	if (!isRecord$1(value)) throw new Error("record fields must contain JSON-only values");
+	const output = Object.create(null);
+	for (const [key, nested] of Object.entries(value)) {
+		if (key.length < 1 || key.length > 256 || UNSAFE_KEYS.has(key)) throw new Error("record fields contain an unsafe nested key");
+		output[key] = cloneJson(nested, depth + 1, budget);
+	}
+	return output;
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/salesforce-client.ts
+/** Bounded direct Salesforce REST client with per-org refresh-and-retry. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+const MAX_ERROR_RESPONSE_BYTES = 64 * 1024;
+const MAX_ACCESS_TOKEN_LENGTH = 16384;
+const API_VERSION_PATTERN = /^(?:[1-9]\d{0,2})\.0$/u;
 var SalesforceClient = class {
 	accessToken;
-	instanceUrl;
+	instanceOrigin;
 	apiVersion;
 	onRefresh;
+	fetchImpl;
+	requestTimeoutMs;
 	constructor(config) {
-		this.accessToken = config.accessToken;
-		this.instanceUrl = config.instanceUrl.replace(/\/+$/, "");
-		this.apiVersion = config.apiVersion;
+		this.accessToken = validateAccessToken(config.accessToken);
+		this.instanceOrigin = validateSalesforceInstanceUrl(config.instanceUrl);
+		this.apiVersion = validateSalesforceApiVersion(config.apiVersion);
+		if (typeof config.onRefresh !== "function") throw new TypeError("Salesforce refresh callback is required");
 		this.onRefresh = config.onRefresh;
+		this.fetchImpl = config.fetchImpl ?? fetch;
+		this.requestTimeoutMs = validateTimeout(config.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
 	}
 	updateToken(accessToken) {
-		this.accessToken = accessToken;
+		this.accessToken = validateAccessToken(accessToken);
 	}
-	get baseUrl() {
-		return `${this.instanceUrl}/services/data/v${this.apiVersion}`;
+	get basePath() {
+		return `/services/data/v${this.apiVersion}`;
 	}
-	/** Run a SOQL query. Returns the standard `{ totalSize, done, records }`. */
 	async query(soql) {
-		return this.request("GET", `${this.baseUrl}/query?q=${encodeURIComponent(soql)}`);
+		const url = new URL(`${this.basePath}/query`, this.instanceOrigin);
+		url.searchParams.set("q", validateQuery("SOQL", soql));
+		return this.request("GET", url);
 	}
-	/** Run a SOSL search. Returns the standard `{ searchRecords }`. */
 	async search(sosl) {
-		return this.request("GET", `${this.baseUrl}/search?q=${encodeURIComponent(sosl)}`);
+		const url = new URL(`${this.basePath}/search`, this.instanceOrigin);
+		url.searchParams.set("q", validateQuery("SOSL", sosl));
+		return this.request("GET", url);
 	}
-	/** Fetch one record by id, optionally projecting a subset of fields. */
 	async getRecord(sobject, id, fields) {
-		let url = `${this.baseUrl}/sobjects/${encodeURIComponent(sobject)}/${encodeURIComponent(id)}`;
-		if (fields?.length) url += `?fields=${encodeURIComponent(fields.join(","))}`;
+		const objectName = encodeURIComponent(validateSObject(sobject));
+		const recordId = encodeURIComponent(validateRecordId(id));
+		const url = new URL(`${this.basePath}/sobjects/${objectName}/${recordId}`, this.instanceOrigin);
+		const selectedFields = validateFieldNames(fields);
+		if (selectedFields) url.searchParams.set("fields", selectedFields.join(","));
 		return this.request("GET", url);
 	}
 	async createRecord(sobject, fields) {
-		return this.request("POST", `${this.baseUrl}/sobjects/${encodeURIComponent(sobject)}`, fields);
+		const objectName = encodeURIComponent(validateSObject(sobject));
+		return this.request("POST", new URL(`${this.basePath}/sobjects/${objectName}`, this.instanceOrigin), validateRecordFields(fields));
 	}
-	/** Update is a PATCH that returns 204 No Content on success. */
 	async updateRecord(sobject, id, fields) {
-		return this.request("PATCH", `${this.baseUrl}/sobjects/${encodeURIComponent(sobject)}/${encodeURIComponent(id)}`, fields);
+		const objectName = encodeURIComponent(validateSObject(sobject));
+		const recordId = encodeURIComponent(validateRecordId(id));
+		await this.request("PATCH", new URL(`${this.basePath}/sobjects/${objectName}/${recordId}`, this.instanceOrigin), validateRecordFields(fields));
 	}
-	/** Delete returns 204 No Content on success. */
 	async deleteRecord(sobject, id) {
-		return this.request("DELETE", `${this.baseUrl}/sobjects/${encodeURIComponent(sobject)}/${encodeURIComponent(id)}`);
+		const objectName = encodeURIComponent(validateSObject(sobject));
+		const recordId = encodeURIComponent(validateRecordId(id));
+		await this.request("DELETE", new URL(`${this.basePath}/sobjects/${objectName}/${recordId}`, this.instanceOrigin));
 	}
-	/** Object metadata (fields, child relationships, picklist values, ...). */
 	async describe(sobject) {
-		return this.request("GET", `${this.baseUrl}/sobjects/${encodeURIComponent(sobject)}/describe`);
+		const objectName = encodeURIComponent(validateSObject(sobject));
+		return this.request("GET", new URL(`${this.basePath}/sobjects/${objectName}/describe`, this.instanceOrigin));
 	}
-	headers() {
+	headers(hasBody) {
 		return {
 			Authorization: `Bearer ${this.accessToken}`,
-			"Content-Type": "application/json",
-			Accept: "application/json"
+			Accept: "application/json",
+			...hasBody ? { "Content-Type": "application/json" } : {}
 		};
 	}
 	async request(method, url, body) {
+		const encodedBody = body === void 0 ? void 0 : encodeRequestBody(body);
 		const doFetch = async () => {
-			const init = {
-				method,
-				headers: this.headers()
-			};
-			if (body !== void 0) init.body = JSON.stringify(body);
-			return fetch(url, init);
+			try {
+				return await this.fetchImpl(url, {
+					method,
+					headers: this.headers(encodedBody !== void 0),
+					body: encodedBody,
+					redirect: "error",
+					signal: AbortSignal.timeout(this.requestTimeoutMs)
+				});
+			} catch (error) {
+				throw new Error(`Salesforce API ${method} ${url.pathname} request failed`, { cause: error });
+			}
 		};
 		let response = await doFetch();
 		if (response.status === 401) {
-			this.accessToken = (await this.onRefresh()).accessToken;
+			let refreshed;
+			try {
+				refreshed = await this.onRefresh();
+			} catch (error) {
+				throw new Error("Salesforce access-token refresh failed", { cause: error });
+			}
+			this.accessToken = validateAccessToken(refreshed.accessToken);
 			response = await doFetch();
 		}
 		if (!response.ok) {
-			const errorBody = await response.text();
-			throw new Error(`Salesforce API ${method} ${url} failed (${String(response.status)}): ${errorBody}`);
+			const errorBody = await readResponseText(response, MAX_ERROR_RESPONSE_BYTES);
+			throw new Error(formatApiError(method, url.pathname, response.status, errorBody));
+		}
+		if (response.status === 204) return {};
+		const text = await readResponseText(response, MAX_RESPONSE_BYTES);
+		if (text.length === 0) return {};
+		try {
+			return JSON.parse(text);
+		} catch (error) {
+			throw new Error(`Salesforce API ${method} ${url.pathname} returned invalid JSON`, { cause: error });
 		}
-		const text = await response.text();
-		if (!text) return {};
-		return JSON.parse(text);
 	}
 };
+function validateSalesforceInstanceUrl(rawUrl) {
+	if (typeof rawUrl !== "string" || rawUrl.length < 1 || rawUrl.length > 2048) throw new TypeError("Salesforce instance URL is invalid");
+	let url;
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		throw new TypeError("Salesforce instance URL is invalid");
+	}
+	const hostname = url.hostname.toLowerCase();
+	const trustedHost = hostname.endsWith(".salesforce.com") || hostname.endsWith(".salesforce.mil");
+	if (url.protocol !== "https:" || !trustedHost || url.username || url.password || url.port || url.pathname !== "" && url.pathname !== "/" || url.search || url.hash) throw new TypeError("Salesforce instance URL must be a canonical HTTPS Salesforce origin");
+	return url.origin;
+}
+function validateSalesforceApiVersion(value) {
+	if (typeof value !== "string" || !API_VERSION_PATTERN.test(value)) throw new TypeError("Salesforce API version must use the numeric form 61.0");
+	return value;
+}
+function validateAccessToken(value) {
+	if (typeof value !== "string" || value.length < 1 || value.length > MAX_ACCESS_TOKEN_LENGTH || value !== value.trim() || /[\r\n]/u.test(value)) throw new TypeError("Salesforce access token is invalid");
+	return value;
+}
+function validateTimeout(value) {
+	if (!Number.isInteger(value) || value < 1e3 || value > 12e4) throw new RangeError("Salesforce request timeout must be between 1000 and 120000 milliseconds");
+	return value;
+}
+function encodeRequestBody(body) {
+	let encoded;
+	try {
+		encoded = JSON.stringify(body);
+	} catch (error) {
+		throw new Error("Salesforce request body is not valid JSON", { cause: error });
+	}
+	if (Buffer.byteLength(encoded, "utf-8") > 1048576) throw new Error(`Salesforce request body exceeds ${String(MAX_REQUEST_BODY_BYTES)} bytes`);
+	return encoded;
+}
+async function readResponseText(response, maxBytes) {
+	const declaredLength = response.headers.get("content-length");
+	if (declaredLength !== null) {
+		const length = Number(declaredLength);
+		if (!Number.isSafeInteger(length) || length < 0 || length > maxBytes) throw new Error(`Salesforce response exceeds ${String(maxBytes)} bytes`);
+	}
+	if (!response.body) return "";
+	const reader = response.body.getReader();
+	const chunks = [];
+	let total = 0;
+	try {
+		for (;;) {
+			const chunk = await reader.read();
+			if (chunk.done) break;
+			const value = chunk.value;
+			if (value === void 0) throw new Error("Salesforce response stream returned an invalid chunk");
+			total += value.byteLength;
+			if (total > maxBytes) {
+				await reader.cancel("response exceeds limit");
+				throw new Error(`Salesforce response exceeds ${String(maxBytes)} bytes`);
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total).toString("utf-8");
+}
+function formatApiError(method, pathname, status, body) {
+	let detail = "";
+	try {
+		const parsed = JSON.parse(body);
+		const first = Array.isArray(parsed) ? parsed[0] : parsed;
+		if (isRecord(first)) detail = [typeof first.errorCode === "string" ? first.errorCode.slice(0, 128) : "", typeof first.message === "string" ? first.message.slice(0, 1024) : ""].filter(Boolean).join(": ");
+	} catch {}
+	return `Salesforce API ${method} ${pathname} failed (${String(status)})${detail ? `: ${detail}` : ""}`;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 //#endregion
 //#region src/tools/shared.ts
-/**
-* Shared `orgId` selector field. Every credential-touching tool requires it
-* (Pattern A per-call dispatch) — one Salesforce OAuth grant maps to one org,
-* so the org id is the stable account selector. `McpServer.registerTool`
-* expects a raw Zod shape (`{ field: z.string() }`), NOT a JSON-Schema object.
-*/
-const orgIdField = z.string().describe("Salesforce org id — use the value from salesforce_list_orgs to pick which connected org this call should target.");
+const orgIdField = z.coerce.string().trim().regex(/^(?:[A-Za-z0-9]{15}|[A-Za-z0-9]{18})$/u, "Expected a 15- or 18-character Salesforce org id").describe("Salesforce org id — use the value from salesforce_list_orgs to pick which connected org this call should target.");
+const sobjectField = z.coerce.string().trim().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/u, "Expected a Salesforce sObject API name");
+const recordIdField = z.coerce.string().trim().regex(/^(?:[A-Za-z0-9]{15}|[A-Za-z0-9]{18})$/u, "Expected a 15- or 18-character Salesforce record id");
+const queryField = (kind) => z.coerce.string().trim().min(1).max(MAX_QUERY_CHARS).describe(`The ${kind} query string.`);
+const fieldName = z.coerce.string().trim().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_]*$/u, "Expected a Salesforce field API name");
+const fieldList = z.array(fieldName).min(1).max(200).refine((fields) => new Set(fields).size === fields.length, "Field API names must be unique").optional();
+const recordFields = z.record(fieldName, z.unknown()).superRefine((value, context) => {
+	try {
+		validateRecordFields(value);
+	} catch (error) {
+		context.addIssue({
+			code: "custom",
+			message: error instanceof Error ? error.message : "Invalid Salesforce record fields"
+		});
+	}
+});
 //#endregion
 //#region src/tools/data.ts
 /**
@@ -105,50 +316,70 @@ function registerDataTools(server, resolveClient) {
 	}] });
 	register("salesforce_query", {
 		description: "Run a SOQL query against a connected Salesforce org. Works for any standard or custom object, e.g. \"SELECT Id, Name FROM Account WHERE Industry = 'Technology' LIMIT 50\".",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			orgId: orgIdField,
-			soql: z.string().describe("The SOQL query string.")
+			soql: queryField("SOQL")
 		}
 	}, async (args) => {
 		return ok(await resolveClient(args.orgId).query(args.soql));
 	});
 	register("salesforce_search", {
 		description: "Run a SOSL search across a connected Salesforce org, e.g. \"FIND {Acme} IN ALL FIELDS RETURNING Account(Id, Name), Contact(Id, Name)\".",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			orgId: orgIdField,
-			sosl: z.string().describe("The SOSL search string.")
+			sosl: queryField("SOSL")
 		}
 	}, async (args) => {
 		return ok(await resolveClient(args.orgId).search(args.sosl));
 	});
 	register("salesforce_get_record", {
 		description: "Fetch a single record by id from a connected Salesforce org.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			orgId: orgIdField,
-			sobject: z.string().describe("The sObject API name, e.g. Account, Contact, Opportunity, or MyObject__c."),
-			id: z.string().describe("The 15- or 18-character record id."),
-			fields: z.array(z.string()).optional().describe("Optional subset of field API names to return. Omit for all accessible fields.")
+			sobject: sobjectField.describe("The sObject API name, e.g. Account, Contact, Opportunity, or MyObject__c."),
+			id: recordIdField.describe("The 15- or 18-character record id."),
+			fields: fieldList.describe("Optional subset of field API names to return. Omit for all accessible fields.")
 		}
 	}, async (args) => {
 		return ok(await resolveClient(args.orgId).getRecord(args.sobject, args.id, args.fields));
 	});
 	register("salesforce_create_record", {
 		description: "Create a record of any sObject type in a connected Salesforce org.",
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: false
+		},
 		inputSchema: {
 			orgId: orgIdField,
-			sobject: z.string().describe("The sObject API name, e.g. Account, Contact, Lead, Case, or MyObject__c."),
-			fields: z.record(z.string(), z.unknown()).describe("Field API name → value map, e.g. { \"Name\": \"Acme Inc\", \"Industry\": \"Technology\" }.")
+			sobject: sobjectField.describe("The sObject API name, e.g. Account, Contact, Lead, Case, or MyObject__c."),
+			fields: recordFields.describe("Field API name → value map, e.g. { \"Name\": \"Acme Inc\", \"Industry\": \"Technology\" }.")
 		}
 	}, async (args) => {
 		return ok(await resolveClient(args.orgId).createRecord(args.sobject, args.fields));
 	});
 	register("salesforce_update_record", {
 		description: "Update fields on an existing record in a connected Salesforce org. Returns no body on success.",
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: true
+		},
 		inputSchema: {
 			orgId: orgIdField,
-			sobject: z.string().describe("The sObject API name."),
-			id: z.string().describe("The record id to update."),
-			fields: z.record(z.string(), z.unknown()).describe("Field API name → new value map. Only the supplied fields are changed.")
+			sobject: sobjectField.describe("The sObject API name."),
+			id: recordIdField.describe("The record id to update."),
+			fields: recordFields.describe("Field API name → new value map. Only the supplied fields are changed.")
 		}
 	}, async (args) => {
 		await resolveClient(args.orgId).updateRecord(args.sobject, args.id, args.fields);
@@ -158,13 +389,20 @@ function registerDataTools(server, resolveClient) {
 		});
 	});
 	register("salesforce_delete_record", {
-		description: "Delete a record by id from a connected Salesforce org. Returns no body on success.",
+		description: "Permanently delete a Salesforce record. Copy the exact id into confirmRecordId to confirm the destructive target.",
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			orgId: orgIdField,
-			sobject: z.string().describe("The sObject API name."),
-			id: z.string().describe("The record id to delete.")
+			sobject: sobjectField.describe("The sObject API name."),
+			id: recordIdField.describe("The record id to delete."),
+			confirmRecordId: recordIdField.describe("Exact record id confirming the permanent deletion target.")
 		}
 	}, async (args) => {
+		if (args.confirmRecordId !== args.id) throw new Error("confirmRecordId must exactly match the record id being deleted");
 		await resolveClient(args.orgId).deleteRecord(args.sobject, args.id);
 		return ok({
 			id: args.id,
@@ -173,9 +411,13 @@ function registerDataTools(server, resolveClient) {
 	});
 	register("salesforce_describe", {
 		description: "Describe an sObject's metadata (fields, types, picklist values, relationships) for a connected Salesforce org. Use this to discover field API names before querying or creating records.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		},
 		inputSchema: {
 			orgId: orgIdField,
-			sobject: z.string().describe("The sObject API name to describe, e.g. Account or MyObject__c.")
+			sobject: sobjectField.describe("The sObject API name to describe, e.g. Account or MyObject__c.")
 		}
 	}, async (args) => {
 		return ok(await resolveClient(args.orgId).describe(args.sobject));
@@ -199,6 +441,7 @@ function registerDataTools(server, resolveClient) {
 * Architecture:
 *   OpenClaw ←(stdio)→ this server ←(https)→ Salesforce REST API
 */
+const packageMetadata = createRequire(import.meta.url)("../package.json");
 /**
 * Salesforce REST API version. The SOQL / sObject CRUD / describe surface is
 * version-stable, so this defaults to a widely-available version and can be
@@ -218,11 +461,12 @@ function log(msg) {
 * the LLM to ask the user to reconnect rather than retrying blindly.
 */
 function resolveClient(orgId) {
-	const c = clients.get(orgId);
+	const normalizedOrgId = validateOrgId(orgId);
+	const c = clients.get(normalizedOrgId);
 	if (c) return c;
-	const known = orgSnapshot.find((o) => o.orgId === orgId);
-	if (known && !known.connected) throw new Error(`orgId ${orgId} is connected on this agent but the server could not initialise a client for it (reason: ${known.reason ?? "unknown"}). Ask the user to reconnect this Salesforce org from the dashboard.`);
-	throw new Error(`Unknown orgId: ${orgId}. Call salesforce_list_orgs to see the connected Salesforce orgs on this agent.`);
+	const known = orgSnapshot.find((o) => o.orgId === normalizedOrgId);
+	if (known && !known.connected) throw new Error(`orgId ${normalizedOrgId} is connected on this agent but the server could not initialise a client for it (reason: ${known.reason ?? "unknown"}). Ask the user to reconnect this Salesforce org from the dashboard.`);
+	throw new Error(`Unknown orgId: ${normalizedOrgId}. Call salesforce_list_orgs to see the connected Salesforce orgs on this agent.`);
 }
 /**
 * Refresh a single org's access token (Salesforce tokens are per-org).
@@ -250,15 +494,28 @@ async function main() {
 		apiKey: config.apiKey,
 		apiUrl: config.apiUrl
 	});
-	const apiVersion = process.env.SALESFORCE_API_VERSION ?? DEFAULT_API_VERSION;
+	const apiVersion = validateSalesforceApiVersion(process.env.SALESFORCE_API_VERSION ?? DEFAULT_API_VERSION);
 	const { accounts } = await apiClient.getSalesforceAccounts();
 	if (accounts.length === 0) log("No Salesforce orgs connected — server will start with salesforce_list_orgs + salesforce_refresh_token only");
+	const seenOrgIds = /* @__PURE__ */ new Set();
 	for (const acct of accounts) {
+		let orgId;
+		try {
+			orgId = validateOrgId(acct.orgId);
+		} catch {
+			log("Skipping Salesforce account with an invalid org id");
+			continue;
+		}
+		if (seenOrgIds.has(orgId)) {
+			log(`Duplicate orgId ${orgId} returned by getSalesforceAccounts() — keeping the first account`);
+			continue;
+		}
+		seenOrgIds.add(orgId);
 		if (!acct.accessToken || !acct.instanceUrl) {
-			log(`Skipping org ${acct.orgId} — missing access token or instance URL`);
+			log(`Skipping org ${orgId} — missing access token or instance URL`);
 			orgSnapshot.push({
-				orgId: acct.orgId,
-				instanceUrl: acct.instanceUrl,
+				orgId,
+				instanceUrl: "",
 				displayName: acct.displayName,
 				connectedAt: acct.connectedAt,
 				connected: false,
@@ -266,34 +523,53 @@ async function main() {
 			});
 			continue;
 		}
-		if (clients.has(acct.orgId)) {
-			log(`Duplicate orgId ${acct.orgId} returned by getSalesforceAccounts() — keeping the first cached client`);
+		let instanceUrl;
+		let client;
+		try {
+			instanceUrl = validateSalesforceInstanceUrl(acct.instanceUrl);
+			client = new SalesforceClient({
+				accessToken: acct.accessToken,
+				instanceUrl,
+				apiVersion,
+				onRefresh: async () => {
+					return { accessToken: await refreshOrg(apiClient, orgId) };
+				}
+			});
+		} catch {
+			log(`Skipping org ${orgId} — invalid Salesforce credential metadata`);
+			orgSnapshot.push({
+				orgId,
+				instanceUrl: "",
+				displayName: acct.displayName,
+				connectedAt: acct.connectedAt,
+				connected: false,
+				reason: "invalid_credential_metadata"
+			});
 			continue;
 		}
-		clients.set(acct.orgId, new SalesforceClient({
-			accessToken: acct.accessToken,
-			instanceUrl: acct.instanceUrl,
-			apiVersion,
-			onRefresh: async () => {
-				return { accessToken: await refreshOrg(apiClient, acct.orgId) };
-			}
-		}));
+		clients.set(orgId, client);
 		orgSnapshot.push({
-			orgId: acct.orgId,
-			instanceUrl: acct.instanceUrl,
+			orgId,
+			instanceUrl,
 			displayName: acct.displayName,
 			connectedAt: acct.connectedAt,
 			connected: true
 		});
-		log(`Cached client for org ${acct.orgId} (${acct.displayName ?? "no display name"})`);
+		log(`Cached client for org ${orgId}`);
 	}
 	const server = new McpServer({
 		name: "salesforce-mcp-server",
-		version: "1.0.0"
+		version: packageMetadata.version
 	});
 	registerDataTools(server, resolveClient);
 	const registerTool = server.registerTool.bind(server);
-	registerTool("salesforce_list_orgs", { description: "List the Salesforce orgs the agent has connected. Returns one entry per OAuth connection — use the returned orgId values as the `orgId` selector arg on every other salesforce_* tool." }, () => {
+	registerTool("salesforce_list_orgs", {
+		description: "List the Salesforce orgs the agent has connected. Returns one entry per OAuth connection — use the returned orgId values as the `orgId` selector arg on every other salesforce_* tool.",
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		}
+	}, () => {
 		return { content: [{
 			type: "text",
 			text: JSON.stringify({ orgs: orgSnapshot }, null, 2)
@@ -301,7 +577,11 @@ async function main() {
 	});
 	registerTool("salesforce_refresh_token", {
 		description: "Force-refresh the Salesforce OAuth2 access token for a connected org. Pass an orgId to refresh that org, or omit it to refresh every connected org. Use this if API calls are failing with authentication errors.",
-		inputSchema: { orgId: z.string().optional().describe("Optional Salesforce org id — omit to refresh every connected org.") }
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: true
+		},
+		inputSchema: { orgId: orgIdField.optional().describe("Optional Salesforce org id — omit to refresh every connected org.") }
 	}, async (args) => {
 		try {
 			if (args.orgId) resolveClient(args.orgId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/salesforce-mcp",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "Salesforce MCP server — direct REST/SOQL integration with Alfe OAuth credentials and automatic per-org token refresh",
   "type": "module",
   "main": "./dist/server.js",
@@ -19,8 +19,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.5",
-    "@alfe.ai/config": "0.3.0",
-    "@alfe.ai/agent-api-client": "0.13.0"
+    "@alfe.ai/config": "0.4.1",
+    "@alfe.ai/agent-api-client": "0.15.0"
   },
   "license": "UNLICENSED",
   "homepage": "https://alfe.ai",
@@ -36,6 +36,7 @@
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "lint": "eslint ."
   }