clokio-mcp 0.17.1 → 0.18.1

package/README.md

@@ -62,16 +62,18 @@ key. Use it only for a **shared or service key** whose issuer is not the person
 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 50 tools to 31. Optional groups are `tasks`,
-`employees` and `attendance` (which includes leave and time entries); combine
-them with commas. The `projects` group (project/client lookups, task statuses
+`CLOKIO_TOOLSETS=tasks`. This cuts the per-session tool-list cost - a
+task-focused session drops from 83 tools to 31. Optional groups are `tasks`,
+`employees`, `attendance` (which includes leave and time entries) and `docs`;
+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
 and labels, and `whoami`) is always on, because the task tools resolve names
 through it.
 
 ## Tools
 
-50 tools across five areas. Read-only tools carry the MCP `readOnlyHint`; writes
+83 tools across six areas. Read-only tools carry the MCP `readOnlyHint`; writes
 are marked mutating (deletes are `destructive`).
 
 | Area | Tools |
@@ -81,6 +83,7 @@ are marked mutating (deletes are `destructive`).
 | **Reference** | task statuses, task labels, locations, list webhooks (read-only), whoami |
 | **Employees** | list (name search), lookup by PIN, task-stats, inbox (mentions, new assignments, others' status changes), create, set status |
 | **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries, leaves, leave balances |
+| **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) |
 
 ### Conventions
 
@@ -107,10 +110,100 @@ are marked mutating (deletes are `destructive`).
   returns every occurrence of one series.
 - An API key sees **public custom fields only**.
 
+## Documents
+
+The Docs tools call `/api/v1/docs...` with the same `CLOKIO_API_KEY` as
+everything else, but documents are permissioned per **person**, so every
+docs call acts as one employee - the key's **effective actor**:
+
+- **The key's "acts as" employee**, when it has one (set in
+  **Settings > API keys**). Only an admin may make a key act as someone else.
+- **Otherwise, the person who created the key** - but only when the key lists
+  `docs:read` / `docs:write` **explicitly**. The wildcard `*` does not grant
+  docs scopes to a key with no acts-as employee, so an ordinary full-access
+  integration key never opens its creator's private documents.
+
+So, to use the Docs tools, either set an acts-as employee on the key, or add
+`docs:read` and `docs:write` to its scope list (it then acts as you, its
+creator). Otherwise every docs tool answers `403`, the same for every
+document id.
+
+**Scopes:** `docs:read` for the read tools (every `GET`) and `docs:write` for
+everything else. On a key with an acts-as employee the wildcard `*` grants
+both; a key with an explicit scope list must include them (otherwise `403`
+naming `required_scope`).
+
+The key then sees exactly what its acting employee sees and can do on the
+web, never more, and writes (comments, versions, activity) are attributed to
+that employee:
+
+- A document the employee cannot see answers **`404`**, the same as one that
+  does not exist (the API never confirms an id to someone not allowed to know it).
+- A visible document they may not change answers **`403`**.
+- The employee's role gates each call: `docs.view` for reads, `docs.create`
+  for content writes, `docs.manage` for delete and sharing. Per document,
+  roles are `view` < `comment` < `edit` < `admin`; each tool's description
+  names what it needs.
+
+| Tool | Endpoint |
+|------|----------|
+| `clokio_list_docs` | `GET /docs` |
+| `clokio_get_doc_tree` | `GET /docs?tree=1` |
+| `clokio_search_docs` | `GET /docs/search` |
+| `clokio_get_doc` | `GET /docs/{id}` |
+| `clokio_create_doc` | `POST /docs` |
+| `clokio_update_doc_content` | `PUT /docs/{id}/content` |
+| `clokio_update_doc_meta` | `PATCH /docs/{id}` |
+| `clokio_move_doc` | `POST /docs/{id}/move` |
+| `clokio_archive_doc` / `clokio_restore_doc` | `POST /docs/{id}/archive` / `restore` |
+| `clokio_delete_doc` | `DELETE /docs/{id}` |
+| `clokio_list_doc_templates` / `clokio_create_doc_from_template` | `GET /docs/templates` / `POST /docs/from-template` |
+| `clokio_list_doc_members` | `GET /docs/{id}/members` (members, teams, inherited, share link) |
+| `clokio_list_doc_shareable_teams` | `GET /docs/{id}/shareable-teams` |
+| `clokio_add_doc_member` / `clokio_update_doc_member` / `clokio_remove_doc_member` | `POST` / `PATCH` / `DELETE /docs/{id}/members` (by `employee_code`), or `PATCH` / `DELETE .../members/{employeeId}` |
+| `clokio_add_doc_team` / `clokio_update_doc_team` / `clokio_remove_doc_team` | `POST /docs/{id}/teams`, `PATCH` / `DELETE .../teams/{teamId}` |
+| `clokio_create_doc_share_link` / `clokio_revoke_doc_share_link` | `POST` / `DELETE /docs/{id}/share-link` |
+| `clokio_list_doc_comments` / `clokio_add_doc_comment` | `GET` / `POST /docs/{id}/comments` |
+| `clokio_resolve_doc_comment` / `clokio_reopen_doc_comment` | `POST .../comments/{commentId}/resolve` / `reopen` |
+| `clokio_list_doc_versions` / `clokio_get_doc_version` / `clokio_restore_doc_version` | `GET .../versions`, `GET .../versions/{versionId}`, `POST .../versions/{versionId}/restore` |
+| `clokio_list_doc_attachments` / `clokio_upload_doc_attachment` / `clokio_download_doc_attachment` | `GET` / `POST /docs/{id}/attachments`, `GET .../attachments/download?path=` |
+
+Working with documents:
+
+- **Every docs tool answers `{data}` or `{data, meta}`**, like the task tools:
+  the record or rows in `data`; paging, counts, your role and permissions in
+  `meta`. `clokio_get_doc` puts the record and its body together in `data`.
+- **Listing covers every scope by default.** `project_id` narrows it: a
+  project id, `"none"` for standalone documents only, or `"all"` (default).
+- **Read as Markdown, write as Markdown.** `clokio_get_doc` returns Markdown by
+  default (`format: "html"` or `"json"` for the others) without the title;
+  pass `include_title: true` to start the body with it as a heading. The
+  create/update tools take Markdown by default (`content_format: "html"` or
+  `"json"`); HTML you write must stay within Clokio's restricted grammar (a
+  `422` names any unsupported tag).
+- **Content writes are optimistic.** `clokio_update_doc_content` REPLACES the
+  whole body and requires `base_version` - the `content_version` you last read.
+  A `409` means someone else edited in between: re-read, reconcile, write
+  again with the new version. Never retry with the same `base_version`.
+- **Public share links expire after 30 days** unless you pass `expires_at` or
+  `never_expires: true`.
+- **Attachments** list `name`, `size`, `mime` and `uploaded_at`; download by
+  `path`. Uploading does not change the text: place the returned `url` in the
+  body yourself (an `image` or `fileAttachment` node in Tiptap JSON).
+- **Members are named by `employee_code`** (e.g. `"00080"`), like everywhere
+  else in this server; the internal `employee_id` is accepted as an
+  alternative. Teams are named by `team_id`, from
+  `clokio_list_doc_shareable_teams`. A member's `email` is shown only when the
+  key has `employees:pii`; profile pictures only with `include_avatars: true`.
+
 ## Security
 
 - The server contains **no secrets**. Your API key lives only in your local
   environment (`CLOKIO_API_KEY`), never in this code or repository.
+- The key is sent **only to `/api/v1`**: a path argument cannot steer a request
+  outside it, and the key is never forwarded on a redirect (attachment
+  downloads that redirect to signed storage are followed with no credential
+  attached).
 - The server **adds no permissions**. What a key can do is decided by the Clokio
   API from that key's scopes — this server only forwards the request. Scope each
   key to what its holder needs.

package/dist/attachments.js

@@ -7,7 +7,7 @@
  * credential and redirect handling. This module never fetches; it only decides
  * what to DO with what it was given.
  */
-import { ClokioApiError, looksLikeText, requestRawBytes } from './client.js';
+import { ClokioApiError, looksLikeText, requestRawBytes, } from './client.js';
 import { mcpContent } from './tools/helpers.js';
 /**
  * How much decoded text (PDF or text file) we return inline before truncating.
@@ -207,6 +207,29 @@ export async function saveBuffer(buffer, savePath, overwrite) {
  */
 export async function downloadAttachment(config, taskId, attachmentId, opts) {
     const { buffer, contentType } = await requestRawBytes(config, `/tasks/${taskId}/attachments/${attachmentId}`);
+    return renderDownload(buffer, contentType, opts);
+}
+/**
+ * Download one Docs attachment
+ * (GET /api/v1/docs/{id}/attachments/download?path=...) and hand it to
+ * the same renderer as a task attachment: save to disk, or PDF text / ZIP
+ * entries / image / text inline. `path` is the storage path the attachment
+ * listing returned; it travels as a QUERY value (URL-encoded by
+ * URLSearchParams), never as path segments, and the API 404s any path that is
+ * not one of this document's own uploads.
+ */
+export async function downloadDocAttachment(config, docId, storagePath, opts) {
+    const { buffer, contentType, fileName } = await requestRawBytes(config, `/docs/${docId}/attachments/download`, { path: storagePath });
+    // The type-detection hint: the caller's name, else what the response
+    // declared, else the last segment of the storage path.
+    const hint = opts.fileName ?? fileName ?? storagePath.split('/').pop();
+    return renderDownload(buffer, contentType, { ...opts, fileName: hint });
+}
+/**
+ * Turn downloaded bytes into the most useful result for their type. Shared by
+ * the task and doc downloads so both behave identically.
+ */
+async function renderDownload(buffer, contentType, opts) {
     const kb = (buffer.byteLength / 1024).toFixed(1);
     if (opts.savePath) {
         const abs = await saveBuffer(buffer, opts.savePath, opts.overwrite ?? false);

package/dist/client.js

@@ -1,10 +1,11 @@
 /**
  * The ONE place that talks to the Clokio Public API.
  *
- * Every tool goes through request(); nothing else builds a fetch. Auth is the
- * per-user `CLOKIO_API_KEY` sent as `X-API-Key`, exactly as the clokio-task CLI
- * does. The key carries its own scopes, so this server never re-implements
- * authorization — a 403/422 from the API is surfaced verbatim.
+ * Every tool goes through this module; nothing else builds a fetch. Auth is
+ * the per-user `CLOKIO_API_KEY` sent as `X-API-Key`, exactly as the
+ * clokio-task CLI does. The key carries its own scopes (and, for documents,
+ * its "acts as" employee), so this server never re-implements authorization -
+ * a 403/404/422 from the API is surfaced verbatim.
  */
 export function loadConfig() {
     const apiKey = process.env.CLOKIO_API_KEY?.trim();
@@ -21,6 +22,46 @@ export function loadConfig() {
     }
     return { baseUrl, apiKey, defaultActor };
 }
+/**
+ * Assemble an /api/v1 request URL and enforce the prefix guard.
+ *
+ * A tool argument interpolated into `path` must never be able to change
+ * WHICH endpoint is called. new URL() normalises the assembled string, so a
+ * value containing `?` truncates the path (turning `/employees/X/status`
+ * into `/employees/X/pin?...`) and `../` segments climb out of /api/v1.
+ * That is an endpoint pivot: a caller who approved "set employee status"
+ * would instead reach PATCH /employees/{code}/pin, which resets a person's
+ * clock-in PIN and returns it in the response. Callers wrap string arguments
+ * in seg(), but this is the invariant that holds even if one forgets.
+ */
+export function buildUrl(config, path) {
+    const url = new URL(`${config.baseUrl}/api/v1${path.startsWith('/') ? path : `/${path}`}`);
+    const expectedPrefix = new URL(config.baseUrl).pathname.replace(/\/+$/, '') + '/api/v1/';
+    if (!url.pathname.startsWith(expectedPrefix)) {
+        throw new ClokioApiError(0, 'Refusing to send a request outside /api/v1 - a path argument tried to change the endpoint.');
+    }
+    return url;
+}
+/**
+ * The file name a download response declares (Content-Disposition), or
+ * undefined. Used only as a type-detection hint and a default display name;
+ * a SAVE never trusts it as a path (see safeAttachmentName in attachments.ts).
+ */
+function dispositionFileName(header) {
+    if (!header)
+        return undefined;
+    const star = header.match(/filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/);
+    if (star) {
+        try {
+            return decodeURIComponent(star[1].trim().replace(/^"|"$/g, ''));
+        }
+        catch {
+            /* fall through to the plain form */
+        }
+    }
+    const plain = header.match(/filename\s*=\s*"?([^";]+)"?/);
+    return plain ? plain[1].trim() : undefined;
+}
 /**
  * Encode ONE path segment supplied by a tool argument.
  *
@@ -66,17 +107,15 @@ export function seg(value) {
  * path. `requestRaw` renders these bytes as text/description for the model;
  * the save-to-disk and typed-content tools consume the bytes directly.
  */
-export async function requestRawBytes(config, path) {
-    const url = new URL(`${config.baseUrl}/api/v1${path.startsWith('/') ? path : `/${path}`}`);
-    const expectedPrefix = new URL(config.baseUrl).pathname.replace(/\/+$/, '') + '/api/v1/';
-    if (!url.pathname.startsWith(expectedPrefix)) {
-        throw new ClokioApiError(0, 'Refusing to send a request outside /api/v1.');
-    }
+export async function requestRawBytes(config, path, query) {
+    const auth = { 'X-API-Key': config.apiKey };
+    const url = buildUrl(config, path);
+    applyQuery(url, query);
     let res;
     try {
-        // `manual`, not 'error' and not 'follow' - see the long note below.
+        // `manual`, not 'error' and not 'follow' - see the long note in requestRaw.
         res = await fetch(url, {
-            headers: { 'X-API-Key': config.apiKey },
+            headers: auth,
             redirect: 'manual',
         });
         if (res.status >= 300 && res.status < 400) {
@@ -111,8 +150,9 @@ export async function requestRawBytes(config, path) {
         throw new ClokioApiError(res.status, message);
     }
     const contentType = res.headers.get('content-type') ?? 'application/octet-stream';
+    const fileName = dispositionFileName(res.headers.get('content-disposition'));
     const buffer = Buffer.from(await res.arrayBuffer());
-    return { buffer, contentType };
+    return { buffer, contentType, fileName };
 }
 /**
  * Decide whether an attachment is text, from BOTH the content-type and the file
@@ -136,11 +176,8 @@ export function looksLikeText(contentType, fileName) {
         TEXT_EXTENSIONS.has(extension));
 }
 export async function requestRaw(config, path, fileName) {
-    const url = new URL(`${config.baseUrl}/api/v1${path.startsWith('/') ? path : `/${path}`}`);
-    const expectedPrefix = new URL(config.baseUrl).pathname.replace(/\/+$/, '') + '/api/v1/';
-    if (!url.pathname.startsWith(expectedPrefix)) {
-        throw new ClokioApiError(0, 'Refusing to send a request outside /api/v1.');
-    }
+    const auth = { 'X-API-Key': config.apiKey };
+    const url = buildUrl(config, path);
     let res;
     try {
         // `manual`, not 'error' and not 'follow'.
@@ -153,7 +190,7 @@ export async function requestRaw(config, path, fileName) {
         // path exists to prevent. So the redirect is followed HERE, by hand,
         // with no credential attached - the signed URL needs none.
         res = await fetch(url, {
-            headers: { 'X-API-Key': config.apiKey },
+            headers: auth,
             redirect: 'manual',
         });
         if (res.status >= 300 && res.status < 400) {
@@ -239,11 +276,8 @@ export async function requestRaw(config, path, fileName) {
 export async function requestUpload(config, path, filePath, fields = {}) {
     const { readFile } = await import('node:fs/promises');
     const { basename } = await import('node:path');
-    const url = new URL(`${config.baseUrl}/api/v1${path.startsWith('/') ? path : `/${path}`}`);
-    const expectedPrefix = new URL(config.baseUrl).pathname.replace(/\/+$/, '') + '/api/v1/';
-    if (!url.pathname.startsWith(expectedPrefix)) {
-        throw new ClokioApiError(0, 'Refusing to send a request outside /api/v1.');
-    }
+    const auth = { 'X-API-Key': config.apiKey };
+    const url = buildUrl(config, path);
     let bytes;
     try {
         bytes = await readFile(filePath);
@@ -265,7 +299,7 @@ export async function requestUpload(config, path, filePath, fields = {}) {
         // not set it by hand or the boundary is lost.
         res = await fetch(url, {
             method: 'POST',
-            headers: { 'X-API-Key': config.apiKey, Accept: 'application/json' },
+            headers: { ...auth, Accept: 'application/json' },
             body: form,
             redirect: 'error',
         });
@@ -273,24 +307,7 @@ export async function requestUpload(config, path, filePath, fields = {}) {
     catch (e) {
         throw new ClokioApiError(0, `Network error reaching Clokio: ${e.message}`);
     }
-    const text = await res.text();
-    let parsed;
-    try {
-        parsed = text ? JSON.parse(text) : undefined;
-    }
-    catch {
-        parsed = text;
-    }
-    if (!res.ok) {
-        const message = parsed && typeof parsed === 'object' && 'message' in parsed && typeof parsed.message === 'string'
-            ? parsed.message
-            : `Clokio API returned HTTP ${res.status}`;
-        throw new ClokioApiError(res.status, message, parsed);
-    }
-    if (parsed && typeof parsed === 'object' && 'data' in parsed) {
-        return parsed.data;
-    }
-    return parsed;
+    return parseEnvelope(res);
 }
 /** A Clokio API error, carrying the HTTP status and the server's message. */
 export class ClokioApiError extends Error {
@@ -311,32 +328,8 @@ export class ClokioApiError extends Error {
  */
 export async function request(config, path, options = {}) {
     const { method = 'GET', query, body } = options;
-    const url = new URL(`${config.baseUrl}/api/v1${path.startsWith('/') ? path : `/${path}`}`);
-    // A tool argument interpolated into `path` must never be able to change
-    // WHICH endpoint is called. new URL() normalises the assembled string, so a
-    // value containing `?` truncates the path (turning `/employees/X/status`
-    // into `/employees/X/pin?...`) and `../` segments climb out of /api/v1.
-    // That is an endpoint pivot: a caller who approved "set employee status"
-    // would instead reach PATCH /employees/{code}/pin, which resets a person's
-    // clock-in PIN and returns it in the response. Callers validate their own
-    // arguments, but this is the invariant that holds even if one forgets.
-    const expectedPrefix = new URL(config.baseUrl).pathname.replace(/\/+$/, '') + '/api/v1/';
-    if (!url.pathname.startsWith(expectedPrefix)) {
-        throw new ClokioApiError(0, 'Refusing to send a request outside /api/v1 - a path argument tried to change the endpoint.');
-    }
-    if (query) {
-        for (const [key, value] of Object.entries(query)) {
-            if (value === undefined || value === null)
-                continue;
-            if (Array.isArray(value)) {
-                for (const v of value)
-                    url.searchParams.append(`${key}[]`, String(v));
-            }
-            else {
-                url.searchParams.set(key, String(value));
-            }
-        }
-    }
+    const url = buildUrl(config, path);
+    applyQuery(url, query);
     const headers = {
         'X-API-Key': config.apiKey,
         Accept: 'application/json',
@@ -350,14 +343,32 @@ export async function request(config, path, options = {}) {
     try {
         // redirect: 'error' - Node's fetch follows redirects and RESENDS the
         // request headers, including X-API-Key, to wherever Location points, on
-        // any origin. The API never redirects an /api/v1 call, so a redirect here
-        // means something between us and it is not the API, and the key must not
-        // be handed over. Failing closed costs nothing on the happy path.
+        // any origin. The API never redirects a JSON /api/v1 call, so a redirect
+        // here means something between us and it is not the API, and the key
+        // must not be handed over. Failing closed costs nothing on the happy path.
         res = await fetch(url, { method, headers, body: payload, redirect: 'error' });
     }
     catch (e) {
         throw new ClokioApiError(0, `Network error reaching Clokio: ${e.message}`);
     }
+    return parseEnvelope(res);
+}
+function applyQuery(url, query) {
+    if (!query)
+        return;
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                url.searchParams.append(`${key}[]`, String(v));
+        }
+        else {
+            url.searchParams.set(key, String(value));
+        }
+    }
+}
+async function parseEnvelope(res) {
     const text = await res.text();
     let parsed = undefined;
     if (text) {

package/dist/index.js

@@ -2,9 +2,11 @@
 /**
  * clokio-mcp — an MCP server for the Clokio Public API.
  *
- * Exposes tasks, projects/clients, employees and attendance as MCP tools over
- * stdio. Auth is the per-user CLOKIO_API_KEY (an X-API-Key credential); the key
- * carries its own scopes, so this server never re-implements authorization.
+ * Exposes tasks, projects/clients, employees, attendance and documents as MCP
+ * tools over stdio. Auth is the per-user CLOKIO_API_KEY (an X-API-Key
+ * credential); the key carries its own scopes, so this server never
+ * re-implements authorization. Documents additionally need a key that "acts
+ * as" an employee - the API decides that, not this server.
  *
  * Run: CLOKIO_API_KEY=clk_... node dist/index.js
  * Or register with: claude mcp add clokio -- npx -y clokio-mcp
@@ -18,6 +20,7 @@ import { registerTaskTools } from './tools/tasks.js';
 import { registerProjectTools } from './tools/projects.js';
 import { registerEmployeeTools } from './tools/employees.js';
 import { registerAttendanceTools } from './tools/attendance.js';
+import { registerDocTools } from './tools/docs.js';
 /**
  * The optional tool groups a session can turn OFF.
  *
@@ -31,7 +34,7 @@ import { registerAttendanceTools } from './tools/attendance.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'];
+const OPTIONAL_TOOLSETS = ['tasks', 'employees', 'attendance', 'docs'];
 function selectedToolsets() {
     const raw = process.env.CLOKIO_TOOLSETS?.trim();
     if (!raw) {
@@ -65,6 +68,8 @@ async function main() {
         registerEmployeeTools(server, config);
     if (toolsets.has('attendance'))
         registerAttendanceTools(server, config);
+    if (toolsets.has('docs'))
+        registerDocTools(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/docs.js

@@ -0,0 +1,607 @@
+import { z } from 'zod';
+import { markdownToHtml } from '../markdown.js';
+import { ClokioApiError, request, requestUpload, seg } from '../client.js';
+import { downloadDocAttachment } from '../attachments.js';
+import { registerTool } from './helpers.js';
+/**
+ * The Docs module, on the Public API (/api/v1/docs...) with CLOKIO_API_KEY.
+ *
+ * Documents are permissioned per PERSON, so every docs request acts as one
+ * employee - the key's EFFECTIVE actor (backend ActsAsAuthority): its
+ * "acts as" employee, else the key's creator, the latter only when the key
+ * lists docs:read / docs:write EXPLICITLY ("*" is not enough for a key with
+ * no actor). The API decides everything else: an invisible document is 404,
+ * a visible one the actor may not change is 403.
+ *
+ * TOKEN BUDGET. tools/list is paid by every session, so the access rules are
+ * spelled out ONCE, on clokio_list_docs, and every other description points
+ * there ("Docs access: see clokio_list_docs"). Each description says only
+ * what the model needs to call the tool correctly: what it does, the doc
+ * role it needs, and any trap (base_version, the 30-day share link default).
+ *
+ * RESPONSE SHAPE. The API answers with named keys (`docs`, `doc`, `comment`,
+ * `comments`, ...). These tools reshape that into the envelope the task tools
+ * return - `{data}` or `{data, meta}` - so a model reads every Clokio tool the
+ * same way: the record or rows in `data`, paging / permissions / counts in
+ * `meta`. See shape*() below.
+ */
+const ACCESS = 'Docs access: see clokio_list_docs.';
+const docId = z.number().int().positive().describe('Document id');
+const CONTENT_FORMATS = ['markdown', 'html', 'json'];
+const contentArg = z
+    .union([z.string(), z.record(z.string(), z.unknown())])
+    .describe('Body. Markdown by default; html = Clokio\'s restricted HTML (a 422 names any unsupported tag); ' +
+    'json = Tiptap {"type":"doc","content":[...]}');
+const contentFormatArg = z.enum(CONTENT_FORMATS).optional().describe('markdown (default), html or json');
+const readFormatArg = z.enum(CONTENT_FORMATS).optional().describe('markdown (default), html or json');
+const includeTitleArg = z
+    .boolean()
+    .optional()
+    .describe('Markdown only: start the body with the title as a heading (default false)');
+const scopeArg = z
+    .union([z.number().int().positive(), z.literal('all'), z.literal('none')])
+    .optional()
+    .describe('Project id, "none" (standalone docs only) or "all" (default)');
+const archivedArg = z.enum(['exclude', 'include', 'only']).optional().describe('Default exclude');
+/**
+ * Map (content, content_format) onto the ONE content field the API accepts.
+ * Sending two content fields is a 422, so exactly one key is produced.
+ *
+ * An empty Markdown/HTML body becomes an empty Tiptap document: the server's
+ * request filter turns "" into null, which fails validation with a misleading
+ * "must be a string" message, and `{"type":"doc","content":[]}` is the
+ * documented way to clear a document.
+ */
+function contentBody(content, format = 'markdown') {
+    if (content === undefined)
+        return {};
+    if (format === 'json') {
+        let tree = content;
+        if (typeof content === 'string') {
+            try {
+                tree = JSON.parse(content);
+            }
+            catch (e) {
+                throw new ClokioApiError(0, `content is not valid JSON: ${e.message}`);
+            }
+        }
+        if (!tree || typeof tree !== 'object' || Array.isArray(tree)) {
+            throw new ClokioApiError(0, 'content_format "json" needs a Tiptap object {"type":"doc","content":[...]}.');
+        }
+        return { content: tree };
+    }
+    if (typeof content !== 'string') {
+        throw new ClokioApiError(0, `content_format "${format}" needs a string; pass content_format "json" to send a Tiptap object.`);
+    }
+    if (content.trim() === '') {
+        return { content: { type: 'doc', content: [] } };
+    }
+    return format === 'html' ? { content_html: content } : { content_markdown: content };
+}
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** `{data, meta}`, with meta left out when it would be empty. */
+export function envelope(data, meta) {
+    const m = meta ? Object.fromEntries(Object.entries(meta).filter(([, v]) => v !== undefined)) : {};
+    return Object.keys(m).length ? { data, meta: m } : { data };
+}
+/** Lift `key` out of the API's data object into `data`; every other key becomes meta. */
+export function liftKey(raw, key) {
+    if (!isObj(raw) || !(key in raw))
+        return envelope(raw);
+    const { [key]: data, ...rest } = raw;
+    // A nested meta (the list endpoints put paging in data.meta) is flattened
+    // into the same meta object rather than nested a second time.
+    const { meta: nested, ...others } = rest;
+    return envelope(data, { ...(isObj(nested) ? nested : {}), ...others });
+}
+/**
+ * A document read (live or a version): the record and its body together in
+ * `data` (the body sits BESIDE the record in the API, which is easy to miss),
+ * the reader's permissions and breadcrumbs in `meta`.
+ */
+export function shapeDocRead(raw, recordKey) {
+    if (!isObj(raw) || !isObj(raw[recordKey]))
+        return envelope(raw);
+    const { [recordKey]: record, ...rest } = raw;
+    const data = { ...record };
+    const meta = {};
+    for (const [k, v] of Object.entries(rest)) {
+        if (k === 'content' || k === 'content_html' || k === 'content_markdown')
+            data[k] = v;
+        else
+            meta[k] = v;
+    }
+    return envelope(data, meta);
+}
+/**
+ * Drop every profile_pic key, at any depth, unless avatars were asked for. A
+ * signed avatar URL is a few hundred characters per person and tells a model
+ * nothing.
+ */
+export function stripAvatars(rows, keep = false) {
+    if (keep)
+        return rows;
+    const strip = (v) => {
+        if (Array.isArray(v))
+            return v.map(strip);
+        if (!isObj(v))
+            return v;
+        const out = {};
+        for (const [k, val] of Object.entries(v)) {
+            if (k === 'profile_pic')
+                continue;
+            out[k] = strip(val);
+        }
+        return out;
+    };
+    return strip(rows);
+}
+/** Attachment rows with name / size / mime / uploaded_at first, null when the API omits one. */
+export function shapeAttachments(raw) {
+    const rows = isObj(raw) && Array.isArray(raw.attachments) ? raw.attachments : Array.isArray(raw) ? raw : null;
+    if (!rows)
+        return envelope(raw);
+    return envelope(rows.map((r) => {
+        if (!isObj(r))
+            return r;
+        const { name, size, mime, uploaded_at, ...rest } = r;
+        return { name: name ?? null, size: size ?? null, mime: mime ?? null, uploaded_at: uploaded_at ?? null, ...rest };
+    }));
+}
+// ---------------------------------------------------------------------- tools
+export function registerDocTools(server, config) {
+    // ---------------------------------------------------------------- reading
+    registerTool(server, config, {
+        name: 'clokio_list_docs',
+        description: 'List documents you can view (all scopes by default; project_id narrows). Rows include effective_role ' +
+            '(view/comment/edit/admin): edit or admin means you may write content. ' +
+            'DOCS ACCESS (applies to every clokio_*doc* tool): each call acts as the API key\'s "acts as" employee, ' +
+            'or, if the key has none, as the key\'s creator - only when the key lists docs:read / docs:write ' +
+            'explicitly ("*" is not enough). Otherwise every docs tool returns 403: set an acts-as employee or add ' +
+            'the docs scopes in Settings > API keys. Reads need scope docs:read, everything else docs:write. You see ' +
+            'exactly what that employee sees; a doc they cannot see is 404.',
+        schema: {
+            project_id: scopeArg,
+            parent_id: z
+                .union([z.number().int().positive(), z.literal('root')])
+                .optional()
+                .describe('A doc id to list its children, or "root" for top-level docs only'),
+            q: z.string().max(120).optional().describe('Title substring'),
+            archived: archivedArg,
+            page: z.number().int().min(1).optional(),
+            per_page: z.number().int().min(1).max(100).optional().describe('Default 50'),
+        },
+        handler: async (args, cfg) => liftKey(await request(cfg, '/docs', {
+            query: {
+                project_id: args.project_id ?? 'all',
+                parent_id: args.parent_id,
+                q: args.q,
+                archived: args.archived,
+                page: args.page,
+                per_page: args.per_page,
+            },
+        }), 'docs'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_doc_tree',
+        description: `Documents you can view as a nested tree (children), paged over the top level. ${ACCESS}`,
+        schema: {
+            project_id: scopeArg,
+            archived: archivedArg,
+            page: z.number().int().min(1).optional(),
+            per_page: z.number().int().min(1).max(100).optional(),
+        },
+        handler: async (args, cfg) => liftKey(await request(cfg, '/docs', {
+            query: {
+                tree: 1,
+                project_id: args.project_id ?? 'all',
+                archived: args.archived,
+                page: args.page,
+                per_page: args.per_page,
+            },
+        }), 'tree'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_search_docs',
+        description: `Search titles and body text (not archived), newest first; each row has a snippet. ${ACCESS}`,
+        schema: {
+            q: z.string().min(2).max(120),
+            project_id: z.number().int().positive().optional(),
+            limit: z.number().int().min(1).max(50).optional().describe('Default 20'),
+        },
+        handler: async (args, cfg) => liftKey(await request(cfg, '/docs/search', { query: { q: args.q, project_id: args.project_id, limit: args.limit } }), 'docs'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_doc',
+        description: 'Read a document: data = the record plus its body; meta = your role and breadcrumbs. Keep ' +
+            `data.content_version for clokio_update_doc_content. ${ACCESS}`,
+        schema: { id: docId, format: readFormatArg, include_title: includeTitleArg },
+        handler: async (args, cfg) => shapeDocRead(await request(cfg, `/docs/${seg(args.id)}`, {
+            query: { format: args.format ?? 'markdown', include_title: args.include_title ? 1 : undefined },
+        }), 'doc'),
+    });
+    // ---------------------------------------------------------------- writing
+    registerTool(server, config, {
+        name: 'clokio_create_doc',
+        description: 'Create a document. parent_id = sub-page (needs edit on the parent); project_id = in that project; ' +
+            'neither = standalone (org admins only). Starts at content_version 0. ' +
+            ACCESS,
+        mutates: true,
+        schema: {
+            title: z.string().min(1).max(255),
+            icon: z.string().max(10).optional().describe('One emoji'),
+            project_id: z.number().int().positive().optional(),
+            parent_id: z.number().int().positive().optional(),
+            content: contentArg.optional(),
+            content_format: contentFormatArg,
+        },
+        handler: async (args, cfg) => {
+            const body = {
+                title: args.title,
+                icon: args.icon,
+                project_id: args.project_id,
+                parent_id: args.parent_id,
+            };
+            // An empty body on create is simply an empty document: omit content.
+            const blank = typeof args.content === 'string' && args.content.trim() === '';
+            if (!blank)
+                Object.assign(body, contentBody(args.content, args.content_format));
+            return liftKey(await request(cfg, '/docs', { method: 'POST', body }), 'doc');
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_update_doc_content',
+        description: 'REPLACE the whole body (needs edit). base_version = the content_version you last read. On 409 do not ' +
+            'retry the same base_version: re-read, reconcile, write with the new version. Empty content clears. ' +
+            ACCESS,
+        mutates: true,
+        schema: {
+            id: docId,
+            content: contentArg,
+            content_format: contentFormatArg,
+            base_version: z.number().int().min(0),
+        },
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/content`, {
+            method: 'PUT',
+            body: { ...contentBody(args.content, args.content_format), base_version: args.base_version },
+        })),
+    });
+    registerTool(server, config, {
+        name: 'clokio_update_doc_meta',
+        description: 'Change metadata; send only what changes. title/icon/full_width/sort_order need edit; visibility, ' +
+            'inherit_permissions, is_archived need admin. Use clokio_move_doc for parent/project. ' +
+            ACCESS,
+        mutates: true,
+        schema: {
+            id: docId,
+            title: z.string().min(1).max(255).optional(),
+            icon: z.string().max(10).nullable().optional().describe('null clears'),
+            full_width: z.boolean().optional(),
+            sort_order: z.number().int().min(0).optional(),
+            visibility: z.enum(['private', 'project', 'organization']).optional(),
+            inherit_permissions: z.boolean().optional(),
+            is_archived: z.boolean().optional(),
+        },
+        handler: async (args, cfg) => {
+            const { id, ...fields } = args;
+            const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+            if (Object.keys(body).length === 0) {
+                throw new ClokioApiError(0, 'Nothing to change: pass at least one field.');
+            }
+            return liftKey(await request(cfg, `/docs/${seg(id)}`, { method: 'PATCH', body }), 'doc');
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_move_doc',
+        description: 'Move a document and its sub-pages (needs admin). Send both parent_id and project_id; null = top ' +
+            `level / standalone. With a parent, the parent's project wins. ${ACCESS}`,
+        mutates: true,
+        schema: {
+            id: docId,
+            parent_id: z.number().int().positive().nullable(),
+            project_id: z.number().int().positive().nullable(),
+            sort_order: z.number().int().min(0).optional(),
+        },
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/move`, {
+            method: 'POST',
+            body: { parent_id: args.parent_id, project_id: args.project_id, sort_order: args.sort_order },
+        }), 'doc'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_archive_doc',
+        description: `Archive a document (needs admin; reversible with clokio_restore_doc). ${ACCESS}`,
+        mutates: true,
+        schema: { id: docId },
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/archive`, { method: 'POST' }), 'doc'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_restore_doc',
+        description: `Un-archive a document (needs admin). ${ACCESS}`,
+        mutates: true,
+        schema: { id: docId },
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/restore`, { method: 'POST' }), 'doc'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_delete_doc',
+        description: `DELETE a document (needs admin and docs.manage; not restorable via the API - prefer archive). ${ACCESS}`,
+        mutates: 'destructive',
+        schema: { id: docId },
+        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}`, { method: 'DELETE' }),
+    });
+    // -------------------------------------------------------------- templates
+    registerTool(server, config, {
+        name: 'clokio_list_doc_templates',
+        description: `List document templates (key, name, description). ${ACCESS}`,
+        schema: {},
+        handler: async (_args, cfg) => liftKey(await request(cfg, '/docs/templates'), 'templates'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_create_doc_from_template',
+        description: `Create a top-level document from a template key. No project_id = standalone (admins only). ${ACCESS}`,
+        mutates: true,
+        schema: {
+            template: z.string().min(1).max(60),
+            title: z.string().max(255).optional(),
+            project_id: z.number().int().positive().optional(),
+        },
+        handler: async (args, cfg) => liftKey(await request(cfg, '/docs/from-template', {
+            method: 'POST',
+            body: { template: args.template, title: args.title, project_id: args.project_id },
+        }), 'doc'),
+    });
+    // ---------------------------------------------------------------- sharing
+    registerTool(server, config, {
+        name: 'clokio_list_doc_members',
+        description: 'Who a document is shared with (needs admin): data = members, teams, inherited (change those on the ' +
+            `parent); meta = visibility, inherit_permissions, share_link. ${ACCESS}`,
+        schema: {
+            id: docId,
+            include_avatars: z.boolean().optional().describe('Include profile pictures (default false)'),
+        },
+        handler: async (args, cfg) => {
+            const raw = await request(cfg, `/docs/${seg(args.id)}/members`, {
+                query: { include_avatars: args.include_avatars ? 1 : undefined },
+            });
+            if (!isObj(raw))
+                return envelope(raw);
+            const { members, teams, inherited, ...meta } = raw;
+            const keep = args.include_avatars === true;
+            return envelope({ members: stripAvatars(members, keep), teams, inherited: stripAvatars(inherited, keep) }, meta);
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_doc_shareable_teams',
+        description: `Teams this document can be shared with (needs admin); use id as team_id. ${ACCESS}`,
+        schema: { id: docId },
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/shareable-teams`), 'teams'),
+    });
+    const memberRole = z.enum(['view', 'comment', 'edit', 'admin']);
+    // A person is named by employee_code (preferred - the way every other tool
+    // here names people) OR by the internal employee_id. Exactly one.
+    const personArgs = {
+        employee_code: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -')
+            .optional()
+            .describe('Zero-padded, e.g. "00080" (preferred)'),
+        employee_id: z.number().int().positive().optional().describe('Internal id, instead of employee_code'),
+    };
+    /** Exactly one of employee_code / employee_id, as the API requires. */
+    function person(args) {
+        const hasCode = args.employee_code !== undefined;
+        const hasId = args.employee_id !== undefined;
+        if (hasCode === hasId) {
+            throw new ClokioApiError(0, 'Name the person with exactly one of employee_code (preferred) or employee_id.');
+        }
+        return hasCode ? { employee_code: args.employee_code } : { employee_id: args.employee_id };
+    }
+    registerTool(server, config, {
+        name: 'clokio_add_doc_member',
+        description: `Share a document with a person or change their role (needs admin; they are notified once). ${ACCESS}`,
+        mutates: true,
+        schema: { id: docId, ...personArgs, role: memberRole },
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/members`, {
+            method: 'POST',
+            body: { ...person(args), role: args.role },
+        })),
+    });
+    registerTool(server, config, {
+        name: 'clokio_update_doc_member',
+        description: `Change a person's direct role (needs admin; demoting the last admin is 422). ${ACCESS}`,
+        mutates: true,
+        schema: { id: docId, ...personArgs, role: memberRole },
+        handler: async (args, cfg) => {
+            const who = person(args);
+            // An id has its own path route; a code rides in the body of the
+            // collection route (PATCH /docs/{id}/members).
+            return envelope('employee_id' in who
+                ? await request(cfg, `/docs/${seg(args.id)}/members/${seg(who.employee_id)}`, {
+                    method: 'PATCH',
+                    body: { role: args.role },
+                })
+                : await request(cfg, `/docs/${seg(args.id)}/members`, {
+                    method: 'PATCH',
+                    body: { ...who, role: args.role },
+                }));
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_remove_doc_member',
+        description: `Remove a person's direct grant (needs admin; a code may name someone who has left). ${ACCESS}`,
+        mutates: 'destructive',
+        schema: { id: docId, ...personArgs },
+        handler: (args, cfg) => {
+            const who = person(args);
+            // A code travels in the query string of DELETE /docs/{id}/members (the
+            // API accepts body or query; a query survives any proxy that drops a
+            // DELETE body).
+            return 'employee_id' in who
+                ? request(cfg, `/docs/${seg(args.id)}/members/${seg(who.employee_id)}`, { method: 'DELETE' })
+                : request(cfg, `/docs/${seg(args.id)}/members`, {
+                    method: 'DELETE',
+                    query: { employee_code: who.employee_code },
+                });
+        },
+    });
+    const teamRole = z.enum(['view', 'comment', 'edit']);
+    const teamId = z.number().int().positive().describe('From clokio_list_doc_shareable_teams');
+    registerTool(server, config, {
+        name: 'clokio_add_doc_team',
+        description: `Share a document with a team (needs admin; teams cannot be admins). ${ACCESS}`,
+        mutates: true,
+        schema: { id: docId, team_id: teamId, role: teamRole },
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/teams`, {
+            method: 'POST',
+            body: { team_id: args.team_id, role: args.role },
+        })),
+    });
+    registerTool(server, config, {
+        name: 'clokio_update_doc_team',
+        description: `Change a team's role on a document (needs admin). ${ACCESS}`,
+        mutates: true,
+        schema: { id: docId, team_id: teamId, role: teamRole },
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/teams/${seg(args.team_id)}`, {
+            method: 'PATCH',
+            body: { role: args.role },
+        })),
+    });
+    registerTool(server, config, {
+        name: 'clokio_remove_doc_team',
+        description: `Remove a team's grant (needs admin). ${ACCESS}`,
+        mutates: 'destructive',
+        schema: { id: docId, team_id: teamId },
+        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/teams/${seg(args.team_id)}`, { method: 'DELETE' }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_create_doc_share_link',
+        description: 'Create or REPLACE the public read link (needs admin; the old URL stops working). Expires in 30 days ' +
+            `unless expires_at or never_expires is given. ${ACCESS}`,
+        mutates: true,
+        schema: {
+            id: docId,
+            expires_at: z.string().optional().describe('Future date or ISO 8601 timestamp'),
+            never_expires: z.boolean().optional().describe('No expiry (overrides the 30-day default)'),
+        },
+        handler: async (args, cfg) => {
+            if (args.never_expires && args.expires_at) {
+                throw new ClokioApiError(0, 'Pass expires_at or never_expires, not both.');
+            }
+            return envelope(await request(cfg, `/docs/${seg(args.id)}/share-link`, {
+                method: 'POST',
+                body: { expires_at: args.expires_at, never_expires: args.never_expires },
+            }));
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_revoke_doc_share_link',
+        description: `Revoke the public link (needs admin). ${ACCESS}`,
+        mutates: 'destructive',
+        schema: { id: docId },
+        handler: (args, cfg) => request(cfg, `/docs/${seg(args.id)}/share-link`, { method: 'DELETE' }),
+    });
+    // --------------------------------------------------------------- comments
+    registerTool(server, config, {
+        name: 'clokio_list_doc_comments',
+        description: `Comment threads, newest first, replies nested; meta has counts. ${ACCESS}`,
+        schema: {
+            id: docId,
+            filter: z.enum(['unresolved', 'resolved', 'all']).optional().describe('Default unresolved'),
+            block_id: z.string().max(40).optional(),
+        },
+        handler: async (args, cfg) => liftKey(stripAvatars(await request(cfg, `/docs/${seg(args.id)}/comments`, {
+            query: { filter: args.filter, block_id: args.block_id },
+        })), 'comments'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_add_doc_comment',
+        description: `Comment, or reply to a thread with parent_id (needs comment). Markdown or HTML; @Full Name notifies. ${ACCESS}`,
+        mutates: true,
+        schema: {
+            id: docId,
+            body: z.string().min(1).max(20000),
+            parent_id: z.number().int().positive().optional(),
+            block_id: z.string().max(40).optional(),
+        },
+        handler: async (args, cfg) => liftKey(stripAvatars(await request(cfg, `/docs/${seg(args.id)}/comments`, {
+            method: 'POST',
+            body: { body: markdownToHtml(args.body), parent_id: args.parent_id, block_id: args.block_id },
+        })), 'comment'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_resolve_doc_comment',
+        description: `Resolve a comment thread (needs comment). ${ACCESS}`,
+        mutates: true,
+        schema: { id: docId, comment_id: z.number().int().positive() },
+        handler: async (args, cfg) => liftKey(stripAvatars(await request(cfg, `/docs/${seg(args.id)}/comments/${seg(args.comment_id)}/resolve`, { method: 'POST' })), 'comment'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_reopen_doc_comment',
+        description: `Reopen a resolved comment thread (needs comment). ${ACCESS}`,
+        mutates: true,
+        schema: { id: docId, comment_id: z.number().int().positive() },
+        handler: async (args, cfg) => liftKey(stripAvatars(await request(cfg, `/docs/${seg(args.id)}/comments/${seg(args.comment_id)}/reopen`, { method: 'POST' })), 'comment'),
+    });
+    // --------------------------------------------------------------- versions
+    registerTool(server, config, {
+        name: 'clokio_list_doc_versions',
+        description: `Version history, newest first. Pass a row's id (not its version number) to the other version tools. ${ACCESS}`,
+        schema: { id: docId },
+        handler: async (args, cfg) => liftKey(await request(cfg, `/docs/${seg(args.id)}/versions`), 'versions'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_doc_version',
+        description: `Read one version snapshot. ${ACCESS}`,
+        schema: {
+            id: docId,
+            version_id: z.number().int().positive(),
+            format: readFormatArg,
+            include_title: includeTitleArg,
+        },
+        handler: async (args, cfg) => shapeDocRead(await request(cfg, `/docs/${seg(args.id)}/versions/${seg(args.version_id)}`, {
+            query: { format: args.format ?? 'markdown', include_title: args.include_title ? 1 : undefined },
+        }), 'version'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_restore_doc_version',
+        description: `Restore a snapshot over the content (needs edit). content_version moves: use the returned one. ${ACCESS}`,
+        mutates: true,
+        schema: { id: docId, version_id: z.number().int().positive() },
+        handler: async (args, cfg) => envelope(await request(cfg, `/docs/${seg(args.id)}/versions/${seg(args.version_id)}/restore`, { method: 'POST' })),
+    });
+    // ------------------------------------------------------------ attachments
+    registerTool(server, config, {
+        name: 'clokio_list_doc_attachments',
+        description: `Files uploaded to a document: name, size, mime, uploaded_at, path (for download). ${ACCESS}`,
+        schema: { id: docId },
+        handler: async (args, cfg) => shapeAttachments(await request(cfg, `/docs/${seg(args.id)}/attachments`)),
+    });
+    registerTool(server, config, {
+        name: 'clokio_upload_doc_attachment',
+        description: 'Upload a LOCAL file (needs edit). kind file (default, 100 MB) or media (images/video, 50 MB). Does not ' +
+            `change the text: reference the returned url in the body yourself. ${ACCESS}`,
+        mutates: true,
+        schema: {
+            id: docId,
+            file_path: z.string().describe('Path on THIS machine'),
+            kind: z.enum(['file', 'media']).optional(),
+        },
+        handler: async (args, cfg) => envelope(await requestUpload(cfg, `/docs/${seg(args.id)}/attachments`, args.file_path, { kind: args.kind ?? 'file' })),
+    });
+    registerTool(server, config, {
+        name: 'clokio_download_doc_attachment',
+        description: 'Download an attachment by its path. save_path writes it to disk; otherwise text, PDF text, ZIP entries ' +
+            `or an image come back inline. ${ACCESS}`,
+        schema: {
+            id: docId,
+            path: z.string().min(1).max(1024).describe('`path` from clokio_list_doc_attachments'),
+            file_name: z.string().optional().describe('`name` from the listing (type detection)'),
+            save_path: z.string().optional(),
+            overwrite: z.boolean().optional().describe('Replace an existing save_path file'),
+        },
+        handler: (args, cfg) => downloadDocAttachment(cfg, args.id, args.path, {
+            fileName: args.file_name,
+            savePath: args.save_path,
+            overwrite: args.overwrite,
+        }),
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clokio-mcp",
-  "version": "0.17.1",
-  "description": "Model Context Protocol (MCP) server for Clokio — manage tasks, projects, clients, employees and attendance from Claude and any MCP client.",
+  "version": "0.18.1",
+  "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": {
     "clokio-mcp": "dist/index.js"
@@ -26,7 +26,8 @@
     "attendance",
     "task-management",
     "project-management",
-    "time-tracking"
+    "time-tracking",
+    "documents"
   ],
   "author": "Matat Technologies LTD",
   "license": "MIT",