@alfe.ai/atlassian-mcp 0.3.27 → 0.3.28

package/dist/server.js

@@ -9,7 +9,6 @@ import { resolveConfig } from "@alfe.ai/config";
 import { AgentApiClient } from "@alfe.ai/agent-api-client";
 import { assertPatternA } from "@alfe.ai/mcp-bundler";
 import { createHash } from "node:crypto";
-//#region src/boundary.ts
 const MAX_FORWARDED_ARGUMENT_BYTES = 1024 * 1024;
 const MAX_TOOL_RESULT_BYTES = 5 * 1024 * 1024;
 const MAX_SCHEMA_BYTES = 512 * 1024;
@@ -130,7 +129,7 @@ function injectCloudIdSelector(tool) {
 		}
 	};
 	if (tool.title !== void 0) result.title = validateText("tool title", tool.title, 256);
-	if (tool.description !== void 0) result.description = validateText("tool description", tool.description, 2e4);
+	if (tool.description !== void 0) result.description = validateDocumentationText("tool description", tool.description, 2e4);
 	if (tool.outputSchema !== void 0) result.outputSchema = cloneJsonRecord("tool output schema", tool.outputSchema, MAX_SCHEMA_BYTES, 1e5);
 	if (tool.annotations !== void 0) result.annotations = validateAnnotations(tool.annotations);
 	if (tool.execution !== void 0) {
@@ -261,6 +260,130 @@ function validateText(label, value, maxChars) {
 	if (value.length < 1 || value.length > maxChars || containsControlCharacter(value)) throw new Error(`${label} must contain 1 to ${String(maxChars)} non-control characters`);
 	return value;
 }
+/**
+* Like `validateText`, but for human-readable documentation (tool
+* descriptions) that legitimately spans lines. Tab, LF and CR are
+* allowed; every other C0 control character and DEL is still rejected.
+* Identifiers and titles keep the strict `validateText` rule.
+*/
+function validateDocumentationText(label, value, maxChars) {
+	if (value.length < 1 || value.length > maxChars || containsUnsafeDocumentationCharacter(value)) throw new Error(`${label} must contain 1 to ${String(maxChars)} safe characters`);
+	return value;
+}
+/**
+* Keep the first occurrence of every cloudId. Atlassian's
+* accessible-resources returns one entry per product (Jira and
+* Confluence) for the same site, so a single Connection can list the same
+* cloudId twice. Without this, the second entry fails the Connection's own
+* first-owner claim and surfaces as a spurious `duplicate_cloudId` row.
+*/
+function dedupeSitesById(sites) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const site of sites) {
+		if (seen.has(site.id)) continue;
+		seen.add(site.id);
+		result.push(site);
+	}
+	return result;
+}
+/**
+* Deduplicate by cloudId, then enforce MAX_SITES_PER_ACCOUNT on the
+* distinct sites. The per-account limit counts Cloud sites, not product
+* entries: 51 sites with Jira and Confluence each (102 raw entries) are
+* within the limit.
+*/
+function dedupeAndLimitSites(sites) {
+	const distinct = dedupeSitesById(sites);
+	if (distinct.length > 100) throw new Error(`Connection exceeds ${String(100)} accessible sites`);
+	return distinct;
+}
+/**
+* Track child catalog loading separately from the list-changed
+* notification, so a failed notification stays retryable instead of being
+* hidden behind an already-loaded catalog.
+*/
+function createCatalogLoader(sendListChanged) {
+	let loaded = false;
+	let notificationPending = false;
+	let inFlight = null;
+	return {
+		get loaded() {
+			return loaded;
+		},
+		get settled() {
+			return loaded && !notificationPending;
+		},
+		async ensure(load, notify) {
+			if (!loaded) {
+				inFlight ??= load().then(() => {
+					loaded = true;
+				}).finally(() => {
+					inFlight = null;
+				});
+				await inFlight;
+				if (notify) notificationPending = true;
+			}
+			if (notify && notificationPending) {
+				await sendListChanged();
+				notificationPending = false;
+			}
+		}
+	};
+}
+/**
+* Run child tool-catalog discovery without letting a failure escape.
+* A catalog that fails validation (or a child that cannot list tools)
+* must degrade the proxy to its meta tools, never kill it before the
+* stdio handshake. Returns whether discovery succeeded.
+*/
+async function discoverCatalogSafely(load, onFailure, secrets = []) {
+	try {
+		await load();
+		return true;
+	} catch (error) {
+		onFailure(safeErrorMessage(error, secrets));
+		return false;
+	}
+}
+/**
+* Re-run `attempt` on a doubling, capped delay until it resolves `true`
+* or `stop()` is called. A rejected attempt counts as "not yet". Timers
+* are unref'd so a pending retry never keeps the process alive.
+*/
+function startBackoffRetry(attempt, options) {
+	let stopped = false;
+	let reportedMaxDelay = false;
+	let timer = null;
+	let delay = options.initialMs;
+	const schedule = () => {
+		if (stopped) return;
+		timer = setTimeout(() => {
+			timer = null;
+			attempt().catch(() => false).then((done) => {
+				if (done) {
+					stopped = true;
+					return;
+				}
+				delay = Math.min(delay * 2, options.maxMs);
+				if (delay === options.maxMs && !reportedMaxDelay) {
+					reportedMaxDelay = true;
+					try {
+						options.onMaxDelay?.();
+					} catch {}
+				}
+				schedule();
+			});
+		}, delay);
+		timer.unref();
+	};
+	schedule();
+	return { stop() {
+		stopped = true;
+		if (timer !== null) clearTimeout(timer);
+		timer = null;
+	} };
+}
 function validateRequired(value) {
 	if (value === void 0) return [];
 	if (!Array.isArray(value) || value.length > 250) throw new Error("tool schema required must be an array");
@@ -375,6 +498,12 @@ function cloneRecord(label, value, depth, budget, maxStringChars) {
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function containsUnsafeDocumentationCharacter(value) {
+	return Array.from(value).some((character) => {
+		const codePoint = character.codePointAt(0) ?? 0;
+		return codePoint < 32 && character !== "	" && character !== "\n" && character !== "\r" || codePoint === 127;
+	});
+}
 function containsControlCharacter(value) {
 	return Array.from(value).some((character) => {
 		const codePoint = character.codePointAt(0) ?? 0;
@@ -434,9 +563,9 @@ const cloudOwners = /* @__PURE__ */ new Map();
 const allSitesSnapshot = [];
 const siteSummaryIndexes = /* @__PURE__ */ new Map();
 let cachedTools = [];
-let childCatalogLoaded = false;
-let catalogLoadPromise = null;
 let proxyServer = null;
+/** No proxy server yet means no connected client to notify. */
+const catalog = createCatalogLoader(() => proxyServer?.sendToolListChanged() ?? Promise.resolve());
 const META_TOOL_NAMES = new Set([
 	"atlassian_list_accounts",
 	"atlassian_check_connection",
@@ -524,24 +653,24 @@ async function killAllChildren() {
 	} catch {}
 	sites.clear();
 }
-async function ensureChildToolCatalog(client, notify) {
-	if (childCatalogLoaded) return;
-	if (catalogLoadPromise !== null) return catalogLoadPromise;
-	catalogLoadPromise = (async () => {
-		const { tools } = await client.listTools(void 0, {
-			timeout: 3e4,
-			signal: AbortSignal.timeout(3e4)
-		});
-		const childTools = validateToolCatalog(tools);
-		const metaTools = cachedTools.filter((tool) => META_TOOL_NAMES.has(tool.name));
-		cachedTools = [...childTools, ...metaTools];
-		childCatalogLoaded = true;
-		log(`Child MCP server provides ${String(childTools.length)} validated tools`);
-		if (notify && proxyServer !== null) await proxyServer.sendToolListChanged();
-	})().finally(() => {
-		catalogLoadPromise = null;
+async function loadChildToolCatalog(client) {
+	if (client === void 0) throw new Error("No live Atlassian child server to list tools from");
+	const { tools } = await client.listTools(void 0, {
+		timeout: 3e4,
+		signal: AbortSignal.timeout(3e4)
 	});
-	return catalogLoadPromise;
+	const childTools = validateToolCatalog(tools);
+	const metaTools = cachedTools.filter((tool) => META_TOOL_NAMES.has(tool.name));
+	cachedTools = [...childTools, ...metaTools];
+	log(`Child MCP server provides ${String(childTools.length)} validated tools`);
+}
+/**
+* Load the child catalog once. With `notify`, also send
+* tools/list_changed; a failed notification stays pending (see
+* `createCatalogLoader`) so the catalog retry re-sends it.
+*/
+async function ensureChildToolCatalog(client, notify) {
+	await catalog.ensure(() => loadChildToolCatalog(client), notify);
 }
 /**
 * Refresh a specific Connection's access token and atomically swap every
@@ -568,6 +697,7 @@ async function refreshConnection(apiClient, accountIdentifier) {
 					await ensureChildToolCatalog(newChild, true).catch((error) => {
 						log(`Could not refresh the Atlassian tool catalog: ${safeErrorMessage(error, [accessToken])}`);
 					});
+					if (!catalog.settled) startCatalogRetry();
 					sites.set(intended.id, {
 						cloudId: intended.id,
 						siteName: intended.name,
@@ -643,6 +773,35 @@ function scheduleRefresh(apiClient, delayMs = REFRESH_INTERVAL_MS) {
 	}, delayMs);
 	refreshTimer.unref();
 }
+const CATALOG_RETRY_INITIAL_MS = 5e3;
+const CATALOG_RETRY_MAX_MS = 6e4;
+let catalogRetry = null;
+function currentAccessTokens() {
+	return Array.from(connections.values(), (connection) => connection.accessToken);
+}
+/**
+* Retry child tool-catalog discovery (5s doubling to 60s) against
+* whichever child is live at the time, until it loads (no attempt cap;
+* one warning is logged when the backoff first reaches 60s). If a refresh
+* respawn loads the catalog first, the next tick stops the retry.
+*/
+function startCatalogRetry() {
+	catalogRetry?.stop();
+	catalogRetry = startBackoffRetry(async () => {
+		if (catalog.settled) return true;
+		const site = sites.values().next().value;
+		if (!catalog.loaded && !site) return false;
+		return discoverCatalogSafely(() => ensureChildToolCatalog(site?.client, true), (message) => {
+			log(`Atlassian tool catalog retry failed: ${message}`);
+		}, currentAccessTokens());
+	}, {
+		initialMs: CATALOG_RETRY_INITIAL_MS,
+		maxMs: CATALOG_RETRY_MAX_MS,
+		onMaxDelay: () => {
+			log(`WARN: Atlassian tool catalog still not loaded; retry backoff reached ${String(CATALOG_RETRY_MAX_MS / 1e3)}s and will keep retrying at that interval`);
+		}
+	});
+}
 async function main() {
 	const config = resolveConfig();
 	const apiClient = new AgentApiClient({
@@ -667,12 +826,12 @@ async function main() {
 				name: acct.siteName,
 				url: acct.siteUrl
 			}] : [];
-			if (rawSites.length > 100) throw new Error(`Connection exceeds ${String(100)} accessible sites`);
-			intendedSitesForAcct = rawSites.map((site) => ({
+			if (rawSites.length > 400) throw new Error(`Connection lists more than ${String(400)} site entries`);
+			intendedSitesForAcct = dedupeAndLimitSites(rawSites.map((site) => ({
 				id: validateCloudId(site.id),
 				name: validateSiteName(site.name),
 				url: validateSiteUrl(site.url)
-			}));
+			})));
 			totalSites += intendedSitesForAcct.length;
 			if (totalSites > 250) throw new Error(`Connect returned more than ${String(250)} Atlassian sites`);
 		} catch (error) {
@@ -767,8 +926,11 @@ async function main() {
 		}
 	}
 	const firstSite = sites.values().next().value;
-	if (firstSite) await ensureChildToolCatalog(firstSite.client, false);
-	else {
+	if (firstSite) {
+		if (!await discoverCatalogSafely(() => ensureChildToolCatalog(firstSite.client, false), (message) => {
+			log(`Atlassian tool catalog discovery failed; exposing only the meta tools and retrying: ${message}`);
+		}, currentAccessTokens())) startCatalogRetry();
+	} else {
 		cachedTools = [];
 		log("No child server available — only atlassian_list_accounts, atlassian_check_connection, and atlassian_refresh_token will be exposed");
 	}
@@ -1038,6 +1200,7 @@ let shutdownPromise = null;
 function shutdown(exitCode) {
 	if (shutdownPromise !== null) return;
 	if (refreshTimer) clearTimeout(refreshTimer);
+	catalogRetry?.stop();
 	shutdownPromise = killAllChildren().finally(() => {
 		process.exit(exitCode);
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/atlassian-mcp",
-  "version": "0.3.27",
+  "version": "0.3.28",
   "description": "Atlassian MCP proxy server — bridges sooperset/mcp-atlassian with Alfe OAuth credentials (Pattern A multi-site)",
   "type": "module",
   "main": "./dist/server.js",