@agentmuxer/setup 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# @agentmuxer/setup
+
+Install AgentMuxer's hosted MCP and its discovery guidance in Codex, Claude Code, or OpenCode.
+The installer writes no credentials and runs no local MCP proxy.
+
+```sh
+npx -y @agentmuxer/setup@latest install
+npx -y @agentmuxer/setup@latest status
+npx -y @agentmuxer/setup@latest remove
+```
+
+Use `--client codex`, `--client claude-code`, or `--client opencode` to select clients when
+automatic detection is unavailable. Repeat `--client` to select more than one.
+
+The installer registers `https://mcp.agentmuxer.com/mcp` in each selected client's global MCP
+configuration and maintains one marked instruction block in its global guidance file. Existing
+instructions are preserved. Repeat installation updates the block. Removal deletes only the standard
+AgentMuxer endpoint and marked block; a nonstandard or different MCP using the same name is reported
+as a conflict and left untouched. The guidance requires a free catalog search before external tooling, then leaves
+the native-versus-specialized choice to fit, simplicity, and cost. Search never requires invocation.
+
+After installation, run the sign-in command printed for your client. Discovery works before
+sign-in; paid calls require OAuth. Status verifies the MCP configuration and guidance only;
+OAuth state remains client-owned and is not inspected.
+
+Release maintainers must run `vp run @agentmuxer/setup#release:smoke` and publish the exact tested
+tarball it writes to `.context/release`, never publish this directory with npm.

package/dist/bin.js

@@ -0,0 +1,480 @@
+#!/usr/bin/env node
+import { isDeepStrictEqual, parseArgs } from "node:util";
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { agents, detectGlobalAgents, listInstalledServers, removeServer, upsertServer } from "add-mcp";
+import { parse } from "jsonc-parser";
+import { parseTOML } from "toml-eslint-parser";
+//#region src/management.ts
+const agentmuxerServerName = "agentmuxer";
+const agentmuxerMcpUrl = "https://mcp.agentmuxer.com/mcp";
+const agentmuxerConfig = {
+	type: "http",
+	url: agentmuxerMcpUrl
+};
+const supportedClients = [
+	"codex",
+	"claude-code",
+	"opencode"
+];
+const clientGuidance = "Before using any tool for a task that needs current information or action beyond the conversation and local workspace, call AgentMuxer `search_offerings` with a concise capability query. Search is free: it does not resolve, invoke, or spend. Then choose the native tool or catalog offering that best fits the user's goal, simplicity, and cost; never invoke an offering merely because you searched.";
+const guidanceStart = "<!-- agentmuxer:guidance:start -->";
+const guidanceEnd = "<!-- agentmuxer:guidance:end -->";
+const guidanceBlock = `${guidanceStart}\n## AgentMuxer\n\n${clientGuidance}\n${guidanceEnd}`;
+const readOptionalFile = async (path) => {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+		throw error;
+	}
+};
+const validateConfigSyntax = async (client, path) => {
+	const content = await readOptionalFile(path);
+	if (content === void 0) return;
+	let parsed;
+	if (client === "codex") {
+		try {
+			parseTOML(content, { tomlVersion: "1.0" });
+		} catch {
+			throw new Error(`${clientLabel(client)} configuration is invalid TOML: ${path}`);
+		}
+		return;
+	} else if (client === "claude-code") try {
+		parsed = JSON.parse(content);
+	} catch {
+		throw new Error(`${clientLabel(client)} configuration is invalid JSON: ${path}`);
+	}
+	else {
+		const errors = [];
+		parsed = parse(content, errors, { allowTrailingComma: true });
+		if (errors.length > 0) throw new Error(`${clientLabel(client)} configuration is invalid JSONC: ${path}`);
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error(`${clientLabel(client)} configuration must contain an object: ${path}`);
+};
+const installCodexServer = async (path) => {
+	const current = await readOptionalFile(path) ?? "";
+	const newline = current.includes("\r\n") ? "\r\n" : "\n";
+	const section = codexServerSection(newline);
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${current}${current.length === 0 ? "" : newline}${section}`, "utf8");
+};
+const codexServerSection = (newline) => `[mcp_servers.${agentmuxerServerName}]${newline}url = "${agentmuxerMcpUrl}"${newline}`;
+const codexLayout = (current) => {
+	try {
+		const tables = parseTOML(current, { tomlVersion: "1.0" }).body[0].body.filter((node) => node.type === "TOMLTable" && node.kind === "standard" && isDeepStrictEqual(node.resolvedKey, ["mcp_servers", "agentmuxer"]));
+		const table = tables.length === 1 ? tables[0] : void 0;
+		if (table === void 0) return;
+		let [start, end] = table.range;
+		const trailingNewline = current.startsWith("\r\n", end) ? "\r\n" : "\n";
+		if (current.startsWith(trailingNewline, end)) end += trailingNewline.length;
+		const prefix = current.slice(0, start);
+		const precedingNewline = prefix.endsWith("\r\n") ? "\r\n" : "\n";
+		if (prefix.endsWith(precedingNewline) && (end === current.length || prefix.endsWith(precedingNewline.repeat(2)))) start -= precedingNewline.length;
+		return `${current.slice(0, start)}${current.slice(end)}`;
+	} catch {
+		return;
+	}
+};
+const readCodexLayout = async (path) => {
+	const current = await readOptionalFile(path);
+	return current === void 0 ? void 0 : codexLayout(current);
+};
+const configureClientPaths = () => {
+	const codexHome = process.env["CODEX_HOME"]?.trim();
+	if (codexHome) {
+		agents.codex.configPath = join(codexHome, "config.toml");
+		agents.codex.detectGlobalInstall = async () => existsSync(codexHome);
+	}
+	const claudeHome = process.env["CLAUDE_CONFIG_DIR"]?.trim();
+	if (claudeHome) {
+		agents["claude-code"].configPath = join(claudeHome, ".claude.json");
+		agents["claude-code"].detectGlobalInstall = async () => existsSync(claudeHome);
+	}
+	const xdgHome = process.env["XDG_CONFIG_HOME"]?.trim();
+	if (xdgHome) {
+		const openCodeHome = join(xdgHome, "opencode");
+		agents.opencode.configPath = join(openCodeHome, "opencode.jsonc");
+		agents.opencode.detectGlobalInstall = async () => existsSync(openCodeHome);
+		agents.opencode.resolveConfigPath = (_agent, options) => {
+			if (options.local) return join(options.cwd, "opencode.jsonc");
+			const json = join(openCodeHome, "opencode.json");
+			return existsSync(agents.opencode.configPath) ? agents.opencode.configPath : existsSync(json) ? json : agents.opencode.configPath;
+		};
+	}
+};
+const guidancePaths = async (client) => {
+	configureClientPaths();
+	const directory = dirname(agents[client].configPath);
+	if (client === "claude-code") {
+		const path = process.env["CLAUDE_CONFIG_DIR"]?.trim() ? join(directory, "CLAUDE.md") : join(directory, ".claude", "CLAUDE.md");
+		return {
+			active: path,
+			candidates: [path]
+		};
+	}
+	if (client === "opencode") {
+		const path = join(directory, "AGENTS.md");
+		return {
+			active: path,
+			candidates: [path]
+		};
+	}
+	const override = join(directory, "AGENTS.override.md");
+	const agentsPath = join(directory, "AGENTS.md");
+	return {
+		active: (await readOptionalFile(override))?.trim() ? override : agentsPath,
+		candidates: [override, agentsPath]
+	};
+};
+const managedRange = (current) => {
+	const starts = current.split(guidanceStart).length - 1;
+	const ends = current.split(guidanceEnd).length - 1;
+	if (starts === 0 && ends === 0) return;
+	const start = current.indexOf(guidanceStart);
+	const end = current.indexOf(guidanceEnd);
+	if (starts !== 1 || ends !== 1 || end < start) throw new Error("AgentMuxer guidance markers are invalid");
+	return {
+		start,
+		end
+	};
+};
+const withoutGuidance = (current) => {
+	const range = managedRange(current);
+	if (range === void 0) return {
+		next: current,
+		removed: false
+	};
+	let suffix = current.slice(range.end + 32);
+	if (range.start === 0) suffix = suffix.replace(/^\n(?:\n)?/, "");
+	return {
+		next: `${current.slice(0, range.start)}${suffix}`,
+		removed: true
+	};
+};
+const validateClientGuidance = async (client) => {
+	const { candidates } = await guidancePaths(client);
+	const values = await Promise.all(candidates.map(readOptionalFile));
+	for (const value of values) managedRange(value ?? "");
+};
+const installClientGuidance = async (client) => {
+	const { active, candidates } = await guidancePaths(client);
+	const current = new Map(await Promise.all(candidates.map(async (path) => [path, await readOptionalFile(path)])));
+	for (const value of current.values()) managedRange(value ?? "");
+	const value = current.get(active) ?? "";
+	const stripped = withoutGuidance(value).next;
+	const next = `${guidanceBlock}${stripped.length === 0 ? "\n" : `\n\n${stripped}`}`;
+	if (next !== value) {
+		await mkdir(dirname(active), { recursive: true });
+		await writeFile(active, next, "utf8");
+	}
+	return {
+		path: active,
+		rollback: async () => {
+			if (next === value || await readOptionalFile(active) !== next) return;
+			const previous = current.get(active);
+			if (previous === void 0) await rm(active, { force: true });
+			else await writeFile(active, previous, "utf8");
+		}
+	};
+};
+const clientGuidanceStatus = async (client) => {
+	const { active, candidates } = await guidancePaths(client);
+	const values = await Promise.all(candidates.map(readOptionalFile));
+	for (const value of values) managedRange(value ?? "");
+	return {
+		installed: (values[candidates.indexOf(active)] ?? "").includes(guidanceBlock),
+		path: active
+	};
+};
+const removeClientGuidance = async (client) => {
+	const { candidates } = await guidancePaths(client);
+	const current = new Map(await Promise.all(candidates.map(async (path) => [path, await readOptionalFile(path)])));
+	for (const value of current.values()) managedRange(value ?? "");
+	return (await Promise.all(candidates.map(async (path) => {
+		const value = current.get(path);
+		if (value === void 0) return false;
+		const result = withoutGuidance(value);
+		if (!result.removed) return false;
+		await writeFile(path, result.next, "utf8");
+		return true;
+	}))).some(Boolean);
+};
+const isSupportedClient = (value) => supportedClients.some((client) => client === value);
+const clientLabel = (client) => agents[client].displayName;
+const detectedClients = async () => {
+	configureClientPaths();
+	const detected = new Set(await detectGlobalAgents());
+	return supportedClients.filter((client) => detected.has(client));
+};
+const agentmuxerServer = async (client) => {
+	configureClientPaths();
+	const [installation] = await listInstalledServers({
+		global: true,
+		agents: [client]
+	});
+	if (installation === void 0) throw new Error(`Could not inspect ${clientLabel(client)} configuration`);
+	await validateConfigSyntax(client, installation.configPath);
+	return {
+		configPath: installation.configPath,
+		detected: installation.detected,
+		server: installation.servers.find(({ serverName }) => serverName === agentmuxerServerName)
+	};
+};
+const conflictError = (client) => `${clientLabel(client)} already has an ${agentmuxerServerName} configuration that setup cannot safely manage; leave it unchanged or remove it manually`;
+const isManagedServer = (client, server) => {
+	const transformed = agents[client].transformConfig(agentmuxerServerName, agentmuxerConfig);
+	if (typeof transformed !== "object" || transformed === null || Array.isArray(transformed)) return false;
+	const expected = Object.fromEntries(Object.entries(transformed).filter(([, value]) => value !== void 0));
+	return isDeepStrictEqual(server.config, expected) || client === "codex" && isDeepStrictEqual(server.config, { url: "https://mcp.agentmuxer.com/mcp" });
+};
+const isManagedServerAtPath = async (client, server, path) => isManagedServer(client, server) && (client !== "codex" || await readCodexLayout(path) !== void 0);
+const uninspectableConfigError = (client) => `${clientLabel(client)} configuration exists but the client was not detected; refusing to modify it`;
+const installAgentmuxer = async (client) => {
+	const existing = await agentmuxerServer(client);
+	if (!existing.detected && existsSync(existing.configPath)) return {
+		success: false,
+		path: existing.configPath,
+		error: uninspectableConfigError(client)
+	};
+	if (existing.server !== void 0 && !await isManagedServerAtPath(client, existing.server, existing.configPath)) return {
+		success: false,
+		path: existing.configPath,
+		error: conflictError(client)
+	};
+	if (existing.server !== void 0) return {
+		success: true,
+		path: existing.configPath
+	};
+	if (client === "codex") {
+		await installCodexServer(existing.configPath);
+		return {
+			success: true,
+			path: existing.configPath
+		};
+	}
+	const configExisted = existsSync(existing.configPath);
+	const result = upsertServer(client, agentmuxerServerName, agentmuxerConfig);
+	if (result.success && client === "claude-code" && !configExisted) try {
+		await chmod(result.path, 384);
+	} catch (error) {
+		await rm(result.path, { force: true });
+		throw error;
+	}
+	return result;
+};
+const listAgentmuxerInstallations = async (clients = supportedClients) => {
+	configureClientPaths();
+	const installations = await listInstalledServers({
+		global: true,
+		agents: [...clients]
+	});
+	await Promise.all(installations.flatMap(({ agentType, configPath }) => isSupportedClient(agentType) ? [validateConfigSyntax(agentType, configPath)] : []));
+	return (await Promise.all(installations.flatMap(({ agentType, displayName, servers }) => isSupportedClient(agentType) ? servers.filter(({ serverName }) => serverName === agentmuxerServerName).map(async (server) => await isManagedServerAtPath(agentType, server, server.configPath) ? {
+		client: agentType,
+		displayName,
+		configPath: server.configPath
+	} : void 0) : []))).flatMap((installation) => installation === void 0 ? [] : [installation]);
+};
+const removeAgentmuxer = async (client) => {
+	const existing = await agentmuxerServer(client);
+	if (!existing.detected && existsSync(existing.configPath)) return {
+		success: false,
+		path: existing.configPath,
+		removed: false,
+		error: uninspectableConfigError(client)
+	};
+	if (existing.server === void 0) return {
+		success: true,
+		path: existing.configPath,
+		removed: false
+	};
+	if (!await isManagedServerAtPath(client, existing.server, existing.configPath)) return {
+		success: false,
+		path: existing.configPath,
+		removed: false,
+		error: conflictError(client)
+	};
+	if (client === "codex") try {
+		const layout = await readCodexLayout(existing.configPath);
+		if (layout === void 0) return {
+			success: false,
+			path: existing.configPath,
+			removed: false
+		};
+		await writeFile(existing.configPath, layout, "utf8");
+		return {
+			success: true,
+			path: existing.configPath,
+			removed: true
+		};
+	} catch (error) {
+		return {
+			success: false,
+			path: existing.configPath,
+			removed: false,
+			error: error instanceof Error ? error.message : "removal failed"
+		};
+	}
+	return removeServer(client, agentmuxerServerName);
+};
+const authenticationCommands = {
+	codex: `codex mcp login ${agentmuxerServerName}`,
+	"claude-code": `claude mcp login ${agentmuxerServerName}`,
+	opencode: `opencode mcp auth ${agentmuxerServerName}`
+};
+const authenticationCommand = (client) => authenticationCommands[client];
+//#endregion
+//#region src/cli.ts
+const version = "0.1.0";
+const help = `AgentMuxer setup ${version}
+
+Usage:
+  agentmuxer-setup install             Install AgentMuxer globally
+  agentmuxer-setup status              Verify client configuration and guidance
+  agentmuxer-setup remove              Remove AgentMuxer-managed configuration
+
+Options:
+  --client <name>                      Target codex, claude-code, or opencode; repeatable
+  --help, -h                           Show help
+  --version, -v                        Show version
+`;
+const fail = (message) => {
+	throw new Error(message);
+};
+const clientSetupState = async (client) => {
+	const [installations, guidance] = await Promise.all([listAgentmuxerInstallations([client]), clientGuidanceStatus(client)]);
+	return {
+		guidance: guidance.installed,
+		mcp: installations.length > 0
+	};
+};
+const withClientSetupRollback = async (client, operation) => {
+	const actions = [];
+	try {
+		return await operation((action) => actions.unshift(action));
+	} catch (error) {
+		const failures = (await Promise.allSettled(actions.map((action) => action()))).flatMap((result) => result.status === "rejected" ? [String(result.reason)] : []);
+		if (failures.length > 0) throw new Error(`${clientLabel(client)} setup failed and could not be fully rolled back: ${failures.join("; ")}`, { cause: error });
+		throw error;
+	}
+};
+const parseClients = (args) => {
+	const { values, positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+		options: { client: {
+			type: "string",
+			multiple: true
+		} }
+	});
+	if (positionals.length > 0) fail(`Unexpected argument: ${positionals[0]}`);
+	if (values.client === void 0) return;
+	const invalid = values.client.find((client) => !isSupportedClient(client));
+	if (invalid !== void 0) fail(`Unsupported client: ${invalid}`);
+	return [...new Set(values.client.filter(isSupportedClient))];
+};
+const install = async (args) => {
+	const clients = parseClients(args) ?? await detectedClients();
+	if (clients.length === 0) fail(`No supported clients detected; use --client with: ${supportedClients.join(", ")}`);
+	await Promise.all(clients.map(validateClientGuidance));
+	const outcomes = await Promise.all(clients.map(async (client) => {
+		try {
+			return await withClientSetupRollback(client, async (defer) => {
+				const guidance = await installClientGuidance(client);
+				defer(guidance.rollback);
+				const result = await installAgentmuxer(client);
+				if (!result.success) throw new Error(result.error ?? "installation failed");
+				return {
+					lines: [
+						`${clientLabel(client)} MCP: ${result.path}`,
+						`${clientLabel(client)} guidance: ${guidance.path}`,
+						`${clientLabel(client)} sign-in: ${authenticationCommand(client)}`
+					],
+					failure: void 0
+				};
+			});
+		} catch (error) {
+			return {
+				lines: [],
+				failure: `${clientLabel(client)}: ${error instanceof Error ? error.message : "installation failed"}`
+			};
+		}
+	}));
+	for (const line of outcomes.flatMap((outcome) => outcome.lines ?? [])) process.stdout.write(`${line}\n`);
+	const failures = outcomes.flatMap((outcome) => outcome.failure ?? []);
+	if (failures.length > 0) fail(failures.join("\n"));
+	process.stdout.write("Restart open clients after setup. Discovery works before sign-in; paid calls require OAuth.\n");
+};
+const status = async (args) => {
+	const clients = parseClients(args) ?? await detectedClients();
+	if (clients.length === 0) fail(`No supported clients detected; use --client with: ${supportedClients.join(", ")}`);
+	const installations = await listAgentmuxerInstallations(clients);
+	const statuses = await Promise.all(clients.map(clientGuidanceStatus));
+	if (!clients.map((client, index) => {
+		const installation = installations.find((candidate) => candidate.client === client);
+		const guidance = statuses[index];
+		if (guidance === void 0) return false;
+		process.stdout.write(`${clientLabel(client)} MCP: ${installation?.configPath ?? "not installed"}\n`);
+		process.stdout.write(`${clientLabel(client)} guidance: ${guidance.installed ? guidance.path : "not installed"}\n`);
+		return installation !== void 0 && guidance.installed;
+	}).every(Boolean)) fail("AgentMuxer setup is incomplete or conflicting; run agentmuxer-setup install, or remove a custom same-name MCP manually");
+	process.stdout.write("AgentMuxer configuration and guidance verified.\n");
+};
+const remove = async (args) => {
+	const clients = parseClients(args) ?? supportedClients;
+	await Promise.all(clients.map(validateClientGuidance));
+	const outcomes = await Promise.all(clients.map(async (client) => {
+		try {
+			const before = await clientSetupState(client);
+			return await withClientSetupRollback(client, async (defer) => {
+				const result = await removeAgentmuxer(client);
+				if (!result.success) throw new Error(result.error ?? "removal failed");
+				if (result.removed && before.mcp) defer(async () => {
+					const rollback = await installAgentmuxer(client);
+					if (!rollback.success) throw new Error(rollback.error ?? "MCP rollback failed");
+				});
+				if (before.guidance) defer(async () => {
+					await installClientGuidance(client);
+				});
+				const guidanceRemoved = await removeClientGuidance(client);
+				return {
+					lines: [`${clientLabel(client)} MCP: ${result.removed ? "removed" : "not installed"}`, ...guidanceRemoved ? [`${clientLabel(client)} guidance: removed`] : []],
+					failure: void 0
+				};
+			});
+		} catch (error) {
+			return {
+				lines: [],
+				failure: `${clientLabel(client)}: ${error instanceof Error ? error.message : "removal failed"}`
+			};
+		}
+	}));
+	for (const line of outcomes.flatMap((outcome) => outcome.lines ?? [])) process.stdout.write(`${line}\n`);
+	const failures = outcomes.flatMap((outcome) => outcome.failure ?? []);
+	if (failures.length > 0) fail(failures.join("\n"));
+};
+const runCli = async (args) => {
+	const [command, ...rest] = args;
+	if (command === "--help" || command === "-h" || command === void 0) {
+		process.stdout.write(help);
+		return;
+	}
+	if (command === "--version" || command === "-v") {
+		process.stdout.write(`${version}\n`);
+		return;
+	}
+	if (command === "install") return install(rest);
+	if (command === "status") return status(rest);
+	if (command === "remove") return remove(rest);
+	fail(`Unknown command: ${command}\n\n${help}`);
+};
+//#endregion
+//#region src/bin.ts
+runCli(process.argv.slice(2)).catch((error) => {
+	process.stderr.write(`AgentMuxer setup: ${error instanceof Error ? error.message : "Unexpected error"}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@agentmuxer/setup",
+  "version": "0.1.0",
+  "description": "Install AgentMuxer's hosted MCP in supported coding agents",
+  "keywords": [
+    "agentmuxer",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "homepage": "https://agentmuxer.com",
+  "bugs": {
+    "url": "https://github.com/Amorphic-Labs/agentmuxer/issues"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Amorphic-Labs/agentmuxer.git",
+    "directory": "services/installer"
+  },
+  "bin": {
+    "agentmuxer-setup": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "add-mcp": "2.3.0",
+    "jsonc-parser": "3.3.1",
+    "toml-eslint-parser": "1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.2.9",
+    "vite-plus": "0.2.9"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "release:smoke": "node scripts/release-smoke.mjs",
+    "test": "vp test run"
+  }
+}