mcp-connectwise-psa 0.1.0

package/dist/tools/tickets.js

@@ -0,0 +1,234 @@
+/** Service ticket tools: search, my tickets, get, create, update, notes. */
+import { z } from "zod";
+import { allOf, q } from "../cw/client.js";
+import { clip, failure, json, pageFooter, pageNumberField, pageSizeField, responseFormatField, text, UNKNOWN_MEMBER_MESSAGE, } from "./shared.js";
+const TICKET_LIST_FIELDS = "id,summary,status/name,company/name,board/name,priority/name,owner/identifier,resources,dateEntered,_info/lastUpdated";
+const TICKET_DETAIL_FIELDS = "id,summary,recordType,board/name,status/name,priority/name,company/name,company/id,contact/name,owner/identifier,resources,closedFlag,dateEntered";
+const NOTE_FIELDS = "id,text,detailDescriptionFlag,internalAnalysisFlag,resolutionFlag,member/name,contact/name,createdBy,dateCreated";
+function ticketLine(t) {
+    const bits = [
+        `#${t.id} ${t.summary ?? "(no summary)"}`,
+        `  ${t.company?.name ?? "?"} | ${t.board?.name ?? "?"} | ${t.status?.name ?? "?"} | priority: ${t.priority?.name ?? "—"}`,
+    ];
+    const assigned = t.resources || t.owner?.identifier;
+    if (assigned)
+        bits.push(`  assigned: ${assigned}`);
+    return bits.join("\n");
+}
+function ticketList(items, page, hasMore) {
+    const lines = [`# Tickets (${items.length} on this page)`, ""];
+    for (const t of items)
+        lines.push(ticketLine(t), "");
+    lines.push(pageFooter(page, hasMore));
+    return lines.join("\n");
+}
+function noteBlock(n) {
+    const kind = n.internalAnalysisFlag ? "internal" : n.resolutionFlag ? "resolution" : "discussion";
+    const author = n.member?.name ?? n.contact?.name ?? n.createdBy ?? "?";
+    return [`— ${author} (${kind}) ${n.dateCreated ?? ""}`, n.text ?? "", ""].join("\n");
+}
+export function registerTicketTools(reg, client) {
+    reg.register({
+        name: "cw_search_tickets",
+        title: "Search ConnectWise Tickets",
+        description: "Search service tickets by company, board, status, summary text, or assigned member. " +
+            "Defaults to open tickets only. Returns ticket ids for use with cw_get_ticket / cw_add_ticket_note / cw_create_time_entry.",
+        inputSchema: {
+            company_id: z.number().int().positive().optional().describe("Filter by company ID"),
+            company_name: z.string().optional().describe("Filter by exact company name"),
+            board: z.string().optional().describe('Service board name (e.g. "Help Desk")'),
+            status: z.string().optional().describe('Status name (e.g. "New", "In Progress")'),
+            summary_contains: z.string().optional().describe("Text the ticket summary contains"),
+            assigned_to: z.string().optional().describe("Member identifier assigned to the ticket"),
+            open_only: z.boolean().default(true).describe("Only tickets that are not closed (default true)"),
+            page_number: pageNumberField,
+            page_size: pageSizeField,
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const conditions = allOf(args.open_only && "closedFlag=false", args.company_id !== undefined && `company/id=${args.company_id}`, args.company_name && `company/name=${q(args.company_name)}`, args.board && `board/name=${q(args.board)}`, args.status && `status/name=${q(args.status)}`, args.summary_contains && `summary contains ${q(args.summary_contains)}`, args.assigned_to &&
+                `(resources contains ${q(args.assigned_to)} OR owner/identifier=${q(args.assigned_to)})`);
+            const page = await client.getList("/service/tickets", {
+                conditions,
+                orderBy: "id desc",
+                fields: TICKET_LIST_FIELDS,
+                page: args.page_number,
+                pageSize: args.page_size,
+            });
+            if (page.items.length === 0)
+                return text("No tickets found.");
+            if (args.response_format === "json")
+                return text(clip(json(page)));
+            return text(clip(ticketList(page.items, page.page, page.hasMore)));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_my_tickets",
+        title: "My ConnectWise Tickets",
+        description: "List open tickets assigned to the member this session acts as (owner or listed in resources).",
+        inputSchema: {
+            page_number: pageNumberField,
+            page_size: pageSizeField,
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const memberId = await client.me();
+            if (!memberId)
+                return { ...text(UNKNOWN_MEMBER_MESSAGE), isError: true };
+            const page = await client.getList("/service/tickets", {
+                conditions: allOf("closedFlag=false", `(resources contains ${q(memberId)} OR owner/identifier=${q(memberId)})`),
+                orderBy: "id desc",
+                fields: TICKET_LIST_FIELDS,
+                page: args.page_number,
+                pageSize: args.page_size,
+            });
+            if (page.items.length === 0)
+                return text(`No open tickets assigned to ${memberId}.`);
+            if (args.response_format === "json")
+                return text(clip(json(page)));
+            return text(clip(`Acting as **${memberId}**\n\n` + ticketList(page.items, page.page, page.hasMore)));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_get_ticket",
+        title: "Get ConnectWise Ticket",
+        description: "Get one ticket with its most recent notes (newest first).",
+        inputSchema: {
+            ticket_id: z.number().int().positive().describe("The ticket ID"),
+            note_count: z.number().int().positive().max(50).default(10).describe("How many recent notes to include"),
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const ticket = await client.getOne(`/service/tickets/${args.ticket_id}`, TICKET_DETAIL_FIELDS);
+            const notes = await client.getList(`/service/tickets/${args.ticket_id}/notes`, {
+                orderBy: "dateCreated desc",
+                fields: NOTE_FIELDS,
+                pageSize: args.note_count,
+            });
+            if (args.response_format === "json") {
+                return text(clip(json({ ...ticket, notes: notes.items })));
+            }
+            const lines = [
+                `# Ticket #${ticket.id}: ${ticket.summary ?? ""}`,
+                "",
+                `- **Company**: ${ticket.company?.name ?? "?"} (ID: ${ticket.company?.id ?? "?"})`,
+                `- **Board**: ${ticket.board?.name ?? "?"} | **Status**: ${ticket.status?.name ?? "?"} | **Priority**: ${ticket.priority?.name ?? "—"}`,
+                `- **Contact**: ${ticket.contact?.name ?? "—"}`,
+                `- **Assigned**: ${ticket.resources || ticket.owner?.identifier || "—"}`,
+                `- **Opened**: ${ticket.dateEntered ?? "?"} | **Closed**: ${ticket.closedFlag ? "yes" : "no"}`,
+                "",
+                `## Recent notes (${notes.items.length})`,
+                "",
+            ];
+            for (const n of notes.items)
+                lines.push(noteBlock(n));
+            return text(clip(lines.join("\n"), "Request fewer notes or json format."));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_create_ticket",
+        title: "Create ConnectWise Ticket",
+        description: "Create a new service ticket on a board for a company.",
+        inputSchema: {
+            company_id: z.number().int().positive().describe("Company ID (find with cw_search_companies)"),
+            board: z.string().describe('Service board name (e.g. "Help Desk")'),
+            summary: z.string().min(1).max(100).describe("Ticket summary (max 100 chars)"),
+            initial_description: z.string().optional().describe("Initial description note"),
+            priority: z.string().optional().describe("Priority name (board default when omitted)"),
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const ticket = await client.post("/service/tickets", {
+                summary: args.summary,
+                company: { id: args.company_id },
+                board: { name: args.board },
+                ...(args.initial_description ? { initialDescription: args.initial_description } : {}),
+                ...(args.priority ? { priority: { name: args.priority } } : {}),
+            });
+            if (args.response_format === "json")
+                return text(json(ticket));
+            return text(`Ticket created: #${ticket.id} "${ticket.summary}" on ${ticket.board?.name ?? args.board} (status: ${ticket.status?.name ?? "?"}).`);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_update_ticket",
+        title: "Update ConnectWise Ticket",
+        description: "Update a ticket's status, priority, summary, or owner. Only provided fields change.",
+        inputSchema: {
+            ticket_id: z.number().int().positive().describe("The ticket ID to update"),
+            status: z.string().optional().describe('New status name (must exist on the ticket\'s board)'),
+            priority: z.string().optional().describe("New priority name"),
+            summary: z.string().max(100).optional().describe("New summary"),
+            owner_identifier: z.string().optional().describe("Member identifier to set as owner"),
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const ops = [];
+            if (args.status)
+                ops.push({ op: "replace", path: "status", value: { name: args.status } });
+            if (args.priority)
+                ops.push({ op: "replace", path: "priority", value: { name: args.priority } });
+            if (args.summary)
+                ops.push({ op: "replace", path: "summary", value: args.summary });
+            if (args.owner_identifier)
+                ops.push({ op: "replace", path: "owner", value: { identifier: args.owner_identifier } });
+            if (ops.length === 0)
+                return text("Nothing to update — provide at least one field.");
+            const ticket = await client.patch(`/service/tickets/${args.ticket_id}`, ops);
+            if (args.response_format === "json")
+                return text(json(ticket));
+            return text(`Ticket #${ticket.id} updated — status: ${ticket.status?.name ?? "?"}, priority: ${ticket.priority?.name ?? "—"}, owner: ${ticket.owner?.identifier ?? "—"}.`);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_add_ticket_note",
+        title: "Add ConnectWise Ticket Note",
+        description: "Add a note to a ticket. Discussion notes are visible to the customer on portals/emails; " +
+            "internal notes are not. Notes are attributed to the member whose API keys this session uses.",
+        inputSchema: {
+            ticket_id: z.number().int().positive().describe("The ticket ID"),
+            note: z.string().min(1).describe("Note text (plain text)"),
+            internal: z.boolean().default(false).describe("Internal analysis note instead of discussion (default false)"),
+            resolution: z.boolean().default(false).describe("Mark as resolution note (default false)"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const created = await client.post(`/service/tickets/${args.ticket_id}/notes`, {
+                text: args.note,
+                detailDescriptionFlag: !args.internal,
+                internalAnalysisFlag: args.internal,
+                resolutionFlag: args.resolution,
+            });
+            return text(`Note ${created.id} added to ticket #${args.ticket_id} (${args.internal ? "internal" : "discussion"}${args.resolution ? ", resolution" : ""}).`);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+}

package/dist/tools/time.js

@@ -0,0 +1,101 @@
+/** Time entry tools: log time against tickets, list my time. */
+import { z } from "zod";
+import { allOf, q } from "../cw/client.js";
+import { clip, failure, json, pageFooter, pageNumberField, pageSizeField, responseFormatField, text, UNKNOWN_MEMBER_MESSAGE, } from "./shared.js";
+const TIME_FIELDS = "id,chargeToId,chargeToType,member/identifier,member/name,company/name,timeStart,timeEnd,actualHours,billableOption,notes";
+/** ConnectWise rejects fractional seconds — format as YYYY-MM-DDTHH:mm:ssZ. */
+const cwTimestamp = (date) => date.toISOString().replace(/\.\d{3}Z$/, "Z");
+export function registerTimeTools(reg, client) {
+    reg.register({
+        name: "cw_create_time_entry",
+        title: "Log ConnectWise Time Entry",
+        description: "Log time against a service ticket. Time is attributed to the member whose API keys this session uses. " +
+            "Provide time_start plus either time_end or hours.",
+        inputSchema: {
+            ticket_id: z.number().int().positive().describe("Ticket to charge the time to"),
+            time_start: z
+                .string()
+                .describe('Start time, ISO 8601 (e.g. "2026-07-04T14:00:00Z")'),
+            time_end: z.string().optional().describe("End time, ISO 8601 (or use hours)"),
+            hours: z.number().positive().max(24).optional().describe("Duration in hours (alternative to time_end)"),
+            notes: z.string().min(1).describe("Work performed"),
+            billable: z.boolean().default(true).describe("Billable (default true)"),
+            add_to_detail: z
+                .boolean()
+                .default(false)
+                .describe("Also show the notes on the ticket as a discussion note (default false)"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const start = new Date(args.time_start);
+            if (Number.isNaN(start.getTime()))
+                return { ...text("Error: time_start is not a valid ISO timestamp."), isError: true };
+            let end;
+            if (args.time_end) {
+                end = new Date(args.time_end);
+            }
+            else if (args.hours !== undefined) {
+                end = new Date(start.getTime() + args.hours * 3_600_000);
+            }
+            if (!end || Number.isNaN(end.getTime()) || end <= start) {
+                return { ...text("Error: provide time_end after time_start, or a positive hours value."), isError: true };
+            }
+            const entry = await client.post("/time/entries", {
+                chargeToId: args.ticket_id,
+                chargeToType: "ServiceTicket",
+                timeStart: cwTimestamp(start),
+                timeEnd: cwTimestamp(end),
+                notes: args.notes,
+                billableOption: args.billable ? "Billable" : "DoNotBill",
+                addToDetailDescriptionFlag: args.add_to_detail,
+            });
+            const hours = entry.actualHours ?? ((end.getTime() - start.getTime()) / 3_600_000).toFixed(2);
+            return text(`Time entry ${entry.id} logged: ${hours}h on ticket #${args.ticket_id} by ${entry.member?.name ?? entry.member?.identifier ?? "(session member)"} (${entry.billableOption ?? (args.billable ? "Billable" : "DoNotBill")}).`);
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_list_my_time",
+        title: "My ConnectWise Time Entries",
+        description: "List time entries for the member this session acts as, newest first, optionally within a date range.",
+        inputSchema: {
+            date_from: z.string().optional().describe('Only entries starting on/after this date (e.g. "2026-07-01")'),
+            date_to: z.string().optional().describe("Only entries starting before this date"),
+            page_number: pageNumberField,
+            page_size: pageSizeField,
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const memberId = await client.me();
+            if (!memberId)
+                return { ...text(UNKNOWN_MEMBER_MESSAGE), isError: true };
+            const page = await client.getList("/time/entries", {
+                conditions: allOf(`member/identifier=${q(memberId)}`, args.date_from && `timeStart >= [${args.date_from}]`, args.date_to && `timeStart < [${args.date_to}]`),
+                orderBy: "timeStart desc",
+                fields: TIME_FIELDS,
+                page: args.page_number,
+                pageSize: args.page_size,
+            });
+            if (page.items.length === 0)
+                return text(`No time entries found for ${memberId}.`);
+            if (args.response_format === "json")
+                return text(clip(json(page)));
+            let total = 0;
+            const lines = [`# Time entries for ${memberId}`, ""];
+            for (const entry of page.items) {
+                total += entry.actualHours ?? 0;
+                lines.push(`- ${entry.timeStart ?? "?"} — ${entry.actualHours ?? "?"}h — ${entry.chargeToType ?? ""} ${entry.chargeToId ?? ""} (${entry.company?.name ?? "?"}) ${entry.billableOption ?? ""}`, `  ${(entry.notes ?? "").split("\n")[0] ?? ""}`);
+            }
+            lines.push("", `**Total on this page:** ${total.toFixed(2)}h`, pageFooter(page.page, page.hasMore));
+            return text(clip(lines.join("\n")));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "mcp-connectwise-psa",
+  "version": "0.1.0",
+  "description": "MCP server for ConnectWise PSA (Manage) — tickets, time entries, companies, and configurations for technicians, with role-based access control and per-tech API keys",
+  "mcpName": "io.github.selic/mcp-connectwise-psa",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/selic/mcp-connectwise-psa.git"
+  },
+  "homepage": "https://github.com/selic/mcp-connectwise-psa#readme",
+  "bugs": {
+    "url": "https://github.com/selic/mcp-connectwise-psa/issues"
+  },
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-connectwise-psa": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "bundle": "npm run build && node scripts/bundle.mjs",
+    "start": "node dist/index.js",
+    "start:http": "node dist/index.js --transport http",
+    "dev": "tsx src/index.ts",
+    "dev:http": "tsx src/index.ts --transport http",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "connectwise",
+    "connectwise-manage",
+    "psa",
+    "msp",
+    "tickets",
+    "rbac"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "Eugene Samotija (selic) <eselic@gmail.com> (https://defency.net)",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "express": "^5.2.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^26.1.0",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}