@nightsquawktech/kimai-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @nightsquawktech/kimai-mcp-server
+
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/NightSquawk/kimai-mcp-server/badge)](https://scorecard.dev/viewer/?uri=github.com/NightSquawk/kimai-mcp-server)
+
+Model Context Protocol server for Kimai time-tracking instances. Read tools cover the full Kimai API surface; timesheet write tools exist but are guarded behind explicit authorization.
+
+## API Notes
+
+Kimai exposes a JSON API under `/api`. Current Kimai documentation uses bearer-token authentication:
+
+```http
+Authorization: Bearer <api-token>
+```
+
+The base URL should be the browser URL without a trailing slash, for example `https://demo.kimai.org`, not `https://demo.kimai.org/`. Kimai's current API docs are available at your own instance under `/api/doc`, and official docs note that the OpenAPI export is available from that UI.
+
+Pagination uses `page` and `size` query parameters. Kimai defaults to 50 records per page and documents 500 as the maximum page size. Paginated responses may include `X-Page`, `X-Total-Count`, `X-Total-Pages`, and `X-Per-Page` headers.
+
+Read tools are safe to call without changing Kimai. Write tools are intentionally guarded because Kimai timekeeping data is sensitive:
+
+- Every write tool requires `authorization_confirmed: true`.
+- Every write tool requires an `authorization_note` describing the user's explicit approval.
+- Every write tool writes a JSON backup under the system temp directory before or immediately after mutation.
+- Update/state-change tools save the previous Kimai record before calling the mutation endpoint.
+- Create/duplicate tools save the request/source and created record so the created ID can be audited and reverted manually if needed.
+- Delete tools are intentionally not exposed.
+
+References:
+
+- https://www.kimai.org/documentation/rest-api.html
+- https://www.kimai.org/documentation/user-api.html
+- https://www.kimai.org/documentation/api-pagination.html
+
+## Tools
+
+- `kimai_get_server_info` reads `/api/ping`, `/api/version`, `/api/plugins`, and `/api/config/timesheet`.
+- `kimai_get_current_user` reads `/api/users/me`.
+- `kimai_list_users` and `kimai_get_user` read users.
+- `kimai_list_customers` and `kimai_get_customer` read customers.
+- `kimai_list_projects` and `kimai_get_project` read projects.
+- `kimai_list_activities` and `kimai_get_activity` read activities.
+- `kimai_list_tags` reads tags.
+- `kimai_list_timesheets`, `kimai_get_timesheet`, `kimai_list_active_timesheets`, and `kimai_list_recent_timesheets` read time entries.
+- `kimai_create_timesheet` creates a time entry after explicit authorization and stores a temp backup.
+- `kimai_update_timesheet` updates a time entry after explicit authorization and stores the previous record in a temp backup.
+- `kimai_stop_timesheet` stops an active time entry after explicit authorization and stores the previous record in a temp backup.
+- `kimai_restart_timesheet` restarts a stopped time entry after explicit authorization and stores the previous record in a temp backup.
+- `kimai_duplicate_timesheet` duplicates a time entry after explicit authorization and stores source/created records in a temp backup.
+- `kimai_list_teams` and `kimai_get_team` read teams.
+- `kimai_list_invoices` and `kimai_get_invoice` read invoice history.
+- `kimai_list_expenses` and `kimai_get_expense` read expenses when that endpoint is available.
+- `kimai_list_tasks` and `kimai_get_task` read tasks when that endpoint is available.
+
+## Setup
+
+Configure an MCP client to run the server with `npx`:
+
+```json
+{
+  "mcpServers": {
+    "kimai": {
+      "command": "npx",
+      "args": ["-y", "@nightsquawktech/kimai-mcp-server"],
+      "env": {
+        "KIMAI_BASE_URL": "https://your-instance.example.com",
+        "KIMAI_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+For Codex global TOML config:
+
+```toml
+[mcp_servers.kimai]
+command = "npx"
+args = ["-y", "@nightsquawktech/kimai-mcp-server"]
+
+[mcp_servers.kimai.env]
+KIMAI_BASE_URL = "https://your-instance.example.com"
+KIMAI_API_TOKEN = "your-api-token"
+```
+
+### Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `KIMAI_BASE_URL` | Yes | Base URL of your Kimai instance without a trailing slash, e.g. `https://your-instance.example.com` |
+| `KIMAI_API_TOKEN` | Yes | Kimai API token (bearer token) |
+| `KIMAI_TIMEOUT_MS` | No | HTTP request timeout in milliseconds, default `30000` |
+
+## Development
+
+```sh
+npm install
+npm run dev
+npm run build
+```
+
+Create `.env` for local development:
+
+```env
+KIMAI_BASE_URL=https://your-instance.example.com
+KIMAI_API_TOKEN=your-api-token
+KIMAI_TIMEOUT_MS=30000
+```
+
+The server uses stdio for local MCP clients. Use stderr for logs so stdout remains reserved for MCP protocol messages.
+
+## License
+
+Licensed under the [GNU AGPL v3.0](./LICENSE). Free for personal and open-source use.
+
+Organizations that cannot comply with the AGPL can purchase a commercial license. See [COMMERCIAL.md](./COMMERCIAL.md) or contact hello@nightsquawk.tech.

package/dist/constants.js

@@ -0,0 +1,9 @@
+export const SERVER_NAME = "kimai-mcp-server";
+export const SERVER_VERSION = "0.1.0";
+export const ENV = {
+    baseUrl: "KIMAI_BASE_URL",
+    apiToken: "KIMAI_API_TOKEN",
+    timeoutMs: "KIMAI_TIMEOUT_MS"
+};
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const RESPONSE_CHARACTER_LIMIT = 25_000;

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
+import { KimaiClient } from "./services/kimai-client.js";
+import { loadConfig } from "./services/config.js";
+import { registerTools } from "./tools/index.js";
+async function main() {
+    const config = loadConfig();
+    const client = new KimaiClient(config);
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION
+    });
+    registerTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${SERVER_NAME} ${SERVER_VERSION} running on stdio`);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/schemas/common.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export const ResponseFormatSchema = z
+    .enum(["markdown", "json"])
+    .default("markdown")
+    .describe("Output format: markdown for human-readable summaries, json for structured output.");
+export const PageSchema = z
+    .number()
+    .int()
+    .min(1)
+    .default(1)
+    .describe("Kimai API page number for paginated endpoints.");
+export const SizeSchema = z
+    .number()
+    .int()
+    .min(1)
+    .max(500)
+    .default(50)
+    .describe("Kimai API page size. Kimai supports a maximum size of 500.");
+export const IdSchema = z.union([z.number().int().positive(), z.string().min(1)]).describe("Kimai entity ID.");
+export const DateTimeSchema = z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Optional date/time filter. Kimai returns ISO 8601; write endpoints use HTML5 local date-time.");
+export const EntityStateSchema = z
+    .enum(["all", "visible", "hidden"])
+    .optional()
+    .describe("Optional visibility filter for endpoints that support it.");

package/dist/schemas/mutations.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { DateTimeSchema, IdSchema, ResponseFormatSchema } from "./common.js";
+const AuthorizationSchema = {
+    authorization_confirmed: z
+        .literal(true)
+        .describe("Must be true only after the human user explicitly authorizes this sensitive Kimai edit."),
+    authorization_note: z
+        .string()
+        .min(8)
+        .describe("Short note capturing the user's explicit authorization and reason for the edit.")
+};
+const TimesheetEditableFields = {
+    begin: DateTimeSchema.describe("Timesheet begin timestamp in Kimai HTML5 datetime-local format, e.g. 2026-06-01T09:00:00."),
+    end: DateTimeSchema.describe("Optional timesheet end timestamp in Kimai HTML5 datetime-local format, e.g. 2026-06-01T10:30:00."),
+    project: IdSchema.optional().describe("Kimai project ID."),
+    activity: IdSchema.optional().describe("Kimai activity ID."),
+    description: z.string().optional().describe("Optional timesheet description."),
+    fixed_rate: z.number().optional().describe("Optional fixed rate override."),
+    hourly_rate: z.number().optional().describe("Optional hourly rate override."),
+    user: IdSchema.optional().describe("Optional user ID; requires permission to edit other users' time."),
+    tags: z.array(z.string().min(1)).optional().describe("Optional tags; sent to Kimai as a comma-separated list."),
+    exported: z.boolean().optional().describe("Optional exported flag. This can lock/unlock timesheet records."),
+    billable: z.boolean().optional().describe("Optional billable flag.")
+};
+export const CreateTimesheetSchema = z
+    .object({
+    ...AuthorizationSchema,
+    begin: z.string().min(1).describe("Timesheet begin timestamp in Kimai HTML5 datetime-local format, e.g. 2026-06-01T09:00:00."),
+    project: IdSchema.describe("Kimai project ID."),
+    activity: IdSchema.describe("Kimai activity ID."),
+    end: TimesheetEditableFields.end,
+    description: TimesheetEditableFields.description,
+    fixed_rate: TimesheetEditableFields.fixed_rate,
+    hourly_rate: TimesheetEditableFields.hourly_rate,
+    user: TimesheetEditableFields.user,
+    tags: TimesheetEditableFields.tags,
+    exported: TimesheetEditableFields.exported,
+    billable: TimesheetEditableFields.billable,
+    full: z.boolean().default(true).describe("Request fully serialized Kimai response where supported."),
+    response_format: ResponseFormatSchema
+})
+    .strict();
+export const UpdateTimesheetSchema = z
+    .object({
+    ...AuthorizationSchema,
+    id: IdSchema,
+    ...TimesheetEditableFields,
+    response_format: ResponseFormatSchema
+})
+    .strict();
+export const TimesheetStateChangeSchema = z
+    .object({
+    ...AuthorizationSchema,
+    id: IdSchema,
+    begin: DateTimeSchema.describe("Optional restart begin timestamp in Kimai HTML5 datetime-local format."),
+    response_format: ResponseFormatSchema
+})
+    .strict();
+export const DuplicateTimesheetSchema = z
+    .object({
+    ...AuthorizationSchema,
+    id: IdSchema,
+    response_format: ResponseFormatSchema
+})
+    .strict();

package/dist/schemas/resources.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { DateTimeSchema, EntityStateSchema, IdSchema, PageSchema, ResponseFormatSchema, SizeSchema } from "./common.js";
+export const CollectionSchema = z
+    .object({
+    page: PageSchema,
+    size: SizeSchema,
+    response_format: ResponseFormatSchema
+})
+    .strict();
+export const EntityIdSchema = z
+    .object({
+    id: IdSchema,
+    response_format: ResponseFormatSchema
+})
+    .strict();
+export const SearchableCollectionSchema = CollectionSchema.extend({
+    term: z.string().min(1).optional().describe("Optional search term for endpoints that support it."),
+    order_by: z.string().min(1).optional().describe("Optional Kimai orderBy field."),
+    order: z.enum(["ASC", "DESC"]).optional().describe("Optional sort direction.")
+}).strict();
+export const CustomerCollectionSchema = SearchableCollectionSchema.extend({
+    visible: EntityStateSchema
+}).strict();
+export const ProjectCollectionSchema = SearchableCollectionSchema.extend({
+    customer: IdSchema.optional().describe("Optional customer ID filter."),
+    visible: EntityStateSchema
+}).strict();
+export const ActivityCollectionSchema = SearchableCollectionSchema.extend({
+    project: IdSchema.optional().describe("Optional project ID filter."),
+    visible: EntityStateSchema
+}).strict();
+export const TimesheetCollectionSchema = CollectionSchema.extend({
+    user: IdSchema.optional().describe("Optional user ID filter."),
+    customer: IdSchema.optional().describe("Optional customer ID filter."),
+    project: IdSchema.optional().describe("Optional project ID filter."),
+    activity: IdSchema.optional().describe("Optional activity ID filter."),
+    begin: DateTimeSchema.describe("Optional begin date/time filter."),
+    end: DateTimeSchema.describe("Optional end date/time filter."),
+    exported: z.boolean().optional().describe("Optional exported-state filter."),
+    active: z.boolean().optional().describe("Optional active/running filter."),
+    tags: z.array(z.string().min(1)).optional().describe("Optional tag filters.")
+}).strict();
+export const TagCollectionSchema = CollectionSchema.extend({
+    name: z.string().min(1).optional().describe("Optional tag name search.")
+}).strict();

package/dist/schemas/server.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { ResponseFormatSchema } from "./common.js";
+export const ServerInfoSchema = z
+    .object({
+    response_format: ResponseFormatSchema
+})
+    .strict();

package/dist/services/backups.js

@@ -0,0 +1,16 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export async function writeMutationBackup(record) {
+    const directory = join(tmpdir(), "kimai-mcp-backups");
+    await mkdir(directory, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const safeOperation = record.operation.replace(/[^a-z0-9_-]+/gi, "-").toLowerCase();
+    const filename = `${stamp}-${safeOperation}.json`;
+    const fullPath = join(directory, filename);
+    await writeFile(fullPath, JSON.stringify({
+        created_at: new Date().toISOString(),
+        ...record
+    }, null, 2), "utf8");
+    return fullPath;
+}

package/dist/services/config.js

@@ -0,0 +1,22 @@
+import "dotenv/config";
+import { DEFAULT_TIMEOUT_MS, ENV } from "../constants.js";
+export function loadConfig() {
+    const baseUrl = process.env[ENV.baseUrl]?.trim();
+    const apiToken = process.env[ENV.apiToken]?.trim();
+    const timeoutRaw = process.env[ENV.timeoutMs]?.trim();
+    if (!baseUrl) {
+        throw new Error(`${ENV.baseUrl} is required, for example https://example.kimai.cloud`);
+    }
+    if (!apiToken) {
+        throw new Error(`${ENV.apiToken} is required. Generate an API token in your Kimai user profile.`);
+    }
+    const timeoutMs = timeoutRaw ? Number.parseInt(timeoutRaw, 10) : DEFAULT_TIMEOUT_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 1_000) {
+        throw new Error(`${ENV.timeoutMs} must be an integer of at least 1000 milliseconds.`);
+    }
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ""),
+        apiToken,
+        timeoutMs
+    };
+}

package/dist/services/errors.js

@@ -0,0 +1,38 @@
+import axios from "axios";
+export function formatApiError(error) {
+    if (axios.isAxiosError(error)) {
+        if (error.response) {
+            const status = error.response.status;
+            const detail = formatErrorData(error.response.data);
+            if (status === 401 || status === 403) {
+                return `Kimai denied the request (${status}). Check KIMAI_API_TOKEN and the user's API permissions.${detail}`;
+            }
+            if (status === 404) {
+                return `Kimai resource not found (404). Check the ID and endpoint path.${detail}`;
+            }
+            if (status === 429) {
+                return `Kimai rate limited the request (429). Retry later or reduce request volume.${detail}`;
+            }
+            return `Kimai API request failed (${status}).${detail}`;
+        }
+        if (error.code === "ECONNABORTED") {
+            return "Kimai API request timed out. Increase KIMAI_TIMEOUT_MS or narrow the query.";
+        }
+        if (error.code) {
+            return `Kimai API connection failed (${error.code}). Check KIMAI_BASE_URL and network access.`;
+        }
+    }
+    return `Unexpected Kimai error: ${error instanceof Error ? error.message : String(error)}`;
+}
+function formatErrorData(data) {
+    if (data === undefined || data === null)
+        return "";
+    if (typeof data === "string")
+        return ` Response: ${data}`;
+    try {
+        return ` Response: ${JSON.stringify(data)}`;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/services/kimai-client.js

@@ -0,0 +1,66 @@
+import axios from "axios";
+export class KimaiClient {
+    http;
+    constructor(config) {
+        this.http = axios.create({
+            baseURL: config.baseUrl,
+            timeout: config.timeoutMs,
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${config.apiToken}`
+            }
+        });
+    }
+    async request(method, path, options = {}) {
+        const response = await this.http.request({
+            method,
+            url: normalizePath(path),
+            ...options
+        });
+        return {
+            data: response.data,
+            pagination: extractPagination(response)
+        };
+    }
+    get(path, params) {
+        return this.request("GET", path, { params: pruneUndefined(params) });
+    }
+    post(path, data, params) {
+        return this.request("POST", path, { data: pruneUndefined(data), params: pruneUndefined(params) });
+    }
+    patch(path, data, params) {
+        return this.request("PATCH", path, { data: pruneUndefined(data), params: pruneUndefined(params) });
+    }
+}
+function normalizePath(path) {
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    return cleanPath.includes("?") ? cleanPath : cleanPath.replace(/\/+$/, "");
+}
+function pruneUndefined(params) {
+    if (!params)
+        return undefined;
+    const entries = Object.entries(params).filter(([, value]) => {
+        if (value === undefined || value === null || value === "")
+            return false;
+        if (Array.isArray(value) && value.length === 0)
+            return false;
+        return true;
+    });
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function extractPagination(response) {
+    const headers = response.headers;
+    return {
+        page: toNumber(headers["x-page"]),
+        total_count: toNumber(headers["x-total-count"]),
+        total_pages: toNumber(headers["x-total-pages"]),
+        per_page: toNumber(headers["x-per-page"])
+    };
+}
+function toNumber(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}

package/dist/tools/business.js

@@ -0,0 +1,45 @@
+import { CollectionSchema, EntityIdSchema, SearchableCollectionSchema } from "../schemas/resources.js";
+import { registerCollectionReadTool, registerEntityReadTool } from "./read-tools.js";
+export function registerBusinessTools(server, client) {
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_teams",
+        title: "List Kimai Teams",
+        description: "List Kimai teams from /api/teams. This tool is read-only.",
+        inputSchema: CollectionSchema.shape,
+        path: () => "/api/teams",
+        preferredFields: ["id", "name"],
+        heading: "Kimai Teams"
+    });
+    registerEntityReadTool(server, client, {
+        name: "kimai_get_team",
+        title: "Get Kimai Team",
+        description: "Read one Kimai team from /api/teams/<id>. This tool is read-only.",
+        inputSchema: EntityIdSchema.shape,
+        path: (params) => `/api/teams/${encodeURIComponent(String(params.id))}`,
+        preferredFields: ["id", "name"],
+        heading: "Kimai Team"
+    });
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_invoices",
+        title: "List Kimai Invoices",
+        description: "List Kimai invoices from /api/invoices. This tool is read-only.",
+        inputSchema: SearchableCollectionSchema.shape,
+        path: () => "/api/invoices",
+        query: (params) => ({
+            term: params.term,
+            orderBy: params.order_by,
+            order: params.order
+        }),
+        preferredFields: ["id", "invoiceNumber", "customer", "user", "total", "createdAt", "status"],
+        heading: "Kimai Invoices"
+    });
+    registerEntityReadTool(server, client, {
+        name: "kimai_get_invoice",
+        title: "Get Kimai Invoice",
+        description: "Read one Kimai invoice from /api/invoices/<id>. This tool is read-only.",
+        inputSchema: EntityIdSchema.shape,
+        path: (params) => `/api/invoices/${encodeURIComponent(String(params.id))}`,
+        preferredFields: ["id", "invoiceNumber", "customer", "user", "total", "createdAt", "status"],
+        heading: "Kimai Invoice"
+    });
+}

package/dist/tools/catalog.js

@@ -0,0 +1,81 @@
+import { ActivityCollectionSchema, CustomerCollectionSchema, EntityIdSchema, ProjectCollectionSchema, TagCollectionSchema } from "../schemas/resources.js";
+import { registerCollectionReadTool, registerEntityReadTool } from "./read-tools.js";
+export function registerCatalogTools(server, client) {
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_customers",
+        title: "List Kimai Customers",
+        description: "List customers visible to the Kimai API token from /api/customers. This tool is read-only.",
+        inputSchema: CustomerCollectionSchema.shape,
+        path: () => "/api/customers",
+        query: (params) => commonQuery(params),
+        preferredFields: ["id", "name", "number", "company", "visible", "country"],
+        heading: "Kimai Customers"
+    });
+    registerEntityReadTool(server, client, {
+        name: "kimai_get_customer",
+        title: "Get Kimai Customer",
+        description: "Read one Kimai customer from /api/customers/<id>. This tool is read-only.",
+        inputSchema: EntityIdSchema.shape,
+        path: (params) => `/api/customers/${encodeURIComponent(String(params.id))}`,
+        preferredFields: ["id", "name", "number", "company", "visible", "country"],
+        heading: "Kimai Customer"
+    });
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_projects",
+        title: "List Kimai Projects",
+        description: "List projects visible to the Kimai API token from /api/projects, optionally filtered by customer. This tool is read-only.",
+        inputSchema: ProjectCollectionSchema.shape,
+        path: () => "/api/projects",
+        query: (params) => commonQuery(params),
+        preferredFields: ["id", "name", "customer", "visible", "orderNumber", "budget"],
+        heading: "Kimai Projects"
+    });
+    registerEntityReadTool(server, client, {
+        name: "kimai_get_project",
+        title: "Get Kimai Project",
+        description: "Read one Kimai project from /api/projects/<id>. This tool is read-only.",
+        inputSchema: EntityIdSchema.shape,
+        path: (params) => `/api/projects/${encodeURIComponent(String(params.id))}`,
+        preferredFields: ["id", "name", "customer", "visible", "orderNumber", "budget"],
+        heading: "Kimai Project"
+    });
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_activities",
+        title: "List Kimai Activities",
+        description: "List activities visible to the Kimai API token from /api/activities, optionally filtered by project. This tool is read-only.",
+        inputSchema: ActivityCollectionSchema.shape,
+        path: () => "/api/activities",
+        query: (params) => commonQuery(params),
+        preferredFields: ["id", "name", "project", "visible", "budget", "timeBudget"],
+        heading: "Kimai Activities"
+    });
+    registerEntityReadTool(server, client, {
+        name: "kimai_get_activity",
+        title: "Get Kimai Activity",
+        description: "Read one Kimai activity from /api/activities/<id>. This tool is read-only.",
+        inputSchema: EntityIdSchema.shape,
+        path: (params) => `/api/activities/${encodeURIComponent(String(params.id))}`,
+        preferredFields: ["id", "name", "project", "visible", "budget", "timeBudget"],
+        heading: "Kimai Activity"
+    });
+    registerCollectionReadTool(server, client, {
+        name: "kimai_list_tags",
+        title: "List Kimai Tags",
+        description: "List Kimai tags from /api/tags/find. This tool is read-only.",
+        inputSchema: TagCollectionSchema.shape,
+        path: () => "/api/tags/find",
+        query: (params) => ({ name: params.name }),
+        preferredFields: ["id", "name", "color"],
+        heading: "Kimai Tags"
+    });
+}
+function commonQuery(params) {
+    return {
+        term: params.term,
+        orderBy: params.order_by,
+        order: params.order,
+        visible: params.visible,
+        customer: params.customer,
+        project: params.project
+    };
+}

package/dist/tools/format.js

@@ -0,0 +1,70 @@
+import { RESPONSE_CHARACTER_LIMIT } from "../constants.js";
+export function paginateResponse(response, page, size) {
+    const items = extractItems(response.data);
+    const total = response.pagination.total_count ?? items.length;
+    const totalPages = response.pagination.total_pages;
+    const currentPage = response.pagination.page ?? page;
+    const hasMore = totalPages !== undefined ? currentPage < totalPages : items.length === size;
+    return {
+        total,
+        count: items.length,
+        page: currentPage,
+        size: response.pagination.per_page ?? size,
+        items,
+        has_more: hasMore,
+        ...(hasMore ? { next_page: currentPage + 1 } : {}),
+        ...(totalPages !== undefined ? { total_pages: totalPages } : {})
+    };
+}
+export function makeToolResponse(data, text, isError = false) {
+    const responseText = text.length > RESPONSE_CHARACTER_LIMIT
+        ? `${text.slice(0, RESPONSE_CHARACTER_LIMIT)}\n\nResponse truncated at ${RESPONSE_CHARACTER_LIMIT} characters. Use filters or a smaller page size.`
+        : text;
+    return {
+        content: [{ type: "text", text: responseText }],
+        structuredContent: data,
+        ...(isError ? { isError: true } : {})
+    };
+}
+export function formatResponse(format, data, markdown) {
+    return format === "json" ? JSON.stringify(data, null, 2) : markdown;
+}
+export function summarizeRecord(record, preferredFields) {
+    if (!record || typeof record !== "object") {
+        return String(record);
+    }
+    const source = record;
+    const fields = preferredFields
+        .filter((field) => source[field] !== undefined && source[field] !== null && source[field] !== "")
+        .map((field) => `${field}: ${formatInline(source[field])}`);
+    return fields.length > 0 ? fields.join(", ") : JSON.stringify(record);
+}
+export function extractItems(raw) {
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (raw && typeof raw === "object") {
+        const source = raw;
+        for (const key of ["results", "items", "data", "rows"]) {
+            if (Array.isArray(source[key])) {
+                return source[key];
+            }
+        }
+    }
+    return raw === undefined || raw === null ? [] : [raw];
+}
+function formatInline(value) {
+    if (value && typeof value === "object") {
+        const source = value;
+        if (typeof source.name === "string")
+            return source.name;
+        if (typeof source.username === "string")
+            return source.username;
+        if (typeof source.alias === "string")
+            return source.alias;
+        if (typeof source.id === "number" || typeof source.id === "string")
+            return String(source.id);
+        return JSON.stringify(value);
+    }
+    return String(value);
+}

package/dist/tools/index.js

@@ -0,0 +1,16 @@
+import { registerBusinessTools } from "./business.js";
+import { registerCatalogTools } from "./catalog.js";
+import { registerPluginTools } from "./plugins.js";
+import { registerServerTools } from "./server.js";
+import { registerTimesheetMutationTools } from "./timesheet-mutations.js";
+import { registerTimesheetTools } from "./timesheets.js";
+import { registerUserTools } from "./users.js";
+export function registerTools(server, client) {
+    registerServerTools(server, client);
+    registerUserTools(server, client);
+    registerCatalogTools(server, client);
+    registerTimesheetTools(server, client);
+    registerTimesheetMutationTools(server, client);
+    registerBusinessTools(server, client);
+    registerPluginTools(server, client);
+}