mcp-connectwise-psa: Instructions file for Claude Code

mcp-connectwise-psa

MCP server for ConnectWise PSA (Manage). TypeScript, ESM, Node ≥20. Transports: stdio (local) and streamable HTTP (shared deployments). Sibling project to mcp-itglue — same auth architecture.

Commands

• npm run build — tsc → dist/ (tests excluded from build)
• npm test — vitest, test files beside sources (src/**/*.test.ts)
• npm run dev / npm run dev:http — run from source via tsx

Architecture

• src/config.ts — env/flag parsing; CW_SITE accepts full URLs (normalized to host)
• src/cw/client.ts — fetch-based CW Manage REST client (API 3.0). Basic auth companyId+publicKey:privateKey + mandatory clientId header. List queries use CW's grammar: conditions (exact for names/ids, contains for text, date literals in [brackets]), orderBy, page/pageSize, and fields (always pass fields — CW records are huge). q() quotes condition values; allOf() joins fragments
• src/tools/registrar.ts — ToolRegistrar registers the full tool surface; no MCP-level role gating (ConnectWise enforces the member's security role — unlike mcp-itglue's single account key, PSA is per-member BYOK)
• src/http/app.ts — pure BYOK: every /mcp session presents its own x-cw-public-key/x-cw-private-key (+ optional x-cw-member-id) headers; no keys → 401; sessions bound to the SHA-256 of the key pair; a different pair on the same session id → 403. stdio uses the server-wide CW_PUBLIC_KEY/CW_PRIVATE_KEY
• src/server.ts — one McpServer per session; the session's CW credentials build its CWClient. Holds the TOOLSETS registry (key → register*Tools); createServer registers only session.toolsets
• src/tools/toolsets.ts — capability keys (tickets/time/companies/configurations/schedule/finance/advanced/sql), persona presets (tech/dispatch/invoicing/all), and resolveToolsets(). Selection: CW_TOOLSETS/--toolsets (stdio, unknown key → ConfigError) or the x-cw-toolsets header (HTTP, unknown token ignored). all and DEFAULT_TOOLSETS are both [...TOOLSET_KEYS] — advanced and sql are ordinary keys there, though the persona presets exclude both. What gates the database is CW_DB_*: withoutDbToolsets() prunes DB_TOOLSETS in loadConfig, sessionToolsets and createServer when no database is configured, and loadConfig only errors when sql was named outright (namesDbToolset) — otherwise a server without a database would refuse to start over the default it never chose
• src/tools/ — tickets, time, companies, configurations (tech); schedule (dispatch); finance (invoicing, read-only); advanced (opt-in escape hatch); helpers in tools/shared.ts
• src/tools/ticket-classification.ts — board-scoped classification (type→subType→item, team, source) and bundling helpers. Values are passed as name or id and sent as {name}/{id} for CW to resolve against the ticket's board — no local resolver, since the same name means a different id per board (cw_get_board lists statuses, types, sub-types, items and teams for discovery). copy_classification_from on cw_create_ticket lifts those fields by id off an existing ticket; explicit args win. partitionBundleCandidates refuses a child that already has a parent instead of re-parenting it — detaching is UI-only, so a wrong bundle is expensive to undo
• src/tools/ticket-kind.ts — service vs project tickets. CW splits them across /service/tickets and /project/tickets with different chargeToType values, so: list tools take ticket_type (both default) and go through listAcrossKinds (one resource failing yields a partial answer plus a note, never an error — a security role can allow one and refuse the other); by-id tools take auto|service|project and resolveTicketKind probes service then project, treating only 404 as "try the other one". TICKET_LIST_FIELDS is deliberately identical for both resources — one unknown field fails the whole call
• src/tools/advanced.ts — cw_get (read-only GET on any path via CWClient.rawGet; strips host//apis/3.0/inline query, then passes conditions/fields/orderBy/page) and cw_find_endpoint (lexical search over src/reference/cw-endpoints.ts). Write passthrough is a deliberate later add
• src/sql/client.ts — SqlClient over the on-prem cwwebapp_* database: lazy await import("mssql") (CJS → .default), one process-wide pool created in index.ts (never per session — the login is server-wide), cleared on a failed connect so an outage isn't permanent. Results are bounded while streaming (request.stream + cancel() at the row cap / ~20k char budget) — slicing afterwards would OOM on SELECT * FROM SR_Service. Isolation is READ UNCOMMITTED via options.connectionIsolationLevel, not a prepended SET (which shifts SQL error line numbers). describeSqlError gives connection errors fixed prose and statement errors the redacted server text; redactSqlMessage strips host/db/user. No statement validation — the db_datareader login is the boundary (deliberate; see README)
• src/sql/library.ts — saved-query library: committed core (src/reference/cw-db-queries.ts) ∪ writable overlay at CW_DB_QUERY_LIBRARY, overlay wins by slug, mtime-based reload, atomic .tmp+rename write, in-process promise chain for concurrent saves. cw_db_save_query is the only tool in the server that writes anything — and it writes to that file, never to ConnectWise
• src/tools/sql.ts — cw_db_query (shape-adaptive rendering: pipe table ≤10 columns, record blocks above), cw_db_find_table, cw_db_find_query, cw_db_save_query (registered only when the library is writable). Takes a SqlContext { client, library } as the third registrar argument
• src/reference/cw-db-schema.ts — generated table catalog (84 entries) from scripts/gen-db-schema.mjs + the hand annotations in scripts/db-enrich.mjs. Curated core only, never a full inventory: no row counts, no custom/UDF tables, nothing identifying an instance — the repo is public. Names came from reading production reporting queries; scripts/dump-db-schema.sql + the generator's dump mode verify them against a live schema
• src/reference/search.ts — lexicalRank() shared by cw_find_endpoint, cw_db_find_table and the query library; findEndpoints kept its signature so advanced.test.ts stayed untouched through the extraction
• src/reference/cw-endpoints.ts — generated endpoint catalog (~1145 paths). CW publishes no fetchable OpenAPI (swagger UI is behind the Manage web login), so a spec is obtained manually and scripts/gen-endpoints.mjs derives this file from it (source kept local under .claude/, gitignored; the generated .ts is committed). Hand annotations (better summaries + keyParams/commonFields/coveredBy) live in the generator's ENRICH map; /count and /info helper paths are dropped