@alfe.ai/connectwise-psa-mcp 0.1.0

package/dist/server2.cjs

@@ -0,0 +1,524 @@
+let node_module = require("node:module");
+let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
+let _modelcontextprotocol_sdk_server_stdio_js = require("@modelcontextprotocol/sdk/server/stdio.js");
+let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
+let _alfe_ai_config = require("@alfe.ai/config");
+let zod = require("zod");
+let node_dns_promises = require("node:dns/promises");
+let node_https = require("node:https");
+let node_net = require("node:net");
+//#region src/boundary.ts
+/** Only errors constructed by this package may cross the MCP boundary. */
+var PsaError = class extends Error {
+	name = "PsaError";
+};
+function safeErrorMessage(error) {
+	return error instanceof PsaError ? error.message : "ConnectWise PSA request failed. Check the selected connection and retry a read before repeating any write.";
+}
+function boundedString(value, max, field) {
+	if (typeof value !== "string" || value.length === 0 || value.length > max || Array.from(value).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)) throw new PsaError(`Invalid ${field}.`);
+	return value;
+}
+function record(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new PsaError("ConnectWise PSA returned an invalid response.");
+	return value;
+}
+async function withDeadline(operation, milliseconds = 2e4) {
+	let timer;
+	try {
+		return await Promise.race([operation, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				reject(new PsaError("ConnectWise PSA request timed out. Check whether a write succeeded before repeating it."));
+			}, milliseconds);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+const MAX_TIMEOUT_MS = 2e4;
+const blocked = new node_net.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]
+]) blocked.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+	["::", 96],
+	["64:ff9b::", 96],
+	["64:ff9b:1::", 48],
+	["100::", 64],
+	["2001::", 32],
+	["2001:db8::", 32],
+	["2002::", 16],
+	["fc00::", 7],
+	["fe80::", 10],
+	["ff00::", 8]
+]) blocked.addSubnet(network, prefix, "ipv6");
+function normalizeSiteUrl(value) {
+	const raw = boundedString(value, 2048, "PSA site URL");
+	let url;
+	try {
+		url = new URL(raw);
+	} catch {
+		throw new PsaError("Invalid PSA site URL.");
+	}
+	const host = url.hostname.toLowerCase().replace(/\.$/u, "");
+	if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash || url.pathname !== "/" || (0, node_net.isIP)(host.replace(/^\[|\]$/gu, "")) !== 0 || !host.includes(".") || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal") || host === "metadata.google.internal") throw new PsaError("PSA requires a public HTTPS origin without a path, userinfo, query, or fragment.");
+	url.hostname = host;
+	return url;
+}
+function isPublicAddress(value) {
+	const family = (0, node_net.isIP)(value.address);
+	return family !== 0 && family === value.family && !blocked.check(value.address, family === 4 ? "ipv4" : "ipv6");
+}
+/** Re-resolve on every call and pin the socket to an address from that answer. */
+async function resolvePublicAddress(url, resolve = (host) => (0, node_dns_promises.lookup)(host, { all: true })) {
+	let addresses;
+	try {
+		addresses = await withDeadline(resolve(url.hostname), 5e3);
+	} catch {
+		throw new PsaError("Unable to resolve a public PSA server address.");
+	}
+	if (addresses.length === 0 || addresses.length > 64 || addresses.some((address) => !isPublicAddress(address))) throw new PsaError("The PSA server must resolve only to public IP addresses.");
+	return addresses[0];
+}
+/** Node HTTPS never follows redirects. TLS is verified against the original hostname. */
+const sendRequest = (input) => new Promise((resolve, reject) => {
+	const req = (0, node_https.request)(input.url, {
+		method: input.method,
+		headers: input.headers,
+		agent: false,
+		family: input.address.family,
+		lookup: (_hostname, options, callback) => {
+			if (options.all) callback(null, [input.address]);
+			else callback(null, input.address.address, input.address.family);
+		}
+	}, (response) => {
+		const status = response.statusCode ?? 0;
+		if (status < 200 || status >= 300) {
+			response.destroy();
+			reject(new PsaError(`ConnectWise PSA returned HTTP ${String(status)}. ${status === 401 || status === 403 ? "Verify the API member keys, security role, company ID, and Alfe ClientID." : status === 429 ? "The PSA rate limit was reached; retry later." : status >= 300 && status < 400 ? "Redirects are refused; use the final PSA API origin." : "Check the record, service board, and required fields."}`));
+			return;
+		}
+		if (Number(response.headers["content-length"] ?? 0) > 2097152) {
+			response.destroy();
+			reject(new PsaError("PSA response is too large; narrow the query or reduce pageSize."));
+			return;
+		}
+		const chunks = [];
+		let bytes = 0;
+		response.on("data", (chunk) => {
+			bytes += chunk.length;
+			if (bytes > 2097152) response.destroy(new PsaError("PSA response is too large; narrow the query or reduce pageSize."));
+			else chunks.push(chunk);
+		});
+		response.once("error", () => {
+			reject(new PsaError("Unable to read the PSA response. Check whether a write succeeded before repeating it."));
+		});
+		response.once("end", () => {
+			try {
+				const text = Buffer.concat(chunks).toString("utf8");
+				resolve(text.length === 0 && status === 204 ? null : JSON.parse(text));
+			} catch {
+				reject(new PsaError("ConnectWise PSA returned invalid JSON."));
+			}
+		});
+	});
+	const timer = setTimeout(() => {
+		req.destroy(new PsaError("PSA request timed out. Check whether a write succeeded before repeating it."));
+	}, MAX_TIMEOUT_MS);
+	req.once("close", () => {
+		clearTimeout(timer);
+	});
+	req.once("error", () => {
+		reject(new PsaError("Unable to reach ConnectWise PSA. Check whether a write succeeded before repeating it."));
+	});
+	req.end(input.body);
+});
+//#endregion
+//#region src/client.ts
+const PROVIDER_ID = "connectwise-psa";
+const API_PATH = "/v4_6_release/apis/3.0";
+const connectionIdSchema = zod.z.string().min(1).max(256).regex(/^con_[A-Za-z0-9_-]+$/u);
+const idSchema = zod.z.coerce.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const listSchema = zod.z.object({
+	page: zod.z.coerce.number().int().min(1).max(1e5).default(1),
+	pageSize: zod.z.coerce.number().int().min(1).max(100).default(25),
+	conditions: zod.z.string().trim().min(1).max(2048).optional(),
+	orderBy: zod.z.string().trim().min(1).max(256).optional()
+}).strict();
+const createTicketSchema = zod.z.object({
+	summary: zod.z.string().trim().min(1).max(100),
+	companyId: idSchema,
+	boardId: idSchema,
+	contactId: idSchema.optional(),
+	statusId: idSchema.optional(),
+	priorityId: idSchema.optional(),
+	initialDescription: zod.z.string().min(1).max(6e4).optional()
+}).strict();
+const updateTicketSchema = zod.z.object({
+	summary: zod.z.string().trim().min(1).max(100).optional(),
+	statusId: idSchema.optional(),
+	priorityId: idSchema.optional(),
+	ownerId: idSchema.optional(),
+	contactId: idSchema.optional()
+}).strict().refine((value) => Object.values(value).some((field) => field !== void 0), "At least one ticket field is required.");
+const noteSchema = zod.z.object({
+	text: zod.z.string().min(1).max(6e4),
+	visibility: zod.z.enum([
+		"internal",
+		"discussion",
+		"resolution"
+	]).default("internal")
+}).strict();
+const LIST_PATHS = {
+	companies: "/company/companies",
+	contacts: "/company/contacts",
+	boards: "/service/boards",
+	priorities: "/service/priorities",
+	members: "/system/members",
+	tickets: "/service/tickets"
+};
+function parseCredentials(input) {
+	const value = record(input);
+	if (value.provider !== "connectwise-psa") throw new PsaError("The selected connection is not ConnectWise PSA.");
+	const companyId = boundedString(value.companyId, 256, "PSA company ID");
+	const publicKey = boundedString(value.publicKey, 1024, "PSA public key");
+	const privateKey = boundedString(value.privateKey, 4096, "PSA private key");
+	const clientId = boundedString(value.clientId, 256, "Alfe PSA ClientID");
+	if (/[+:]/u.test(companyId) || publicKey.includes(":") || clientId.trim().toLowerCase() === "placeholder") throw new PsaError("ConnectWise PSA credentials or the Alfe ClientID are invalid.");
+	return {
+		provider: PROVIDER_ID,
+		connectionId: connectionIdSchema.parse(value.connectionId),
+		siteUrl: normalizeSiteUrl(value.siteUrl).origin,
+		companyId,
+		publicKey,
+		privateKey,
+		clientId
+	};
+}
+/** Direct, finite REST operations; no arbitrary URL tool and no mutation retries. */
+var PsaClient = class {
+	credentials;
+	options;
+	constructor(credentials, options = {}) {
+		this.credentials = parseCredentials(credentials);
+		this.options = options;
+	}
+	async list(resource, input = {}) {
+		if (!Object.hasOwn(LIST_PATHS, resource)) throw new PsaError("Unknown PSA list resource.");
+		const path = LIST_PATHS[resource];
+		return this.listPath(path, input);
+	}
+	async get(resource, id) {
+		if (![
+			"companies",
+			"contacts",
+			"tickets"
+		].includes(resource)) throw new PsaError("Unknown PSA record resource.");
+		return record(await this.call(`${LIST_PATHS[resource]}/${String(idSchema.parse(id))}`));
+	}
+	async listBoardStatuses(boardId, input = {}) {
+		return this.listPath(`/service/boards/${String(idSchema.parse(boardId))}/statuses`, input);
+	}
+	async listTicketNotes(ticketId, input = {}) {
+		return this.listPath(`/service/tickets/${String(idSchema.parse(ticketId))}/notes`, input);
+	}
+	async createTicket(input) {
+		const data = createTicketSchema.parse(input);
+		return record(await this.call("/service/tickets", "POST", {
+			summary: data.summary,
+			company: { id: data.companyId },
+			board: { id: data.boardId },
+			...data.contactId === void 0 ? {} : { contact: { id: data.contactId } },
+			...data.statusId === void 0 ? {} : { status: { id: data.statusId } },
+			...data.priorityId === void 0 ? {} : { priority: { id: data.priorityId } },
+			...data.initialDescription === void 0 ? {} : { initialDescription: data.initialDescription }
+		}));
+	}
+	async updateTicket(ticketId, input) {
+		const data = updateTicketSchema.parse(input);
+		const operations = [];
+		if (data.summary !== void 0) operations.push({
+			op: "replace",
+			path: "summary",
+			value: data.summary
+		});
+		for (const [key, path] of [
+			["statusId", "status"],
+			["priorityId", "priority"],
+			["ownerId", "owner"],
+			["contactId", "contact"]
+		]) if (data[key] !== void 0) operations.push({
+			op: "replace",
+			path,
+			value: { id: data[key] }
+		});
+		return record(await this.call(`/service/tickets/${String(idSchema.parse(ticketId))}`, "PATCH", operations));
+	}
+	async addTicketNote(ticketId, input) {
+		const data = noteSchema.parse(input);
+		return record(await this.call(`/service/tickets/${String(idSchema.parse(ticketId))}/notes`, "POST", {
+			text: data.text,
+			internalAnalysisFlag: data.visibility === "internal",
+			detailDescriptionFlag: data.visibility === "discussion",
+			resolutionFlag: data.visibility === "resolution"
+		}));
+	}
+	async listPath(path, input) {
+		const query = listSchema.parse(input);
+		const result = await this.call(path, "GET", void 0, query);
+		if (!Array.isArray(result) || result.length > query.pageSize) throw new PsaError("PSA returned an invalid or oversized page.");
+		for (const item of result) record(item);
+		return result;
+	}
+	async call(path, method = "GET", data, query) {
+		const url = new URL(`${API_PATH}${path}`, this.credentials.siteUrl);
+		if (query) {
+			for (const [key, value] of Object.entries(query)) if (typeof value === "string" || typeof value === "number") url.searchParams.set(key, String(value));
+		}
+		const body = data === void 0 ? void 0 : JSON.stringify(data);
+		if (body && Buffer.byteLength(body) > 131072) throw new PsaError("PSA request is too large.");
+		const address = await resolvePublicAddress(url, this.options.resolve);
+		const { companyId, publicKey, privateKey, clientId } = this.credentials;
+		const authorization = `Basic ${Buffer.from(`${companyId}+${publicKey}:${privateKey}`).toString("base64")}`;
+		const result = await withDeadline((this.options.send ?? sendRequest)({
+			url,
+			address,
+			method,
+			body,
+			headers: {
+				Authorization: authorization,
+				clientId,
+				Accept: "application/json",
+				"Content-Type": "application/json"
+			}
+		}));
+		let text = JSON.stringify(result);
+		if (Buffer.byteLength(text) > 2097152) throw new PsaError("PSA response is too large.");
+		for (const secret of [
+			authorization,
+			authorization.slice(6),
+			publicKey,
+			privateKey,
+			clientId
+		]) text = text.split(JSON.stringify(secret).slice(1, -1)).join("[redacted]");
+		return JSON.parse(text);
+	}
+};
+//#endregion
+//#region src/tools.ts
+const LIST_CONNECTIONS_TOOL = "connectwise_psa_list_connections";
+const connectionIdField = connectionIdSchema.describe("Exact connectionId from connectwise_psa_list_connections. Required even when only one account is connected.");
+const readAnnotations = {
+	readOnlyHint: true,
+	destructiveHint: false,
+	idempotentHint: true,
+	openWorldHint: true
+};
+const writeAnnotations = {
+	readOnlyHint: false,
+	destructiveHint: false,
+	idempotentHint: false,
+	openWorldHint: true
+};
+async function guarded(operation) {
+	try {
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(await operation())
+		}] };
+	} catch (error) {
+		return {
+			isError: true,
+			content: [{
+				type: "text",
+				text: safeErrorMessage(error)
+			}]
+		};
+	}
+}
+function registerTools(server, connect, options = {}) {
+	const resolve = async (connectionId) => {
+		connectionIdSchema.parse(connectionId);
+		const credentials = record(await withDeadline(connect.getConnectionCredentials(connectionId)));
+		if (credentials.connectionId !== connectionId || credentials.provider !== "connectwise-psa") throw new PsaError("The selected connection is not an accessible ConnectWise PSA connection.");
+		return new PsaClient(credentials, options);
+	};
+	server.registerTool(LIST_CONNECTIONS_TOOL, {
+		description: "List accessible ConnectWise PSA connections. Choose the exact connectionId for every subsequent tool call.",
+		inputSchema: {},
+		annotations: readAnnotations
+	}, () => guarded(async () => {
+		const result = record(await withDeadline(connect.getConnectProviderAccounts(PROVIDER_ID)));
+		if (result.provider !== "connectwise-psa" || !Array.isArray(result.accounts) || result.accounts.length > 200) throw new PsaError("Connect returned an invalid PSA connection list.");
+		const seen = /* @__PURE__ */ new Set();
+		return { connections: result.accounts.map((raw) => {
+			const account = record(raw);
+			const connectionId = connectionIdSchema.parse(account.connectionId);
+			if (seen.has(connectionId)) throw new PsaError("Connect returned duplicate PSA connections.");
+			seen.add(connectionId);
+			return {
+				connectionId,
+				accountIdentifier: boundedString(account.accountIdentifier, 2048, "PSA account identifier"),
+				displayName: typeof account.displayName === "string" ? boundedString(account.displayName, 512, "PSA display name") : null
+			};
+		}) };
+	}));
+	for (const resource of [
+		"companies",
+		"contacts",
+		"boards",
+		"priorities",
+		"members",
+		"tickets"
+	]) server.registerTool(`connectwise_psa_list_${resource}`, {
+		description: `List one page of PSA ${resource}. Optional conditions use PSA query syntax; page starts at 1. Continue with page + 1 when a full page is returned.`,
+		inputSchema: {
+			connectionId: connectionIdField,
+			...listSchema.shape
+		},
+		annotations: readAnnotations
+	}, ({ connectionId, ...query }) => guarded(async () => (await resolve(connectionId)).list(resource, query)));
+	for (const [resource, singular] of [
+		["companies", "company"],
+		["contacts", "contact"],
+		["tickets", "ticket"]
+	]) server.registerTool(`connectwise_psa_get_${singular}`, {
+		description: `Read a PSA ${singular} by its numeric ID.`,
+		inputSchema: {
+			connectionId: connectionIdField,
+			id: idSchema
+		},
+		annotations: readAnnotations
+	}, ({ connectionId, id }) => guarded(async () => (await resolve(connectionId)).get(resource, id)));
+	server.registerTool("connectwise_psa_list_board_statuses", {
+		description: "List statuses for a specific service board before creating or changing a ticket status.",
+		inputSchema: {
+			connectionId: connectionIdField,
+			boardId: idSchema,
+			...listSchema.shape
+		},
+		annotations: readAnnotations
+	}, ({ connectionId, boardId, ...query }) => guarded(async () => (await resolve(connectionId)).listBoardStatuses(boardId, query)));
+	server.registerTool("connectwise_psa_list_ticket_notes", {
+		description: "List direct notes on a service ticket. This endpoint excludes separate time-entry and child-ticket notes.",
+		inputSchema: {
+			connectionId: connectionIdField,
+			ticketId: idSchema,
+			...listSchema.shape
+		},
+		annotations: readAnnotations
+	}, ({ connectionId, ticketId, ...query }) => guarded(async () => (await resolve(connectionId)).listTicketNotes(ticketId, query)));
+	server.registerTool("connectwise_psa_create_ticket", {
+		description: "Create a service ticket for the chosen PSA company and board. Get company/board/status IDs from list tools. A timeout can occur after creation: search for the ticket before repeating.",
+		inputSchema: {
+			connectionId: connectionIdField,
+			...createTicketSchema.shape
+		},
+		annotations: writeAnnotations
+	}, ({ connectionId, ...input }) => guarded(async () => (await resolve(connectionId)).createTicket(input)));
+	server.registerTool("connectwise_psa_update_ticket", {
+		description: "Update supplied fields of a service ticket using PSA JSON Patch. Get valid status IDs from its board. A status change may close/reopen the ticket; only apply the requested status.",
+		inputSchema: {
+			connectionId: connectionIdField,
+			ticketId: idSchema,
+			...updateTicketSchema.shape
+		},
+		annotations: {
+			...writeAnnotations,
+			idempotentHint: true,
+			destructiveHint: true
+		}
+	}, ({ connectionId, ticketId, ...input }) => guarded(async () => (await resolve(connectionId)).updateTicket(ticketId, input)));
+	server.registerTool("connectwise_psa_add_ticket_note", {
+		description: "Append a note to a service ticket. Internal is the default. Discussion/resolution notes may be visible to customers; choose that visibility only when requested. Check notes before retrying an ambiguous failure.",
+		inputSchema: {
+			connectionId: connectionIdField,
+			ticketId: idSchema,
+			...noteSchema.shape
+		},
+		annotations: writeAnnotations
+	}, ({ connectionId, ticketId, ...input }) => guarded(async () => (await resolve(connectionId)).addTicketNote(ticketId, input)));
+}
+const SERVER_VERSION = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../package.json").version;
+const SERVER_NAME = "connectwise-psa";
+function createServer(connect, options = {}) {
+	const server = new _modelcontextprotocol_sdk_server_mcp_js.McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	});
+	registerTools(server, connect, options);
+	return server;
+}
+function configuredClient() {
+	const config = (0, _alfe_ai_config.resolveConfig)();
+	const url = new URL(config.apiUrl);
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && [
+		"localhost",
+		"127.0.0.1",
+		"[::1]"
+	].includes(url.hostname)) || url.username || url.password || url.search || url.hash) throw new PsaError("Configure a valid Alfe API URL with alfe login.");
+	return new _alfe_ai_agent_api_client.AgentApiClient({
+		apiUrl: config.apiUrl,
+		apiKey: config.apiKey
+	});
+}
+async function main(connect = configuredClient(), transport = new _modelcontextprotocol_sdk_server_stdio_js.StdioServerTransport()) {
+	const server = createServer(connect);
+	try {
+		await server.connect(transport);
+		return server;
+	} catch (error) {
+		await server.close().catch(() => void 0);
+		throw error;
+	}
+}
+//#endregion
+Object.defineProperty(exports, "PsaClient", {
+	enumerable: true,
+	get: function() {
+		return PsaClient;
+	}
+});
+Object.defineProperty(exports, "SERVER_NAME", {
+	enumerable: true,
+	get: function() {
+		return SERVER_NAME;
+	}
+});
+Object.defineProperty(exports, "SERVER_VERSION", {
+	enumerable: true,
+	get: function() {
+		return SERVER_VERSION;
+	}
+});
+Object.defineProperty(exports, "createServer", {
+	enumerable: true,
+	get: function() {
+		return createServer;
+	}
+});
+Object.defineProperty(exports, "main", {
+	enumerable: true,
+	get: function() {
+		return main;
+	}
+});
+Object.defineProperty(exports, "safeErrorMessage", {
+	enumerable: true,
+	get: function() {
+		return safeErrorMessage;
+	}
+});