mcp-connectwise-psa 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Samotija
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# mcp-connectwise-psa
+
+An MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server for [ConnectWise PSA](https://www.connectwise.com/platform/psa) (Manage), focused on what technicians do all day:
+
+- **Tickets** — my tickets, search, full detail with notes, create, update status/priority/owner, add discussion/internal notes
+- **Time entries** — log time against tickets, review your own time
+- **Companies & contacts** — fast lookup (read-only)
+- **Configurations** — devices/assets with serials, IPs, OS, warranty (read-only)
+- **Role-based access control** — viewer / editor bearer tokens decide which tools a session sees
+- **Per-tech API keys (BYOK)** — techs supply their own ConnectWise member keys, so notes and time entries are attributed to the *actual person* in ConnectWise
+- **Transports** — stdio for local use, streamable HTTP for shared deployments; Docker image included
+
+## Quick start (local, stdio)
+
+```bash
+npm install && npm run build
+CW_SITE=na.myconnectwise.net \
+CW_COMPANY_ID=yourcompany \
+CW_CLIENT_ID=<integration clientId> \
+CW_PUBLIC_KEY=xxxx CW_PRIVATE_KEY=yyyy \
+CW_MEMBER_IDENTIFIER=JSmith \
+node dist/index.js
+```
+
+Claude Desktop / Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "connectwise": {
+      "command": "node",
+      "args": ["/path/to/mcp-connectwise-psa/dist/index.js"],
+      "env": {
+        "CW_SITE": "na.myconnectwise.net",
+        "CW_COMPANY_ID": "yourcompany",
+        "CW_CLIENT_ID": "<clientId>",
+        "CW_PUBLIC_KEY": "xxxx",
+        "CW_PRIVATE_KEY": "yyyy",
+        "CW_MEMBER_IDENTIFIER": "JSmith"
+      }
+    }
+  }
+}
+```
+
+A `clientId` is required by the ConnectWise API — register a (free) integration at [developer.connectwise.com](https://developer.connectwise.com). API member keys are created in ConnectWise under **My Account → API Keys** (per member) or **System → Members → API Members** (integration accounts).
+
+## HTTP deployment
+
+```bash
+CW_SITE=… CW_COMPANY_ID=… CW_CLIENT_ID=… \
+MCP_TOKENS_VIEWER="alice:$(openssl rand -hex 32)" \
+MCP_TOKENS_EDITOR="bot:$(openssl rand -hex 32)" \
+node dist/index.js --transport http --port 3000
+```
+
+Or with Docker: `docker build -t mcp-connectwise-psa . && docker run -p 3000:3000 -e CW_SITE -e CW_COMPANY_ID -e CW_CLIENT_ID -e MCP_TOKENS_VIEWER -e MCP_TOKENS_EDITOR mcp-connectwise-psa`
+
+| Route | Purpose |
+|---|---|
+| `POST/GET/DELETE /mcp` | MCP streamable-http endpoint |
+| `GET /health` | Liveness probe |
+
+> Sessions are held in memory — run a single instance (or sticky sessions).
+
+## Access control
+
+### Role tokens
+
+```bash
+MCP_TOKENS_VIEWER="alice:tokA,bob:tokB"   # read-only tools
+MCP_TOKENS_EDITOR="helpdesk-bot:tokC"     # + create/update tickets, notes, time entries
+MCP_TOKENS_ADMIN="ops:tokD"               # reserved for future destructive tools
+```
+
+Clients send `Authorization: Bearer <token>`. Tools outside the role are not even registered for the session, a runtime guard re-checks every call, and session ids never carry privilege (each request re-authenticates; principal mismatch → 403). Labels appear in the audit log and allow per-person revocation. With no tokens configured the server runs in dev mode (full access + loud warning).
+
+### Bring your own keys (BYOK) — recommended for techs
+
+Send your own ConnectWise member API keys on the initialize request:
+
+```
+x-cw-public-key:  <public key>
+x-cw-private-key: <private key>
+x-cw-member-id:   <your member identifier>   (optional — enables "my tickets"/"my time")
+```
+
+The session then acts as *you* in ConnectWise: your security role limits what succeeds, and every note and time entry is attributed to you. `CLIENT_CW_KEYS` controls the policy: `with-token` (default — a bearer token is still required), `open`, or `disabled`. Keys are never logged; sessions are bound to a SHA-256 hash of the pair.
+
+Token-only sessions use the server-wide `CW_PUBLIC_KEY`/`CW_PRIVATE_KEY` (use an integration API member with a conservative security role — its writes are attributed to that integration member).
+
+## Tools
+
+| Tool | Tier |
+|---|---|
+| `cw_my_tickets`, `cw_search_tickets`, `cw_get_ticket` | read |
+| `cw_list_my_time` | read |
+| `cw_search_companies`, `cw_get_company`, `cw_search_contacts` | read |
+| `cw_list_configurations`, `cw_get_configuration` | read |
+| `cw_create_ticket`, `cw_update_ticket`, `cw_add_ticket_note` | write |
+| `cw_create_time_entry` | write |
+
+Viewer = read. Editor/Admin = read + write. No destructive (delete) tools in v1.
+
+## Configuration reference
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CW_SITE` | — | ConnectWise host (cloud or on-prem; full URLs accepted) |
+| `CW_COMPANY_ID` | — | Login company id |
+| `CW_CLIENT_ID` | — | Integration clientId |
+| `CW_PUBLIC_KEY` / `CW_PRIVATE_KEY` | — | Server-wide API member keys (optional when BYOK is enabled) |
+| `CW_MEMBER_IDENTIFIER` | — | Member the server-wide keys belong to |
+| `TRANSPORT` / `PORT` | `stdio` / `3000` | Transport selection |
+| `CLIENT_CW_KEYS` | `with-token` | BYOK policy: `disabled`, `with-token`, `open` |
+| `MCP_TOKENS_VIEWER/EDITOR/ADMIN` | — | `label:token,label:token` per role |
+
+## Notes & limits
+
+- Ticket searches default to open tickets; status/board names are exact, text filters are substrings.
+- Timestamps must have whole seconds — the server normalizes (ConnectWise rejects fractional seconds).
+- Time entries require an **open time report period** in ConnectWise for the entry date; the API's message is passed through when none exists.
+- `/system/myAccount` is missing on some on-prem versions — provide the member identifier explicitly (`CW_MEMBER_IDENTIFIER` or `x-cw-member-id`) for "my tickets"/"my time".
+- Discussion notes are customer-visible; internal notes are not — the tool makes this explicit.
+
+## Development
+
+```bash
+npm install
+npm run dev          # stdio via tsx
+npm run dev:http     # http via tsx
+npm test             # vitest
+npm run build        # tsc → dist/
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/auth/roles.js

@@ -0,0 +1,74 @@
+/**
+ * Role-based tool gating.
+ *
+ * Every tool belongs to a tier. The tier is derived from the tool's MCP
+ * annotations (readOnlyHint / destructiveHint) unless the tool declares an
+ * explicit `tier` override — used when the RBAC intent differs from the
+ * annotation (e.g. deleting a document section is destructive for clients,
+ * but editors need it to restructure documents).
+ *
+ * Enforcement is two-layered:
+ *  1. Tools outside the session's role are never registered, so they don't
+ *     even appear in tools/list.
+ *  2. Registered handlers are wrapped with a runtime re-check, so a
+ *     registration bug can never reach the IT Glue client.
+ */
+const TIER_ROLES = {
+    read: ["viewer", "editor", "admin"],
+    write: ["editor", "admin"],
+    destructive: ["admin"],
+};
+export function tierOf(spec) {
+    if (spec.tier)
+        return spec.tier;
+    if (spec.annotations.readOnlyHint === true)
+        return "read";
+    if (spec.annotations.destructiveHint === true)
+        return "destructive";
+    return "write";
+}
+export function roleAllows(role, tier) {
+    return TIER_ROLES[tier].includes(role);
+}
+/** Minimum role that can use a tier — for error messages. */
+function tierRequires(tier) {
+    return TIER_ROLES[tier][0] === "viewer" ? "viewer" : tier === "write" ? "editor" : "admin";
+}
+/**
+ * Registers tools on an McpServer, filtered and guarded by the session role.
+ */
+export class ToolRegistrar {
+    server;
+    role;
+    constructor(server, role) {
+        this.server = server;
+        this.role = role;
+    }
+    register(spec, handler) {
+        const tier = tierOf(spec);
+        if (!roleAllows(this.role, tier)) {
+            return; // tool is invisible to this session
+        }
+        const role = this.role;
+        const guarded = async (args) => {
+            if (!roleAllows(role, tier)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: ${spec.name} requires the ${tierRequires(tier)} role; this session is authenticated as ${role}.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return handler(args);
+        };
+        this.server.registerTool(spec.name, {
+            title: spec.title,
+            description: spec.description,
+            inputSchema: spec.inputSchema,
+            annotations: spec.annotations,
+        }, guarded);
+    }
+}

package/dist/auth/tokens.js

@@ -0,0 +1,93 @@
+/**
+ * Bearer-token authentication with per-role token pools.
+ *
+ * Tokens are configured through three environment variables, one per role:
+ *
+ *   MCP_TOKENS_VIEWER="alice:tok1,bob:tok2"
+ *   MCP_TOKENS_EDITOR="automation:tok3"
+ *   MCP_TOKENS_ADMIN="ops:tok4"
+ *
+ * Each entry is `label:token`; the label identifies the holder in audit logs
+ * and lets individual tokens be revoked. Entries without a label get an
+ * auto-generated one (`viewer-1`, ...). Tokens must be unique across roles —
+ * duplicates are dropped with a warning.
+ */
+import { timingSafeEqual } from "node:crypto";
+const ROLE_ENV_VARS = [
+    ["viewer", "MCP_TOKENS_VIEWER"],
+    ["editor", "MCP_TOKENS_EDITOR"],
+    ["admin", "MCP_TOKENS_ADMIN"],
+];
+export function parseTokenList(raw, role) {
+    const entries = [];
+    let unlabeled = 0;
+    for (const piece of raw.split(",")) {
+        const trimmed = piece.trim();
+        if (!trimmed)
+            continue;
+        const sep = trimmed.indexOf(":");
+        if (sep > 0 && sep < trimmed.length - 1) {
+            entries.push({
+                role,
+                label: trimmed.slice(0, sep).trim(),
+                token: trimmed.slice(sep + 1).trim(),
+            });
+        }
+        else {
+            unlabeled += 1;
+            entries.push({ role, label: `${role}-${unlabeled}`, token: trimmed.replace(/^:|:$/g, "") });
+        }
+    }
+    return entries.filter((e) => e.token.length > 0);
+}
+/** Load all configured token entries; duplicate token values are dropped. */
+export function loadTokenEntries(env = process.env) {
+    const entries = [];
+    for (const [role, envVar] of ROLE_ENV_VARS) {
+        const raw = env[envVar];
+        if (raw)
+            entries.push(...parseTokenList(raw, role));
+    }
+    const seen = new Set();
+    return entries.filter((entry) => {
+        if (seen.has(entry.token)) {
+            console.error(`[auth] Warning: duplicate token for "${entry.label}" (${entry.role}) ignored — tokens must be unique across roles.`);
+            return false;
+        }
+        seen.add(entry.token);
+        return true;
+    });
+}
+/** Timing-safe string comparison for secrets. */
+export function safeEquals(a, b) {
+    const bufA = Buffer.from(a, "utf-8");
+    const bufB = Buffer.from(b, "utf-8");
+    if (bufA.length !== bufB.length)
+        return false;
+    try {
+        return timingSafeEqual(bufA, bufB);
+    }
+    catch {
+        return false;
+    }
+}
+/** Extract the token from an `Authorization: Bearer <token>` header. */
+export function bearerToken(authorizationHeader) {
+    if (!authorizationHeader)
+        return null;
+    const parts = authorizationHeader.split(" ");
+    if (parts.length !== 2 || parts[0] !== "Bearer" || !parts[1])
+        return null;
+    return parts[1];
+}
+/** Match an Authorization header against the configured tokens. */
+export function authenticateToken(authorizationHeader, entries) {
+    const presented = bearerToken(authorizationHeader);
+    if (!presented)
+        return null;
+    for (const entry of entries) {
+        if (safeEquals(presented, entry.token))
+            return entry;
+    }
+    return null;
+}

package/dist/config.js

@@ -0,0 +1,92 @@
+/**
+ * Server configuration, resolved from CLI flags and environment variables.
+ *
+ * Environment variables:
+ *   CW_SITE               ConnectWise host (e.g. na.myconnectwise.net or an
+ *                         on-prem host). A full URL is accepted; scheme and
+ *                         path are stripped.
+ *   CW_COMPANY_ID         ConnectWise login company id (required)
+ *   CW_CLIENT_ID          Integration clientId from developer.connectwise.com (required)
+ *   CW_PUBLIC_KEY         Server-wide API member public key (optional — enables
+ *   CW_PRIVATE_KEY        token-only sessions; omit to require per-tech keys)
+ *   CW_MEMBER_IDENTIFIER  Member identifier the server-wide keys belong to
+ *                         (enables "my tickets"/"my time" for token-only sessions)
+ *   TRANSPORT             stdio | http (default: stdio)
+ *   PORT                  HTTP port (default: 3000)
+ *   CLIENT_CW_KEYS        disabled | with-token | open (default: with-token) —
+ *                         whether HTTP clients may supply their own member API
+ *                         keys via x-cw-public-key / x-cw-private-key headers
+ *   MCP_TOKENS_VIEWER     Comma-separated label:token list for the viewer role
+ *   MCP_TOKENS_EDITOR     Comma-separated label:token list for the editor role
+ *   MCP_TOKENS_ADMIN      Comma-separated label:token list for the admin role
+ */
+const CLIENT_KEY_MODES = ["disabled", "with-token", "open"];
+export class ConfigError extends Error {
+}
+function flagValue(argv, name) {
+    const idx = argv.indexOf(name);
+    if (idx === -1)
+        return undefined;
+    const value = argv[idx + 1];
+    if (value === undefined || value.startsWith("--")) {
+        throw new ConfigError(`Missing value for ${name}`);
+    }
+    return value;
+}
+/** Accept "host", "https://host", or "https://host/v4_6_release/apis/3.0/". */
+export function normalizeSite(raw) {
+    const withoutScheme = raw.replace(/^https?:\/\//i, "");
+    const host = withoutScheme.split("/")[0]?.trim();
+    if (!host)
+        throw new ConfigError(`Invalid CW_SITE "${raw}"`);
+    return host;
+}
+export function loadConfig(argv = process.argv.slice(2), env = process.env) {
+    // `||` not `??`: desktop hosts (MCPB) pass unset optional config as empty strings
+    const transport = ((flagValue(argv, "--transport") ?? env.TRANSPORT) || "stdio");
+    if (transport !== "stdio" && transport !== "http") {
+        throw new ConfigError(`Invalid transport "${transport}" — expected "stdio" or "http"`);
+    }
+    const portRaw = (flagValue(argv, "--port") ?? env.PORT) || "3000";
+    const port = Number(portRaw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new ConfigError(`Invalid port "${portRaw}"`);
+    }
+    const siteRaw = flagValue(argv, "--site") ?? env.CW_SITE;
+    if (!siteRaw)
+        throw new ConfigError("CW_SITE is required (ConnectWise host)");
+    const site = normalizeSite(siteRaw);
+    const companyId = env.CW_COMPANY_ID;
+    if (!companyId)
+        throw new ConfigError("CW_COMPANY_ID is required");
+    const clientId = env.CW_CLIENT_ID;
+    if (!clientId) {
+        throw new ConfigError("CW_CLIENT_ID is required — register an integration at developer.connectwise.com");
+    }
+    const clientKeyMode = (env.CLIENT_CW_KEYS || "with-token");
+    if (!CLIENT_KEY_MODES.includes(clientKeyMode)) {
+        throw new ConfigError(`Invalid CLIENT_CW_KEYS "${clientKeyMode}" — expected one of: ${CLIENT_KEY_MODES.join(", ")}`);
+    }
+    const publicKey = env.CW_PUBLIC_KEY || undefined;
+    const privateKey = env.CW_PRIVATE_KEY || undefined;
+    if (!!publicKey !== !!privateKey) {
+        throw new ConfigError("CW_PUBLIC_KEY and CW_PRIVATE_KEY must be set together");
+    }
+    if (transport === "stdio" && !publicKey) {
+        throw new ConfigError("CW_PUBLIC_KEY / CW_PRIVATE_KEY are required for stdio transport");
+    }
+    if (transport === "http" && !publicKey && clientKeyMode === "disabled") {
+        throw new ConfigError("CW_PUBLIC_KEY / CW_PRIVATE_KEY are required when CLIENT_CW_KEYS=disabled — there are no keys the server could use");
+    }
+    return {
+        transport,
+        port,
+        site,
+        companyId,
+        clientId,
+        publicKey,
+        privateKey,
+        memberIdentifier: env.CW_MEMBER_IDENTIFIER || undefined,
+        clientKeyMode,
+    };
+}

package/dist/cw/client.js

@@ -0,0 +1,156 @@
+/**
+ * ConnectWise Manage REST client (API 3.0) on the global fetch API.
+ *
+ * - Base URL: https://<site>/v4_6_release/apis/3.0
+ * - Auth: HTTP Basic with username "<companyId>+<publicKey>" and the private
+ *   key as password, plus the mandatory `clientId` header.
+ * - Lists use CW's query grammar: `conditions` (e.g. `name contains "x" AND
+ *   closedFlag=false`, date literals in [brackets]), `orderBy`, `page`,
+ *   `pageSize` (max 1000), and `fields` for server-side field selection.
+ */
+const REQUEST_TIMEOUT_MS = 30_000;
+export const MAX_PAGE_SIZE = 1000;
+/** Quote a string value for use inside a `conditions` expression. */
+export function q(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+/** Join condition fragments with AND, skipping empties. */
+export function allOf(...parts) {
+    const joined = parts.filter(Boolean).join(" AND ");
+    return joined || undefined;
+}
+export class CWApiError extends Error {
+    status;
+    detail;
+    constructor(message, status, detail) {
+        super(message);
+        this.status = status;
+        this.detail = detail;
+        this.name = "CWApiError";
+    }
+}
+export function describeError(error) {
+    if (error instanceof CWApiError) {
+        const detail = error.detail ? ` ${error.detail}` : "";
+        switch (error.status) {
+            case 400:
+                return `Error: Bad request.${detail} Check the parameters/conditions syntax.`;
+            case 401:
+                return "Error: ConnectWise authentication failed — check the API keys, company id, and clientId.";
+            case 403:
+                return `Error: Permission denied.${detail} The API member's security role may not allow this.`;
+            case 404:
+                return "Error: Resource not found. Verify the ID is correct.";
+            case 429:
+                return "Error: ConnectWise rate limit hit. Wait a moment and retry.";
+            default:
+                if (error.status && error.status >= 500) {
+                    return `Error: ConnectWise server error (${error.status}). Try again later.`;
+                }
+                return `Error: ConnectWise request failed${error.status ? ` with status ${error.status}` : ""}.${detail}`;
+        }
+    }
+    if (error instanceof Error && error.name === "TimeoutError") {
+        return "Error: ConnectWise request timed out. Try again.";
+    }
+    return `Error: ${error instanceof Error ? error.message : String(error)}`;
+}
+export class CWClient {
+    baseUrl;
+    authHeader;
+    clientId;
+    memberIdentifier;
+    triedSelfResolve = false;
+    constructor(options) {
+        this.baseUrl = `https://${options.site}/v4_6_release/apis/3.0`;
+        this.authHeader =
+            "Basic " +
+                Buffer.from(`${options.companyId}+${options.credentials.publicKey}:${options.credentials.privateKey}`).toString("base64");
+        this.clientId = options.clientId;
+        this.memberIdentifier = options.credentials.memberIdentifier;
+    }
+    async request(method, path, query, body) {
+        const url = new URL(this.baseUrl + path);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: this.authHeader,
+                    clientId: this.clientId,
+                    Accept: "application/json",
+                    ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "TimeoutError")
+                throw err;
+            throw new CWApiError(`Could not reach ConnectWise at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!response.ok) {
+            let detail;
+            try {
+                const errBody = (await response.json());
+                detail = errBody.errors?.[0]?.message ?? errBody.message;
+            }
+            catch {
+                // non-JSON error body
+            }
+            throw new CWApiError(`ConnectWise responded with ${response.status}`, response.status, detail);
+        }
+        if (response.status === 204)
+            return undefined;
+        return (await response.json());
+    }
+    async getOne(path, fields) {
+        return this.request("GET", path, { fields });
+    }
+    async getList(path, queryOptions = {}) {
+        const page = queryOptions.page ?? 1;
+        const pageSize = Math.min(queryOptions.pageSize ?? 25, MAX_PAGE_SIZE);
+        const items = await this.request("GET", path, {
+            conditions: queryOptions.conditions,
+            childConditions: queryOptions.childConditions,
+            orderBy: queryOptions.orderBy,
+            fields: queryOptions.fields,
+            page,
+            pageSize,
+        });
+        return { items, hasMore: items.length === pageSize, page };
+    }
+    async post(path, body) {
+        return this.request("POST", path, undefined, body);
+    }
+    /** JSON-Patch style operations, e.g. [{op:"replace", path:"status", value:{name:"Closed"}}]. */
+    async patch(path, operations) {
+        return this.request("PATCH", path, undefined, operations);
+    }
+    /**
+     * The member identifier this session acts as. Uses the explicitly provided
+     * identifier when available; otherwise tries /system/myAccount once (not
+     * present on all CW versions). Returns undefined when unknown.
+     */
+    async me() {
+        if (this.memberIdentifier)
+            return this.memberIdentifier;
+        if (this.triedSelfResolve)
+            return undefined;
+        this.triedSelfResolve = true;
+        try {
+            const account = await this.request("GET", "/system/myAccount");
+            if (account?.identifier)
+                this.memberIdentifier = account.identifier;
+        }
+        catch {
+            // endpoint missing on this CW version — caller will ask for an explicit identifier
+        }
+        return this.memberIdentifier;
+    }
+}

package/dist/cw/types.js

@@ -0,0 +1,2 @@
+/** ConnectWise Manage REST resource shapes (fields this server selects). */
+export {};