clokio-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matat Technologies LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# Clokio MCP Server
+
+[![npm version](https://img.shields.io/npm/v/clokio-mcp.svg)](https://www.npmjs.com/package/clokio-mcp)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for the
+**[Clokio](https://clokio.io) Public API**. Connect Claude — or any MCP client —
+to your Clokio workspace to read and manage tasks, projects, clients, employees
+and attendance in natural language.
+
+Every request is authenticated with **your own** Clokio API key (`clk_...`),
+sent as `X-API-Key`. The key carries its own scopes, so this server never
+re-implements authorization: it is a thin, stateless client, and a `403` / `422`
+from the API is surfaced verbatim.
+
+## Install
+
+You need a Clokio API key. Create and scope keys in the admin dashboard at
+**Settings → API Keys** (`/admin/api-keys/`). Each person uses their own key, so
+permissions and the audit trail stay per-user.
+
+### Claude Code
+
+```bash
+claude mcp add clokio \
+  --env CLOKIO_API_KEY=clk_your_key_here \
+  -- npx -y clokio-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "clokio": {
+      "command": "npx",
+      "args": ["-y", "clokio-mcp"],
+      "env": { "CLOKIO_API_KEY": "clk_your_key_here" }
+    }
+  }
+}
+```
+
+### Cursor / Cline / Zed / any MCP client
+
+Use the same command — `npx -y clokio-mcp` with `CLOKIO_API_KEY` in the env.
+MCP is an open standard.
+
+Optional: set `CLOKIO_BASE_URL` to point at a different Clokio installation
+(defaults to `https://app.clokio.io`).
+
+## Tools
+
+36 tools across five areas. Read-only tools carry the MCP `readOnlyHint`; writes
+are marked mutating (deletes are `destructive`).
+
+| Area | Tools |
+|------|-------|
+| **Tasks** | list, get, create, update, delete, set assignees, list/add comments, activity, list/add dependencies, set custom field |
+| **Projects & clients** | list projects, project statuses, project custom fields, project contacts, get client, add client contact |
+| **Reference** | task statuses, task labels, locations |
+| **Employees** | list, lookup, task-stats, create, set status |
+| **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries, balances |
+
+### Conventions
+
+- **People are identified by `employee_code`** (e.g. `00080`), not internal ids.
+  Use `clokio_lookup_employee` to resolve a name to a code.
+- **Attribute writes to a person** — pass `creator_employee_code` when creating a
+  task, `author_employee_code` when commenting, or the entry shows as the API key
+  owner ("External System").
+- **Status slugs** come from `clokio_list_task_statuses` /
+  `clokio_get_project_statuses`.
+- An API key sees **public custom fields only**.
+
+## 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 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.
+- All authorization, tenancy (`organization_id` scoping) and rate limiting are
+  enforced server-side by the Clokio API, exactly as for any other API consumer.
+
+## Local development
+
+```bash
+git clone https://github.com/AmitMatat/clokio-mcp.git
+cd clokio-mcp
+npm install     # includes devDependencies (typescript)
+npm run build   # rebuilds dist/
+```
+
+The prebuilt `dist/` is committed so `npx` can run the server with no build step
+(this also keeps it working when `NODE_ENV=production`, where npm skips
+devDependencies). Rebuild and commit `dist/` alongside any source change.
+
+The tool surface tracks the Clokio Public API v1; its OpenAPI spec is served
+(unauthenticated) at `/api/v1/openapi.json` and is the source of truth for
+request shapes.
+
+## License
+
+MIT © Matat Technologies LTD

package/dist/client.js

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ */
+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 baseUrl = (process.env.CLOKIO_BASE_URL?.trim() || 'https://app.clokio.io').replace(/\/+$/, '');
+    return { baseUrl, apiKey };
+}
+/** A Clokio API error, carrying the HTTP status and the server's message. */
+export class ClokioApiError extends Error {
+    status;
+    body;
+    constructor(status, message, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'ClokioApiError';
+    }
+}
+/**
+ * Perform a Clokio API v1 request under `/api/v1`. Returns the parsed `data`
+ * field of the standard `{status, message, data}` envelope when present, or the
+ * whole parsed body otherwise. Throws ClokioApiError on a non-2xx response with
+ * the server's own message.
+ */
+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}`}`);
+    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 headers = {
+        'X-API-Key': config.apiKey,
+        Accept: 'application/json',
+    };
+    let payload;
+    if (body !== undefined) {
+        headers['Content-Type'] = 'application/json';
+        payload = JSON.stringify(body);
+    }
+    let res;
+    try {
+        res = await fetch(url, { method, headers, body: payload });
+    }
+    catch (e) {
+        throw new ClokioApiError(0, `Network error reaching Clokio: ${e.message}`);
+    }
+    const text = await res.text();
+    let parsed = undefined;
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        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);
+    }
+    // Standard envelope: {status, message, data}. Unwrap `data` when present.
+    if (parsed && typeof parsed === 'object' && 'data' in parsed) {
+        return parsed.data;
+    }
+    return parsed;
+}

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ *
+ * Run: CLOKIO_API_KEY=clk_... node dist/index.js
+ * Or register with: claude mcp add clokio -- npx -y clokio-mcp
+ * (set CLOKIO_API_KEY, and optionally CLOKIO_BASE_URL, in the MCP env).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './client.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';
+async function main() {
+    const config = loadConfig();
+    const server = new McpServer({
+        name: 'clokio-mcp',
+        version: '0.1.0',
+    });
+    registerTaskTools(server, config);
+    registerProjectTools(server, config);
+    registerEmployeeTools(server, config);
+    registerAttendanceTools(server, config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr is safe for logs on stdio transport (stdout carries the protocol).
+    process.stderr.write(`clokio-mcp connected (base: ${config.baseUrl})\n`);
+}
+main().catch((e) => {
+    process.stderr.write(`clokio-mcp failed to start: ${e.message}\n`);
+    process.exit(1);
+});

package/dist/tools/attendance.js

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import { request } from '../client.js';
+import { registerTool } from './helpers.js';
+/** Attendance reads + clock/break writes, plus time entries and balances. */
+export function registerAttendanceTools(server, config) {
+    registerTool(server, config, {
+        name: 'clokio_attendance_daily',
+        description: 'Attendance for a single date (YYYY-MM-DD, defaults to today).',
+        schema: { date: z.string().optional().describe('YYYY-MM-DD') },
+        handler: (args, cfg) => request(cfg, '/attendance/daily', { query: { date: args.date } }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_attendance_range',
+        description: 'Attendance for a date range (max 31 days).',
+        schema: {
+            start_date: z.string().describe('YYYY-MM-DD'),
+            end_date: z.string().describe('YYYY-MM-DD'),
+        },
+        handler: (args, cfg) => request(cfg, '/attendance/range', { query: { start_date: args.start_date, end_date: args.end_date } }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_attendance_for_employee',
+        description: "One employee's attendance. Optionally scope to a date range.",
+        schema: {
+            employee_code: z.string(),
+            start_date: z.string().optional().describe('YYYY-MM-DD'),
+            end_date: z.string().optional().describe('YYYY-MM-DD'),
+        },
+        handler: (args, cfg) => request(cfg, `/attendance/employee/${args.employee_code}`, {
+            query: { start_date: args.start_date, end_date: args.end_date },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_attendance_summary',
+        description: 'Monthly attendance summary.',
+        schema: {
+            month: z.string().optional().describe('YYYY-MM'),
+        },
+        handler: (args, cfg) => request(cfg, '/attendance/summary', { query: { month: args.month } }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_clock_in',
+        mutates: true,
+        description: 'Clock an employee in. A PIN may be required depending on org configuration. Timestamps are clamped to ' +
+            '+/-10 minutes of server time.',
+        schema: {
+            employee_code: z.string(),
+            pin: z.string().optional(),
+            location_id: z.number().int().optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/attendance/clock-in', {
+            method: 'POST',
+            body: { employee_code: args.employee_code, pin: args.pin, location_id: args.location_id },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_clock_out',
+        mutates: true,
+        description: 'Clock an employee out.',
+        schema: {
+            employee_code: z.string(),
+            pin: z.string().optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/attendance/clock-out', {
+            method: 'POST',
+            body: { employee_code: args.employee_code, pin: args.pin },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_break_start',
+        mutates: true,
+        description: 'Start a break for an employee.',
+        schema: { employee_code: z.string(), pin: z.string().optional() },
+        handler: (args, cfg) => request(cfg, '/attendance/break-start', {
+            method: 'POST',
+            body: { employee_code: args.employee_code, pin: args.pin },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_break_end',
+        mutates: true,
+        description: 'End a break for an employee.',
+        schema: { employee_code: z.string(), pin: z.string().optional() },
+        handler: (args, cfg) => request(cfg, '/attendance/break-end', {
+            method: 'POST',
+            body: { employee_code: args.employee_code, pin: args.pin },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_time_entries',
+        description: 'List time-tracking entries. Filterable by employee_code and date range.',
+        schema: {
+            employee_code: z.string().optional(),
+            start_date: z.string().optional().describe('YYYY-MM-DD'),
+            end_date: z.string().optional().describe('YYYY-MM-DD'),
+        },
+        handler: (args, cfg) => request(cfg, '/time-entries', {
+            query: { employee_code: args.employee_code, start_date: args.start_date, end_date: args.end_date },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_balances',
+        description: 'Leave / hour balances.',
+        schema: { employee_code: z.string().optional() },
+        handler: (args, cfg) => request(cfg, '/balances', { query: { employee_code: args.employee_code } }),
+    });
+}

package/dist/tools/employees.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { request } from '../client.js';
+import { registerTool } from './helpers.js';
+/** Employee directory + provisioning. */
+export function registerEmployeeTools(server, config) {
+    registerTool(server, config, {
+        name: 'clokio_list_employees',
+        description: 'List employees. Returns employee_code (the stable id used everywhere else, e.g. for assignees), name, ' +
+            'and non-PII fields. email is only returned if the key holds the employees:pii scope.',
+        schema: {
+            search: z.string().optional().describe('Name filter'),
+            page: z.number().int().optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/employees', { query: { search: args.search, page: args.page } }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_lookup_employee',
+        description: 'Look up an employee by name or email to resolve their employee_code. Use this before assigning a task ' +
+            'when you only know the person\'s name.',
+        schema: {
+            name: z.string().optional(),
+            email: z.string().optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/employees/lookup', {
+            method: 'POST',
+            body: { name: args.name, email: args.email },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_employee_task_stats',
+        description: "One employee's open / delayed_from_open / past_due task counts. stale_days sets the 'delayed' threshold " +
+            '(default 7, range 1-365). A task with N assignees counts for each of them.',
+        schema: {
+            employee_code: z.string(),
+            stale_days: z.number().int().min(1).max(365).optional(),
+        },
+        handler: (args, cfg) => request(cfg, `/employees/${args.employee_code}/task-stats`, {
+            query: { stale_days: args.stale_days },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_create_employee',
+        mutates: true,
+        description: 'Create (or reactivate) an employee. Reactivating an existing inactive employee never resets their ' +
+            'password. A pin (4-6 digits, org-unique) can be supplied or is auto-generated; it is returned only here.',
+        schema: {
+            name: z.string(),
+            email: z.string().optional(),
+            phone: z.string().optional(),
+            location_id: z.number().int().optional(),
+            pin: z.string().optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/employees', {
+            method: 'POST',
+            body: { name: args.name, email: args.email, phone: args.phone, location_id: args.location_id, pin: args.pin },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_set_employee_status',
+        mutates: true,
+        description: 'Set an employee\'s status (active / inactive / resign).',
+        schema: {
+            employee_code: z.string(),
+            status: z.enum(['active', 'inactive', 'resign']),
+        },
+        handler: (args, cfg) => request(cfg, `/employees/${args.employee_code}/status`, {
+            method: 'PATCH',
+            body: { status: args.status },
+        }),
+    });
+}

package/dist/tools/helpers.js

@@ -0,0 +1,55 @@
+import { ClokioApiError } from '../client.js';
+/**
+ * Register one Clokio tool. The handler returns any JSON-serialisable value,
+ * rendered as pretty JSON text. ClokioApiError becomes an isError tool result
+ * carrying the API's own status + message, so the model can correct its request
+ * (a 422 naming the bad field, a 404, a 403 scope refusal).
+ *
+ * `mutates` marks a tool that changes data (create/update/delete): it sets the
+ * MCP readOnlyHint/destructiveHint annotations so clients can surface a warning.
+ */
+export function registerTool(server, config, def) {
+    const callback = async (args) => {
+        try {
+            const result = await def.handler(args, config);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            if (e instanceof ClokioApiError) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Clokio API error (HTTP ${e.status}): ${e.message}` +
+                                (e.body ? `\n\nDetails:\n${JSON.stringify(e.body, null, 2)}` : ''),
+                        },
+                    ],
+                };
+            }
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Error: ${e.message}` }],
+            };
+        }
+    };
+    server.registerTool(def.name, {
+        description: def.description,
+        inputSchema: def.schema,
+        annotations: {
+            readOnlyHint: !def.mutates,
+            destructiveHint: def.mutates === 'destructive',
+        },
+    }, 
+    // The SDK's callback type is an inline structural shape that our
+    // CallToolResult return does not unify with under strict generics; the
+    // runtime shape is correct, so the cast is the pragmatic bridge.
+    callback);
+}

package/dist/tools/projects.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { request } from '../client.js';
+import { registerTool } from './helpers.js';
+/** Projects, clients, and the board-configuration + reference lookups. */
+export function registerProjectTools(server, config) {
+    registerTool(server, config, {
+        name: 'clokio_list_projects',
+        description: 'List projects, optionally filtered by a search term (name / client).',
+        schema: { search: z.string().optional() },
+        handler: (args, cfg) => request(cfg, '/projects', { query: { search: args.search } }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_project_statuses',
+        description: "A project's resolved task-status set, in order (what a task in this project may become).",
+        schema: { project_id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/projects/${args.project_id}/statuses`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_project_custom_fields',
+        description: "A project's custom-field definitions, in sort order. An API key sees PUBLIC fields only.",
+        schema: { project_id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/projects/${args.project_id}/custom-fields`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_project_contacts',
+        description: "The contacts for a project's client.",
+        schema: { project_id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/projects/${args.project_id}/contacts`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_client',
+        description: 'Get a client by id.',
+        schema: { client_id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/clients/${args.client_id}`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_add_client_contact',
+        mutates: true,
+        description: 'Add a contact to a client.',
+        schema: {
+            client_id: z.number().int(),
+            name: z.string(),
+            email: z.string().optional(),
+            phone: z.string().optional(),
+            role: z.string().optional(),
+        },
+        handler: (args, cfg) => request(cfg, `/clients/${args.client_id}/contacts`, {
+            method: 'POST',
+            body: { name: args.name, email: args.email, phone: args.phone, role: args.role },
+        }),
+    });
+    // ── Reference / vocabulary lookups ──
+    registerTool(server, config, {
+        name: 'clokio_list_task_statuses',
+        description: 'The organisation-wide task-status vocabulary, with is_open per slug (including project-specific slugs). ' +
+            'Use this to discover valid status slugs before creating/updating a task.',
+        schema: {},
+        handler: (_args, cfg) => request(cfg, '/task-statuses'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_task_labels',
+        description: 'List the available task labels (tags), with names and colors.',
+        schema: {},
+        handler: (_args, cfg) => request(cfg, '/task-labels'),
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_locations',
+        description: 'List the organisation\'s locations.',
+        schema: {},
+        handler: (_args, cfg) => request(cfg, '/locations'),
+    });
+}

package/dist/tools/tasks.js

@@ -0,0 +1,189 @@
+import { z } from 'zod';
+import { request } from '../client.js';
+import { registerTool } from './helpers.js';
+/** Task-management tools: the core of the Clokio API surface. */
+export function registerTaskTools(server, config) {
+    registerTool(server, config, {
+        name: 'clokio_list_tasks',
+        description: 'List tasks. Supports filters: project_id, status (slug), priority, assignee (employee_code), ' +
+            'label, search, open (1 = only open tasks), created_before / due_before (YYYY-MM-DD, org timezone). ' +
+            'Paginate with page, or crawl with cursor. Each task carries a task_url.',
+        schema: {
+            project_id: z.number().int().optional(),
+            status: z.string().optional().describe('Status slug, e.g. "in_progress"'),
+            priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+            assignee: z.string().optional().describe('employee_code, e.g. "00080"'),
+            label: z.string().optional(),
+            search: z.string().optional(),
+            open: z.boolean().optional().describe('true = only tasks whose status is not "done"'),
+            created_before: z.string().optional().describe('YYYY-MM-DD'),
+            due_before: z.string().optional().describe('YYYY-MM-DD'),
+            page: z.number().int().optional(),
+            cursor: z.string().optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/tasks', {
+            query: {
+                project_id: args.project_id,
+                status: args.status,
+                priority: args.priority,
+                assignee: args.assignee,
+                label: args.label,
+                search: args.search,
+                open: args.open ? 1 : undefined,
+                created_before: args.created_before,
+                due_before: args.due_before,
+                page: args.page,
+                cursor: args.cursor,
+            },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_task',
+        description: 'Get one task by id, with its full detail (assignees, labels, status, custom fields, task_url).',
+        schema: { id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_create_task',
+        mutates: true,
+        description: 'Create a task in a project. assignees/creator use employee_code (e.g. "00080"), not internal ids. ' +
+            'To attribute the task to a person set creator_employee_code, otherwise it shows as the API key owner.',
+        schema: {
+            project_id: z.number().int(),
+            title: z.string(),
+            description: z.string().optional().describe('HTML or plain text'),
+            priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+            status: z.string().optional().describe('Status slug'),
+            due_date: z.string().optional().describe('YYYY-MM-DD'),
+            assignee_employee_codes: z.array(z.string()).optional(),
+            label_names: z.array(z.string()).optional(),
+            creator_employee_code: z.string().optional(),
+        },
+        handler: (args, cfg) => request(cfg, '/tasks', {
+            method: 'POST',
+            body: {
+                project_id: args.project_id,
+                title: args.title,
+                description: args.description,
+                priority: args.priority,
+                status: args.status,
+                due_date: args.due_date,
+                assignees: args.assignee_employee_codes,
+                labels: args.label_names,
+                created_by_employee_code: args.creator_employee_code,
+            },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_update_task',
+        mutates: true,
+        description: 'Update a task. Only the fields you pass are changed. status/priority/title/description/due_date are supported.',
+        schema: {
+            id: z.number().int(),
+            title: z.string().optional(),
+            description: z.string().optional(),
+            priority: z.enum(['low', 'medium', 'high', 'urgent']).optional(),
+            status: z.string().optional().describe('Status slug'),
+            due_date: z.string().optional().describe('YYYY-MM-DD, or empty string to clear'),
+        },
+        handler: (args, cfg) => {
+            const body = {};
+            if (args.title !== undefined)
+                body.title = args.title;
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.priority !== undefined)
+                body.priority = args.priority;
+            if (args.status !== undefined)
+                body.status = args.status;
+            if (args.due_date !== undefined)
+                body.due_date = args.due_date;
+            return request(cfg, `/tasks/${args.id}`, { method: 'PATCH', body });
+        },
+    });
+    registerTool(server, config, {
+        name: 'clokio_delete_task',
+        mutates: 'destructive',
+        description: 'Delete a task by id. This is irreversible.',
+        schema: { id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}`, { method: 'DELETE' }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_set_task_assignees',
+        mutates: true,
+        description: 'Set a task\'s assignees. mode "add" appends, "replace" overwrites, "remove" removes. ' +
+            'Assignees are employee_codes (e.g. "00080").',
+        schema: {
+            id: z.number().int(),
+            employee_codes: z.array(z.string()),
+            mode: z.enum(['add', 'replace', 'remove']).optional().describe('default: add'),
+        },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/assignees`, {
+            method: 'PATCH',
+            body: { assignees: args.employee_codes, mode: args.mode ?? 'add' },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_task_comments',
+        description: 'List the comments on a task.',
+        schema: { id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/comments`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_add_task_comment',
+        mutates: true,
+        description: 'Add a comment to a task. Set author_employee_code to attribute it to a person; otherwise it shows as ' +
+            'the API key owner ("External System"). Use readable formatting (paragraphs, bullet lists); markdown ' +
+            'tables are not rendered.',
+        schema: {
+            id: z.number().int(),
+            body: z.string(),
+            author_employee_code: z.string().optional(),
+        },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/comments`, {
+            method: 'POST',
+            body: { body: args.body, author_employee_code: args.author_employee_code },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_get_task_activity',
+        description: 'Get the activity log (audit trail) for a task.',
+        schema: { id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/activity`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_list_task_dependencies',
+        description: 'List a task\'s dependencies (blocks / waiting-on).',
+        schema: { id: z.number().int() },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/dependencies`),
+    });
+    registerTool(server, config, {
+        name: 'clokio_add_task_dependency',
+        mutates: true,
+        description: 'Add a dependency between two tasks. Circular dependencies are rejected by the API.',
+        schema: {
+            id: z.number().int().describe('The task that depends'),
+            depends_on_task_id: z.number().int(),
+            type: z.enum(['blocks', 'waiting_on']).optional(),
+        },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/dependencies`, {
+            method: 'POST',
+            body: { depends_on_task_id: args.depends_on_task_id, type: args.type },
+        }),
+    });
+    registerTool(server, config, {
+        name: 'clokio_set_task_custom_field',
+        mutates: true,
+        description: 'Set one custom field value on a task, identified by field_key (never field_id). An API key sees ' +
+            'PUBLIC fields only.',
+        schema: {
+            id: z.number().int(),
+            field_key: z.string(),
+            value: z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]),
+        },
+        handler: (args, cfg) => request(cfg, `/tasks/${args.id}/custom-fields`, {
+            method: 'PATCH',
+            body: { field_key: args.field_key, value: args.value },
+        }),
+    });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "clokio-mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol (MCP) server for Clokio — manage tasks, projects, clients, employees and attendance from Claude and any MCP client.",
+  "type": "module",
+  "bin": {
+    "clokio-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "clokio",
+    "claude",
+    "ai",
+    "attendance",
+    "task-management",
+    "project-management",
+    "time-tracking"
+  ],
+  "author": "Matat Technologies LTD",
+  "license": "MIT",
+  "homepage": "https://clokio.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AmitMatat/clokio-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AmitMatat/clokio-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}