@alfe.ai/connectwise-psa-mcp 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# ConnectWise PSA MCP
+
+Runtime-neutral stdio MCP server for ConnectWise PSA (formerly Manage). It runs
+under OpenClaw, Hermes, or Claude Code through the Alfe integration manifest.
+
+Launch the released package with `npx -y @alfe.ai/connectwise-psa-mcp@0.1.0`.
+Node 22+ and an existing `alfe login` configuration are required. There are no
+provider-credential environment variables or separate login files.
+
+Create a **ConnectWise PSA** connection in Alfe Connections with the final PSA
+API server origin, company ID, and an API member's public/private keys. The
+Alfe service supplies its registered PSA ClientID. For cloud tenants, use your
+region's API hostname (for example `https://api-na.myconnectwise.net`), rather
+than a browser deep link. On-premises deployments require a publicly resolvable
+HTTPS hostname and a trusted TLS certificate. The runtime appends
+`/v4_6_release/apis/3.0` and refuses redirects and non-public destinations.
+
+Call `connectwise_psa_list_connections` first. Every provider operation requires
+the selected `connectionId`; it never silently chooses a default account.
+Credentials are resolved again on every operation, so changing keys or removing
+access applies to the next call without restarting the server.
+
+Available tools:
+
+- Connection discovery
+- List companies, contacts, service boards, priorities, members, and tickets
+- Get a company, contact, or ticket
+- List a board's statuses and a ticket's direct notes
+- Create a service ticket, update selected fields, and append a note
+
+List tools return a single page (25 rows by default, maximum 100), with `page`,
+`pageSize`, `conditions`, and `orderBy`. Notes default to internal-only.
+Discussion/resolution notes may be customer-visible; select visibility
+deliberately. Writes are never automatically retried: after a timeout, read the
+ticket or notes to check whether the write succeeded before repeating it.
+The API member's PSA security role controls which operations are allowed.
+
+## API references and verification status
+
+- [ConnectWise Getting Started](https://developer.connectwise.com/Best_Practices/Getting_Started)
+  documents product-specific developer access and sandbox requests.
+- [PSA REST reference](https://developer.connectwise.com/Products/Manage/REST)
+  and [Developer Guide](https://developer.connectwise.com/Products/Manage/Developer_Guide)
+  are the canonical endpoint and authentication references.
+
+On 2026-09-08 the REST reference and Developer Guide required an approved
+Developer Network login. The implementation uses the PSA REST 3.0 resource
+contract, with local HTTP-contract/security/MCP-exchange tests; those tests do
+not constitute verification against a customer PSA server. An approved PSA
+sandbox should verify company/board/status reads, create a disposable ticket,
+update it, and add an internal note before release. Version-specific codebase
+paths other than `/v4_6_release` are not supported by this release.
+
+## Development
+
+```sh
+pnpm --filter @alfe.ai/connectwise-psa-mcp typecheck
+pnpm --filter @alfe.ai/connectwise-psa-mcp lint
+pnpm --filter @alfe.ai/connectwise-psa-mcp test
+pnpm --filter @alfe.ai/connectwise-psa-mcp build
+```

package/dist/bin.cjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+const require_server = require("./server2.cjs");
+//#region src/bin.ts
+require_server.main().then((server) => {
+	let closing;
+	const shutdown = () => {
+		closing ??= server.close().catch(() => {
+			process.stderr.write("ConnectWise PSA shutdown failed.\n");
+		});
+	};
+	process.once("SIGTERM", shutdown);
+	process.once("SIGINT", shutdown);
+}).catch((error) => {
+	process.stderr.write(`${require_server.safeErrorMessage(error)}\n`);
+	process.exitCode = 1;
+});
+//#endregion

package/dist/bin.d.cts

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

package/dist/bin.d.ts

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

package/dist/bin.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { i as main, o as safeErrorMessage } from "./server2.js";
+//#region src/bin.ts
+main().then((server) => {
+	let closing;
+	const shutdown = () => {
+		closing ??= server.close().catch(() => {
+			process.stderr.write("ConnectWise PSA shutdown failed.\n");
+		});
+	};
+	process.once("SIGTERM", shutdown);
+	process.once("SIGINT", shutdown);
+}).catch((error) => {
+	process.stderr.write(`${safeErrorMessage(error)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/dist/server.cjs

@@ -0,0 +1,7 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_server = require("./server2.cjs");
+exports.PsaClient = require_server.PsaClient;
+exports.SERVER_NAME = require_server.SERVER_NAME;
+exports.SERVER_VERSION = require_server.SERVER_VERSION;
+exports.createServer = require_server.createServer;
+exports.main = require_server.main;

package/dist/server.d.cts

@@ -0,0 +1,102 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { z } from "zod";
+
+//#region src/transport.d.ts
+interface ResolvedAddress {
+  address: string;
+  family: number;
+}
+type ResolveHost = (hostname: string) => Promise<ResolvedAddress[]>;
+interface RequestInput {
+  url: URL;
+  address: ResolvedAddress;
+  method: 'GET' | 'POST' | 'PATCH';
+  headers: Record<string, string>;
+  body?: string;
+}
+type SendRequest = (input: RequestInput) => Promise<unknown>;
+//#endregion
+//#region src/client.d.ts
+declare const listSchema: z.ZodObject<{
+  page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+  pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+  conditions: z.ZodOptional<z.ZodString>;
+  orderBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const createTicketSchema: z.ZodObject<{
+  summary: z.ZodString;
+  companyId: z.ZodCoercedNumber<unknown>;
+  boardId: z.ZodCoercedNumber<unknown>;
+  contactId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  statusId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  priorityId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  initialDescription: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const updateTicketSchema: z.ZodObject<{
+  summary: z.ZodOptional<z.ZodString>;
+  statusId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  priorityId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  ownerId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  contactId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+declare const noteSchema: z.ZodObject<{
+  text: z.ZodString;
+  visibility: z.ZodDefault<z.ZodEnum<{
+    internal: "internal";
+    discussion: "discussion";
+    resolution: "resolution";
+  }>>;
+}, z.core.$strict>;
+declare const LIST_PATHS: {
+  readonly companies: "/company/companies";
+  readonly contacts: "/company/contacts";
+  readonly boards: "/service/boards";
+  readonly priorities: "/service/priorities";
+  readonly members: "/system/members";
+  readonly tickets: "/service/tickets";
+};
+type ListResource = keyof typeof LIST_PATHS;
+type ListInput = z.input<typeof listSchema>;
+interface PsaCredentials {
+  provider: 'connectwise-psa';
+  connectionId: string;
+  siteUrl: string;
+  companyId: string;
+  publicKey: string;
+  privateKey: string;
+  clientId: string;
+}
+interface PsaClientOptions {
+  resolve?: ResolveHost;
+  send?: SendRequest;
+}
+/** Direct, finite REST operations; no arbitrary URL tool and no mutation retries. */
+declare class PsaClient {
+  private readonly credentials;
+  private readonly options;
+  constructor(credentials: unknown, options?: PsaClientOptions);
+  list(resource: ListResource, input?: ListInput): Promise<unknown[]>;
+  get(resource: 'companies' | 'contacts' | 'tickets', id: number): Promise<Record<string, unknown>>;
+  listBoardStatuses(boardId: number, input?: ListInput): Promise<unknown[]>;
+  listTicketNotes(ticketId: number, input?: ListInput): Promise<unknown[]>;
+  createTicket(input: z.input<typeof createTicketSchema>): Promise<Record<string, unknown>>;
+  updateTicket(ticketId: number, input: z.input<typeof updateTicketSchema>): Promise<Record<string, unknown>>;
+  addTicketNote(ticketId: number, input: z.input<typeof noteSchema>): Promise<Record<string, unknown>>;
+  private listPath;
+  private call;
+}
+//#endregion
+//#region src/tools.d.ts
+interface ConnectClient {
+  getConnectProviderAccounts(provider: string): Promise<unknown>;
+  getConnectionCredentials(connectionId: string): Promise<unknown>;
+}
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_VERSION: string;
+declare const SERVER_NAME = "connectwise-psa";
+declare function createServer(connect: ConnectClient, options?: PsaClientOptions): McpServer;
+declare function main(connect?: ConnectClient, transport?: Transport): Promise<McpServer>;
+//#endregion
+export { type ConnectClient, type ListInput, type ListResource, PsaClient, type PsaClientOptions, type PsaCredentials, SERVER_NAME, SERVER_VERSION, createServer, main };

package/dist/server.d.ts

@@ -0,0 +1,102 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+
+//#region src/transport.d.ts
+interface ResolvedAddress {
+  address: string;
+  family: number;
+}
+type ResolveHost = (hostname: string) => Promise<ResolvedAddress[]>;
+interface RequestInput {
+  url: URL;
+  address: ResolvedAddress;
+  method: 'GET' | 'POST' | 'PATCH';
+  headers: Record<string, string>;
+  body?: string;
+}
+type SendRequest = (input: RequestInput) => Promise<unknown>;
+//#endregion
+//#region src/client.d.ts
+declare const listSchema: z.ZodObject<{
+  page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+  pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+  conditions: z.ZodOptional<z.ZodString>;
+  orderBy: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const createTicketSchema: z.ZodObject<{
+  summary: z.ZodString;
+  companyId: z.ZodCoercedNumber<unknown>;
+  boardId: z.ZodCoercedNumber<unknown>;
+  contactId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  statusId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  priorityId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  initialDescription: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const updateTicketSchema: z.ZodObject<{
+  summary: z.ZodOptional<z.ZodString>;
+  statusId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  priorityId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  ownerId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+  contactId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+declare const noteSchema: z.ZodObject<{
+  text: z.ZodString;
+  visibility: z.ZodDefault<z.ZodEnum<{
+    internal: "internal";
+    discussion: "discussion";
+    resolution: "resolution";
+  }>>;
+}, z.core.$strict>;
+declare const LIST_PATHS: {
+  readonly companies: "/company/companies";
+  readonly contacts: "/company/contacts";
+  readonly boards: "/service/boards";
+  readonly priorities: "/service/priorities";
+  readonly members: "/system/members";
+  readonly tickets: "/service/tickets";
+};
+type ListResource = keyof typeof LIST_PATHS;
+type ListInput = z.input<typeof listSchema>;
+interface PsaCredentials {
+  provider: 'connectwise-psa';
+  connectionId: string;
+  siteUrl: string;
+  companyId: string;
+  publicKey: string;
+  privateKey: string;
+  clientId: string;
+}
+interface PsaClientOptions {
+  resolve?: ResolveHost;
+  send?: SendRequest;
+}
+/** Direct, finite REST operations; no arbitrary URL tool and no mutation retries. */
+declare class PsaClient {
+  private readonly credentials;
+  private readonly options;
+  constructor(credentials: unknown, options?: PsaClientOptions);
+  list(resource: ListResource, input?: ListInput): Promise<unknown[]>;
+  get(resource: 'companies' | 'contacts' | 'tickets', id: number): Promise<Record<string, unknown>>;
+  listBoardStatuses(boardId: number, input?: ListInput): Promise<unknown[]>;
+  listTicketNotes(ticketId: number, input?: ListInput): Promise<unknown[]>;
+  createTicket(input: z.input<typeof createTicketSchema>): Promise<Record<string, unknown>>;
+  updateTicket(ticketId: number, input: z.input<typeof updateTicketSchema>): Promise<Record<string, unknown>>;
+  addTicketNote(ticketId: number, input: z.input<typeof noteSchema>): Promise<Record<string, unknown>>;
+  private listPath;
+  private call;
+}
+//#endregion
+//#region src/tools.d.ts
+interface ConnectClient {
+  getConnectProviderAccounts(provider: string): Promise<unknown>;
+  getConnectionCredentials(connectionId: string): Promise<unknown>;
+}
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_VERSION: string;
+declare const SERVER_NAME = "connectwise-psa";
+declare function createServer(connect: ConnectClient, options?: PsaClientOptions): McpServer;
+declare function main(connect?: ConnectClient, transport?: Transport): Promise<McpServer>;
+//#endregion
+export { type ConnectClient, type ListInput, type ListResource, PsaClient, type PsaClientOptions, type PsaCredentials, SERVER_NAME, SERVER_VERSION, createServer, main };

package/dist/server.js

@@ -0,0 +1,2 @@
+import { a as PsaClient, i as main, n as SERVER_VERSION, r as createServer, t as SERVER_NAME } from "./server2.js";
+export { PsaClient, SERVER_NAME, SERVER_VERSION, createServer, main };