@alfe.ai/salesforce-mcp 0.0.2

package/dist/server.d.ts

@@ -0,0 +1,29 @@
+//#region src/server.d.ts
+/**
+ * Salesforce MCP Server (Pattern A multi-org)
+ *
+ * Custom MCP server implementing the Salesforce REST/SOQL API directly
+ * (like the MYOB server; unlike the Xero proxy that wraps a child MCP).
+ * Every tool that touches credentials requires the LLM to pass `orgId`
+ * explicitly — the server keeps one `SalesforceClient` per connected org
+ * and dispatches per-call.
+ *
+ * Salesforce access tokens are per-org and NOT interchangeable, so token
+ * refresh is per-org (via the connect per-account refresh endpoint), unlike
+ * MYOB's interchangeable fan-out.
+ *
+ * Architecture:
+ *   OpenClaw ←(stdio)→ this server ←(https)→ Salesforce REST API
+ */
+interface SalesforceOrgSummary {
+  orgId: string;
+  instanceUrl: string;
+  displayName: string | null;
+  connectedAt: string;
+  /** Whether the server has a live client for this org (false = init skipped). */
+  connected: boolean;
+  /** Why init was skipped, when `connected` is false. */
+  reason?: string;
+}
+//#endregion
+export { SalesforceOrgSummary };

package/dist/server.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+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";
+//#region src/salesforce-client.ts
+var SalesforceClient = class {
+	accessToken;
+	instanceUrl;
+	apiVersion;
+	onRefresh;
+	constructor(config) {
+		this.accessToken = config.accessToken;
+		this.instanceUrl = config.instanceUrl.replace(/\/+$/, "");
+		this.apiVersion = config.apiVersion;
+		this.onRefresh = config.onRefresh;
+	}
+	updateToken(accessToken) {
+		this.accessToken = accessToken;
+	}
+	get baseUrl() {
+		return `${this.instanceUrl}/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)}`);
+	}
+	/** Run a SOSL search. Returns the standard `{ searchRecords }`. */
+	async search(sosl) {
+		return this.request("GET", `${this.baseUrl}/search?q=${encodeURIComponent(sosl)}`);
+	}
+	/** 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(","))}`;
+		return this.request("GET", url);
+	}
+	async createRecord(sobject, fields) {
+		return this.request("POST", `${this.baseUrl}/sobjects/${encodeURIComponent(sobject)}`, 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);
+	}
+	/** Delete returns 204 No Content on success. */
+	async deleteRecord(sobject, id) {
+		return this.request("DELETE", `${this.baseUrl}/sobjects/${encodeURIComponent(sobject)}/${encodeURIComponent(id)}`);
+	}
+	/** Object metadata (fields, child relationships, picklist values, ...). */
+	async describe(sobject) {
+		return this.request("GET", `${this.baseUrl}/sobjects/${encodeURIComponent(sobject)}/describe`);
+	}
+	headers() {
+		return {
+			Authorization: `Bearer ${this.accessToken}`,
+			"Content-Type": "application/json",
+			Accept: "application/json"
+		};
+	}
+	async request(method, url, body) {
+		const doFetch = async () => {
+			const init = {
+				method,
+				headers: this.headers()
+			};
+			if (body !== void 0) init.body = JSON.stringify(body);
+			return fetch(url, init);
+		};
+		let response = await doFetch();
+		if (response.status === 401) {
+			this.accessToken = (await this.onRefresh()).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 text = await response.text();
+		if (!text) return {};
+		return JSON.parse(text);
+	}
+};
+//#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.");
+//#endregion
+//#region src/tools/data.ts
+/**
+* Generic REST/SOQL core. These tools cover every standard AND custom object
+* (Account, Contact, Opportunity, Lead, Case, `MyObject__c`, ...) without a
+* per-object tool explosion — the LLM names the sObject as an argument.
+*/
+function registerDataTools(server, resolveClient) {
+	const register = server.registerTool.bind(server);
+	const ok = (result) => ({ content: [{
+		type: "text",
+		text: JSON.stringify(result, null, 2)
+	}] });
+	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\".",
+		inputSchema: {
+			orgId: orgIdField,
+			soql: z.string().describe("The SOQL query string.")
+		}
+	}, 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)\".",
+		inputSchema: {
+			orgId: orgIdField,
+			sosl: z.string().describe("The SOSL search string.")
+		}
+	}, 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.",
+		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.")
+		}
+	}, 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.",
+		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\" }.")
+		}
+	}, 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.",
+		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.")
+		}
+	}, async (args) => {
+		await resolveClient(args.orgId).updateRecord(args.sobject, args.id, args.fields);
+		return ok({
+			id: args.id,
+			success: true
+		});
+	});
+	register("salesforce_delete_record", {
+		description: "Delete a record by id from a connected Salesforce org. Returns no body on success.",
+		inputSchema: {
+			orgId: orgIdField,
+			sobject: z.string().describe("The sObject API name."),
+			id: z.string().describe("The record id to delete.")
+		}
+	}, async (args) => {
+		await resolveClient(args.orgId).deleteRecord(args.sobject, args.id);
+		return ok({
+			id: args.id,
+			deleted: true
+		});
+	});
+	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.",
+		inputSchema: {
+			orgId: orgIdField,
+			sobject: z.string().describe("The sObject API name to describe, e.g. Account or MyObject__c.")
+		}
+	}, async (args) => {
+		return ok(await resolveClient(args.orgId).describe(args.sobject));
+	});
+}
+//#endregion
+//#region src/server.ts
+/**
+* Salesforce MCP Server (Pattern A multi-org)
+*
+* Custom MCP server implementing the Salesforce REST/SOQL API directly
+* (like the MYOB server; unlike the Xero proxy that wraps a child MCP).
+* Every tool that touches credentials requires the LLM to pass `orgId`
+* explicitly — the server keeps one `SalesforceClient` per connected org
+* and dispatches per-call.
+*
+* Salesforce access tokens are per-org and NOT interchangeable, so token
+* refresh is per-org (via the connect per-account refresh endpoint), unlike
+* MYOB's interchangeable fan-out.
+*
+* Architecture:
+*   OpenClaw ←(stdio)→ this server ←(https)→ Salesforce REST API
+*/
+/**
+* Salesforce REST API version. The SOQL / sObject CRUD / describe surface is
+* version-stable, so this defaults to a widely-available version and can be
+* bumped per-deploy via `SALESFORCE_API_VERSION` without a code change.
+*/
+const DEFAULT_API_VERSION = "61.0";
+const clients = /* @__PURE__ */ new Map();
+const inFlightRefreshByOrg = /* @__PURE__ */ new Map();
+const orgSnapshot = [];
+function log(msg) {
+	process.stderr.write(`[salesforce-mcp-server] ${msg}\n`);
+}
+/**
+* Resolve an `orgId` selector to its `SalesforceClient`. Throws if unknown —
+* the LLM should call `salesforce_list_orgs` to discover the valid set. If the
+* org is connected on the agent but couldn't be initialised, the error tells
+* the LLM to ask the user to reconnect rather than retrying blindly.
+*/
+function resolveClient(orgId) {
+	const c = clients.get(orgId);
+	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.`);
+}
+/**
+* Refresh a single org's access token (Salesforce tokens are per-org).
+* Concurrent callers for the same org share one in-flight request; the
+* refreshed token is pushed into the cached client.
+*/
+async function refreshOrg(apiClient, orgId) {
+	const existing = inFlightRefreshByOrg.get(orgId);
+	if (existing) return existing;
+	const promise = (async () => {
+		try {
+			const { accessToken } = await apiClient.refreshSalesforceAccountToken(orgId);
+			clients.get(orgId)?.updateToken(accessToken);
+			return accessToken;
+		} finally {
+			inFlightRefreshByOrg.delete(orgId);
+		}
+	})();
+	inFlightRefreshByOrg.set(orgId, promise);
+	return promise;
+}
+async function main() {
+	const config = resolveConfig();
+	const apiClient = new AgentApiClient({
+		apiKey: config.apiKey,
+		apiUrl: config.apiUrl
+	});
+	const apiVersion = 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");
+	for (const acct of accounts) {
+		if (!acct.accessToken || !acct.instanceUrl) {
+			log(`Skipping org ${acct.orgId} — missing access token or instance URL`);
+			orgSnapshot.push({
+				orgId: acct.orgId,
+				instanceUrl: acct.instanceUrl,
+				displayName: acct.displayName,
+				connectedAt: acct.connectedAt,
+				connected: false,
+				reason: "missing_access_token_or_instance_url"
+			});
+			continue;
+		}
+		if (clients.has(acct.orgId)) {
+			log(`Duplicate orgId ${acct.orgId} returned by getSalesforceAccounts() — keeping the first cached client`);
+			continue;
+		}
+		clients.set(acct.orgId, new SalesforceClient({
+			accessToken: acct.accessToken,
+			instanceUrl: acct.instanceUrl,
+			apiVersion,
+			onRefresh: async () => {
+				return { accessToken: await refreshOrg(apiClient, acct.orgId) };
+			}
+		}));
+		orgSnapshot.push({
+			orgId: acct.orgId,
+			instanceUrl: acct.instanceUrl,
+			displayName: acct.displayName,
+			connectedAt: acct.connectedAt,
+			connected: true
+		});
+		log(`Cached client for org ${acct.orgId} (${acct.displayName ?? "no display name"})`);
+	}
+	const server = new McpServer({
+		name: "salesforce-mcp-server",
+		version: "1.0.0"
+	});
+	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." }, () => {
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({ orgs: orgSnapshot }, null, 2)
+		}] };
+	});
+	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.") }
+	}, async (args) => {
+		try {
+			if (args.orgId) resolveClient(args.orgId);
+			const targets = args.orgId ? [args.orgId] : [...clients.keys()];
+			for (const orgId of targets) await refreshOrg(apiClient, orgId);
+			return { content: [{
+				type: "text",
+				text: JSON.stringify({ refreshed: targets })
+			}] };
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
+				}],
+				isError: true
+			};
+		}
+	});
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	log(`Salesforce MCP server running with ${String(clients.size)} connected org(s) and Pattern A selector enforcement`);
+}
+for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => {
+	process.exit(0);
+});
+main().catch((err) => {
+	log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@alfe.ai/salesforce-mcp",
+  "version": "0.0.2",
+  "description": "Salesforce MCP server — direct REST/SOQL integration with Alfe OAuth credentials and automatic per-org token refresh",
+  "type": "module",
+  "main": "./dist/server.js",
+  "bin": {
+    "salesforce-mcp-server": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.5",
+    "@alfe.ai/config": "0.1.0",
+    "@alfe.ai/agent-api-client": "0.3.0"
+  },
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  }
+}