@alfe.ai/xero-mcp 0.3.21 → 0.4.1

package/dist/child-shim.cjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_fs = require("node:fs");
+let node_module = require("node:module");
+let node_path = require("node:path");
+let node_url = require("node:url");
+//#region src/child-shim.ts
+/**
+* Child bootstrap shim (runs INSIDE the spawned child process).
+*
+* The official `@xeroapi/xero-mcp-server` has no organisation selector: its
+* `MCPXeroClient.updateTenants()` unconditionally assigns
+* `this.tenantId = this.tenants[0].tenantId`, so a bearer token spanning several
+* Xero organisations silently acts on whichever one Xero happens to return
+* first. Every one of the child's tools resolves its organisation through that
+* single field (`xeroClient.tenantId`), so pinning it here bounds the whole
+* catalog.
+*
+* This shim imports the child's client module, re-pins `tenantId` to the
+* explicitly selected organisation after each `updateTenants()`, and only then
+* starts the child's real entrypoint.
+*
+* FAIL-CLOSED: every failure path throws instead of falling through to the
+* child's first-organisation default. A missing selector, an unrecognised
+* module shape, or a selector absent from the grant must stop the child, never
+* silently target another organisation's books. Writing to the wrong company's
+* ledger is the exact risk this boundary exists to prevent.
+*/
+const CHILD_PACKAGE = "@xeroapi/xero-mcp-server";
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isPatchableClient(value) {
+	return isRecord(value) && typeof value.updateTenants === "function";
+}
+/**
+* Resolve the child package root the same way the parent proxy does
+* (`require.resolve` + `realpathSync`) so this shim and the child's own
+* internal relative imports land on one module instance — and therefore one
+* `xeroClient` singleton. A divergent specifier would yield a second, unpatched
+* instance and defeat the pin.
+*/
+function resolveChildRoot() {
+	return (0, node_fs.realpathSync)((0, node_path.dirname)((0, node_module.createRequire)(require("url").pathToFileURL(__filename).href).resolve(`${CHILD_PACKAGE}/package.json`)));
+}
+function childModuleUrl(root, relativePath) {
+	return (0, node_url.pathToFileURL)((0, node_path.join)(root, relativePath)).href;
+}
+/**
+* Compared case-insensitively to match `validateXeroTenantId` in `boundary.ts`,
+* which lowercases. Xero's `/connections` body is untouched by the child, so a
+* non-lowercase UUID would otherwise verify in the parent and throw here.
+*/
+function assertTenantInGrant(tenants, selectedTenantId) {
+	const list = Array.isArray(tenants) ? tenants : [];
+	const wanted = selectedTenantId.toLowerCase();
+	if (!list.some((entry) => isRecord(entry) && typeof entry.tenantId === "string" && entry.tenantId.toLowerCase() === wanted)) throw new Error(`Xero grant does not expose organisation ${selectedTenantId}; refusing to start`);
+}
+async function main() {
+	const selectedTenantId = process.env.XERO_TENANT_ID;
+	if (selectedTenantId === void 0 || selectedTenantId === "") throw new Error("XERO_TENANT_ID is required; refusing to start without an explicit organisation");
+	const root = resolveChildRoot();
+	const clientModule = await import(childModuleUrl(root, "dist/clients/xero-client.js"));
+	if (!isRecord(clientModule) || !isPatchableClient(clientModule.xeroClient)) throw new Error(`${CHILD_PACKAGE} did not export a patchable xeroClient; refusing to start`);
+	installTenantPin(clientModule.xeroClient, selectedTenantId);
+	await import(childModuleUrl(root, "dist/index.js"));
+}
+function installTenantPin(client, selectedTenantId) {
+	Object.defineProperty(client, "tenantId", {
+		get: () => selectedTenantId,
+		set: () => {},
+		configurable: false,
+		enumerable: true
+	});
+	const updateTenants = client.updateTenants.bind(client);
+	client.updateTenants = async () => {
+		const tenants = await updateTenants(false);
+		assertTenantInGrant(tenants, selectedTenantId);
+		return tenants;
+	};
+}
+/**
+* Mirrors `isProcessEntrypoint` in `server.ts` rather than importing it: this
+* module runs inside the spawned child and must not pull the proxy (and its
+* AgentApiClient/config dependencies) in with it. Keeping the import inert also
+* lets the pin helpers be unit-tested without starting a child.
+*/
+function isProcessEntrypoint(argvPath, metaUrl) {
+	try {
+		if (argvPath === void 0 || argvPath === "") return false;
+		return (0, node_url.pathToFileURL)((0, node_fs.realpathSync)(argvPath)).href === (0, node_url.pathToFileURL)((0, node_fs.realpathSync)((0, node_url.fileURLToPath)(metaUrl))).href;
+	} catch {
+		return false;
+	}
+}
+if (isProcessEntrypoint(process.argv[1], require("url").pathToFileURL(__filename).href)) main().catch((error) => {
+	console.error(`xero-mcp child shim: ${error instanceof Error ? error.message : String(error)}`);
+	process.exit(1);
+});
+//#endregion
+exports.assertTenantInGrant = assertTenantInGrant;
+exports.installTenantPin = installTenantPin;

package/dist/child-shim.d.cts

@@ -0,0 +1,35 @@
+//#region src/child-shim.d.ts
+/**
+ * Child bootstrap shim (runs INSIDE the spawned child process).
+ *
+ * The official `@xeroapi/xero-mcp-server` has no organisation selector: its
+ * `MCPXeroClient.updateTenants()` unconditionally assigns
+ * `this.tenantId = this.tenants[0].tenantId`, so a bearer token spanning several
+ * Xero organisations silently acts on whichever one Xero happens to return
+ * first. Every one of the child's tools resolves its organisation through that
+ * single field (`xeroClient.tenantId`), so pinning it here bounds the whole
+ * catalog.
+ *
+ * This shim imports the child's client module, re-pins `tenantId` to the
+ * explicitly selected organisation after each `updateTenants()`, and only then
+ * starts the child's real entrypoint.
+ *
+ * FAIL-CLOSED: every failure path throws instead of falling through to the
+ * child's first-organisation default. A missing selector, an unrecognised
+ * module shape, or a selector absent from the grant must stop the child, never
+ * silently target another organisation's books. Writing to the wrong company's
+ * ledger is the exact risk this boundary exists to prevent.
+ */
+interface PatchableClient {
+  tenantId: string;
+  updateTenants: (fullOrgDetails?: unknown) => Promise<unknown>;
+}
+/**
+ * Compared case-insensitively to match `validateXeroTenantId` in `boundary.ts`,
+ * which lowercases. Xero's `/connections` body is untouched by the child, so a
+ * non-lowercase UUID would otherwise verify in the parent and throw here.
+ */
+declare function assertTenantInGrant(tenants: unknown, selectedTenantId: string): void;
+declare function installTenantPin(client: PatchableClient, selectedTenantId: string): void;
+//#endregion
+export { assertTenantInGrant, installTenantPin };

package/dist/child-shim.d.ts

@@ -0,0 +1,35 @@
+//#region src/child-shim.d.ts
+/**
+ * Child bootstrap shim (runs INSIDE the spawned child process).
+ *
+ * The official `@xeroapi/xero-mcp-server` has no organisation selector: its
+ * `MCPXeroClient.updateTenants()` unconditionally assigns
+ * `this.tenantId = this.tenants[0].tenantId`, so a bearer token spanning several
+ * Xero organisations silently acts on whichever one Xero happens to return
+ * first. Every one of the child's tools resolves its organisation through that
+ * single field (`xeroClient.tenantId`), so pinning it here bounds the whole
+ * catalog.
+ *
+ * This shim imports the child's client module, re-pins `tenantId` to the
+ * explicitly selected organisation after each `updateTenants()`, and only then
+ * starts the child's real entrypoint.
+ *
+ * FAIL-CLOSED: every failure path throws instead of falling through to the
+ * child's first-organisation default. A missing selector, an unrecognised
+ * module shape, or a selector absent from the grant must stop the child, never
+ * silently target another organisation's books. Writing to the wrong company's
+ * ledger is the exact risk this boundary exists to prevent.
+ */
+interface PatchableClient {
+  tenantId: string;
+  updateTenants: (fullOrgDetails?: unknown) => Promise<unknown>;
+}
+/**
+ * Compared case-insensitively to match `validateXeroTenantId` in `boundary.ts`,
+ * which lowercases. Xero's `/connections` body is untouched by the child, so a
+ * non-lowercase UUID would otherwise verify in the parent and throw here.
+ */
+declare function assertTenantInGrant(tenants: unknown, selectedTenantId: string): void;
+declare function installTenantPin(client: PatchableClient, selectedTenantId: string): void;
+//#endregion
+export { assertTenantInGrant, installTenantPin };

package/dist/child-shim.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+//#region src/child-shim.ts
+/**
+* Child bootstrap shim (runs INSIDE the spawned child process).
+*
+* The official `@xeroapi/xero-mcp-server` has no organisation selector: its
+* `MCPXeroClient.updateTenants()` unconditionally assigns
+* `this.tenantId = this.tenants[0].tenantId`, so a bearer token spanning several
+* Xero organisations silently acts on whichever one Xero happens to return
+* first. Every one of the child's tools resolves its organisation through that
+* single field (`xeroClient.tenantId`), so pinning it here bounds the whole
+* catalog.
+*
+* This shim imports the child's client module, re-pins `tenantId` to the
+* explicitly selected organisation after each `updateTenants()`, and only then
+* starts the child's real entrypoint.
+*
+* FAIL-CLOSED: every failure path throws instead of falling through to the
+* child's first-organisation default. A missing selector, an unrecognised
+* module shape, or a selector absent from the grant must stop the child, never
+* silently target another organisation's books. Writing to the wrong company's
+* ledger is the exact risk this boundary exists to prevent.
+*/
+const CHILD_PACKAGE = "@xeroapi/xero-mcp-server";
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isPatchableClient(value) {
+	return isRecord(value) && typeof value.updateTenants === "function";
+}
+/**
+* Resolve the child package root the same way the parent proxy does
+* (`require.resolve` + `realpathSync`) so this shim and the child's own
+* internal relative imports land on one module instance — and therefore one
+* `xeroClient` singleton. A divergent specifier would yield a second, unpatched
+* instance and defeat the pin.
+*/
+function resolveChildRoot() {
+	return realpathSync(dirname(createRequire(import.meta.url).resolve(`${CHILD_PACKAGE}/package.json`)));
+}
+function childModuleUrl(root, relativePath) {
+	return pathToFileURL(join(root, relativePath)).href;
+}
+/**
+* Compared case-insensitively to match `validateXeroTenantId` in `boundary.ts`,
+* which lowercases. Xero's `/connections` body is untouched by the child, so a
+* non-lowercase UUID would otherwise verify in the parent and throw here.
+*/
+function assertTenantInGrant(tenants, selectedTenantId) {
+	const list = Array.isArray(tenants) ? tenants : [];
+	const wanted = selectedTenantId.toLowerCase();
+	if (!list.some((entry) => isRecord(entry) && typeof entry.tenantId === "string" && entry.tenantId.toLowerCase() === wanted)) throw new Error(`Xero grant does not expose organisation ${selectedTenantId}; refusing to start`);
+}
+async function main() {
+	const selectedTenantId = process.env.XERO_TENANT_ID;
+	if (selectedTenantId === void 0 || selectedTenantId === "") throw new Error("XERO_TENANT_ID is required; refusing to start without an explicit organisation");
+	const root = resolveChildRoot();
+	const clientModule = await import(childModuleUrl(root, "dist/clients/xero-client.js"));
+	if (!isRecord(clientModule) || !isPatchableClient(clientModule.xeroClient)) throw new Error(`${CHILD_PACKAGE} did not export a patchable xeroClient; refusing to start`);
+	installTenantPin(clientModule.xeroClient, selectedTenantId);
+	await import(childModuleUrl(root, "dist/index.js"));
+}
+function installTenantPin(client, selectedTenantId) {
+	Object.defineProperty(client, "tenantId", {
+		get: () => selectedTenantId,
+		set: () => {},
+		configurable: false,
+		enumerable: true
+	});
+	const updateTenants = client.updateTenants.bind(client);
+	client.updateTenants = async () => {
+		const tenants = await updateTenants(false);
+		assertTenantInGrant(tenants, selectedTenantId);
+		return tenants;
+	};
+}
+/**
+* Mirrors `isProcessEntrypoint` in `server.ts` rather than importing it: this
+* module runs inside the spawned child and must not pull the proxy (and its
+* AgentApiClient/config dependencies) in with it. Keeping the import inert also
+* lets the pin helpers be unit-tested without starting a child.
+*/
+function isProcessEntrypoint(argvPath, metaUrl) {
+	try {
+		if (argvPath === void 0 || argvPath === "") return false;
+		return pathToFileURL(realpathSync(argvPath)).href === pathToFileURL(realpathSync(fileURLToPath(metaUrl))).href;
+	} catch {
+		return false;
+	}
+}
+if (isProcessEntrypoint(process.argv[1], import.meta.url)) main().catch((error) => {
+	console.error(`xero-mcp child shim: ${error instanceof Error ? error.message : String(error)}`);
+	process.exit(1);
+});
+//#endregion
+export { assertTenantInGrant, installTenantPin };

package/dist/server.cjs

@@ -51,8 +51,9 @@ const CHILD_ENV_ALLOWLIST = [
 	"https_proxy",
 	"no_proxy"
 ];
-function buildChildEnvironment(accessToken, source = process.env) {
+function buildChildEnvironment(accessToken, xeroTenantId, source = process.env) {
 	const token = validateAccessToken(accessToken, false);
+	const selectedTenantId = validateXeroTenantId(xeroTenantId);
 	const environment = Object.create(null);
 	for (const name of CHILD_ENV_ALLOWLIST) {
 		const value = source[name];
@@ -60,7 +61,8 @@ function buildChildEnvironment(accessToken, source = process.env) {
 	}
 	return {
 		...environment,
-		XERO_CLIENT_BEARER_TOKEN: token
+		XERO_CLIENT_BEARER_TOKEN: token,
+		XERO_TENANT_ID: selectedTenantId
 	};
 }
 function normalizeXeroAccount(value) {
@@ -176,10 +178,10 @@ async function verifyXeroTenantAccess(accessToken, xeroTenantId, fetchFn = fetch
 		throw new Error("Xero connections response was invalid JSON");
 	}
 	if (!Array.isArray(parsed) || parsed.length > 50) throw new Error("Xero connections response was invalid");
-	if (parsed.length !== 1) return "ambiguous";
-	const only = parsed[0];
-	if (!isRecord(only)) throw new Error("Xero connection entry was invalid");
-	return validateXeroTenantId(only.tenantId) === selectedTenantId ? "verified" : "mismatch";
+	return parsed.map((entry) => {
+		if (!isRecord(entry)) throw new Error("Xero connection entry was invalid");
+		return validateXeroTenantId(entry.tenantId);
+	}).includes(selectedTenantId) ? "verified" : "mismatch";
 }
 function snapshotToolCatalog(tools) {
 	return tools.map((tool) => structuredClone(tool));
@@ -367,9 +369,14 @@ function isRecord(value) {
 * Xero MCP proxy (Pattern A multi-connection boundary).
 *
 * The official child chooses the first organisation returned by Xero and does
-* not consume XERO_TENANT_ID. This proxy therefore starts a child only after a
-* bounded /connections preflight proves that the token exposes exactly one
-* organisation and that it equals the explicit xeroTenantId selector.
+* not consume XERO_TENANT_ID. Children are therefore launched through
+* `child-shim.ts`, which pins the child's `tenantId` to the explicitly selected
+* organisation before starting it, and fails closed if it cannot.
+*
+* One OAuth grant may cover several organisations, so the proxy runs one child
+* per selected organisation off a single shared token, keyed by xeroTenantId. A
+* bounded /connections preflight proves the selected organisation is still in
+* the grant before spawning; the first entry is never assumed.
 */
 const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
 const CHILD_PACKAGE = "@xeroapi/xero-mcp-server";
@@ -380,6 +387,23 @@ const SERVER_VERSION = validateSemver("xero-mcp package version", packageMetadat
 const CHILD_VERSION = validateExactChildVersion(packageMetadata.dependencies?.[CHILD_PACKAGE], childMetadata.version);
 const CHILD_BIN_PATH = resolveChildBin(childPackagePath, childMetadata.bin);
 const CHILD_PACKAGE_ROOT = (0, node_fs.realpathSync)((0, node_path.dirname)(childPackagePath));
+/**
+* The child is launched through our own shim rather than `CHILD_BIN_PATH`
+* directly: the shim pins the organisation before starting the child's real
+* entrypoint (see `child-shim.ts`). It is emitted alongside this module, so it
+* resolves relative to the built file.
+*/
+const CHILD_SHIM_PATH = (0, node_url.fileURLToPath)(new URL("./child-shim.js", require("url").pathToFileURL(__filename).href));
+/**
+* Ceiling on concurrently-running child processes, independent of
+* `MAX_XERO_ACCOUNTS` (which bounds the accounts payload). Since one grant can
+* now cover many organisations and each gets its own child, this bounds memory
+* on the agent VM: a warmed child costs roughly 125 MB RSS, so an unbounded
+* fan-out would OOM a 4 GB box that is also running the runtime and other MCP
+* servers. Organisations beyond the ceiling are reported as `child_limit` by
+* `xero_list_accounts` rather than dropped silently.
+*/
+const MAX_CONCURRENT_CHILDREN = 8;
 const CHILD_START_TIMEOUT_MS = 3e4;
 const CHILD_CATALOG_TIMEOUT_MS = 15e3;
 const CHILD_CALL_TIMEOUT_MS = 6e4;
@@ -441,7 +465,7 @@ var XeroRuntime = class {
 				if (Object.keys(prepared.forwarded).length !== 0) throw new Error("xero_refresh_token accepts only xeroTenantId");
 				tenant = this.resolveTenant(prepared.xeroTenantId);
 			} catch (error) {
-				return publicErrorResult(error);
+				return this.tenantSelectionErrorResult(error);
 			}
 			try {
 				await this.refreshTenant(tenant.xeroTenantId);
@@ -461,7 +485,7 @@ var XeroRuntime = class {
 			tenant = this.resolveTenant(prepared.xeroTenantId);
 			forwarded = prepared.forwarded;
 		} catch (error) {
-			return publicErrorResult(error);
+			return this.tenantSelectionErrorResult(error);
 		}
 		let result;
 		try {
@@ -530,6 +554,11 @@ var XeroRuntime = class {
 				this.allAccountsSnapshot.push(summary(account, false, "missing_access_token"));
 				continue;
 			}
+			if (this.tenants.size >= MAX_CONCURRENT_CHILDREN) {
+				log(`Child ceiling of ${String(MAX_CONCURRENT_CHILDREN)} reached; skipping Xero connection ${connectionLogId(account.connectionId)}`);
+				this.allAccountsSnapshot.push(summary(account, false, "child_limit"));
+				continue;
+			}
 			const controller = new AbortController();
 			let verification;
 			try {
@@ -541,11 +570,11 @@ var XeroRuntime = class {
 				continue;
 			}
 			if (verification !== "verified") {
-				this.allAccountsSnapshot.push(summary(account, false, verification === "ambiguous" ? "ambiguous_token" : "tenant_mismatch"));
+				this.allAccountsSnapshot.push(summary(account, false, "tenant_mismatch"));
 				continue;
 			}
 			try {
-				const client = await withDeadline(this.spawnChild(account.accessToken, controller.signal), CHILD_START_TIMEOUT_MS, "Xero child startup");
+				const client = await withDeadline(this.spawnChild(account.accessToken, account.xeroTenantId, controller.signal), CHILD_START_TIMEOUT_MS, "Xero child startup");
 				if (this.closed) {
 					await closeChild(client);
 					throw new Error("Xero runtime closed during child startup");
@@ -577,8 +606,34 @@ var XeroRuntime = class {
 		const tenant = this.tenants.get(xeroTenantId);
 		if (tenant !== void 0) return tenant;
 		const known = this.allAccountsSnapshot.find((candidate) => candidate.xeroTenantId === xeroTenantId);
-		if (known !== void 0) throw new Error(`xeroTenantId ${xeroTenantId} is connected but unavailable (${known.reason ?? "unknown"}). Ask the user to reconnect an OAuth credential that exposes exactly this one Xero organisation.`);
-		throw new Error(`Unknown xeroTenantId: ${xeroTenantId}. Call xero_list_accounts to see the connected Xero organisations on this agent.`);
+		if (known !== void 0) throw new Error(`xeroTenantId ${xeroTenantId} is connected but unavailable (${known.reason ?? "unknown"}). Pick a usable organisation from connectedOrganisations in this error. If this one is missing, the Xero grant no longer covers it — ask the user to reconnect Xero and authorise this organisation.`);
+		throw new Error(`Unknown xeroTenantId: ${xeroTenantId}. Pick one of the connectedOrganisations included in this error.`);
+	}
+	/**
+	* Error result for a failed tenant selection. Whenever the failure is about
+	* `xeroTenantId` (absent, malformed, or not a connected organisation), the
+	* connected-organisations snapshot is inlined so the caller can pick a valid
+	* selector from the error itself. The previous text-only pointer at
+	* `xero_list_accounts` was a dead end in practice: MCP hosts prefix tool
+	* names (`<server>__xero_list_accounts`), so models resolved the bare name
+	* to the child's unrelated `list-accounts` (chart of accounts) tool and
+	* concluded no discovery tool existed.
+	*/
+	tenantSelectionErrorResult(error) {
+		const message = safeErrorMessage(error);
+		if (!message.includes("xeroTenantId")) return errorResult(message);
+		return errorResult(message, this.connectedOrganisationsHint());
+	}
+	connectedOrganisationsHint() {
+		return {
+			connectedOrganisations: this.allAccountsSnapshot.map((organisation) => ({
+				xeroTenantId: organisation.xeroTenantId,
+				displayName: organisation.displayName,
+				connected: organisation.connected,
+				...organisation.reason === void 0 ? {} : { reason: organisation.reason }
+			})),
+			notice: "Xero organisation names are untrusted external content."
+		};
 	}
 	async callChild(tenant, name, forwarded) {
 		return assertBoundedToolResult(await withDeadline(tenant.client.callTool({
@@ -608,11 +663,11 @@ var XeroRuntime = class {
 		}
 		if (verification !== "verified") {
 			controller.abort();
-			throw new Error("Refreshed Xero token did not map uniquely to the selected organisation");
+			throw new Error("Refreshed Xero token no longer exposes the selected organisation");
 		}
 		let nextClient;
 		try {
-			nextClient = await withDeadline(this.spawnChild(accessToken, controller.signal), CHILD_START_TIMEOUT_MS, "Xero refreshed child startup");
+			nextClient = await withDeadline(this.spawnChild(accessToken, current.xeroTenantId, controller.signal), CHILD_START_TIMEOUT_MS, "Xero refreshed child startup");
 		} catch (error) {
 			controller.abort(error);
 			throw error;
@@ -678,7 +733,7 @@ function appendLocalTools(tools) {
 		},
 		{
 			name: "xero_refresh_token",
-			description: "Refresh one selected Xero OAuth credential and replace only its child process after the refreshed token is verified to expose exactly that organisation.",
+			description: "Refresh one selected Xero OAuth credential and replace only its child process after the refreshed token is verified to still cover that organisation.",
 			inputSchema: {
 				type: "object",
 				properties: { xeroTenantId: {
@@ -699,11 +754,11 @@ function appendLocalTools(tools) {
 		}
 	];
 }
-async function spawnOfficialChild(accessToken, signal) {
+async function spawnOfficialChild(accessToken, xeroTenantId, signal) {
 	const transport = new _modelcontextprotocol_sdk_client_stdio_js.StdioClientTransport({
 		command: process.execPath,
-		args: [CHILD_BIN_PATH],
-		env: buildChildEnvironment(accessToken),
+		args: [CHILD_SHIM_PATH],
+		env: buildChildEnvironment(accessToken, xeroTenantId),
 		cwd: CHILD_PACKAGE_ROOT,
 		stderr: "ignore"
 	});
@@ -848,6 +903,7 @@ if (isProcessEntrypoint(process.argv[1], require("url").pathToFileURL(__filename
 //#endregion
 exports.CHILD_BIN_PATH = CHILD_BIN_PATH;
 exports.CHILD_PACKAGE_ROOT = CHILD_PACKAGE_ROOT;
+exports.CHILD_SHIM_PATH = CHILD_SHIM_PATH;
 exports.CHILD_VERSION = CHILD_VERSION;
 exports.SERVER_VERSION = SERVER_VERSION;
 exports.XeroRuntime = XeroRuntime;

package/dist/server.d.cts

@@ -29,7 +29,7 @@ interface ProxiedTool {
   annotations?: ChildToolDescriptor["annotations"];
   execution?: ChildToolDescriptor["execution"];
 }
-type XeroTenantVerification = "verified" | "ambiguous" | "mismatch";
+type XeroTenantVerification = "verified" | "mismatch";
 type JsonPrimitive = null | boolean | number | string;
 type JsonValue = JsonPrimitive | JsonValue[] | {
   [key: string]: JsonValue;
@@ -40,6 +40,13 @@ declare const SERVER_VERSION: string;
 declare const CHILD_VERSION: string;
 declare const CHILD_BIN_PATH: string;
 declare const CHILD_PACKAGE_ROOT: string;
+/**
+ * The child is launched through our own shim rather than `CHILD_BIN_PATH`
+ * directly: the shim pins the organisation before starting the child's real
+ * entrypoint (see `child-shim.ts`). It is emitted alongside this module, so it
+ * resolves relative to the built file.
+ */
+declare const CHILD_SHIM_PATH: string;
 interface XeroApiClient {
   getXeroAccounts(): Promise<unknown>;
   refreshXeroAccountToken(accountIdentifier: string): Promise<unknown>;
@@ -55,7 +62,7 @@ interface XeroChildClient {
   close(): Promise<void>;
 }
 interface XeroProxyOptions {
-  spawnChild?: (accessToken: string, signal: AbortSignal) => Promise<XeroChildClient>;
+  spawnChild?: (accessToken: string, xeroTenantId: string, signal: AbortSignal) => Promise<XeroChildClient>;
   verifyTenantAccess?: (accessToken: string, xeroTenantId: string, signal: AbortSignal) => Promise<XeroTenantVerification>;
   scheduleRefresh?: boolean;
 }
@@ -87,6 +94,18 @@ declare class XeroRuntime {
   private loadAccounts;
   private discoverChildCatalog;
   private resolveTenant;
+  /**
+   * Error result for a failed tenant selection. Whenever the failure is about
+   * `xeroTenantId` (absent, malformed, or not a connected organisation), the
+   * connected-organisations snapshot is inlined so the caller can pick a valid
+   * selector from the error itself. The previous text-only pointer at
+   * `xero_list_accounts` was a dead end in practice: MCP hosts prefix tool
+   * names (`<server>__xero_list_accounts`), so models resolved the bare name
+   * to the child's unrelated `list-accounts` (chart of accounts) tool and
+   * concluded no discovery tool existed.
+   */
+  private tenantSelectionErrorResult;
+  private connectedOrganisationsHint;
   private callChild;
   private refreshTenant;
   private refreshTenantInner;
@@ -105,4 +124,4 @@ interface RunningXeroProxy {
 declare function startServer(apiClient?: XeroApiClient, options?: XeroProxyOptions): Promise<RunningXeroProxy>;
 declare function isProcessEntrypoint(argvPath: string | undefined, metaUrl: string): boolean;
 //#endregion
-export { CHILD_BIN_PATH, CHILD_PACKAGE_ROOT, CHILD_VERSION, RunningXeroProxy, SERVER_VERSION, XeroApiClient, XeroChildClient, XeroProxyOptions, XeroRuntime, createProxyServer, isProcessEntrypoint, startServer };
+export { CHILD_BIN_PATH, CHILD_PACKAGE_ROOT, CHILD_SHIM_PATH, CHILD_VERSION, RunningXeroProxy, SERVER_VERSION, XeroApiClient, XeroChildClient, XeroProxyOptions, XeroRuntime, createProxyServer, isProcessEntrypoint, startServer };

package/dist/server.d.ts

@@ -29,7 +29,7 @@ interface ProxiedTool {
   annotations?: ChildToolDescriptor["annotations"];
   execution?: ChildToolDescriptor["execution"];
 }
-type XeroTenantVerification = "verified" | "ambiguous" | "mismatch";
+type XeroTenantVerification = "verified" | "mismatch";
 type JsonPrimitive = null | boolean | number | string;
 type JsonValue = JsonPrimitive | JsonValue[] | {
   [key: string]: JsonValue;
@@ -40,6 +40,13 @@ declare const SERVER_VERSION: string;
 declare const CHILD_VERSION: string;
 declare const CHILD_BIN_PATH: string;
 declare const CHILD_PACKAGE_ROOT: string;
+/**
+ * The child is launched through our own shim rather than `CHILD_BIN_PATH`
+ * directly: the shim pins the organisation before starting the child's real
+ * entrypoint (see `child-shim.ts`). It is emitted alongside this module, so it
+ * resolves relative to the built file.
+ */
+declare const CHILD_SHIM_PATH: string;
 interface XeroApiClient {
   getXeroAccounts(): Promise<unknown>;
   refreshXeroAccountToken(accountIdentifier: string): Promise<unknown>;
@@ -55,7 +62,7 @@ interface XeroChildClient {
   close(): Promise<void>;
 }
 interface XeroProxyOptions {
-  spawnChild?: (accessToken: string, signal: AbortSignal) => Promise<XeroChildClient>;
+  spawnChild?: (accessToken: string, xeroTenantId: string, signal: AbortSignal) => Promise<XeroChildClient>;
   verifyTenantAccess?: (accessToken: string, xeroTenantId: string, signal: AbortSignal) => Promise<XeroTenantVerification>;
   scheduleRefresh?: boolean;
 }
@@ -87,6 +94,18 @@ declare class XeroRuntime {
   private loadAccounts;
   private discoverChildCatalog;
   private resolveTenant;
+  /**
+   * Error result for a failed tenant selection. Whenever the failure is about
+   * `xeroTenantId` (absent, malformed, or not a connected organisation), the
+   * connected-organisations snapshot is inlined so the caller can pick a valid
+   * selector from the error itself. The previous text-only pointer at
+   * `xero_list_accounts` was a dead end in practice: MCP hosts prefix tool
+   * names (`<server>__xero_list_accounts`), so models resolved the bare name
+   * to the child's unrelated `list-accounts` (chart of accounts) tool and
+   * concluded no discovery tool existed.
+   */
+  private tenantSelectionErrorResult;
+  private connectedOrganisationsHint;
   private callChild;
   private refreshTenant;
   private refreshTenantInner;
@@ -105,4 +124,4 @@ interface RunningXeroProxy {
 declare function startServer(apiClient?: XeroApiClient, options?: XeroProxyOptions): Promise<RunningXeroProxy>;
 declare function isProcessEntrypoint(argvPath: string | undefined, metaUrl: string): boolean;
 //#endregion
-export { CHILD_BIN_PATH, CHILD_PACKAGE_ROOT, CHILD_VERSION, RunningXeroProxy, SERVER_VERSION, XeroApiClient, XeroChildClient, XeroProxyOptions, XeroRuntime, createProxyServer, isProcessEntrypoint, startServer };
+export { CHILD_BIN_PATH, CHILD_PACKAGE_ROOT, CHILD_SHIM_PATH, CHILD_VERSION, RunningXeroProxy, SERVER_VERSION, XeroApiClient, XeroChildClient, XeroProxyOptions, XeroRuntime, createProxyServer, isProcessEntrypoint, startServer };

package/dist/server.js

@@ -50,8 +50,9 @@ const CHILD_ENV_ALLOWLIST = [
 	"https_proxy",
 	"no_proxy"
 ];
-function buildChildEnvironment(accessToken, source = process.env) {
+function buildChildEnvironment(accessToken, xeroTenantId, source = process.env) {
 	const token = validateAccessToken(accessToken, false);
+	const selectedTenantId = validateXeroTenantId(xeroTenantId);
 	const environment = Object.create(null);
 	for (const name of CHILD_ENV_ALLOWLIST) {
 		const value = source[name];
@@ -59,7 +60,8 @@ function buildChildEnvironment(accessToken, source = process.env) {
 	}
 	return {
 		...environment,
-		XERO_CLIENT_BEARER_TOKEN: token
+		XERO_CLIENT_BEARER_TOKEN: token,
+		XERO_TENANT_ID: selectedTenantId
 	};
 }
 function normalizeXeroAccount(value) {
@@ -175,10 +177,10 @@ async function verifyXeroTenantAccess(accessToken, xeroTenantId, fetchFn = fetch
 		throw new Error("Xero connections response was invalid JSON");
 	}
 	if (!Array.isArray(parsed) || parsed.length > 50) throw new Error("Xero connections response was invalid");
-	if (parsed.length !== 1) return "ambiguous";
-	const only = parsed[0];
-	if (!isRecord(only)) throw new Error("Xero connection entry was invalid");
-	return validateXeroTenantId(only.tenantId) === selectedTenantId ? "verified" : "mismatch";
+	return parsed.map((entry) => {
+		if (!isRecord(entry)) throw new Error("Xero connection entry was invalid");
+		return validateXeroTenantId(entry.tenantId);
+	}).includes(selectedTenantId) ? "verified" : "mismatch";
 }
 function snapshotToolCatalog(tools) {
 	return tools.map((tool) => structuredClone(tool));
@@ -366,9 +368,14 @@ function isRecord(value) {
 * Xero MCP proxy (Pattern A multi-connection boundary).
 *
 * The official child chooses the first organisation returned by Xero and does
-* not consume XERO_TENANT_ID. This proxy therefore starts a child only after a
-* bounded /connections preflight proves that the token exposes exactly one
-* organisation and that it equals the explicit xeroTenantId selector.
+* not consume XERO_TENANT_ID. Children are therefore launched through
+* `child-shim.ts`, which pins the child's `tenantId` to the explicitly selected
+* organisation before starting it, and fails closed if it cannot.
+*
+* One OAuth grant may cover several organisations, so the proxy runs one child
+* per selected organisation off a single shared token, keyed by xeroTenantId. A
+* bounded /connections preflight proves the selected organisation is still in
+* the grant before spawning; the first entry is never assumed.
 */
 const require = createRequire(import.meta.url);
 const CHILD_PACKAGE = "@xeroapi/xero-mcp-server";
@@ -379,6 +386,23 @@ const SERVER_VERSION = validateSemver("xero-mcp package version", packageMetadat
 const CHILD_VERSION = validateExactChildVersion(packageMetadata.dependencies?.[CHILD_PACKAGE], childMetadata.version);
 const CHILD_BIN_PATH = resolveChildBin(childPackagePath, childMetadata.bin);
 const CHILD_PACKAGE_ROOT = realpathSync(dirname(childPackagePath));
+/**
+* The child is launched through our own shim rather than `CHILD_BIN_PATH`
+* directly: the shim pins the organisation before starting the child's real
+* entrypoint (see `child-shim.ts`). It is emitted alongside this module, so it
+* resolves relative to the built file.
+*/
+const CHILD_SHIM_PATH = fileURLToPath(new URL("./child-shim.js", import.meta.url));
+/**
+* Ceiling on concurrently-running child processes, independent of
+* `MAX_XERO_ACCOUNTS` (which bounds the accounts payload). Since one grant can
+* now cover many organisations and each gets its own child, this bounds memory
+* on the agent VM: a warmed child costs roughly 125 MB RSS, so an unbounded
+* fan-out would OOM a 4 GB box that is also running the runtime and other MCP
+* servers. Organisations beyond the ceiling are reported as `child_limit` by
+* `xero_list_accounts` rather than dropped silently.
+*/
+const MAX_CONCURRENT_CHILDREN = 8;
 const CHILD_START_TIMEOUT_MS = 3e4;
 const CHILD_CATALOG_TIMEOUT_MS = 15e3;
 const CHILD_CALL_TIMEOUT_MS = 6e4;
@@ -440,7 +464,7 @@ var XeroRuntime = class {
 				if (Object.keys(prepared.forwarded).length !== 0) throw new Error("xero_refresh_token accepts only xeroTenantId");
 				tenant = this.resolveTenant(prepared.xeroTenantId);
 			} catch (error) {
-				return publicErrorResult(error);
+				return this.tenantSelectionErrorResult(error);
 			}
 			try {
 				await this.refreshTenant(tenant.xeroTenantId);
@@ -460,7 +484,7 @@ var XeroRuntime = class {
 			tenant = this.resolveTenant(prepared.xeroTenantId);
 			forwarded = prepared.forwarded;
 		} catch (error) {
-			return publicErrorResult(error);
+			return this.tenantSelectionErrorResult(error);
 		}
 		let result;
 		try {
@@ -529,6 +553,11 @@ var XeroRuntime = class {
 				this.allAccountsSnapshot.push(summary(account, false, "missing_access_token"));
 				continue;
 			}
+			if (this.tenants.size >= MAX_CONCURRENT_CHILDREN) {
+				log(`Child ceiling of ${String(MAX_CONCURRENT_CHILDREN)} reached; skipping Xero connection ${connectionLogId(account.connectionId)}`);
+				this.allAccountsSnapshot.push(summary(account, false, "child_limit"));
+				continue;
+			}
 			const controller = new AbortController();
 			let verification;
 			try {
@@ -540,11 +569,11 @@ var XeroRuntime = class {
 				continue;
 			}
 			if (verification !== "verified") {
-				this.allAccountsSnapshot.push(summary(account, false, verification === "ambiguous" ? "ambiguous_token" : "tenant_mismatch"));
+				this.allAccountsSnapshot.push(summary(account, false, "tenant_mismatch"));
 				continue;
 			}
 			try {
-				const client = await withDeadline(this.spawnChild(account.accessToken, controller.signal), CHILD_START_TIMEOUT_MS, "Xero child startup");
+				const client = await withDeadline(this.spawnChild(account.accessToken, account.xeroTenantId, controller.signal), CHILD_START_TIMEOUT_MS, "Xero child startup");
 				if (this.closed) {
 					await closeChild(client);
 					throw new Error("Xero runtime closed during child startup");
@@ -576,8 +605,34 @@ var XeroRuntime = class {
 		const tenant = this.tenants.get(xeroTenantId);
 		if (tenant !== void 0) return tenant;
 		const known = this.allAccountsSnapshot.find((candidate) => candidate.xeroTenantId === xeroTenantId);
-		if (known !== void 0) throw new Error(`xeroTenantId ${xeroTenantId} is connected but unavailable (${known.reason ?? "unknown"}). Ask the user to reconnect an OAuth credential that exposes exactly this one Xero organisation.`);
-		throw new Error(`Unknown xeroTenantId: ${xeroTenantId}. Call xero_list_accounts to see the connected Xero organisations on this agent.`);
+		if (known !== void 0) throw new Error(`xeroTenantId ${xeroTenantId} is connected but unavailable (${known.reason ?? "unknown"}). Pick a usable organisation from connectedOrganisations in this error. If this one is missing, the Xero grant no longer covers it — ask the user to reconnect Xero and authorise this organisation.`);
+		throw new Error(`Unknown xeroTenantId: ${xeroTenantId}. Pick one of the connectedOrganisations included in this error.`);
+	}
+	/**
+	* Error result for a failed tenant selection. Whenever the failure is about
+	* `xeroTenantId` (absent, malformed, or not a connected organisation), the
+	* connected-organisations snapshot is inlined so the caller can pick a valid
+	* selector from the error itself. The previous text-only pointer at
+	* `xero_list_accounts` was a dead end in practice: MCP hosts prefix tool
+	* names (`<server>__xero_list_accounts`), so models resolved the bare name
+	* to the child's unrelated `list-accounts` (chart of accounts) tool and
+	* concluded no discovery tool existed.
+	*/
+	tenantSelectionErrorResult(error) {
+		const message = safeErrorMessage(error);
+		if (!message.includes("xeroTenantId")) return errorResult(message);
+		return errorResult(message, this.connectedOrganisationsHint());
+	}
+	connectedOrganisationsHint() {
+		return {
+			connectedOrganisations: this.allAccountsSnapshot.map((organisation) => ({
+				xeroTenantId: organisation.xeroTenantId,
+				displayName: organisation.displayName,
+				connected: organisation.connected,
+				...organisation.reason === void 0 ? {} : { reason: organisation.reason }
+			})),
+			notice: "Xero organisation names are untrusted external content."
+		};
 	}
 	async callChild(tenant, name, forwarded) {
 		return assertBoundedToolResult(await withDeadline(tenant.client.callTool({
@@ -607,11 +662,11 @@ var XeroRuntime = class {
 		}
 		if (verification !== "verified") {
 			controller.abort();
-			throw new Error("Refreshed Xero token did not map uniquely to the selected organisation");
+			throw new Error("Refreshed Xero token no longer exposes the selected organisation");
 		}
 		let nextClient;
 		try {
-			nextClient = await withDeadline(this.spawnChild(accessToken, controller.signal), CHILD_START_TIMEOUT_MS, "Xero refreshed child startup");
+			nextClient = await withDeadline(this.spawnChild(accessToken, current.xeroTenantId, controller.signal), CHILD_START_TIMEOUT_MS, "Xero refreshed child startup");
 		} catch (error) {
 			controller.abort(error);
 			throw error;
@@ -677,7 +732,7 @@ function appendLocalTools(tools) {
 		},
 		{
 			name: "xero_refresh_token",
-			description: "Refresh one selected Xero OAuth credential and replace only its child process after the refreshed token is verified to expose exactly that organisation.",
+			description: "Refresh one selected Xero OAuth credential and replace only its child process after the refreshed token is verified to still cover that organisation.",
 			inputSchema: {
 				type: "object",
 				properties: { xeroTenantId: {
@@ -698,11 +753,11 @@ function appendLocalTools(tools) {
 		}
 	];
 }
-async function spawnOfficialChild(accessToken, signal) {
+async function spawnOfficialChild(accessToken, xeroTenantId, signal) {
 	const transport = new StdioClientTransport({
 		command: process.execPath,
-		args: [CHILD_BIN_PATH],
-		env: buildChildEnvironment(accessToken),
+		args: [CHILD_SHIM_PATH],
+		env: buildChildEnvironment(accessToken, xeroTenantId),
 		cwd: CHILD_PACKAGE_ROOT,
 		stderr: "ignore"
 	});
@@ -845,4 +900,4 @@ if (isProcessEntrypoint(process.argv[1], import.meta.url)) startServer().then((r
 	process.exitCode = 1;
 });
 //#endregion
-export { CHILD_BIN_PATH, CHILD_PACKAGE_ROOT, CHILD_VERSION, SERVER_VERSION, XeroRuntime, createProxyServer, isProcessEntrypoint, startServer };
+export { CHILD_BIN_PATH, CHILD_PACKAGE_ROOT, CHILD_SHIM_PATH, CHILD_VERSION, SERVER_VERSION, XeroRuntime, createProxyServer, isProcessEntrypoint, startServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/xero-mcp",
-  "version": "0.3.21",
+  "version": "0.4.1",
   "description": "Xero MCP proxy server — bridges the official @xeroapi/xero-mcp-server with Alfe OAuth credentials and automatic token refresh",
   "type": "module",
   "main": "./dist/server.js",
@@ -21,7 +21,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@xeroapi/xero-mcp-server": "0.0.14",
-    "@alfe.ai/agent-api-client": "0.17.1",
+    "@alfe.ai/agent-api-client": "0.18.0",
     "@alfe.ai/config": "0.4.1",
     "@alfe.ai/mcp-bundler": "0.4.1"
   },