@alfe.ai/connectwise-automate-mcp 0.1.0

package/dist/server2.js

@@ -0,0 +1,557 @@
+import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+import { resolveConfig } from "@alfe.ai/config";
+import { z } from "zod";
+import dns from "node:dns/promises";
+import https from "node:https";
+import { BlockList, isIP } from "node:net";
+//#region src/boundary.ts
+const PROVIDER_ID = "connectwise-automate";
+const messages = {
+	invalid_connection: "Select an available Automate connection using automate_list_connections.",
+	invalid_credentials: "The Automate connection credentials are invalid. Reconnect it in Alfe.",
+	unsafe_server: "The Automate server must resolve only to public HTTPS addresses.",
+	timeout: "The Automate request timed out. Narrow the request and try again.",
+	authentication_failed: "Automate rejected the credentials. Check the integrator account and Alfe ClientID configuration.",
+	interactive_authentication: "Automate requires interactive authentication. Connect an integrator account suitable for unattended API access.",
+	permission_denied: "The Automate integrator account cannot access this resource.",
+	rate_limited: "Automate rate limited the request. Wait before retrying.",
+	not_found: "Automate did not find this resource or API route.",
+	invalid_response: "Automate returned an invalid response.",
+	response_too_large: "Automate returned too much data. Use a smaller page or a narrower condition.",
+	request_failed: "The Automate request could not be completed.",
+	invalid_arguments: "The Automate tool arguments are invalid."
+};
+var AutomateError = class extends Error {
+	constructor(code) {
+		super(messages[code]);
+		this.code = code;
+		this.name = "AutomateError";
+	}
+};
+function safeError(error) {
+	return error instanceof AutomateError ? {
+		code: error.code,
+		message: error.message
+	} : {
+		code: "request_failed",
+		message: messages.request_failed
+	};
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasControlCharacters(value) {
+	return Array.from(value).some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127);
+}
+function boundedSecret(value, max = 4096) {
+	if (typeof value !== "string" || !value.trim() || value.length > max || hasControlCharacters(value)) throw new AutomateError("invalid_credentials");
+	return value;
+}
+function validateConnectionId(value) {
+	if (typeof value !== "string" || !/^con_[A-Za-z0-9_-]{1,180}$/u.test(value)) throw new AutomateError("invalid_connection");
+	return value;
+}
+function serverOrigin(value) {
+	try {
+		if (typeof value !== "string" || value.length > 2048 || value !== value.trim()) throw new Error();
+		const url = new URL(value);
+		const host = url.hostname.toLowerCase().replace(/\.$/u, "");
+		if (url.protocol !== "https:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash || isIP(host.replace(/^\[|\]$/gu, "")) || !host.includes(".") || !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])$/u.test(host) || host.split(".").some((label) => !label || label.length > 63) || /(?:^|\.)(?:localhost|local|internal|metadata|test|invalid)$/u.test(host)) throw new Error();
+		url.hostname = host;
+		return url.origin;
+	} catch {
+		throw new AutomateError("unsafe_server");
+	}
+}
+function credentialsFrom(value, connectionId) {
+	if (!isRecord(value) || value.provider !== "connectwise-automate" || value.connectionId !== connectionId) throw new AutomateError("invalid_connection");
+	const clientId = boundedSecret(value.clientId, 256);
+	if (clientId.trim().toLowerCase() === "placeholder") throw new AutomateError("invalid_credentials");
+	return {
+		serverUrl: serverOrigin(value.serverUrl),
+		username: boundedSecret(value.username, 256),
+		password: boundedSecret(value.password),
+		clientId
+	};
+}
+const defaultResolver = (hostname) => dns.lookup(hostname, { all: true });
+const blocked4 = new BlockList();
+const blocked6 = new BlockList();
+for (const [network, prefix] of [
+	["0.0.0.0", 8],
+	["10.0.0.0", 8],
+	["100.64.0.0", 10],
+	["127.0.0.0", 8],
+	["169.254.0.0", 16],
+	["172.16.0.0", 12],
+	["192.0.0.0", 24],
+	["192.0.2.0", 24],
+	["192.168.0.0", 16],
+	["198.18.0.0", 15],
+	["198.51.100.0", 24],
+	["203.0.113.0", 24],
+	["224.0.0.0", 4],
+	["240.0.0.0", 4]
+]) blocked4.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+	["::", 96],
+	["::ffff:0:0", 96],
+	["64:ff9b::", 96],
+	["64:ff9b:1::", 48],
+	["100::", 64],
+	["2001::", 32],
+	["2001:db8::", 32],
+	["2002::", 16],
+	["fc00::", 7],
+	["fe80::", 10],
+	["ff00::", 8]
+]) blocked6.addSubnet(network, prefix, "ipv6");
+/** Each credentialed request resolves afresh; its socket uses this exact address. */
+async function resolvePublicAddress(url, resolve) {
+	let addresses;
+	try {
+		addresses = await resolve(url.hostname);
+	} catch {
+		throw new AutomateError("unsafe_server");
+	}
+	if (addresses.length === 0 || addresses.length > 64 || addresses.some(({ address, family }) => ![4, 6].includes(family) || isIP(address) !== family || (family === 4 ? blocked4.check(address, "ipv4") : blocked6.check(address, "ipv6")))) throw new AutomateError("unsafe_server");
+	return addresses[0];
+}
+/** TLS validates the original hostname while lookup pins the checked public IP. */
+const httpsTransport = ({ url, address, method, headers, body, signal }) => new Promise((resolve, reject) => {
+	const request = https.request(url, {
+		method,
+		headers,
+		agent: false,
+		family: address.family,
+		lookup: (_hostname, _options, callback) => {
+			callback(null, address.address, address.family);
+		},
+		signal
+	}, (response) => {
+		const status = response.statusCode ?? 0;
+		if (status < 200 || status >= 300) {
+			response.destroy();
+			resolve({
+				status,
+				body: ""
+			});
+			return;
+		}
+		const declared = response.headers["content-length"];
+		if (declared !== void 0 && (!/^\d+$/u.test(declared) || Number(declared) > 2097152)) {
+			response.destroy();
+			reject(new AutomateError("response_too_large"));
+			return;
+		}
+		const chunks = [];
+		let bytes = 0;
+		response.on("data", (chunk) => {
+			bytes += chunk.length;
+			if (bytes > 2097152) {
+				response.destroy();
+				reject(new AutomateError("response_too_large"));
+				return;
+			}
+			chunks.push(chunk);
+		});
+		response.on("error", () => {
+			reject(new AutomateError("request_failed"));
+		});
+		response.on("end", () => {
+			resolve({
+				status,
+				body: Buffer.concat(chunks).toString("utf8")
+			});
+		});
+	});
+	request.on("error", () => {
+		reject(new AutomateError(signal.aborted ? "timeout" : "request_failed"));
+	});
+	request.end(body);
+});
+async function withDeadline(operation, timeoutMs) {
+	const controller = new AbortController();
+	let timer;
+	const deadline = new Promise((_resolve, reject) => {
+		timer = setTimeout(() => {
+			controller.abort();
+			reject(new AutomateError("timeout"));
+		}, timeoutMs);
+	});
+	try {
+		return await Promise.race([operation(controller.signal), deadline]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** JSON payloads may echo credentials even on success. Never forward those fields. */
+function redactResult(value, secrets) {
+	let nodes = 0;
+	const redactText = (text) => secrets.reduce((result, secret) => secret.length > 0 ? result.split(secret).join("[redacted]") : result, text);
+	const visit = (item, depth) => {
+		if (++nodes > 3e4 || depth > 30) throw new AutomateError("response_too_large");
+		if (typeof item === "string") return redactText(item);
+		if (Array.isArray(item)) return item.map((child) => visit(child, depth + 1));
+		if (isRecord(item)) return Object.fromEntries(Object.entries(item).filter(([key]) => !/password|secret|token|authorization|cookie|^__proto__$|^constructor$|^prototype$/iu.test(key)).map(([key, child]) => [redactText(key), visit(child, depth + 1)]));
+		if (item === null || typeof item === "boolean" || typeof item === "number" && Number.isFinite(item)) return item;
+		throw new AutomateError("invalid_response");
+	};
+	const result = visit(value, 0);
+	if (Buffer.byteLength(JSON.stringify(result)) > 524288) throw new AutomateError("response_too_large");
+	return result;
+}
+//#endregion
+//#region src/client.ts
+const LIST_RESOURCES = [
+	"clients",
+	"locations",
+	"computers",
+	"scripts",
+	"monitor_history",
+	"internal_monitor_results"
+];
+const listPaths = {
+	clients: "Clients",
+	locations: "Locations",
+	computers: "Computers",
+	scripts: "Scripts",
+	monitor_history: "MonitorHistory",
+	internal_monitor_results: "InternalMonitorResults"
+};
+function parseExpiry(value) {
+	if (typeof value !== "string" || value.length > 64) throw new AutomateError("invalid_response");
+	if (!/^\d{4}-\d{2}-\d{2}T[\d:.]+(?:Z|[+-]\d{2}:\d{2})$/u.test(value)) throw new AutomateError("invalid_response");
+	const parsed = Date.parse(value);
+	if (!Number.isFinite(parsed)) throw new AutomateError("invalid_response");
+	return parsed;
+}
+function buildListQuery(options) {
+	const page = options.page ?? 1;
+	const pageSize = options.pageSize ?? 50;
+	if (!Number.isInteger(page) || page < 1 || page > 1e5 || !Number.isInteger(pageSize) || pageSize < 1 || pageSize > 200) throw new AutomateError("invalid_arguments");
+	const query = new URLSearchParams({
+		"options.page": String(page),
+		"options.pageSize": String(pageSize)
+	});
+	if (options.condition !== void 0) {
+		if (typeof options.condition !== "string" || !options.condition.trim() || options.condition.length > 2e3 || hasControlCharacters(options.condition)) throw new AutomateError("invalid_arguments");
+		query.set("options.condition", options.condition);
+	}
+	return query;
+}
+var AutomateClient = class {
+	credentials;
+	resolve;
+	transport;
+	now;
+	timeoutMs;
+	token;
+	tokenRequest;
+	constructor(credentials, options = {}) {
+		this.credentials = {
+			serverUrl: serverOrigin(credentials.serverUrl),
+			username: boundedSecret(credentials.username, 256),
+			password: boundedSecret(credentials.password),
+			clientId: boundedSecret(credentials.clientId, 256)
+		};
+		if (this.credentials.clientId.toLowerCase() === "placeholder") throw new AutomateError("invalid_credentials");
+		this.resolve = options.resolve ?? defaultResolver;
+		this.transport = options.transport ?? httpsTransport;
+		this.now = options.now ?? Date.now;
+		this.timeoutMs = options.timeoutMs ?? 3e4;
+		if (!Number.isInteger(this.timeoutMs) || this.timeoutMs < 1 || this.timeoutMs > 6e4) throw new AutomateError("invalid_arguments");
+	}
+	async list(resource, options = {}) {
+		if (!LIST_RESOURCES.includes(resource)) throw new AutomateError("invalid_arguments");
+		return this.readList(listPaths[resource], options);
+	}
+	async listComputer(resource, computerId, options = {}) {
+		if (!Number.isInteger(computerId) || computerId < 1 || computerId > 2147483647 || !["monitors", "script_history"].includes(resource)) throw new AutomateError("invalid_arguments");
+		const suffix = resource === "monitors" ? "Monitors" : "ScriptHistory";
+		return this.readList(`Computers/${String(computerId)}/${suffix}`, options);
+	}
+	async checkConnection() {
+		await this.list("clients", {
+			page: 1,
+			pageSize: 1
+		});
+		return { connected: true };
+	}
+	async readList(path, options) {
+		const query = buildListQuery(options);
+		let token = await this.getToken();
+		let data;
+		try {
+			data = await this.request("GET", path, token.accessToken, void 0, query);
+		} catch (error) {
+			if (!(error instanceof AutomateError) || error.code !== "authentication_failed") throw error;
+			token = await this.getToken(token.accessToken);
+			data = await this.request("GET", path, token.accessToken, void 0, query);
+		}
+		if (!Array.isArray(data)) throw new AutomateError("invalid_response");
+		const { password, username, clientId } = this.credentials;
+		return redactResult({
+			items: data,
+			page: options.page ?? 1,
+			pageSize: options.pageSize ?? 50
+		}, [
+			password,
+			username,
+			clientId,
+			token.accessToken
+		]);
+	}
+	getToken(rejectedToken) {
+		if (rejectedToken && this.token?.accessToken === rejectedToken) this.token = void 0;
+		if (this.token && this.token.expiresAt > this.now() + 6e4 && this.token.absoluteExpiresAt > this.now() + 6e4) return Promise.resolve(this.token);
+		if (this.tokenRequest) return this.tokenRequest;
+		const previous = this.token;
+		this.tokenRequest = this.acquireToken(previous).then((token) => {
+			this.token = token;
+			return token;
+		}).finally(() => {
+			this.tokenRequest = void 0;
+		});
+		return this.tokenRequest;
+	}
+	async acquireToken(previous) {
+		let value;
+		if (previous && previous.expiresAt > this.now() && previous.absoluteExpiresAt > this.now() + 6e4) try {
+			value = await this.request("POST", "APIToken/Refresh", previous.accessToken, JSON.stringify(previous.accessToken));
+		} catch (error) {
+			if (!(error instanceof AutomateError) || error.code !== "authentication_failed") throw error;
+			value = await this.mintToken();
+		}
+		else value = await this.mintToken();
+		if (!isRecord(value)) throw new AutomateError("invalid_response");
+		if (value.IsTwoFactorRequired === true || value.IsInternalTwoFactorRequired === true) throw new AutomateError("interactive_authentication");
+		if (typeof value.AccessToken !== "string" || !value.AccessToken || value.AccessToken.length > 16384 || /\s/u.test(value.AccessToken)) throw new AutomateError("invalid_response");
+		if (value.TokenType !== void 0 && value.TokenType !== "Bearer" && value.TokenType !== "bearer") throw new AutomateError("invalid_response");
+		const expiresAt = parseExpiry(value.ExpirationDate);
+		const absoluteExpiresAt = value.AbsoluteExpirationDate === void 0 ? expiresAt : parseExpiry(value.AbsoluteExpirationDate);
+		if (expiresAt <= this.now() || absoluteExpiresAt <= this.now()) throw new AutomateError("authentication_failed");
+		return {
+			accessToken: value.AccessToken,
+			expiresAt,
+			absoluteExpiresAt
+		};
+	}
+	mintToken() {
+		return this.request("POST", "APIToken", void 0, JSON.stringify({
+			Username: this.credentials.username,
+			Password: this.credentials.password
+		}));
+	}
+	request(method, path, token, body, query) {
+		return withDeadline(async (signal) => {
+			const url = new URL(`/cwa/api/v1/${path}`, this.credentials.serverUrl);
+			if (query) url.search = query.toString();
+			const address = await resolvePublicAddress(url, this.resolve);
+			if (signal.aborted) throw new AutomateError("timeout");
+			let response;
+			try {
+				response = await this.transport({
+					url,
+					address,
+					method,
+					signal,
+					body,
+					headers: {
+						Accept: "application/json",
+						clientId: this.credentials.clientId,
+						...body !== void 0 ? { "Content-Type": "application/json" } : {},
+						...token ? { Authorization: `Bearer ${token}` } : {}
+					}
+				});
+			} catch (error) {
+				throw error instanceof AutomateError ? error : new AutomateError("request_failed");
+			}
+			if (response.status === 401) throw new AutomateError("authentication_failed");
+			if (response.status === 403) throw new AutomateError("permission_denied");
+			if (response.status === 404) throw new AutomateError("not_found");
+			if (response.status === 429) throw new AutomateError("rate_limited");
+			if (response.status < 200 || response.status >= 300) throw new AutomateError("request_failed");
+			if (Buffer.byteLength(response.body) > 2097152) throw new AutomateError("response_too_large");
+			try {
+				return JSON.parse(response.body);
+			} catch {
+				throw new AutomateError("invalid_response");
+			}
+		}, this.timeoutMs);
+	}
+};
+//#endregion
+//#region src/server.ts
+const metadata = createRequire(import.meta.url)("../package.json");
+const SERVER_NAME = "connectwise-automate-mcp";
+const SERVER_VERSION = metadata.version;
+var AutomateRuntime = class {
+	clients = /* @__PURE__ */ new Map();
+	constructor(source, options = {}) {
+		this.source = source;
+		this.options = options;
+	}
+	async listConnections() {
+		const result = await withDeadline(() => this.source.getConnectProviderAccounts(PROVIDER_ID), 3e4);
+		if (!isRecord(result) || result.provider !== "connectwise-automate" || !Array.isArray(result.accounts) || result.accounts.length > 100) throw new AutomateError("invalid_response");
+		const seen = /* @__PURE__ */ new Set();
+		return { connections: result.accounts.map((row) => {
+			if (!isRecord(row)) throw new AutomateError("invalid_response");
+			const connectionId = validateConnectionId(row.connectionId);
+			if (seen.has(connectionId)) throw new AutomateError("invalid_response");
+			seen.add(connectionId);
+			const serverUrl = serverOrigin(row.serverUrl);
+			const displayName = typeof row.displayName === "string" && row.displayName.length <= 256 ? Array.from(row.displayName, (character) => hasControlCharacters(character) ? " " : character).join("") : null;
+			const secrets = [
+				row.username,
+				row.password,
+				row.clientId,
+				row.accessToken
+			].filter((value) => typeof value === "string");
+			return redactResult({
+				connectionId,
+				serverUrl,
+				displayName
+			}, secrets);
+		}) };
+	}
+	async getClient(selector) {
+		const connectionId = validateConnectionId(selector);
+		try {
+			const credentials = credentialsFrom(await withDeadline(() => this.source.getConnectionCredentials(connectionId), 3e4), connectionId);
+			const fingerprint = createHash("sha256").update(JSON.stringify(credentials)).digest("hex");
+			const cached = this.clients.get(connectionId);
+			if (cached?.fingerprint === fingerprint) return cached.client;
+			if (this.clients.size >= 100 && !cached) {
+				const first = this.clients.keys().next();
+				if (!first.done) this.clients.delete(first.value);
+			}
+			const client = new AutomateClient(credentials, this.options);
+			this.clients.set(connectionId, {
+				fingerprint,
+				client
+			});
+			return client;
+		} catch (error) {
+			this.clients.delete(connectionId);
+			throw error;
+		}
+	}
+	clear() {
+		this.clients.clear();
+	}
+};
+const connectionField = z.string().regex(/^con_[A-Za-z0-9_-]{1,180}$/u).describe("Exact connectionId from automate_list_connections; select the intended Automate server explicitly.");
+const listFields = {
+	connectionId: connectionField,
+	page: z.coerce.number().int().min(1).max(1e5).optional().describe("1-based page number."),
+	pageSize: z.coerce.number().int().min(1).max(200).optional().describe("Records per page, defaults to 50."),
+	condition: z.string().trim().min(1).max(2e3).refine((value) => !hasControlCharacters(value)).optional().describe("Automate API condition expression using documented field names, for example Id = 42.")
+};
+const annotations = {
+	readOnlyHint: true,
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: true
+};
+async function execute(tool, operation, emit) {
+	try {
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(await operation())
+		}] };
+	} catch (error) {
+		const safe = safeError(error);
+		try {
+			emit(`[ERROR] alfe-tool plugin=connectwise-automate-mcp tool=${tool} result-error: ${safe.code}`);
+		} catch {}
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify({
+					error: safe.code,
+					message: safe.message
+				})
+			}],
+			isError: true
+		};
+	}
+}
+function createServer(source, options = {}) {
+	const server = new McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	});
+	const runtime = new AutomateRuntime(source, options);
+	const emit = options.emit ?? ((line) => {
+		process.stderr.write(`${line}\n`);
+	});
+	server.registerTool("automate_list_connections", {
+		description: "List the Automate servers available to this agent. Use the exact connectionId on every other tool.",
+		inputSchema: {},
+		annotations
+	}, () => execute("automate_list_connections", () => runtime.listConnections(), emit));
+	server.registerTool("automate_check_connection", {
+		description: "Check the selected Automate connection by authenticating and reading one client. Returns no token or customer data.",
+		inputSchema: { connectionId: connectionField },
+		annotations
+	}, ({ connectionId }) => execute("automate_check_connection", async () => (await runtime.getClient(connectionId)).checkConnection(), emit));
+	const descriptions = {
+		clients: "List client companies visible to this Automate account.",
+		locations: "List Automate locations; narrow using an Automate condition expression.",
+		computers: "List Automate endpoint inventory and current status; narrow or paginate large fleets.",
+		scripts: "List available Automate script metadata. This does not execute a script.",
+		monitor_history: "Read Automate monitor history, using conditions and pages to narrow the time window.",
+		internal_monitor_results: "Read Automate internal monitor results for diagnosing fleet issues."
+	};
+	for (const resource of LIST_RESOURCES) {
+		const name = `automate_list_${resource}`;
+		server.registerTool(name, {
+			description: descriptions[resource],
+			inputSchema: listFields,
+			annotations
+		}, ({ connectionId, ...args }) => execute(name, async () => (await runtime.getClient(connectionId)).list(resource, args), emit));
+	}
+	for (const resource of ["monitors", "script_history"]) {
+		const name = `automate_list_computer_${resource}`;
+		server.registerTool(name, {
+			description: resource === "monitors" ? "Read the monitors attached to one Automate computer." : "Read script execution history for one Automate computer. Does not run scripts.",
+			inputSchema: {
+				...listFields,
+				computerId: z.coerce.number().int().positive().max(2147483647)
+			},
+			annotations
+		}, ({ connectionId, computerId, ...args }) => execute(name, async () => (await runtime.getClient(connectionId)).listComputer(resource, computerId, args), emit));
+	}
+	return {
+		server,
+		runtime
+	};
+}
+async function startServer(source, transport = new StdioServerTransport()) {
+	const { server, runtime } = createServer(source ?? new AgentApiClient(resolveConfig()));
+	let closing;
+	const close = () => {
+		closing ??= withDeadline(() => server.close(), 5e3).finally(() => {
+			runtime.clear();
+		});
+		return closing;
+	};
+	try {
+		await server.connect(transport);
+	} catch (error) {
+		await close().catch(() => void 0);
+		throw error;
+	}
+	return {
+		server,
+		close
+	};
+}
+//#endregion
+export { startServer as a, createServer as i, SERVER_NAME as n, AutomateClient as o, SERVER_VERSION as r, safeError as s, AutomateRuntime as t };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@alfe.ai/connectwise-automate-mcp",
+  "version": "0.1.0",
+  "description": "ConnectWise Automate inventory and monitoring MCP server with Alfe connections",
+  "type": "module",
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "bin": {
+    "connectwise-automate-mcp": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "require": "./dist/server.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.5",
+    "@alfe.ai/agent-api-client": "0.19.0",
+    "@alfe.ai/config": "0.4.1"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://alfe.ai",
+  "author": "Alfe (https://alfe.ai)",
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}