clokio-mcp 0.33.0 → 0.34.0

package/README.md

@@ -90,8 +90,8 @@ acting. An explicit code on a tool call always takes precedence.
 Optional: set `CLOKIO_TOOLSETS` to register only the tool groups you need, e.g.
 `CLOKIO_TOOLSETS=tasks`. This cuts the per-session tool-list cost - a
 task-focused session drops from 137 tools to 48. Optional groups are `tasks`,
-`employees`, `attendance` (which includes leave, time entries and logging time), `docs` and
-`tickets`;
+`employees`, `attendance` (which includes leave, time entries and logging time), `docs`,
+`tickets` and `invoices` (read only: needs `invoices:read` and billing access);
 combine them with commas. If your key cannot open documents (no acts-as
 employee and no explicit docs scopes), leaving `docs` out saves 33 tools it
 cannot use. The `projects` group (project/client lookups, task statuses
@@ -112,6 +112,7 @@ are marked mutating (deletes are `destructive`).
 | **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries (local times in the person's zone; edit / delete your own), leaves (with `days`, half days counted 0.5), days of leave taken per type and year (`clokio_get_leave_days_taken`; the old name `clokio_get_leave_balances` still works; Clokio tracks no quota or remaining balance; leave and time-entry lists take `employee_code` and at most 92 days per call), **log time on a task**, start / stop / read the timer (see [Logging time](#logging-time)) |
 | **Documents** (see [Documents](#documents) for who a key acts as) | list, tree, search, get (Markdown / HTML / JSON), create, replace content, update meta, move, archive, restore, delete, templates + create from template, members (by `employee_code`) and teams (list/add/update/remove, shareable teams), public share link, comments (list/add/resolve/reopen), versions (list/get/restore), attachments (list/upload/download) |
 | **Tickets** (see [Tickets](#tickets)) | list (filters incl. several labels, created dates, needs reply, sort + cursor), **open a new ticket by email or WhatsApp template** (sent, or as a draft a person sends; `Idempotency-Key` per call, `destructive`), a WhatsApp number's approved templates with the slots to fill, get (with its newest messages; internal notes labelled, everything the customer wrote wrapped as untrusted), more messages, **reply to the customer** (fresh `Idempotency-Key` per call, `destructive`), **files on an outgoing email** (`file_paths` or `attachment_ids` on a new email and a reply), internal note (with mentions), update state / assignee (resolve without the satisfaction survey), **a contact's client with its projects, open tasks and recently done tasks** ("what is the status of my task?"), add / remove one label, contacts list / get / create / update, inboxes, ticket labels (list / create), saved replies, download a file a customer sent, save / delete your own reply draft, list the tasks opened from a ticket, **open a task from a ticket** (with its files; `Idempotency-Key` per call), **reports** (overview, agents, satisfaction + its ratings, workload) |
+| **Invoices** (`invoices` toolset, read only) | list invoices (client, number, months, several statuses), get one (with `include_employees`), a task's billing, a client's month-by-month billing summary, one month across all clients, what a client has unbilled in a month. Needs `invoices:read` and billing access for the key's person; "paid" is a status set in Clokio, not a payment record; totals are per currency; no iCount data |
 
 ### Conventions
 

package/dist/index.js

@@ -18,6 +18,7 @@ import { ClokioApiError, loadConfig, request } from './client.js';
 import { VERSION } from './version.js';
 import { registerTaskTools } from './tools/tasks.js';
 import { registerProjectTools } from './tools/projects.js';
+import { registerInvoiceTools } from './tools/invoices.js';
 import { registerEmployeeTools } from './tools/employees.js';
 import { registerAttendanceTools } from './tools/attendance.js';
 import { registerDocTools } from './tools/docs.js';
@@ -36,7 +37,7 @@ import { registerTicketTools } from './tools/tickets.js';
  * to resolve names to ids, so it is always registered. Naming a toolset that
  * does not exist is refused at startup rather than silently ignored.
  */
-const OPTIONAL_TOOLSETS = ['tasks', 'employees', 'attendance', 'docs', 'tickets'];
+const OPTIONAL_TOOLSETS = ['tasks', 'employees', 'attendance', 'docs', 'tickets', 'invoices'];
 function selectedToolsets() {
     const raw = process.env.CLOKIO_TOOLSETS?.trim();
     if (!raw) {
@@ -125,6 +126,8 @@ async function main() {
         registerDocTools(server, config);
     if (toolsets.has('tickets'))
         registerTicketTools(server, config);
+    if (toolsets.has('invoices'))
+        registerInvoiceTools(server, config);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // stderr is safe for logs on stdio transport (stdout carries the protocol).

package/dist/tools/invoices.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { request } from '../client.js';
+import { registerTool } from './helpers.js';
+/**
+ * The read-only invoices toolset (0.34.0). Every tool is a GET over the
+ * backend's /invoices family; nothing here creates, sends, marks paid or
+ * cancels an invoice.
+ */
+const ACCESS = 'Needs the invoices:read scope AND billing access for the key\'s person (otherwise 403 NO_BILLING_ACCESS). ' +
+    'Read only. These are Clokio\'s own invoices; no iCount data. "paid" is a status someone set in Clokio, ' +
+    'not a payment record.';
+const month = (what) => z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/, 'month must be YYYY-MM (month 01-12)').describe(what);
+const id = z.number().int().positive();
+const includeEmployees = z
+    .boolean()
+    .optional()
+    .describe('true: each line also lists who worked it and for how many hours (include=employees); ' +
+    'a task line lists everyone who worked that task in the period, even when the task is split over several lines.');
+export function registerInvoiceTools(server, config) {
+    registerTool(server, config, {
+        name: 'clokio_list_invoices',
+        description: 'List Clokio invoices, newest first, optionally by client, exact number, period months and status. ' +
+            'Paginated: {data, meta}. ' + ACCESS,
+        schema: {
+            client_id: id.optional(),
+            number: z.string().min(1).max(50).optional().describe('Exact invoice number, e.g. INV-0012'),
+            from_month: month('First period month, YYYY-MM').optional(),
+            to_month: month('Last period month, YYYY-MM; at most 24 months after from_month').optional(),
+            status: z.array(z.enum(['draft', 'finalized', 'sent', 'paid', 'cancelled'])).min(1).optional()
+                .describe('One or more statuses'),
+            per_page: z.number().int().min(1).max(100).optional(),
+            page: z.number().int().min(1).optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/invoices', {
+            query: {
+                client_id: args.client_id,
+                number: args.number,
+                from_month: args.from_month,
+                to_month: args.to_month,
+                status: args.status,
+                per_page: args.per_page,
+                page: args.page,
+            },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_invoice',
+        description: 'One invoice with its lines (include_employees adds who worked each line). ' + ACCESS,
+        schema: { id, include_employees: includeEmployees },
+        handler: (args, cfg) => request(cfg, `/invoices/${args.id}`, { query: { include: args.include_employees ? 'employees' : undefined } }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_task_billing',
+        description: "A task's billing history: its invoice lines (newest period first), totals by status, and its unbilled hours and months. Amounts are keyed by currency. " + ACCESS,
+        schema: { task_id: id },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.task_id}/billing`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_client_billing_summary',
+        description: "A client's month-by-month billing (every month in the span, default the last 12 full months, at most 24): " +
+            'per month the invoice, billable hours and estimated amount; totals keyed by currency. Money totals are per currency, never summed ' +
+            'across currencies. ' + ACCESS,
+        schema: {
+            client_id: id,
+            from_month: month('First month, YYYY-MM').optional(),
+            to_month: month('Last month, YYYY-MM').optional(),
+        },
+        handler: (args, cfg) => request(cfg, `/clients/${args.client_id}/billing-summary`, {
+            query: { from_month: args.from_month, to_month: args.to_month },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_billing_month',
+        description: 'One month across all clients, as the web /invoices screen: per client hours, estimated amount and invoice, the client ids not yet invoiced, and totals. Money totals are per currency, never summed. ' +
+            ACCESS,
+        schema: { month: month('The month, YYYY-MM; not in the future') },
+        handler: (args, cfg) => request(cfg, '/invoices/month', { query: { month: args.month } }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_client_unbilled',
+        description: "What is still unbilled for a client in a month: the web invoice review's lines, from finished web-timer entries; " +
+            'non-billable ones appear with is_billable false and price 0; subtotal counts billable lines only. client_id 0 is the "No Client" bucket. If an invoice already exists for that month the ' +
+            'answer is existing_invoice and no lines. Amounts are in one currency per answer; each line carries its own. ' +
+            ACCESS,
+        schema: {
+            client_id: z.number().int().min(0),
+            month: month('The month, YYYY-MM; not in the future'),
+            include_employees: includeEmployees,
+        },
+        handler: (args, cfg) => request(cfg, `/clients/${args.client_id}/unbilled`, {
+            query: { month: args.month, include: args.include_employees ? 'employees' : undefined },
+        }),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clokio-mcp",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Model Context Protocol (MCP) server for Clokio - manage tasks, projects, clients, employees, attendance and documents from Claude and any MCP client.",
   "type": "module",
   "bin": {