clokio-mcp 0.33.0 → 0.35.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, minimum total; rows carry billable hours), get one (with `include_employees` and `include_activities`; lines carry `task_state` and `missing_rate`), a task's billing (with a `note` when it bills nothing), a client's month-by-month billing summary, one month across all clients (**compact by default**, filters for clients, not invoiced, dismissed, minimum billable hours), what a client has unbilled in a month. Month rows carry `amount` (the invoice's own numbers, or the same estimate as the unbilled tool) beside the deprecated `estimated_amount`; `invoiced` / `total` count issued invoices only, drafts are `draft`; the No Client bucket is client id 0. 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 beyond the number stored as `invoice_number` (the provider's document number when an invoicing integration finalized the invoice) |
 
 ### 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,138 @@
+import { z } from 'zod';
+import { request } from '../client.js';
+import { registerTool } from './helpers.js';
+/**
+ * The read-only invoices toolset (0.34.0; round 2 in 0.35.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 beyond the number stored as invoice_number. "paid" is a status someone set in Clokio, ' +
+    'not a payment record.';
+const NO_CLIENT = 'The "No Client" bucket is client id 0 everywhere (client {id: 0, name: "No Client"}). ';
+const AMOUNT = 'Each row has amount {source, subtotal, vat_amount, total, currency}: source "invoice" is the invoice\'s own numbers, ' +
+    'source "estimate" is exactly what clokio_get_client_unbilled answers for that client and month (VAT at the organisation rate). ' +
+    'Use amount, not estimated_amount: estimated_amount is the screen\'s figure, deprecated (the invoice total WITH VAT, or hours times rates ' +
+    'WITHOUT VAT, rounded differently). Compact rows (clokio_get_billing_month by default) carry only amount {source, total, currency}. ' +
+    'missing_rate is true when billable hours have no rate (amount 0). ';
+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 ' +
+    '(employees_scope "task"); a task-less line lists that line\'s people (employees_scope "line").');
+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, status and minimum total. ' +
+            'Rows carry billable_hours (sum of the billable lines). invoice_number is the number Clokio stored at finalize: ' +
+            'INV-<year>-<seq> style without an invoicing integration, the provider\'s document number (plain digits) with one. ' +
+            'client_id 0 lists the invoices with no client. ' + NO_CLIENT +
+            'Paginated: {data, meta}. ' + ACCESS,
+        schema: {
+            client_id: z.number().int().min(0).optional().describe('Only this client; 0 = invoices with no client'),
+            number: z.string().min(1).max(50).optional().describe('Exact invoice number, e.g. INV-2026-0012 (Clokio\'s own) or 3529 (a provider document number)'),
+            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'),
+            min_total: z.number().min(0).optional().describe('Only invoices whose total is at least this (in each invoice\'s own currency)'),
+            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,
+                min_total: args.min_total,
+                per_page: args.per_page,
+                page: args.page,
+            },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_invoice',
+        description: 'One invoice with its lines and activity_count (include_employees adds who worked each line; include_activities adds the activity trail). ' +
+            'Each line has task_state: "linked" (the task exists), "deleted" (the task was deleted or is gone; the stored title still shows), ' +
+            '"none" (no task), and missing_rate (billable hours with no price). ' + NO_CLIENT + ACCESS,
+        schema: {
+            id,
+            include_employees: includeEmployees,
+            include_activities: z.boolean().optional().describe('true: also return the activity trail (include=activities). Default false: only activity_count.'),
+        },
+        handler: (args, cfg) => {
+            const include = [args.include_employees ? 'employees' : null, args.include_activities ? 'activities' : null].filter(Boolean).join(',');
+            return request(cfg, `/invoices/${args.id}`, { query: { include: include || 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. " +
+            'note says why the hours may bill nothing: "no_client" (the project has no client), "project_not_billable", or null. ' + NO_CLIENT + 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, amount and missing_rate; totals keyed by currency: invoiced counts ISSUED invoices only ' +
+            '(finalized + sent + paid), draft is the drafts\' total, plus marked_paid, outstanding and overdue_count. Money totals are per currency, never summed ' +
+            'across currencies. ' + AMOUNT + 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, amount and invoice, the client ids not yet invoiced (not_invoiced, 0 = No Client), and totals. ' +
+            'COMPACT BY DEFAULT: the full answer is large enough to overflow an agent, so this tool sends compact=1 unless compact is false ' +
+            '(compact rows: client, billable_hours, amount {source, total, currency}, invoice {id, status}, dismissed, missing_rate). ' +
+            'Filters client_ids, only_not_invoiced, exclude_dismissed, min_billable_hours; rows, not_invoiced and totals are computed over the FILTERED rows. ' +
+            'totals per currency: total = ISSUED invoices only (finalized + sent + paid), draft = the drafts, pending = finalized + sent, overdue_count. Money totals are per currency, never summed. ' +
+            AMOUNT + NO_CLIENT + ACCESS,
+        schema: {
+            month: month('The month, YYYY-MM; not in the future'),
+            client_ids: z.array(z.number().int().min(0)).min(1).max(500).optional().describe('Only these clients; 0 = the No Client bucket'),
+            only_not_invoiced: z.boolean().optional().describe('true: only clients with billable hours, no invoice and not dismissed'),
+            exclude_dismissed: z.boolean().optional().describe('true: leave dismissed clients out'),
+            min_billable_hours: z.number().min(0).optional().describe('Only clients with at least this many billable hours'),
+            compact: z.boolean().optional().describe('Default true (smaller rows). false: the full rows (total_hours, projects, estimated_amount, the full amount, the invoice number and total).'),
+        },
+        handler: (args, cfg) => request(cfg, '/invoices/month', {
+            query: {
+                month: args.month,
+                client_ids: args.client_ids,
+                only_not_invoiced: args.only_not_invoiced === undefined ? undefined : args.only_not_invoiced ? 1 : 0,
+                exclude_dismissed: args.exclude_dismissed === undefined ? undefined : args.exclude_dismissed ? 1 : 0,
+                min_billable_hours: args.min_billable_hours,
+                compact: args.compact === false ? 0 : 1,
+            },
+        }),
+    });
+    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. ' +
+            'Each line has missing_rate (billable hours with no rate). ' + NO_CLIENT +
+            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.35.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": {