mcp-connectwise-psa 0.2.0 → 0.3.0

package/README.md

@@ -17,7 +17,7 @@ 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 \
+CW_MEMBER_IDENTIFIER=jdoe \
 node dist/index.js
 ```
 
@@ -35,7 +35,7 @@ Claude Desktop / Claude Code config:
         "CW_CLIENT_ID": "<clientId>",
         "CW_PUBLIC_KEY": "xxxx",
         "CW_PRIVATE_KEY": "yyyy",
-        "CW_MEMBER_IDENTIFIER": "JSmith"
+        "CW_MEMBER_IDENTIFIER": "jdoe"
       }
     }
   }
@@ -78,20 +78,27 @@ x-cw-member-id:   <your member identifier>   (optional — enables "my tickets"/
 
 Local **stdio** is single-user and uses the `CW_PUBLIC_KEY`/`CW_PRIVATE_KEY` from the environment instead of headers.
 
-## Tools
+## Toolsets
 
-The full tool surface is always available; whether a write succeeds is governed by the member's ConnectWise security role.
+Tools are grouped into **toolsets** so a session only sees the capabilities it needs — a dispatcher doesn't need the invoicing tools, and a small tool surface keeps the assistant focused (and its context cheap). Whether a write actually succeeds is still governed by the member's ConnectWise security role.
 
-| Tool | Access |
+| Toolset key | Tools |
 |---|---|
-| `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 |
+| `tickets` | `cw_search_tickets`, `cw_my_tickets`, `cw_get_ticket`, `cw_create_ticket`, `cw_update_ticket`, `cw_add_ticket_note`, `cw_list_boards`, `cw_get_board`, `cw_list_priorities`, `cw_list_ticket_time`, `cw_list_ticket_tasks` |
+| `time` | `cw_create_time_entry`, `cw_list_my_time`, `cw_list_work_roles`, `cw_list_my_timesheets`, `cw_submit_timesheet` |
+| `companies` | `cw_search_companies`, `cw_get_company`, `cw_search_contacts`, `cw_get_contact`, `cw_list_company_sites` |
+| `configurations` | `cw_list_configurations`, `cw_get_configuration` |
+| `schedule` | `cw_list_schedule_entries`, `cw_my_schedule`, `cw_schedule_ticket`, `cw_update_schedule_entry`, `cw_delete_schedule_entry`, `cw_member_availability`, `cw_list_members`, `cw_get_member` |
+| `finance` | `cw_list_invoices`, `cw_get_invoice`, `cw_list_agreements`, `cw_get_agreement`, `cw_list_unbilled_time` |
 
-No destructive (delete) tools in v1.
+**Presets** bundle keys per persona: `tech` = tickets + time + companies + configurations · `dispatch` = tickets + schedule + companies + configurations · `invoicing` = finance + time + companies · `all` = everything.
+
+Select toolsets with a comma list mixing keys and presets:
+
+- **HTTP** — the `x-cw-toolsets` header, per session: `x-cw-toolsets: dispatch` or `x-cw-toolsets: tech,finance`.
+- **stdio** — the `CW_TOOLSETS` env var or `--toolsets` flag: `CW_TOOLSETS=invoicing`.
+
+The **default is the `tech` preset** — the same tools this server exposed before toolsets existed, so nothing changes for existing clients until they opt in. Unknown keys in `CW_TOOLSETS`/`--toolsets` fail fast; unknown tokens in the `x-cw-toolsets` header are ignored. The only destructive tool is `cw_delete_schedule_entry` (dispatch); finance is read-only.
 
 ## Configuration reference
 
@@ -103,6 +110,7 @@ No destructive (delete) tools in v1.
 | `CW_PUBLIC_KEY` / `CW_PRIVATE_KEY` | — | API member keys — required for stdio; unused on HTTP (BYOK) |
 | `CW_MEMBER_IDENTIFIER` | — | Member the stdio keys belong to (my-tickets/my-time) |
 | `TRANSPORT` / `PORT` | `stdio` / `3000` | Transport selection |
+| `CW_TOOLSETS` | `tech` | Enabled toolsets (keys/presets); HTTP overrides per session via `x-cw-toolsets` |
 
 ## Notes & limits
 

package/dist/config.js

@@ -13,12 +13,16 @@
  *                         "my tickets"/"my time")
  *   TRANSPORT             stdio | http (default: stdio)
  *   PORT                  HTTP port (default: 3000)
+ *   CW_TOOLSETS           Comma list of toolset keys/presets to expose (default:
+ *                         the "tech" preset). HTTP sessions may override per
+ *                         request via the x-cw-toolsets header.
  *
  * Access model: stdio uses the server-wide keys above (single local user). HTTP
  * sessions each bring their own member API keys (BYOK) via x-cw-public-key /
  * x-cw-private-key headers; ConnectWise enforces that member's security role.
  * There is no MCP-level role gating.
  */
+import { DEFAULT_TOOLSETS, resolveToolsets } from "./tools/toolsets.js";
 export class ConfigError extends Error {
 }
 function flagValue(argv, name) {
@@ -69,6 +73,13 @@ export function loadConfig(argv = process.argv.slice(2), env = process.env) {
     if (transport === "stdio" && !publicKey) {
         throw new ConfigError("CW_PUBLIC_KEY / CW_PRIVATE_KEY are required for stdio transport");
     }
+    let toolsets;
+    try {
+        toolsets = resolveToolsets(flagValue(argv, "--toolsets") ?? env.CW_TOOLSETS, DEFAULT_TOOLSETS, "throw");
+    }
+    catch (err) {
+        throw new ConfigError(err instanceof Error ? err.message : String(err));
+    }
     return {
         transport,
         port,
@@ -78,5 +89,6 @@ export function loadConfig(argv = process.argv.slice(2), env = process.env) {
         publicKey,
         privateKey,
         memberIdentifier: env.CW_MEMBER_IDENTIFIER || undefined,
+        toolsets,
     };
 }

package/dist/cw/client.js

@@ -132,6 +132,10 @@ export class CWClient {
     async patch(path, operations) {
         return this.request("PATCH", path, undefined, operations);
     }
+    /** DELETE a resource (e.g. /schedule/entries/{id}). Returns void (CW replies 204/200). */
+    async del(path) {
+        await this.request("DELETE", path);
+    }
     /**
      * The member identifier this session acts as. Uses the explicitly provided
      * identifier when available; otherwise tries /system/myAccount once (not

package/dist/http/app.js

@@ -19,6 +19,7 @@ import express from "express";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { createServer, SERVER_NAME, SERVER_VERSION } from "../server.js";
+import { resolveToolsets } from "../tools/toolsets.js";
 const sha256 = (value) => createHash("sha256").update(value).digest("hex");
 function rpcError(res, status, code, message) {
     res.status(status).json({ jsonrpc: "2.0", error: { code, message }, id: null });
@@ -59,6 +60,14 @@ export function resolveAuth(req) {
 function principalMatches(session, auth) {
     return session.keyHash === auth.keyHash;
 }
+/**
+ * Toolsets for a new session: the x-cw-toolsets header narrows/widens within the
+ * valid keys, falling back to the server default. Unknown tokens are ignored
+ * (warn) rather than failing the request. Exported for tests.
+ */
+export function sessionToolsets(req, config) {
+    return resolveToolsets(headerValue(req, "x-cw-toolsets"), config.toolsets, "warn");
+}
 export function createApp(config) {
     const app = express();
     app.use(express.json({ limit: "2mb" }));
@@ -103,6 +112,7 @@ export function createApp(config) {
             const server = createServer(config, {
                 label: auth.label,
                 credentials: auth.credentials,
+                toolsets: sessionToolsets(req, config),
             });
             await server.connect(transport);
             await transport.handleRequest(req, res, req.body);

package/dist/index.js

@@ -12,6 +12,7 @@ Options:
   --transport stdio|http   Transport (default: stdio; env TRANSPORT)
   --port <n>               HTTP port (default: 3000; env PORT)
   --site <host>            ConnectWise host (env CW_SITE)
+  --toolsets <list>        Enabled toolsets (env CW_TOOLSETS; default: tech)
   --help                   Show this help
 
 Environment:
@@ -21,10 +22,13 @@ Environment:
   CW_PUBLIC_KEY            API member public key (required for stdio)
   CW_PRIVATE_KEY           API member private key (required for stdio)
   CW_MEMBER_IDENTIFIER     Member the stdio keys belong to (my-tickets/my-time)
+  CW_TOOLSETS              Comma list of toolset keys/presets (default: tech).
+                           Keys: tickets, time, companies, configurations,
+                           schedule, finance. Presets: tech, dispatch, invoicing, all.
 
 HTTP sessions authenticate per-request with their own member keys via the
 x-cw-public-key / x-cw-private-key headers (BYOK); the CW_* keys above are used
-only by stdio.
+only by stdio. HTTP clients pick toolsets per session with the x-cw-toolsets header.
 `;
 function logStartupSummary(config) {
     console.error("[auth] HTTP: each session must present its own ConnectWise keys via " +
@@ -41,6 +45,7 @@ async function runStdio(config) {
             privateKey: config.privateKey,
             memberIdentifier: config.memberIdentifier,
         },
+        toolsets: config.toolsets,
     });
     await server.connect(new StdioServerTransport());
     console.error(`${SERVER_NAME} v${SERVER_VERSION} running on stdio (${config.site})`);

package/dist/server.js

@@ -1,8 +1,8 @@
 /**
  * Builds an McpServer for one session. A session is defined by the ConnectWise
- * credentials it uses (server-wide keys on stdio, or client-supplied via BYOK).
- * The full tool surface is always registered; the member's ConnectWise security
- * role is the access control.
+ * credentials it uses (server-wide keys on stdio, or client-supplied via BYOK)
+ * and the toolsets it selected. Only the selected toolsets are registered; the
+ * member's ConnectWise security role is the access control.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createRequire } from "node:module";
@@ -12,10 +12,21 @@ import { registerTicketTools } from "./tools/tickets.js";
 import { registerTimeTools } from "./tools/time.js";
 import { registerCompanyTools } from "./tools/companies.js";
 import { registerConfigurationTools } from "./tools/configurations.js";
+import { registerScheduleTools } from "./tools/schedule.js";
+import { registerFinanceTools } from "./tools/finance.js";
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
 export const SERVER_NAME = pkg.name;
 export const SERVER_VERSION = pkg.version;
+/** Maps each toolset key to the function that registers its tools. */
+const TOOLSETS = {
+    tickets: registerTicketTools,
+    time: registerTimeTools,
+    companies: registerCompanyTools,
+    configurations: registerConfigurationTools,
+    schedule: registerScheduleTools,
+    finance: registerFinanceTools,
+};
 const INSTRUCTIONS = `# ConnectWise PSA MCP server
 
 ## Finding things
@@ -32,7 +43,8 @@ const INSTRUCTIONS = `# ConnectWise PSA MCP server
 
 ## Notes
 - Lists are paginated; ask for more pages rather than huge page sizes.
-- A write may still fail if your ConnectWise security role forbids it.`;
+- A write may still fail if your ConnectWise security role forbids it.
+- Only the tools for this session's enabled toolsets are listed; other capabilities may exist on the server.`;
 export function createServer(config, session) {
     const client = new CWClient({
         site: config.site,
@@ -42,9 +54,8 @@ export function createServer(config, session) {
     });
     const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { instructions: INSTRUCTIONS });
     const reg = new ToolRegistrar(server);
-    registerTicketTools(reg, client);
-    registerTimeTools(reg, client);
-    registerCompanyTools(reg, client);
-    registerConfigurationTools(reg, client);
+    for (const key of session.toolsets) {
+        TOOLSETS[key](reg, client);
+    }
     return server;
 }

package/dist/tools/companies.js

@@ -106,4 +106,66 @@ export function registerCompanyTools(reg, client) {
             return failure(error);
         }
     });
+    reg.register({
+        name: "cw_get_contact",
+        title: "Get ConnectWise Contact",
+        description: "Get one contact with their phone numbers and email addresses (communication items).",
+        inputSchema: {
+            contact_id: z.number().int().positive().describe("The contact ID (from cw_search_contacts)"),
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const c = await client.getOne(`/company/contacts/${args.contact_id}`, "id,firstName,lastName,title,company/name,company/id,inactiveFlag,communicationItems");
+            if (args.response_format === "json")
+                return text(clip(json(c)));
+            const lines = [
+                `# ${c.firstName ?? ""} ${c.lastName ?? ""}${c.inactiveFlag ? " (inactive)" : ""}`.trim(),
+                "",
+                `- **Company**: ${c.company?.name ?? "?"}`,
+                `- **Title**: ${c.title ?? "—"}`,
+            ];
+            const comms = c.communicationItems ?? [];
+            if (comms.length) {
+                lines.push("", "## Contact methods");
+                for (const ci of comms)
+                    lines.push(`- ${ci.type?.name ?? ci.communicationType ?? "?"}: ${ci.value ?? ""}${ci.defaultFlag ? " (default)" : ""}`);
+            }
+            return text(clip(lines.join("\n")));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_list_company_sites",
+        title: "List ConnectWise Company Sites",
+        description: "List a company's sites (locations/addresses), with phone and timezone.",
+        inputSchema: {
+            company_id: z.number().int().positive().describe("The company ID"),
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const page = await client.getList(`/company/companies/${args.company_id}/sites`, {
+                fields: "id,name,addressLine1,city,stateReference/name,zip,phoneNumber,timeZone/name,inactiveFlag,primaryAddressFlag",
+                pageSize: 200,
+            });
+            if (page.items.length === 0)
+                return text(`No sites for company #${args.company_id}.`);
+            if (args.response_format === "json")
+                return text(clip(json(page.items)));
+            const lines = [`# Sites for company #${args.company_id} (${page.items.length})`, ""];
+            for (const s of page.items) {
+                const addr = [s.addressLine1, s.city, s.stateReference?.name, s.zip].filter(Boolean).join(", ");
+                lines.push(`- **${s.name ?? "?"}**${s.primaryAddressFlag ? " (primary)" : ""}${s.inactiveFlag ? " (inactive)" : ""}`, `  ${addr || "—"}${s.phoneNumber ? ` | ${s.phoneNumber}` : ""}${s.timeZone?.name ? ` | TZ: ${s.timeZone.name}` : ""}`);
+            }
+            return text(clip(lines.join("\n")));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
 }

package/dist/tools/finance.js

@@ -0,0 +1,202 @@
+/** Invoicing tools: invoices and agreements (read-only). */
+import { z } from "zod";
+import { allOf, q } from "../cw/client.js";
+import { clip, failure, json, pageFooter, pageNumberField, pageSizeField, responseFormatField, text, } from "./shared.js";
+const INVOICE_FIELDS = "id,invoiceNumber,type,status/name,company/name,company/id,date,dueDate,total,balance";
+const AGREEMENT_FIELDS = "id,name,type/name,company/name,company/id,agreementStatus,startDate,endDate,billAmount,cancelledFlag,noEndingDateFlag";
+function money(value) {
+    return value == null ? "—" : `$${value.toFixed(2)}`;
+}
+function invoiceLine(inv) {
+    return [
+        `#${inv.id} ${inv.invoiceNumber ?? "(no number)"} — ${inv.company?.name ?? "?"}`,
+        `  ${inv.status?.name ?? "?"} | ${inv.date ?? "?"}${inv.dueDate ? ` (due ${inv.dueDate})` : ""} | total ${money(inv.total)} | balance ${money(inv.balance)}`,
+    ].join("\n");
+}
+function agreementLine(a) {
+    const period = a.noEndingDateFlag ? `${a.startDate ?? "?"} → (ongoing)` : `${a.startDate ?? "?"} → ${a.endDate ?? "?"}`;
+    const status = a.cancelledFlag ? "cancelled" : (a.agreementStatus ?? "?");
+    return [
+        `#${a.id} ${a.name ?? "(unnamed)"} — ${a.company?.name ?? "?"}`,
+        `  ${a.type?.name ?? "?"} | ${status} | ${period} | ${money(a.billAmount)}`,
+    ].join("\n");
+}
+export function registerFinanceTools(reg, client) {
+    reg.register({
+        name: "cw_list_invoices",
+        title: "List ConnectWise Invoices",
+        description: "List invoices, optionally filtered by company, status, or invoice date range (YYYY-MM-DD). Read-only.",
+        inputSchema: {
+            company_id: z.number().int().positive().optional().describe("Filter by company ID"),
+            company_name: z.string().optional().describe("Filter by exact company name"),
+            status: z.string().optional().describe('Invoice status name (e.g. "Open", "Paid")'),
+            on_or_after: z.string().optional().describe("Invoice date on/after (YYYY-MM-DD)"),
+            on_or_before: z.string().optional().describe("Invoice date on/before (YYYY-MM-DD)"),
+            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.company_id !== undefined && `company/id=${args.company_id}`, args.company_name && `company/name=${q(args.company_name)}`, args.status && `status/name=${q(args.status)}`, args.on_or_after && `date>=[${args.on_or_after}]`, args.on_or_before && `date<=[${args.on_or_before}]`);
+            const page = await client.getList("/finance/invoices", {
+                conditions,
+                orderBy: "date desc",
+                fields: INVOICE_FIELDS,
+                page: args.page_number,
+                pageSize: args.page_size,
+            });
+            if (page.items.length === 0)
+                return text("No invoices found.");
+            if (args.response_format === "json")
+                return text(clip(json(page)));
+            const lines = [`# Invoices (${page.items.length} on this page)`, ""];
+            for (const inv of page.items)
+                lines.push(invoiceLine(inv), "");
+            lines.push(pageFooter(page.page, page.hasMore));
+            return text(clip(lines.join("\n")));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_get_invoice",
+        title: "Get ConnectWise Invoice",
+        description: "Get one invoice by ID. Read-only.",
+        inputSchema: {
+            invoice_id: z.number().int().positive().describe("The invoice ID"),
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const inv = await client.getOne(`/finance/invoices/${args.invoice_id}`, INVOICE_FIELDS);
+            if (args.response_format === "json")
+                return text(clip(json(inv)));
+            return text([
+                `# Invoice ${inv.invoiceNumber ?? inv.id}`,
+                "",
+                `- **Company**: ${inv.company?.name ?? "?"} (ID: ${inv.company?.id ?? "?"})`,
+                `- **Status**: ${inv.status?.name ?? "?"} | **Type**: ${inv.type ?? "—"}`,
+                `- **Date**: ${inv.date ?? "?"}${inv.dueDate ? ` | **Due**: ${inv.dueDate}` : ""}`,
+                `- **Total**: ${money(inv.total)} | **Balance**: ${money(inv.balance)}`,
+            ].join("\n"));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_list_agreements",
+        title: "List ConnectWise Agreements",
+        description: "List service agreements (contracts), optionally filtered by company or status. Read-only.",
+        inputSchema: {
+            company_id: z.number().int().positive().optional().describe("Filter by company ID"),
+            company_name: z.string().optional().describe("Filter by exact company name"),
+            status: z.string().optional().describe("Agreement status name"),
+            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.company_id !== undefined && `company/id=${args.company_id}`, args.company_name && `company/name=${q(args.company_name)}`, args.status && `agreementStatus=${q(args.status)}`);
+            const page = await client.getList("/finance/agreements", {
+                conditions,
+                orderBy: "name asc",
+                fields: AGREEMENT_FIELDS,
+                page: args.page_number,
+                pageSize: args.page_size,
+            });
+            if (page.items.length === 0)
+                return text("No agreements found.");
+            if (args.response_format === "json")
+                return text(clip(json(page)));
+            const lines = [`# Agreements (${page.items.length} on this page)`, ""];
+            for (const a of page.items)
+                lines.push(agreementLine(a), "");
+            lines.push(pageFooter(page.page, page.hasMore));
+            return text(clip(lines.join("\n")));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_get_agreement",
+        title: "Get ConnectWise Agreement",
+        description: "Get one agreement (contract) with its coverage limits and billing cycle. Read-only.",
+        inputSchema: {
+            agreement_id: z.number().int().positive().describe("The agreement ID (from cw_list_agreements)"),
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const a = await client.getOne(`/finance/agreements/${args.agreement_id}`, "id,name,type/name,company/name,company/id,agreementStatus,startDate,endDate,noEndingDateFlag,cancelledFlag,billAmount,billingCycle/name,applicationUnits,applicationLimit,applicationCycle,applicationUnlimitedFlag");
+            if (args.response_format === "json")
+                return text(clip(json(a)));
+            const period = a.noEndingDateFlag ? `${a.startDate ?? "?"} → (ongoing)` : `${a.startDate ?? "?"} → ${a.endDate ?? "?"}`;
+            const limit = a.applicationUnlimitedFlag
+                ? "unlimited"
+                : a.applicationLimit != null
+                    ? `${a.applicationLimit} ${a.applicationUnits ?? ""}${a.applicationCycle ? ` / ${a.applicationCycle}` : ""}`
+                    : "—";
+            return text([
+                `# ${a.name ?? `Agreement #${a.id}`}`,
+                "",
+                `- **Company**: ${a.company?.name ?? "?"}`,
+                `- **Type**: ${a.type?.name ?? "—"} | **Status**: ${a.cancelledFlag ? "cancelled" : (a.agreementStatus ?? "?")}`,
+                `- **Period**: ${period}`,
+                `- **Bill amount**: ${a.billAmount != null ? `$${a.billAmount.toFixed(2)}` : "—"}${a.billingCycle?.name ? ` / ${a.billingCycle.name}` : ""}`,
+                `- **Coverage**: ${limit}`,
+            ].join("\n"));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    reg.register({
+        name: "cw_list_unbilled_time",
+        title: "List Unbilled Time",
+        description: "List billable time entries not yet on an invoice — what's ready to bill. Filter by company " +
+            "or date range (YYYY-MM-DD). Read-only.",
+        inputSchema: {
+            company_id: z.number().int().positive().optional().describe("Filter by company ID"),
+            company_name: z.string().optional().describe("Filter by exact company name"),
+            on_or_after: z.string().optional().describe("Time entries on/after this date (YYYY-MM-DD)"),
+            on_or_before: z.string().optional().describe("Time entries on/before this date (YYYY-MM-DD)"),
+            page_number: pageNumberField,
+            page_size: pageSizeField,
+            response_format: responseFormatField,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => {
+        try {
+            const conditions = allOf('billableOption="Billable"', "invoiceFlag=false", args.company_id !== undefined && `company/id=${args.company_id}`, args.company_name && `company/name=${q(args.company_name)}`, args.on_or_after && `timeStart>=[${args.on_or_after}]`, args.on_or_before && `timeStart<=[${args.on_or_before}]`);
+            const page = await client.getList("/time/entries", {
+                conditions,
+                orderBy: "timeStart desc",
+                fields: "id,member/identifier,company/name,chargeToId,timeStart,actualHours,workType/name,notes",
+                page: args.page_number,
+                pageSize: args.page_size,
+            });
+            if (page.items.length === 0)
+                return text("No unbilled billable time found.");
+            if (args.response_format === "json")
+                return text(clip(json(page)));
+            const total = page.items.reduce((s, e) => s + (e.actualHours ?? 0), 0);
+            const lines = [`# Unbilled billable time (${page.items.length} entries, ${total.toFixed(2)}h shown)`, ""];
+            for (const e of page.items)
+                lines.push(`- ${e.company?.name ?? "?"} | ticket #${e.chargeToId ?? "?"} | ${e.member?.identifier ?? "?"} | ${e.actualHours ?? 0}h | ${e.timeStart?.slice(0, 10) ?? "?"}`);
+            lines.push("", pageFooter(page.page, page.hasMore));
+            return text(clip(lines.join("\n")));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+}