@alfe.ai/xero-mcp 0.3.0

package/dist/server.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { resolveConfig } from "@alfe.ai/config";
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+//#region src/server.ts
+/**
+* Xero MCP Proxy Server (Pattern A multi-account)
+*
+* A thin proxy that fans out to one official `@xeroapi/xero-mcp-server`
+* child process per connected Xero tenant. Every credential-touching
+* tool requires the LLM to pass a `xeroTenantId` selector arg; the proxy
+* strips that arg, dispatches to the right child, and returns the result.
+*
+* Pattern A locked in PR 7.3 of channels-and-credential-driven-
+* integrations. See `packages/mcp-bundler/DEVELOPING.md` for the
+* contract; `services/connect/DEVELOPING.md` for the provider table.
+*
+* Architecture:
+*   OpenClaw ←(stdio)→ this proxy ←(stdio fan-out)→ N × @xeroapi/xero-mcp-server
+*
+* Token refresh is per-tenant: Xero access tokens are NOT interchangeable
+* across tenants on the same agent (unlike MYOB), so a 401 from one
+* tenant refreshes only that tenant's token via
+* `apiClient.refreshXeroAccountToken(xeroTenantId)` and respawns only
+* that tenant's child. Xero tokens expire every 30 minutes, so the
+* scheduled refresh path walks every cached tenant on a 25-minute
+* cadence.
+*
+* Uses the low-level Server class (not McpServer) because child tools
+* return JSON Schema objects — McpServer.registerTool requires Zod.
+*/
+const tenants = /* @__PURE__ */ new Map();
+/** Full getXeroAccounts() snapshot — includes rows we couldn't spawn. */
+const allAccountsSnapshot = [];
+/** Cached, selector-injected tool list. */
+let cachedTools = [];
+let refreshTimer = null;
+/**
+* Collapse concurrent refreshes on a per-tenant basis. A burst of 401s
+* across the same tenant share one in-flight refresh call.
+*/
+const inFlightRefreshByTenant = /* @__PURE__ */ new Map();
+const REFRESH_INTERVAL_MS = 1500 * 1e3;
+const REFRESH_RETRY_MS = 60 * 1e3;
+function log(msg) {
+	process.stderr.write(`[xero-mcp-proxy] ${msg}\n`);
+}
+function resolveTenant(xeroTenantId) {
+	if (!xeroTenantId) throw new Error("Missing required xeroTenantId argument. Call xero_list_accounts to see the connected Xero tenants and pass the xeroTenantId you want to target.");
+	const t = tenants.get(xeroTenantId);
+	if (!t) {
+		const known = allAccountsSnapshot.find((s) => s.xeroTenantId === xeroTenantId);
+		if (known && !known.connected) throw new Error(`xeroTenantId ${xeroTenantId} is connected on this agent but the proxy could not initialise a child server for it (reason: ${known.reason ?? "unknown"}). Ask the user to reconnect this Xero tenant from the dashboard.`);
+		throw new Error(`Unknown xeroTenantId: ${xeroTenantId}. Call xero_list_accounts to see the connected Xero tenants on this agent.`);
+	}
+	return t;
+}
+async function spawnChild(accessToken, xeroTenantId) {
+	const transport = new StdioClientTransport({
+		command: "npx",
+		args: ["-y", "@xeroapi/xero-mcp-server"],
+		env: {
+			...process.env,
+			XERO_CLIENT_BEARER_TOKEN: accessToken,
+			XERO_TENANT_ID: xeroTenantId
+		}
+	});
+	const client = new Client({
+		name: "xero-mcp-proxy",
+		version: "2.0.0"
+	});
+	await client.connect(transport);
+	return client;
+}
+async function killAllChildren() {
+	for (const t of tenants.values()) try {
+		await t.client.close();
+	} catch {}
+	tenants.clear();
+}
+/**
+* Refresh a specific tenant's access token and atomically swap its
+* child server. Concurrent callers for the same tenant share one
+* in-flight refresh + respawn.
+*/
+async function refreshTenant(apiClient, xeroTenantId) {
+	const existing = inFlightRefreshByTenant.get(xeroTenantId);
+	if (existing) return existing;
+	const promise = (async () => {
+		try {
+			const { accessToken } = await apiClient.refreshXeroAccountToken(xeroTenantId);
+			const newChild = await spawnChild(accessToken, xeroTenantId);
+			const old = tenants.get(xeroTenantId);
+			tenants.set(xeroTenantId, {
+				xeroTenantId,
+				displayName: old?.displayName ?? null,
+				connectedAt: old?.connectedAt ?? "",
+				accessToken,
+				client: newChild
+			});
+			if (old) try {
+				await old.client.close();
+			} catch {}
+			return accessToken;
+		} finally {
+			inFlightRefreshByTenant.delete(xeroTenantId);
+		}
+	})();
+	inFlightRefreshByTenant.set(xeroTenantId, promise);
+	return promise;
+}
+function scheduleRefresh(apiClient) {
+	if (refreshTimer) clearTimeout(refreshTimer);
+	refreshTimer = setTimeout(() => {
+		(async () => {
+			const tenantIds = Array.from(tenants.keys());
+			if (tenantIds.length === 0) {
+				refreshTimer = setTimeout(() => {
+					scheduleRefresh(apiClient);
+				}, REFRESH_INTERVAL_MS);
+				return;
+			}
+			log(`Refreshing Xero access tokens across ${String(tenantIds.length)} tenant(s)...`);
+			let anyFailed = false;
+			for (const tid of tenantIds) try {
+				await refreshTenant(apiClient, tid);
+			} catch (err) {
+				anyFailed = true;
+				log(`Token refresh failed for tenant ${tid}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			refreshTimer = setTimeout(() => {
+				scheduleRefresh(apiClient);
+			}, anyFailed ? REFRESH_RETRY_MS : REFRESH_INTERVAL_MS);
+		})();
+	}, REFRESH_INTERVAL_MS);
+}
+/**
+* Inject a required `xeroTenantId` string property into a child tool's
+* inputSchema. The proxy strips this arg before forwarding to the child.
+*/
+function injectTenantSelector(tool) {
+	const original = tool.inputSchema ?? {};
+	const originalProperties = original.properties ?? {};
+	const originalRequired = Array.isArray(original.required) ? original.required : [];
+	const injectedProperties = {
+		...originalProperties,
+		xeroTenantId: {
+			type: "string",
+			description: "Xero tenantId — use the value from xero_list_accounts to pick which connected tenant this call should target."
+		}
+	};
+	const injectedRequired = originalRequired.includes("xeroTenantId") ? originalRequired : ["xeroTenantId", ...originalRequired];
+	return {
+		name: tool.name,
+		description: tool.description,
+		inputSchema: {
+			...original,
+			type: original.type ?? "object",
+			properties: injectedProperties,
+			required: injectedRequired
+		}
+	};
+}
+async function main() {
+	const config = resolveConfig();
+	const apiClient = new AgentApiClient({
+		apiKey: config.apiKey,
+		apiUrl: config.apiUrl
+	});
+	const { accounts } = await apiClient.getXeroAccounts();
+	if (accounts.length === 0) log("No Xero tenants connected — proxy will start with xero_list_accounts and xero_refresh_token only");
+	for (const acct of accounts) {
+		if (!acct.accessToken) {
+			log(`Skipping tenant ${acct.xeroTenantId} — no access token`);
+			allAccountsSnapshot.push({
+				xeroTenantId: acct.xeroTenantId,
+				displayName: acct.displayName,
+				connectedAt: acct.connectedAt,
+				connected: false,
+				reason: "missing_access_token"
+			});
+			continue;
+		}
+		if (tenants.has(acct.xeroTenantId)) {
+			log(`Duplicate xeroTenantId ${acct.xeroTenantId} returned by getXeroAccounts() — keeping the first cached child`);
+			continue;
+		}
+		try {
+			const client = await spawnChild(acct.accessToken, acct.xeroTenantId);
+			tenants.set(acct.xeroTenantId, {
+				xeroTenantId: acct.xeroTenantId,
+				displayName: acct.displayName,
+				connectedAt: acct.connectedAt,
+				accessToken: acct.accessToken,
+				client
+			});
+			allAccountsSnapshot.push({
+				xeroTenantId: acct.xeroTenantId,
+				displayName: acct.displayName,
+				connectedAt: acct.connectedAt,
+				connected: true
+			});
+			log(`Spawned child server for tenant ${acct.xeroTenantId} (${acct.displayName ?? "unnamed"})`);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			log(`Failed to spawn child for tenant ${acct.xeroTenantId}: ${message}`);
+			allAccountsSnapshot.push({
+				xeroTenantId: acct.xeroTenantId,
+				displayName: acct.displayName,
+				connectedAt: acct.connectedAt,
+				connected: false,
+				reason: `spawn_failed: ${message}`
+			});
+		}
+	}
+	const firstTenant = tenants.values().next().value;
+	if (firstTenant) {
+		const { tools } = await firstTenant.client.listTools();
+		cachedTools = tools.map(injectTenantSelector);
+		log(`Child MCP server provides ${String(cachedTools.length)} tools (selector injected)`);
+	} else {
+		cachedTools = [];
+		log("No child server available — only xero_list_accounts and xero_refresh_token will be exposed");
+	}
+	cachedTools.push({
+		name: "xero_list_accounts",
+		description: "List the Xero tenants the agent has connected. Returns one entry per OAuth connection — use the returned xeroTenantId values as the `xeroTenantId` selector arg on every other Xero tool.",
+		inputSchema: {
+			type: "object",
+			properties: {}
+		}
+	});
+	cachedTools.push({
+		name: "xero_refresh_token",
+		description: "Force-refresh the Xero OAuth2 access token for a specific connected tenant. Use this if Xero API calls are failing with authentication errors. Each Xero tenant has its own access token — pass the tenant you want to refresh.",
+		inputSchema: {
+			type: "object",
+			properties: { xeroTenantId: {
+				type: "string",
+				description: "Xero tenantId — use the value from xero_list_accounts."
+			} },
+			required: ["xeroTenantId"]
+		}
+	});
+	const proxy = new Server({
+		name: "xero-mcp-proxy",
+		version: "2.0.0"
+	}, { capabilities: { tools: {} } });
+	proxy.setRequestHandler(ListToolsRequestSchema, () => ({ tools: cachedTools }));
+	proxy.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const { name, arguments: args } = request.params;
+		const argMap = args ?? {};
+		if (name === "xero_list_accounts") return { content: [{
+			type: "text",
+			text: JSON.stringify({ tenants: allAccountsSnapshot }, null, 2)
+		}] };
+		if (name === "xero_refresh_token") try {
+			const t = resolveTenant(typeof argMap.xeroTenantId === "string" ? argMap.xeroTenantId : void 0);
+			await refreshTenant(apiClient, t.xeroTenantId);
+			return { content: [{
+				type: "text",
+				text: JSON.stringify({
+					xeroTenantId: t.xeroTenantId,
+					refreshed: true
+				})
+			}] };
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
+				}],
+				isError: true
+			};
+		}
+		let t;
+		try {
+			t = resolveTenant(typeof argMap.xeroTenantId === "string" ? argMap.xeroTenantId : void 0);
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) })
+				}],
+				isError: true
+			};
+		}
+		const { xeroTenantId: _ignored, ...forwarded } = argMap;
+		let result;
+		try {
+			result = await t.client.callTool({
+				name,
+				arguments: forwarded
+			});
+		} catch (err) {
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						xeroTenantId: t.xeroTenantId,
+						tool: name,
+						error: err instanceof Error ? err.message : String(err)
+					})
+				}],
+				isError: true
+			};
+		}
+		if (result.isError) {
+			const errorText = result.content.map((c) => c.text ?? "").join("\n");
+			if (errorText.includes("401") || errorText.toLowerCase().includes("unauthorized")) {
+				log(`401 from tenant ${t.xeroTenantId}, refreshing and retrying...`);
+				try {
+					await refreshTenant(apiClient, t.xeroTenantId);
+					const refreshed = tenants.get(t.xeroTenantId);
+					if (!refreshed) throw new Error("Tenant disappeared after refresh");
+					return await refreshed.client.callTool({
+						name,
+						arguments: forwarded
+					});
+				} catch (refreshErr) {
+					return {
+						content: [{
+							type: "text",
+							text: JSON.stringify({
+								xeroTenantId: t.xeroTenantId,
+								error: `Token refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}`
+							})
+						}],
+						isError: true
+					};
+				}
+			}
+		}
+		return result;
+	});
+	scheduleRefresh(apiClient);
+	const transport = new StdioServerTransport();
+	await proxy.connect(transport);
+	log(`Proxy running with ${String(tenants.size)} connected tenant(s) and Pattern A selector enforcement`);
+}
+for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => {
+	if (refreshTimer) clearTimeout(refreshTimer);
+	killAllChildren().then(() => {
+		process.exit(0);
+	});
+});
+main().catch((err) => {
+	log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+	if (refreshTimer) clearTimeout(refreshTimer);
+	killAllChildren().finally(() => {
+		process.exit(1);
+	});
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@alfe.ai/xero-mcp",
+  "version": "0.3.0",
+  "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",
+  "bin": {
+    "xero-mcp-proxy": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": ">=1.24.0",
+    "@xeroapi/xero-mcp-server": "^0.0.14",
+    "@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 ."
+  }
+}