clokio-mcp 0.1.0 → 0.1.2

package/dist/client.js

@@ -15,6 +15,32 @@ export function loadConfig() {
     const baseUrl = (process.env.CLOKIO_BASE_URL?.trim() || 'https://app.clokio.io').replace(/\/+$/, '');
     return { baseUrl, apiKey };
 }
+/**
+ * Encode ONE path segment supplied by a tool argument.
+ *
+ * Interpolating a raw argument into a request path lets it change which
+ * endpoint is called: `?` truncates the path (so a hardcoded `/status` suffix
+ * becomes query noise and the request lands on a different route), `/` adds
+ * segments, and `..` climbs. encodeURIComponent turns all of them into their
+ * percent-encoded forms, which the API then sees as a single literal value -
+ * and its own `[A-Za-z0-9_-]` route constraint rejects it.
+ *
+ * Every tool that puts a STRING into a path must wrap it in this. Numeric
+ * (z.number().int()) arguments cannot carry separators and need no wrapping,
+ * but passing them through is harmless.
+ */
+export function seg(value) {
+    const s = String(value);
+    // encodeURIComponent leaves `.` alone, so a bare `.` or `..` would survive
+    // as a real dot-segment and be normalised away by new URL(). The prefix
+    // guard in request() already catches the escape; refusing here keeps the
+    // error at the argument that caused it, and an empty segment would silently
+    // collapse `/a//b` into `/a/b` and hit a neighbouring route.
+    if (s === '' || s === '.' || s === '..') {
+        throw new ClokioApiError(0, `Invalid path argument ${JSON.stringify(s)}.`);
+    }
+    return encodeURIComponent(s);
+}
 /** A Clokio API error, carrying the HTTP status and the server's message. */
 export class ClokioApiError extends Error {
     status;
@@ -35,6 +61,18 @@ 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)
@@ -59,7 +97,12 @@ export async function request(config, path, options = {}) {
     }
     let res;
     try {
-        res = await fetch(url, { method, headers, body: payload });
+        // 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.
+        res = await fetch(url, { method, headers, body: payload, redirect: 'error' });
     }
     catch (e) {
         throw new ClokioApiError(0, `Network error reaching Clokio: ${e.message}`);

package/dist/index.js

@@ -10,6 +10,7 @@
  * 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 { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { loadConfig } from './client.js';
@@ -17,11 +18,14 @@ import { registerTaskTools } from './tools/tasks.js';
 import { registerProjectTools } from './tools/projects.js';
 import { registerEmployeeTools } from './tools/employees.js';
 import { registerAttendanceTools } from './tools/attendance.js';
+// The version the MCP handshake announces is package.json's, read at runtime -
+// a literal here went stale on the first patch release (0.1.1 said 0.1.0).
+const { version } = createRequire(import.meta.url)('../package.json');
 async function main() {
     const config = loadConfig();
     const server = new McpServer({
         name: 'clokio-mcp',
-        version: '0.1.0',
+        version,
     });
     registerTaskTools(server, config);
     registerProjectTools(server, config);

package/dist/tools/attendance.js

@@ -1,6 +1,10 @@
 import { z } from 'zod';
-import { request } from '../client.js';
+import { request, seg } from '../client.js';
 import { registerTool } from './helpers.js';
+/** See employees.ts - an employee_code reaches the request path. */
+const employeeCode = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -');
 /** Attendance reads + clock/break writes, plus time entries and balances. */
 export function registerAttendanceTools(server, config) {
     registerTool(server, config, {
@@ -22,11 +26,11 @@ export function registerAttendanceTools(server, config) {
         name: 'clokio_attendance_for_employee',
         description: "One employee's attendance. Optionally scope to a date range.",
         schema: {
-            employee_code: z.string(),
+            employee_code: employeeCode,
             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}`, {
+        handler: (args, cfg) => request(cfg, `/attendance/employee/${seg(args.employee_code)}`, {
             query: { start_date: args.start_date, end_date: args.end_date },
         }),
     });

package/dist/tools/employees.js

@@ -1,6 +1,15 @@
 import { z } from 'zod';
-import { request } from '../client.js';
+import { request, seg } from '../client.js';
 import { registerTool } from './helpers.js';
+/**
+ * An employee_code goes into the request PATH, so it must not be able to carry
+ * a path separator or a query marker - see seg() / the /api/v1 guard in
+ * client.js. This mirrors the constraint the API route itself declares
+ * (`->where('employeeCode', '[A-Za-z0-9_-]{1,50}')`).
+ */
+const employeeCode = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]{1,50}$/, 'employee_code must be 1-50 chars of letters, digits, _ or -');
 /** Employee directory + provisioning. */
 export function registerEmployeeTools(server, config) {
     registerTool(server, config, {
@@ -31,10 +40,10 @@ export function registerEmployeeTools(server, config) {
         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(),
+            employee_code: employeeCode,
             stale_days: z.number().int().min(1).max(365).optional(),
         },
-        handler: (args, cfg) => request(cfg, `/employees/${args.employee_code}/task-stats`, {
+        handler: (args, cfg) => request(cfg, `/employees/${seg(args.employee_code)}/task-stats`, {
             query: { stale_days: args.stale_days },
         }),
     });
@@ -60,10 +69,10 @@ export function registerEmployeeTools(server, config) {
         mutates: true,
         description: 'Set an employee\'s status (active / inactive / resign).',
         schema: {
-            employee_code: z.string(),
+            employee_code: employeeCode,
             status: z.enum(['active', 'inactive', 'resign']),
         },
-        handler: (args, cfg) => request(cfg, `/employees/${args.employee_code}/status`, {
+        handler: (args, cfg) => request(cfg, `/employees/${seg(args.employee_code)}/status`, {
             method: 'PATCH',
             body: { status: args.status },
         }),

package/dist/tools/helpers.js

@@ -16,7 +16,13 @@ export function registerTool(server, config, def) {
                 content: [
                     {
                         type: 'text',
-                        text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                        // A 204 (delete) has no body, so request() resolves undefined and
+                        // JSON.stringify(undefined) is undefined - not a valid text block.
+                        text: result === undefined
+                            ? 'OK (no content)'
+                            : typeof result === 'string'
+                                ? result
+                                : JSON.stringify(result, null, 2),
                     },
                 ],
             };

package/package.json

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