@nightsquawktech/kimai-mcp-server 0.1.0

package/dist/tools/plugins.js

@@ -0,0 +1,40 @@
+import { CollectionSchema, EntityIdSchema } from "../schemas/resources.js";
+import { registerCollectionReadTool, registerEntityReadTool } from "./read-tools.js";
+export function registerPluginTools(server, client) {
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_expenses",
+        title: "List Kimai Expenses",
+        description: "List expenses from /api/expenses when the Kimai expenses feature/plugin is available. This tool is read-only.",
+        inputSchema: CollectionSchema.shape,
+        path: () => "/api/expenses",
+        preferredFields: ["id", "user", "project", "activity", "date", "amount", "description"],
+        heading: "Kimai Expenses"
+    });
+    registerEntityReadTool(server, client, {
+        name: "kimai_get_expense",
+        title: "Get Kimai Expense",
+        description: "Read one expense from /api/expenses/<id> when the Kimai expenses feature/plugin is available. This tool is read-only.",
+        inputSchema: EntityIdSchema.shape,
+        path: (params) => `/api/expenses/${encodeURIComponent(String(params.id))}`,
+        preferredFields: ["id", "user", "project", "activity", "date", "amount", "description"],
+        heading: "Kimai Expense"
+    });
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_tasks",
+        title: "List Kimai Tasks",
+        description: "List tasks from /api/tasks when the Kimai tasks feature/plugin is available. This tool is read-only.",
+        inputSchema: CollectionSchema.shape,
+        path: () => "/api/tasks",
+        preferredFields: ["id", "title", "user", "project", "activity", "status", "priority"],
+        heading: "Kimai Tasks"
+    });
+    registerEntityReadTool(server, client, {
+        name: "kimai_get_task",
+        title: "Get Kimai Task",
+        description: "Read one task from /api/tasks/<id> when the Kimai tasks feature/plugin is available. This tool is read-only.",
+        inputSchema: EntityIdSchema.shape,
+        path: (params) => `/api/tasks/${encodeURIComponent(String(params.id))}`,
+        preferredFields: ["id", "title", "user", "project", "activity", "status", "priority"],
+        heading: "Kimai Task"
+    });
+}

package/dist/tools/read-tools.js

@@ -0,0 +1,66 @@
+import { formatApiError } from "../services/errors.js";
+import { formatResponse, makeToolResponse, paginateResponse, summarizeRecord } from "./format.js";
+export function registerCollectionReadTool(server, client, options) {
+    server.registerTool(options.name, {
+        title: options.title,
+        description: options.description,
+        inputSchema: options.inputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const paging = params;
+            const response = await client.get(options.path(params), {
+                page: paging.page,
+                size: paging.size,
+                ...options.query?.(params)
+            });
+            const data = paginateResponse(response, paging.page, paging.size);
+            const markdown = [
+                `# ${options.heading}`,
+                "",
+                `Showing ${data.count} of ${data.total} records on page ${data.page}.`,
+                "",
+                ...data.items.map((item) => `- ${summarizeRecord(item, options.preferredFields)}`)
+            ].join("\n");
+            return makeToolResponse(data, formatResponse(paging.response_format, data, markdown));
+        }
+        catch (error) {
+            const data = { error: formatApiError(error) };
+            return makeToolResponse(data, data.error, true);
+        }
+    });
+}
+export function registerEntityReadTool(server, client, options) {
+    server.registerTool(options.name, {
+        title: options.title,
+        description: options.description,
+        inputSchema: options.inputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const responseFormat = params.response_format;
+            const response = await client.get(options.path(params));
+            const data = { item: response.data };
+            const markdown = [
+                `# ${options.heading}`,
+                "",
+                summarizeRecord(response.data, options.preferredFields)
+            ].join("\n");
+            return makeToolResponse(data, formatResponse(responseFormat, data, markdown));
+        }
+        catch (error) {
+            const data = { error: formatApiError(error) };
+            return makeToolResponse(data, data.error, true);
+        }
+    });
+}

package/dist/tools/server.js

@@ -0,0 +1,37 @@
+import { formatApiError } from "../services/errors.js";
+import { ServerInfoSchema } from "../schemas/server.js";
+import { formatResponse, makeToolResponse } from "./format.js";
+export function registerServerTools(server, client) {
+    server.registerTool("kimai_get_server_info", {
+        title: "Get Kimai Server Info",
+        description: "Read Kimai API status, version, plugin, and timesheet configuration endpoints. This tool is read-only.",
+        inputSchema: ServerInfoSchema.shape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async ({ response_format }) => {
+        const checks = await Promise.allSettled([
+            client.get("/api/ping"),
+            client.get("/api/version"),
+            client.get("/api/plugins"),
+            client.get("/api/config/timesheet")
+        ]);
+        const [ping, version, plugins, timesheetConfig] = checks.map((result) => result.status === "fulfilled" ? result.value.data : { error: formatApiError(result.reason) });
+        const data = { ping, version, plugins, timesheet_config: timesheetConfig };
+        const markdown = [
+            "# Kimai Server Info",
+            "",
+            `- Ping: ${formatInline(ping)}`,
+            `- Version: ${formatInline(version)}`,
+            `- Plugins: ${formatInline(plugins)}`,
+            `- Timesheet config: ${formatInline(timesheetConfig)}`
+        ].join("\n");
+        return makeToolResponse(data, formatResponse(response_format, data, markdown));
+    });
+}
+function formatInline(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}

package/dist/tools/timesheet-mutations.js

@@ -0,0 +1,190 @@
+import { writeMutationBackup } from "../services/backups.js";
+import { formatApiError } from "../services/errors.js";
+import { CreateTimesheetSchema, DuplicateTimesheetSchema, TimesheetStateChangeSchema, UpdateTimesheetSchema } from "../schemas/mutations.js";
+import { formatResponse, makeToolResponse, summarizeRecord } from "./format.js";
+export function registerTimesheetMutationTools(server, client) {
+    server.registerTool("kimai_create_timesheet", {
+        title: "Create Kimai Timesheet",
+        description: "Create a Kimai timesheet record. Sensitive edit: call only after explicit human authorization. The request and created record are saved to a temp backup file.",
+        inputSchema: CreateTimesheetSchema.shape,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const payload = buildTimesheetPayload(params, ["authorization_confirmed", "authorization_note", "full", "response_format"]);
+            const response = await client.post("/api/timesheets", payload, params.full ? { full: "true" } : undefined);
+            const backupFile = await writeMutationBackup({
+                operation: "kimai_create_timesheet",
+                endpoint: "POST /api/timesheets",
+                authorization_note: params.authorization_note,
+                before: null,
+                request: payload,
+                after: response.data
+            });
+            const data = { backup_file: backupFile, timesheet: response.data };
+            const markdown = [
+                "# Kimai Timesheet Created",
+                "",
+                `Backup file: ${backupFile}`,
+                "",
+                summarizeRecord(response.data, ["id", "user", "project", "activity", "begin", "end", "duration", "description"])
+            ].join("\n");
+            return makeToolResponse(data, formatResponse(params.response_format, data, markdown));
+        }
+        catch (error) {
+            const data = { error: formatApiError(error) };
+            return makeToolResponse(data, data.error, true);
+        }
+    });
+    server.registerTool("kimai_update_timesheet", {
+        title: "Update Kimai Timesheet",
+        description: "Update a Kimai timesheet record. Sensitive edit: call only after explicit human authorization. The existing record is saved to a temp backup file before the edit.",
+        inputSchema: UpdateTimesheetSchema.shape,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const payload = buildTimesheetPayload(params, ["authorization_confirmed", "authorization_note", "id", "response_format"]);
+            if (Object.keys(payload).length === 0) {
+                return makeToolResponse({ error: "No editable fields were provided." }, "No editable fields were provided.", true);
+            }
+            const endpoint = `/api/timesheets/${encodeURIComponent(String(params.id))}`;
+            const before = await client.get(endpoint);
+            const response = await client.patch(endpoint, payload);
+            const backupFile = await writeMutationBackup({
+                operation: "kimai_update_timesheet",
+                endpoint: `PATCH ${endpoint}`,
+                authorization_note: params.authorization_note,
+                before: before.data,
+                request: payload,
+                after: response.data
+            });
+            const data = { backup_file: backupFile, before: before.data, timesheet: response.data };
+            const markdown = [
+                "# Kimai Timesheet Updated",
+                "",
+                `Backup file: ${backupFile}`,
+                "",
+                summarizeRecord(response.data, ["id", "user", "project", "activity", "begin", "end", "duration", "description"])
+            ].join("\n");
+            return makeToolResponse(data, formatResponse(params.response_format, data, markdown));
+        }
+        catch (error) {
+            const data = { error: formatApiError(error) };
+            return makeToolResponse(data, data.error, true);
+        }
+    });
+    server.registerTool("kimai_stop_timesheet", {
+        title: "Stop Kimai Timesheet",
+        description: "Stop an active Kimai timesheet. Sensitive edit: call only after explicit human authorization. The existing record is saved to a temp backup file before stopping.",
+        inputSchema: TimesheetStateChangeSchema.shape,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => runStateChange(client, params, "kimai_stop_timesheet", "stop"));
+    server.registerTool("kimai_restart_timesheet", {
+        title: "Restart Kimai Timesheet",
+        description: "Restart a stopped Kimai timesheet. Sensitive edit: call only after explicit human authorization. The existing record is saved to a temp backup file before restarting.",
+        inputSchema: TimesheetStateChangeSchema.shape,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => runStateChange(client, params, "kimai_restart_timesheet", "restart"));
+    server.registerTool("kimai_duplicate_timesheet", {
+        title: "Duplicate Kimai Timesheet",
+        description: "Duplicate an existing Kimai timesheet. Sensitive edit: call only after explicit human authorization. The source and created record are saved to a temp backup file.",
+        inputSchema: DuplicateTimesheetSchema.shape,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const sourceEndpoint = `/api/timesheets/${encodeURIComponent(String(params.id))}`;
+            const before = await client.get(sourceEndpoint);
+            const response = await client.patch(`${sourceEndpoint}/duplicate`);
+            const backupFile = await writeMutationBackup({
+                operation: "kimai_duplicate_timesheet",
+                endpoint: `PATCH ${sourceEndpoint}/duplicate`,
+                authorization_note: params.authorization_note,
+                before: before.data,
+                after: response.data
+            });
+            const data = { backup_file: backupFile, source: before.data, timesheet: response.data };
+            const markdown = [
+                "# Kimai Timesheet Duplicated",
+                "",
+                `Backup file: ${backupFile}`,
+                "",
+                summarizeRecord(response.data, ["id", "user", "project", "activity", "begin", "end", "duration", "description"])
+            ].join("\n");
+            return makeToolResponse(data, formatResponse(params.response_format, data, markdown));
+        }
+        catch (error) {
+            const data = { error: formatApiError(error) };
+            return makeToolResponse(data, data.error, true);
+        }
+    });
+}
+async function runStateChange(client, params, operation, action) {
+    try {
+        const sourceEndpoint = `/api/timesheets/${encodeURIComponent(String(params.id))}`;
+        const before = await client.get(sourceEndpoint);
+        const request = action === "restart" && params.begin ? { begin: params.begin } : undefined;
+        const response = await client.patch(`${sourceEndpoint}/${action}`, request);
+        const backupFile = await writeMutationBackup({
+            operation,
+            endpoint: `PATCH ${sourceEndpoint}/${action}`,
+            authorization_note: params.authorization_note,
+            before: before.data,
+            request,
+            after: response.data
+        });
+        const data = { backup_file: backupFile, before: before.data, timesheet: response.data };
+        const markdown = [
+            `# Kimai Timesheet ${action === "stop" ? "Stopped" : "Restarted"}`,
+            "",
+            `Backup file: ${backupFile}`,
+            "",
+            summarizeRecord(response.data, ["id", "user", "project", "activity", "begin", "end", "duration", "description"])
+        ].join("\n");
+        return makeToolResponse(data, formatResponse(params.response_format, data, markdown));
+    }
+    catch (error) {
+        const data = { error: formatApiError(error) };
+        return makeToolResponse(data, data.error, true);
+    }
+}
+function buildTimesheetPayload(params, excludedKeys) {
+    const excluded = new Set(excludedKeys);
+    const payload = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (excluded.has(key) || value === undefined || value === null || value === "")
+            continue;
+        payload[toKimaiFieldName(key)] = Array.isArray(value) ? value.join(",") : value;
+    }
+    return payload;
+}
+function toKimaiFieldName(key) {
+    if (key === "fixed_rate")
+        return "fixedRate";
+    if (key === "hourly_rate")
+        return "hourlyRate";
+    return key;
+}

package/dist/tools/timesheets.js

@@ -0,0 +1,51 @@
+import { CollectionSchema, EntityIdSchema, TimesheetCollectionSchema } from "../schemas/resources.js";
+import { registerCollectionReadTool, registerEntityReadTool } from "./read-tools.js";
+export function registerTimesheetTools(server, client) {
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_timesheets",
+        title: "List Kimai Timesheets",
+        description: "List Kimai timesheet entries from /api/timesheets with optional user, customer, project, activity, date, tag, exported, and active filters. This tool is read-only.",
+        inputSchema: TimesheetCollectionSchema.shape,
+        path: () => "/api/timesheets",
+        query: (params) => ({
+            user: params.user,
+            customer: params.customer,
+            project: params.project,
+            activity: params.activity,
+            begin: params.begin,
+            end: params.end,
+            exported: params.exported,
+            active: params.active,
+            tags: Array.isArray(params.tags) ? params.tags.join(",") : undefined
+        }),
+        preferredFields: ["id", "user", "project", "activity", "begin", "end", "duration", "rate", "description"],
+        heading: "Kimai Timesheets"
+    });
+    registerEntityReadTool(server, client, {
+        name: "kimai_get_timesheet",
+        title: "Get Kimai Timesheet",
+        description: "Read one Kimai timesheet entry from /api/timesheets/<id>. This tool is read-only.",
+        inputSchema: EntityIdSchema.shape,
+        path: (params) => `/api/timesheets/${encodeURIComponent(String(params.id))}`,
+        preferredFields: ["id", "user", "project", "activity", "begin", "end", "duration", "rate", "description"],
+        heading: "Kimai Timesheet"
+    });
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_active_timesheets",
+        title: "List Active Kimai Timesheets",
+        description: "List currently running Kimai timesheet entries from /api/timesheets/active. This tool is read-only.",
+        inputSchema: CollectionSchema.shape,
+        path: () => "/api/timesheets/active",
+        preferredFields: ["id", "user", "project", "activity", "begin", "duration", "description"],
+        heading: "Active Kimai Timesheets"
+    });
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_recent_timesheets",
+        title: "List Recent Kimai Timesheets",
+        description: "List recent Kimai timesheet entries from /api/timesheets/recent. This tool is read-only.",
+        inputSchema: CollectionSchema.shape,
+        path: () => "/api/timesheets/recent",
+        preferredFields: ["id", "user", "project", "activity", "begin", "end", "duration", "description"],
+        heading: "Recent Kimai Timesheets"
+    });
+}

package/dist/tools/users.js

@@ -0,0 +1,47 @@
+import { formatApiError } from "../services/errors.js";
+import { CollectionSchema, EntityIdSchema } from "../schemas/resources.js";
+import { ServerInfoSchema } from "../schemas/server.js";
+import { formatResponse, makeToolResponse, summarizeRecord } from "./format.js";
+import { registerCollectionReadTool, registerEntityReadTool } from "./read-tools.js";
+export function registerUserTools(server, client) {
+    server.registerTool("kimai_get_current_user", {
+        title: "Get Current Kimai User",
+        description: "Read the current Kimai user from /api/users/me. This tool is read-only.",
+        inputSchema: ServerInfoSchema.shape,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async ({ response_format }) => {
+        try {
+            const response = await client.get("/api/users/me");
+            const data = { user: response.data };
+            const markdown = ["# Current Kimai User", "", summarizeRecord(response.data, ["id", "username", "alias", "email", "enabled"])].join("\n");
+            return makeToolResponse(data, formatResponse(response_format, data, markdown));
+        }
+        catch (error) {
+            const data = { error: formatApiError(error) };
+            return makeToolResponse(data, data.error, true);
+        }
+    });
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_users",
+        title: "List Kimai Users",
+        description: "List Kimai users visible to the API token from /api/users. This tool is read-only.",
+        inputSchema: CollectionSchema.shape,
+        path: () => "/api/users",
+        preferredFields: ["id", "username", "alias", "email", "enabled"],
+        heading: "Kimai Users"
+    });
+    registerEntityReadTool(server, client, {
+        name: "kimai_get_user",
+        title: "Get Kimai User",
+        description: "Read one Kimai user from /api/users/<id>. This tool is read-only.",
+        inputSchema: EntityIdSchema.shape,
+        path: (params) => `/api/users/${encodeURIComponent(String(params.id))}`,
+        preferredFields: ["id", "username", "alias", "email", "enabled"],
+        heading: "Kimai User"
+    });
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@nightsquawktech/kimai-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for read-only access to Kimai time-tracking instances.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "COMMERCIAL.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "clean": "rimraf dist"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "axios": "^1.13.2",
+    "dotenv": "^16.4.7",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "license": "AGPL-3.0-only",
+  "author": "Kevin Reyes (NightSquawk Tech) <hello@nightsquawk.tech>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NightSquawk/kimai-mcp-server.git"
+  },
+  "homepage": "https://github.com/NightSquawk/kimai-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/NightSquawk/kimai-mcp-server/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}