clokio-mcp 0.28.1 → 0.29.1

package/README.md

@@ -49,6 +49,30 @@ Add to `claude_desktop_config.json`:
 }
 ```
 
+### Acting as yourself: an employee key
+
+An admin `clk_` key reaches the whole organisation. If you are not an admin, or you want
+every write bound by **your own** roles and project permissions, use a personal employee key
+instead - any employee can issue one at **Profile → API keys**:
+
+```bash
+claude mcp add clokio \
+  --env CLOKIO_EMPLOYEE_KEY=your_personal_key \
+  -- npx -y clokio-mcp@latest
+```
+
+Set exactly one of `CLOKIO_API_KEY` / `CLOKIO_EMPLOYEE_KEY`. In employee mode the server
+talks to `/api/employee` with `X-Employee-Key`, announces who it is acting as at startup
+(`acting as Anil Pujara (00081)`), and fails there if the key is revoked or expired. It
+registers only what that surface allows: your assigned-task queue, reading and creating
+tasks where you may, updating, commenting, attachments, logging time, and the whole Docs
+module. Nothing takes an `employee_code` to credit a writer: the key is the identity, and a
+`403` from Clokio means you may not do that in that project. `CLOKIO_TOOLSETS` may name
+`tasks` and/or `docs` (`clokio_whoami` and `clokio_list_projects` are always on);
+`CLOKIO_DEFAULT_ACTOR` is refused. Employee mode needs a Clokio server with
+`GET /api/employee/me` (app.clokio.io has it since 2026-10-26). If the startup check cannot
+reach Clokio, the server says so and does not blame the key.
+
 ### Cursor / Cline / Zed / any MCP client
 
 Use the same command - `npx -y clokio-mcp@latest` with `CLOKIO_API_KEY` in the env.

package/dist/client.js

@@ -8,19 +8,38 @@
  * a 403/404/422 from the API is surfaced verbatim.
  */
 export function loadConfig() {
-    const apiKey = process.env.CLOKIO_API_KEY?.trim();
-    if (!apiKey) {
-        throw new Error('CLOKIO_API_KEY is not set. Provide your Clokio API key (clk_...) via the ' +
-            'CLOKIO_API_KEY environment variable.');
+    const adminKey = process.env.CLOKIO_API_KEY?.trim();
+    const employeeKey = process.env.CLOKIO_EMPLOYEE_KEY?.trim();
+    if (adminKey && employeeKey) {
+        throw new Error('Both CLOKIO_API_KEY and CLOKIO_EMPLOYEE_KEY are set. Set exactly one: CLOKIO_API_KEY for the ' +
+            'organisation-wide Public API (admin, clk_...), or CLOKIO_EMPLOYEE_KEY to act as one person with ' +
+            'their own permissions.');
     }
+    if (!adminKey && !employeeKey) {
+        throw new Error('No Clokio key is set. Provide CLOKIO_API_KEY (an admin Public API key, clk_...) or ' +
+            'CLOKIO_EMPLOYEE_KEY (a personal key from Profile -> API keys, acts as you with your own permissions).');
+    }
+    const mode = employeeKey ? 'employee' : 'admin';
+    const apiKey = (employeeKey ?? adminKey);
     const baseUrl = (process.env.CLOKIO_BASE_URL?.trim() || 'https://app.clokio.io').replace(/\/+$/, '');
     const defaultActor = process.env.CLOKIO_DEFAULT_ACTOR?.trim() || undefined;
     // Validate the same way the API constrains an employee_code, so a
     // misconfigured value fails at startup rather than silently on every write.
+    if (defaultActor && mode === 'employee') {
+        throw new Error('CLOKIO_DEFAULT_ACTOR has no meaning with CLOKIO_EMPLOYEE_KEY: the key already IS the actor. Unset it.');
+    }
     if (defaultActor && !/^[A-Za-z0-9_-]{1,50}$/.test(defaultActor)) {
         throw new Error('CLOKIO_DEFAULT_ACTOR must be an employee_code (1-50 chars of letters, digits, _ or -).');
     }
-    return { baseUrl, apiKey, defaultActor };
+    return { baseUrl, mode, apiKey, defaultActor };
+}
+/** The URL prefix the mode talks to. */
+export function apiPrefix(config) {
+    return config.mode === 'employee' ? '/api/employee' : '/api/v1';
+}
+/** The one header that authenticates the mode's key. */
+export function authHeaders(config) {
+    return config.mode === 'employee' ? { 'X-Employee-Key': config.apiKey } : { 'X-API-Key': config.apiKey };
 }
 /**
  * Assemble an /api/v1 request URL and enforce the prefix guard.
@@ -35,10 +54,11 @@ export function loadConfig() {
  * 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/';
+    const prefix = apiPrefix(config);
+    const url = new URL(`${config.baseUrl}${prefix}${path.startsWith('/') ? path : `/${path}`}`);
+    const expectedPrefix = new URL(config.baseUrl).pathname.replace(/\/+$/, '') + prefix + '/';
     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.');
+        throw new ClokioApiError(0, `Refusing to send a request outside ${prefix} - a path argument tried to change the endpoint.`);
     }
     return url;
 }
@@ -108,7 +128,7 @@ export function seg(value) {
  * the save-to-disk and typed-content tools consume the bytes directly.
  */
 export async function requestRawBytes(config, path, query) {
-    const auth = { 'X-API-Key': config.apiKey };
+    const auth = authHeaders(config);
     const url = buildUrl(config, path);
     applyQuery(url, query);
     let res;
@@ -176,7 +196,7 @@ export function looksLikeText(contentType, fileName) {
         TEXT_EXTENSIONS.has(extension));
 }
 export async function requestRaw(config, path, fileName) {
-    const auth = { 'X-API-Key': config.apiKey };
+    const auth = authHeaders(config);
     const url = buildUrl(config, path);
     let res;
     try {
@@ -276,7 +296,7 @@ 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 auth = { 'X-API-Key': config.apiKey };
+    const auth = authHeaders(config);
     const url = buildUrl(config, path);
     let bytes;
     try {
@@ -327,12 +347,12 @@ export class ClokioApiError extends Error {
  * the server's own message.
  */
 export async function request(config, path, options = {}) {
-    const { method = 'GET', query, body, headers: extra, onHeaders } = options;
+    const { method = 'GET', query, body, headers: extra, onHeaders, timeoutMs } = options;
     const url = buildUrl(config, path);
     applyQuery(url, query);
     const headers = {
         ...(extra ?? {}),
-        'X-API-Key': config.apiKey,
+        ...authHeaders(config),
         Accept: 'application/json',
     };
     let payload;
@@ -347,7 +367,13 @@ export async function request(config, path, options = {}) {
         // 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' });
+        res = await fetch(url, {
+            method,
+            headers,
+            body: payload,
+            redirect: 'error',
+            signal: timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined,
+        });
     }
     catch (e) {
         throw new ClokioApiError(0, `Network error reaching Clokio: ${e.message}`);

package/dist/index.js

@@ -14,13 +14,14 @@
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { loadConfig } from './client.js';
+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 { registerEmployeeTools } from './tools/employees.js';
 import { registerAttendanceTools } from './tools/attendance.js';
 import { registerDocTools } from './tools/docs.js';
+import { registerEmployeeIdentityTools, registerEmployeeModeTools } from './tools/employee.js';
 import { registerTicketTools } from './tools/tickets.js';
 /**
  * The optional tool groups a session can turn OFF.
@@ -53,15 +54,66 @@ function selectedToolsets() {
     }
     return new Set(requested);
 }
+const EMPLOYEE_TOOLSETS = ['tasks', 'docs'];
+/**
+ * Employee mode: the personal X-Employee-Key surface. Only tasks and docs
+ * exist there, so CLOKIO_TOOLSETS may name those two and nothing else.
+ */
+function selectedEmployeeToolsets() {
+    const raw = process.env.CLOKIO_TOOLSETS?.trim();
+    if (!raw)
+        return new Set(EMPLOYEE_TOOLSETS);
+    // Its own check, never the admin one: that error lists the admin toolsets
+    // and says "projects is always on", neither of which is true here.
+    const requested = raw.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+    const unsupported = requested.filter((t) => !EMPLOYEE_TOOLSETS.includes(t));
+    if (unsupported.length) {
+        throw new Error(`CLOKIO_TOOLSETS names toolset(s) the employee surface does not have: ${unsupported.join(', ')}. ` +
+            `With CLOKIO_EMPLOYEE_KEY the choices are: ${EMPLOYEE_TOOLSETS.join(', ')} (clokio_whoami and clokio_list_projects are always on).`);
+    }
+    return new Set(requested);
+}
+/** How long the startup /me check may take before the server says so and stops. */
+const STARTUP_TIMEOUT_MS = 15_000;
 async function main() {
     const config = loadConfig();
-    const toolsets = selectedToolsets();
     const server = new McpServer({
         name: 'clokio-mcp',
         version: VERSION,
     });
-    // Always on: whoami plus the reference lookups the task tools resolve
-    // names against.
+    if (config.mode === 'employee') {
+        // Fail at startup, not on the first write: a revoked or expired key is
+        // 401 here, and the person the key acts as is announced so a session
+        // never has to guess whose name its writes will carry.
+        const employeeToolsets = selectedEmployeeToolsets();
+        let me = {};
+        try {
+            me = (await request(config, '/me', { timeoutMs: STARTUP_TIMEOUT_MS }));
+        }
+        catch (e) {
+            // Only a 401/403 means the KEY is bad. A network failure, a timeout, a
+            // 5xx during a deploy, a 429 or a server without /me (404) must not send
+            // the person to rotate a key that works (review of PR #2).
+            const status = e instanceof ClokioApiError ? e.status : 0;
+            if (status === 401 || status === 403) {
+                throw new Error(`CLOKIO_EMPLOYEE_KEY was refused by ${config.baseUrl} (${e.message}). The key may be revoked or expired - ` +
+                    'issue a new one at Profile -> API keys.');
+            }
+            throw new Error(`Could not check CLOKIO_EMPLOYEE_KEY with ${config.baseUrl}: ${e.message}` +
+                (status === 404 ? ' (this Clokio server has no /api/employee/me yet: it needs a newer Clokio).' : '') +
+                ' The key itself was not refused; try again once Clokio answers.');
+        }
+        registerEmployeeIdentityTools(server, config);
+        if (employeeToolsets.has('tasks'))
+            registerEmployeeModeTools(server, config);
+        if (employeeToolsets.has('docs'))
+            registerDocTools(server, config);
+        await server.connect(new StdioServerTransport());
+        process.stderr.write(`clokio-mcp ${VERSION} connected in employee mode, acting as ${me.name ?? '?'} (${me.employee_code ?? '?'}) ` +
+            `(base: ${config.baseUrl}, toolsets: ${[...employeeToolsets].join(', ')})\n`);
+        return;
+    }
+    const toolsets = selectedToolsets();
     registerProjectTools(server, config);
     if (toolsets.has('tasks'))
         registerTaskTools(server, config);

package/dist/tools/employee.js

@@ -0,0 +1,175 @@
+import { z } from 'zod';
+import { markdownToHtml } from '../markdown.js';
+import { request, requestUpload, seg } from '../client.js';
+import { VERSION } from '../version.js';
+import { ESTIMATED_HOURS_MAX } from './tasks.js';
+import { downloadAttachment } from '../attachments.js';
+import { registerTool } from './helpers.js';
+/**
+ * Employee mode: the tools a personal X-Employee-Key can use, acting AS that
+ * person. The server judges every call against the employee's own roles and
+ * project permissions, so nothing here takes an employee_code to credit a
+ * writer - the key is the identity, and a 403 means "you may not do that in
+ * this project", verbatim from Clokio.
+ *
+ * Same tool names as admin mode where the contract is a subset of it (the
+ * model's habits carry over); the admin-only tools simply do not exist here.
+ * The docs tools are the admin ones unchanged: that surface is identical for
+ * both keys, only the identity differs.
+ */
+/**
+ * Always registered in employee mode, whatever CLOKIO_TOOLSETS names, like the
+ * admin `projects` group: a session is told to call clokio_whoami first, and
+ * without it a docs-only session could not learn who it acts as or which
+ * build it runs (review of PR #2, 2026-10-26).
+ */
+export function registerEmployeeIdentityTools(server, config) {
+    registerTool(server, config, {
+        name: 'clokio_whoami',
+        description: 'Who this employee key acts as: the person (employee_code, name, role, position, department), their ' +
+            'organisation, and the key\'s name and expiry. Every write this session makes carries that name. ' +
+            'Also `mcp_version`, the running clokio-mcp build: if it is older than the current release, start a NEW session. ' +
+            'CALL THIS FIRST in a session.',
+        schema: {},
+        // mcp_version is added client-side, as the admin whoami does: `npx -y
+        // clokio-mcp` can serve a cached old build, and only the running package
+        // knows which one it is.
+        handler: async (_args, cfg) => ({ ...(await request(cfg, '/me')), mcp_version: VERSION }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_projects',
+        description: 'Projects this person can create tasks in, with ids. Acting as the key\'s employee, with their own permissions.',
+        schema: {},
+        handler: (_args, cfg) => request(cfg, '/projects'),
+    });
+}
+export function registerEmployeeModeTools(server, config) {
+    const ACTS = 'Acting as the key\'s employee, with their own permissions.';
+    registerTool(server, config, {
+        name: 'clokio_list_tasks',
+        description: 'Tasks ASSIGNED to this person (their queue), open ones by default. Filter by status slug, ' +
+            'updated_since (ISO-8601, incremental sync) or include_done. limit 1-100. ' +
+            'Tasks they are not assigned to are not listed here; open one directly with clokio_get_task if they can see it.',
+        schema: {
+            status: z.string().max(60).optional().describe('Status slug, e.g. "in_progress"'),
+            updated_since: z.string().optional().describe('ISO-8601: only tasks changed at or after this instant'),
+            include_done: z.boolean().optional().describe('Include completed tasks (default false)'),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+        // include_done as 1/0: the server's `boolean` rule refuses the strings
+        // "true"/"false" a query would otherwise carry (a 422 on every call).
+        handler: (args, cfg) => request(cfg, '/tasks', {
+            query: { ...args, include_done: args.include_done === undefined ? undefined : args.include_done ? 1 : 0 },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_task',
+        description: `One task in full: description, subtasks, assignees, the newest 50 comments, attachments. ${ACTS}`,
+        schema: { id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/tasks/${seg(args.id)}`),
+    });
+    // description, dates and estimate take null to CLEAR them, as the server
+    // allows (`nullable`) and as the admin update_task does.
+    const taskFields = {
+        description: z.string().nullable().optional().describe('Markdown, HTML or plain text (Markdown is converted to HTML); null clears it'),
+        status: z.string().max(60).optional().describe("Status slug valid for THIS project's board"),
+        priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+        due_date: z.string().nullable().optional().describe('YYYY-MM-DD, or null to clear'),
+        start_date: z.string().nullable().optional().describe('YYYY-MM-DD, or null to clear'),
+        estimated_hours: z.number().min(0).max(ESTIMATED_HOURS_MAX).nullable().optional().describe('null clears it'),
+    };
+    registerTool(server, config, {
+        name: 'clokio_create_task',
+        mutates: true,
+        description: `Create a task in a project the person may create in (clokio_list_projects); it is created BY them and they watch it. ${ACTS} ` +
+            'Mention someone in the description as plain text "@Full Name".',
+        schema: { project_id: z.number().int(), title: z.string().min(1).max(255), ...taskFields },
+        handler: (args, cfg) => request(cfg, '/tasks', {
+            method: 'POST',
+            body: strip({ ...args, description: htmlField(args.description, 'description', false) }),
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_update_task',
+        mutates: true,
+        description: `Change title, description, status, priority, dates or estimate on a task the person may edit. Only the fields you pass change. ${ACTS}`,
+        schema: { id: z.number().int(), title: z.string().min(1).max(255).optional(), ...taskFields },
+        handler: (args, cfg) => {
+            const { id, ...rest } = args;
+            const body = strip({ ...rest, description: htmlField(rest.description, 'description', false) });
+            return request(cfg, `/tasks/${seg(id)}`, { method: 'PATCH', body });
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_add_task_comment',
+        mutates: true,
+        description: `Comment on a task the person may comment on, as them. ${ACTS} Markdown is converted to HTML. ` +
+            'TO MENTION SOMEONE, write @ followed by their full name as Clokio spells it; it becomes a real mention and notifies them.',
+        schema: { id: z.number().int(), body: z.string().min(1).max(65535) },
+        handler: (args, cfg) => request(cfg, `/tasks/${seg(args.id)}/comments`, { method: 'POST', body: { body: htmlField(args.body, 'body', true) } }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_upload_task_attachment',
+        mutates: true,
+        description: `Upload a LOCAL FILE to a task as an attachment, uploaded by the person. ${ACTS}`,
+        schema: { id: z.number().int(), file_path: z.string().describe('Path to a file on THIS machine') },
+        handler: (args, cfg) => requestUpload(cfg, `/tasks/${seg(args.id)}/attachments`, args.file_path),
+    });
+    registerTool(server, config, {
+        name: 'clokio_download_task_attachment',
+        description: 'Download one attachment of a task the person can see. With save_path, writes it to disk; otherwise text, ' +
+            'PDF text, ZIP entries or an image come back inline. Attachment ids are in clokio_get_task.',
+        schema: {
+            id: z.number().int().describe('The task id'),
+            attachment_id: z.number().int(),
+            file_name: z.string().optional().describe('Drives type detection (text/PDF/zip/image)'),
+            save_path: z.string().optional(),
+            overwrite: z.boolean().optional(),
+        },
+        handler: (args, cfg) => downloadAttachment(cfg, args.id, args.attachment_id, {
+            fileName: args.file_name,
+            savePath: args.save_path,
+            overwrite: args.overwrite,
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_log_time',
+        mutates: true,
+        description: `Record a work session of the person on a task (a timer entry between two instants). ${ACTS}`,
+        schema: {
+            id: z.number().int(),
+            started_at: z.string().describe('ISO-8601 with offset'),
+            ended_at: z.string().describe('ISO-8601 with offset, after started_at'),
+            description: z.string().max(255).optional(),
+        },
+        handler: (args, cfg) => {
+            const { id, ...body } = args;
+            return request(cfg, `/tasks/${seg(id)}/time`, { method: 'POST', body: strip(body) });
+        },
+    });
+}
+/** The server's cap on a description or a comment body, measured AFTER the Markdown conversion. */
+const HTML_MAX = 65535;
+/**
+ * Markdown to the HTML Clokio stores, checked the way the server will check
+ * it: the conversion can turn whitespace into '' and grow long Markdown past
+ * the cap, so the limits are judged on the result, with a sentence the model
+ * can act on instead of the server's bare 422 (review of PR #2). undefined
+ * stays undefined (not sent) and null stays null (clears the field).
+ */
+function htmlField(value, field, required) {
+    if (value === undefined || value === null)
+        return value;
+    const html = markdownToHtml(value);
+    if (html.trim() === '' && (required || value.trim() !== '')) {
+        throw new Error(`The ${field} is empty once converted to HTML. Write some text, or ${required ? 'leave the comment out' : 'pass null to clear it'}.`);
+    }
+    if (html.length > HTML_MAX) {
+        throw new Error(`The ${field} is ${html.length} characters once converted to HTML; the limit is ${HTML_MAX}. Shorten it.`);
+    }
+    return html;
+}
+/** Drop undefined entries so a PATCH changes only what was named. */
+function strip(o) {
+    return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clokio-mcp",
-  "version": "0.28.1",
+  "version": "0.29.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": {