mcp-costlocker 0.1.0

package/dist/tools/timesheet.js

@@ -0,0 +1,206 @@
+import { SortDirections, TimeEntryGroupByOptions, TimeEntryGroupSortingOptions, TimeEntrySortingOptions, } from "../integrations/costlocker/generated/client.js";
+import { toNextDate, validateDate } from "../integrations/costlocker/client.js";
+import { jsonText, toolError, truncateItems, TRUNCATION_LIMIT } from "./shared.js";
+import { z } from "zod";
+const dateSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "Expected YYYY-MM-DD");
+async function fetchTimeEntriesMerged(sdk, filterBase) {
+    const filterProject = {
+        ...filterBase,
+        nonproject: false,
+    };
+    const filterNon = {
+        ...filterBase,
+        nonproject: true,
+    };
+    const sort = {
+        sortBy: [TimeEntrySortingOptions.Date],
+        direction: SortDirections.Asc,
+    };
+    const pageSize = 100;
+    const fetchAll = async (filter) => {
+        const out = [];
+        let page = 1;
+        let total = 0;
+        while (true) {
+            const res = await sdk.McpTimeEntries({
+                filter,
+                pagination: { page, pageSize },
+                sorting: sort,
+            });
+            const items = res.timeEntries.items ?? [];
+            total = res.timeEntries.totalCount ?? items.length + out.length;
+            out.push(...items);
+            if (items.length < pageSize || out.length >= total)
+                break;
+            page += 1;
+            if (out.length >= TRUNCATION_LIMIT * 2)
+                break;
+        }
+        return out;
+    };
+    const [a, b] = await Promise.all([fetchAll(filterProject), fetchAll(filterNon)]);
+    const byUuid = new Map();
+    for (const e of [...a, ...b]) {
+        byUuid.set(String(e.uuid), e);
+    }
+    return Array.from(byUuid.values());
+}
+export function registerTimesheetTools(server, sdk) {
+    server.registerTool("costlocker_log_time", {
+        title: "Log time",
+        description: "[WRITE] Create a time entry on a budget activity. Duration is in hours. Confirm with the user first.",
+        annotations: {
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        inputSchema: {
+            budget_id: z.number().int().positive(),
+            activity_id: z.number().int().positive(),
+            person_id: z.number().int().positive().optional(),
+            hours: z.number().positive().max(24),
+            date: dateSchema.optional().describe("Defaults to today (UTC date)"),
+            description: z.string().optional(),
+        },
+    }, async (args) => {
+        try {
+            const budget_id = args.budget_id;
+            const activity_id = args.activity_id;
+            const hours = args.hours;
+            const dateStr = args.date ?? new Date().toISOString().slice(0, 10);
+            validateDate(dateStr);
+            const me = args.person_id
+                ? { id: args.person_id }
+                : (await sdk.McpGetMe({})).currentPerson;
+            const startAt = `${dateStr}T12:00:00.000Z`;
+            const data = await sdk.McpCreateTimeEntry({
+                input: [
+                    {
+                        assignmentKey: {
+                            personId: me.id,
+                            taskKey: {
+                                budgetId: budget_id,
+                                activityId: activity_id,
+                            },
+                        },
+                        duration: hours,
+                        description: args.description,
+                        startAt,
+                    },
+                ],
+            });
+            return jsonText(`Logged ${hours}h on budget ${budget_id}, activity ${activity_id}`, { entries: data.createTimeEntry });
+        }
+        catch (error) {
+            return toolError("logging time", error);
+        }
+    });
+    server.registerTool("costlocker_get_timesheet", {
+        description: "List time entries in a date range (project + non-project). Optional filters by person and budget.",
+        inputSchema: {
+            date_from: dateSchema.optional(),
+            date_to: dateSchema.optional().describe("Inclusive end date"),
+            person_id: z.number().int().positive().optional(),
+            budget_id: z.number().int().positive().optional(),
+        },
+    }, async (args) => {
+        try {
+            const today = new Date().toISOString().slice(0, 10);
+            const dateFrom = validateDate(args.date_from ?? today);
+            const dateTo = validateDate(args.date_to ?? dateFrom);
+            const endExclusive = toNextDate(dateTo);
+            const filterBase = {
+                dateRange: { start: dateFrom, end: endExclusive },
+            };
+            if (args.person_id) {
+                filterBase.personIds = { includeIds: [args.person_id] };
+            }
+            if (args.budget_id) {
+                filterBase.budget = [args.budget_id];
+            }
+            const merged = await fetchTimeEntriesMerged(sdk, filterBase);
+            const { items, truncated, total } = truncateItems(merged);
+            return jsonText(`Found ${total} entries${truncated ? ` (showing first ${items.length})` : ""}`, { entries: items });
+        }
+        catch (error) {
+            return toolError("getting timesheet", error);
+        }
+    });
+    server.registerTool("costlocker_get_monthly_timesheet", {
+        description: "Aggregated hours grouped by project and person for a date range.",
+        inputSchema: {
+            date_from: dateSchema,
+            date_to: dateSchema.describe("Inclusive end date"),
+            person_id: z.number().int().positive().optional(),
+            budget_id: z.number().int().positive().optional(),
+        },
+    }, async (args) => {
+        try {
+            const dateFrom = validateDate(args.date_from);
+            const dateTo = validateDate(args.date_to);
+            const endExclusive = toNextDate(dateTo);
+            const filter = {
+                dateRange: { start: dateFrom, end: endExclusive },
+                nonproject: false,
+            };
+            if (args.person_id)
+                filter.personIds = { includeIds: [args.person_id] };
+            if (args.budget_id)
+                filter.budget = [args.budget_id];
+            const data = await sdk.McpTimeEntriesGroup({
+                filter,
+                groupBy: {
+                    groups: [
+                        TimeEntryGroupByOptions.Projects,
+                        TimeEntryGroupByOptions.Persons,
+                    ],
+                },
+                sorting: {
+                    sortBy: [TimeEntryGroupSortingOptions.Hours],
+                    direction: SortDirections.Desc,
+                },
+            });
+            const groups = data.timeEntriesGroup ?? [];
+            const { items, truncated, total } = truncateItems(groups);
+            return jsonText(`Aggregated ${total} group row(s)${truncated ? ` (showing first ${items.length})` : ""}`, { data: items });
+        }
+        catch (error) {
+            return toolError("getting monthly timesheet", error);
+        }
+    });
+    server.registerTool("costlocker_get_running_entry", {
+        description: "Get the currently running time entry, if any.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const data = await sdk.McpRunningTracking({});
+            return jsonText("Running time entry", { entry: data.runningTracking });
+        }
+        catch (error) {
+            return toolError("getting running entry", error);
+        }
+    });
+    server.registerTool("costlocker_get_assignments", {
+        description: "List assignments the user can log time to. Uses current person unless person_id is set.",
+        inputSchema: {
+            person_id: z.number().int().positive().optional(),
+        },
+    }, async (args) => {
+        try {
+            const personId = args.person_id ?? (await sdk.McpGetMe({})).currentPerson.id;
+            const startsBefore = new Date(Date.now() + 1000 * 86400 * 365 * 10).toISOString();
+            const data = await sdk.McpAssignments({
+                personId,
+                startsBefore,
+            });
+            const raw = data.assignments ?? [];
+            const { items, truncated, total } = truncateItems(raw);
+            return jsonText(`${total} assignment(s)${truncated ? ` (showing first ${items.length})` : ""}`, { assignments: items });
+        }
+        catch (error) {
+            return toolError("getting assignments", error);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "mcp-costlocker",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for Costlocker (GraphQL time entries).",
+  "type": "module",
+  "bin": {
+    "mcp-costlocker": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
+    "format": "prettier --write .",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --config=jest.config.mjs",
+    "docs:list": "tsx scripts/docs-list.ts",
+    "graphql:codegen": "graphql-codegen --config codegen.ts",
+    "start": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "dotenv": "^16.5.0",
+    "graphql-tag": "^2.12.6",
+    "tslab": "^1.0.22",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@eslint/eslintrc": "^3",
+    "@eslint/js": "^9.26.0",
+    "@graphql-codegen/cli": "^6.2.1",
+    "@graphql-codegen/typescript": "^5.0.9",
+    "@graphql-codegen/typescript-generic-sdk": "^5.0.0",
+    "@graphql-codegen/typescript-operations": "^5.0.9",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20",
+    "@types/uuid": "^9.0.8",
+    "@typescript-eslint/eslint-plugin": "^8.32.0",
+    "@typescript-eslint/parser": "^8.32.0",
+    "cross-env": "^7.0.3",
+    "eslint": "^9",
+    "eslint-config-prettier": "^10.1.3",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-no-instanceof": "^1.0.1",
+    "eslint-plugin-unused-imports": "^4.1.4",
+    "globals": "^16.1.0",
+    "graphql": "^16.13.2",
+    "jest": "^29.7.0",
+    "jest-ts-webcompat-resolver": "^1.0.1",
+    "prettier": "^3.5.3",
+    "ts-jest": "^29.1.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5",
+    "uuid": "^9.0.1"
+  },
+  "packageManager": "pnpm@10.9.0+sha512.0486e394640d3c1fb3c9d43d49cf92879ff74f8516959c235308f5a8f62e2e19528a65cdc2a3058f587cde71eba3d5b56327c8c33a97e4c4051ca48a10ca2d5f"
+}