itfin-mcp 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# itfin-mcp
+
+Report time and request leave in ITFin by chatting with Claude Code, Codex or Claude Desktop.
+
+## Install (about 2 minutes)
+
+You need macOS, Node.js 22+ and Chrome, Edge, Brave, Arc or Chromium.
+
+1. Run:
+   ```bash
+   npx itfin-mcp@latest install
+   ```
+2. Pick the apps: Claude Code, Codex, Claude Desktop. Space ticks or unticks one, Enter confirms.
+3. Type your company name: `acme` for `https://acme.itfin.io`.
+4. Claude Desktop only: restart it (Cmd+Q, then open it).
+5. Start a new session and say **"log in to ITFin"**.
+
+## Update
+
+Run the same command again. It installs the latest version from npm, keeps your apps and settings and asks nothing.
+
+Installs from before the npm package (a git clone in `~/.itfin-mcp`) are replaced on the first update.
+
+If the update changed anything, it stops the ITFin servers that are still running the old version. Then start a new session (in Claude Code, `/mcp` → reconnect itfin also works) and restart Claude Desktop (Cmd+Q, then open it).
+
+## Log in (once a week)
+
+1. Say **"log in to ITFin"**.
+2. Pick your Google account in the window that opens.
+
+ITFin tokens last 7 days and can't be extended. A macOS notification reminds you at the start of your working day before yours expires.
+
+## Settings
+
+Add flags to the install command to change a setting:
+
+```bash
+npx itfin-mcp@latest install --browser brave --work-start 09:00
+```
+
+| Flag | Default | Sets |
+|---|---|---|
+| `--clients claude,codex,desktop` | asked | Apps to install for |
+| `--company acme` | asked | Workspace `https://acme.itfin.io` |
+| `--url <address>` | | Workspace not on `itfin.io` |
+| `--browser` | `chrome` | `chrome`, `edge`, `brave`, `arc`, `chromium` or a path to the browser |
+| `--work-start` | `10:00` | When relogin reminders fire |
+| `--timezone` | system | IANA timezone, e.g. `Europe/Kyiv` |
+| `--dir` | `~/.itfin-mcp` | Install folder |
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `itfin_login` / `itfin_auth_status` | Log in; check when the token expires |
+| `itfin_list_projects` | Projects and tasks you can report to |
+| `itfin_get_entries` | Your time entries, and which days are open, closed or in the future |
+| `itfin_create_entry` / `itfin_update_entry` / `itfin_delete_entry` | Change time entries |
+| `itfin_get_workspace_settings` | Minimum comment length; whether reopen requests are on |
+| `itfin_request_reopen` / `itfin_list_reopen_requests` | Ask a manager to reopen closed days; see your requests |
+| `itfin_list_leave_types` | Leave types and reasons you can use |
+| `itfin_request_leave` | Request full days, or some hours of one day |
+| `itfin_list_leave_requests` / `itfin_cancel_leave_request` | See or cancel your leave requests |
+
+Reopen and leave requests are sent as soon as you ask for them. Your manager still approves them.
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+```
+
+To try a local build with the installer, pack it and point the installer at the tarball:
+
+```bash
+npm pack
+ITFIN_MCP_PACKAGE=$PWD/itfin-mcp-0.1.0.tgz bash scripts/install.sh
+```
+
+## Releases
+
+Every merge into `main` publishes to npm ([workflow](.github/workflows/publish.yml)) as the next patch version and tags it `v<version>`. For a minor or major release, raise `version` in `package.json` in the PR.

package/dist/clock.js

@@ -0,0 +1 @@
+export const systemClock = { now: () => new Date() };

package/dist/config.js

@@ -0,0 +1,14 @@
+export function loadConfig(env = process.env) {
+    const workspaceUrl = env.ITFIN_URL?.trim().replace(/\/+$/, "");
+    if (!workspaceUrl)
+        throw new Error("ITFIN_URL is required, e.g. https://acme.itfin.io");
+    const workStart = env.ITFIN_WORK_START?.trim() || "10:00";
+    if (!/^\d{1,2}:\d{2}$/.test(workStart))
+        throw new Error("ITFIN_WORK_START must be HH:mm, e.g. 10:00");
+    return {
+        workspaceUrl,
+        browser: env.ITFIN_BROWSER?.trim() || "chrome",
+        workStart,
+        timezone: env.ITFIN_TIMEZONE?.trim() || Intl.DateTimeFormat().resolvedOptions().timeZone,
+    };
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+export class ToolError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+export const TRACKING_NOT_ALLOWED = "Tracking is not allowed for this day.";

package/dist/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { systemClock } from "./clock.js";
+import { loadConfig } from "./config.js";
+import { createItfinServer } from "./server.js";
+import { KeychainTokenStore } from "./tokenStore.js";
+// `npx itfin-mcp install [flags]` runs the installer shipped in the package. Without arguments this
+// is the MCP server itself.
+if (process.argv[2] === "install") {
+    const script = fileURLToPath(new URL("../scripts/install.sh", import.meta.url));
+    const result = spawnSync("bash", [script, ...process.argv.slice(3)], { stdio: "inherit" });
+    process.exit(result.status ?? 1);
+}
+const config = loadConfig();
+const server = createItfinServer({
+    config,
+    clock: systemClock,
+    tokenStore: new KeychainTokenStore("itfin-mcp", config.workspaceUrl),
+});
+await server.connect(new StdioServerTransport());

package/dist/itfinClient.js

@@ -0,0 +1,79 @@
+import { ToolError, TRACKING_NOT_ALLOWED } from "./errors.js";
+const MAX_ATTEMPTS = 3;
+/** Only these are retried; a retried POST could create a second time entry or reopen request. */
+const RETRYABLE_METHODS = new Set(["GET", "PUT", "DELETE"]);
+/** Thin HTTP client for `<workspace>/api`, mapping ITFin failures onto tool errors. */
+export class ItfinClient {
+    workspaceUrl;
+    getToken;
+    retryDelayMs;
+    onUnauthorized;
+    constructor(workspaceUrl, getToken, retryDelayMs, 
+    /** Called with the token ITFin rejected with a 401. */
+    onUnauthorized) {
+        this.workspaceUrl = workspaceUrl;
+        this.getToken = getToken;
+        this.retryDelayMs = retryDelayMs;
+        this.onUnauthorized = onUnauthorized;
+    }
+    get(path, query) {
+        return this.request("GET", path, { query });
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(`${this.workspaceUrl}/api${path}`);
+        for (const [k, v] of Object.entries(opts.query ?? {}))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        const headers = { accept: "application/json" };
+        const token = opts.anonymous ? undefined : await this.getToken();
+        // The raw token, as the web app sends it: /v1 also accepts "Bearer <token>", but /v3 answers that with 401 "Invalid token".
+        if (token)
+            headers.authorization = token;
+        const maxAttempts = RETRYABLE_METHODS.has(method) ? MAX_ATTEMPTS : 1;
+        if (opts.body !== undefined)
+            headers["content-type"] = "application/json";
+        for (let attempt = 1;; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, { method, headers, body: opts.body === undefined ? undefined : JSON.stringify(opts.body) });
+            }
+            catch (err) {
+                if (attempt < maxAttempts) {
+                    await this.backoff(attempt);
+                    continue;
+                }
+                throw new ToolError("ITFIN_ERROR", `ITFin is unreachable: ${err.message}`);
+            }
+            if (res.status >= 500 && attempt < maxAttempts) {
+                await this.backoff(attempt);
+                continue;
+            }
+            const text = await res.text();
+            const data = text ? safeJson(text) : undefined;
+            if (res.ok)
+                return data;
+            const message = data?.message ?? (text || res.statusText);
+            if (res.status === 401) {
+                if (token)
+                    await this.onUnauthorized(token);
+                throw new ToolError("AUTH_REQUIRED", `ITFin rejected the token (${message}). Ask the user to log in.`);
+            }
+            if (res.status === 400 && message === TRACKING_NOT_ALLOWED)
+                throw new ToolError("DAY_CLOSED", message);
+            if (res.status === 404)
+                throw new ToolError("NOT_FOUND", message, { status: 404 });
+            throw new ToolError("ITFIN_ERROR", message, { status: res.status });
+        }
+    }
+    backoff(attempt) {
+        return new Promise((r) => setTimeout(r, this.retryDelayMs * 2 ** (attempt - 1)));
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text };
+    }
+}

package/dist/jwt.js

@@ -0,0 +1,10 @@
+/** Decodes the payload of an ITFin token without verifying it. */
+export function decodeToken(token) {
+    const payload = token.split(".")[1];
+    if (!payload)
+        throw new Error("Malformed ITFin token");
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    if (typeof claims.exp !== "number")
+        throw new Error("ITFin token has no exp claim");
+    return claims;
+}

package/dist/leave.js

@@ -0,0 +1,56 @@
+// Leave requests (vacation, sick leave, paid and unpaid leave), mirroring ITFin's "Request time off" form.
+/** Leave type ids compared as strings, so "12" and 12 are the same type. */
+export function sameLeaveTypeId(a, b) {
+    return String(a) === String(b);
+}
+/** Request types the web app shows as leave (`loadMyVacationsForPeriod`). */
+export const LEAVE_REQUEST_TYPES = ["Vacation", "Sickness", "Unpaid", "PaidLeave", "CarryOver"];
+/** Statuses after which a request can no longer be cancelled. */
+export const CLOSED_REQUEST_STATUSES = ["Canceled", "Rejected"];
+/** The web app's built-in reasons per request type. */
+const BUILT_IN_REASONS = {
+    Sickness: ["Airborne disease", "Trauma", "Mental health", "Poisoning, Gastrointestinal disorder", "Surgery, hospital stay", "Other"],
+    Vacation: [
+        "Rest and relax",
+        "Improve physical health",
+        "Increase mental power",
+        "Improve well-being",
+        "Decreased burnout",
+        "Maternity leave",
+        "Child rearing leave",
+        "Other",
+    ],
+    PaidLeave: ["Birthday", "Wedding", "Death of relative", "Force majeure", "Personal circumstances", "Other"],
+};
+/** Workspace settings holding extra reasons, one per line; a leading "-" line replaces the built-in ones. */
+export const ADDITIONAL_REASONS_SETTING = {
+    Vacation: "AdditionalVacationLeaveReasons",
+    Sickness: "AdditionalSicknessReasons",
+    PaidLeave: "AdditionalPaidLeaveReasons",
+};
+/** The reasons the web app offers for a leave type; an empty list means the form has no reason field. */
+export function leaveReasons(requestType, additional) {
+    const builtIn = BUILT_IN_REASONS[requestType ?? ""] ?? [];
+    const extra = typeof additional === "string" ? additional.split("\n").map((r) => r.trim()).filter(Boolean) : [];
+    if (extra[0] === "-")
+        return extra.filter((r) => r !== "-");
+    return [...builtIn, ...extra];
+}
+/** Minutes as the web app's part-day "FormattedHours" field, e.g. 270 → "04h 30m", 30 → "0h 30m". */
+export function formatHours(minutes) {
+    const h = Math.floor(minutes / 60);
+    const m = String(minutes % 60).padStart(2, "0");
+    return h ? `${String(h).padStart(2, "0")}h ${m}m` : `0h ${m}m`;
+}
+export function toLeaveRequest(r) {
+    return {
+        id: r.Id,
+        type: r.RequestType,
+        from: r.DateFrom.slice(0, 10),
+        to: r.DateTo.slice(0, 10),
+        status: r.Status,
+        reason: r.Reason ?? undefined,
+        comment: r.Comment ?? undefined,
+        createdAt: r.CreatedAt,
+    };
+}

package/dist/login.js

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { createServer } from "node:net";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const BROWSERS = {
+    chrome: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    edge: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+    brave: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    arc: "/Applications/Arc.app/Contents/MacOS/Arc",
+    chromium: "/Applications/Chromium.app/Contents/MacOS/Chromium",
+};
+const TOKEN_COOKIE = "itfin-jwt";
+/**
+ * Opens the workspace in a Chromium-based browser with a dedicated profile and watches, over the
+ * DevTools protocol, for the ITFin token cookie that ITFin sets after the user signs in.
+ * Nothing is clicked or typed: the user signs in themselves.
+ */
+export async function startBrowserLogin(opts) {
+    const executable = BROWSERS[opts.browser.toLowerCase()] ?? opts.browser;
+    if (!existsSync(executable))
+        throw new Error(`Browser not found: ${executable}. Set ITFIN_BROWSER to chrome, edge, brave, arc, chromium or a path.`);
+    const profileDir = opts.profileDir ?? join(homedir(), "Library", "Application Support", "itfin-mcp", "browser-profile");
+    mkdirSync(profileDir, { recursive: true });
+    const port = await freePort();
+    const child = spawn(executable, [`--remote-debugging-port=${port}`, `--user-data-dir=${profileDir}`, "--no-first-run", "--no-default-browser-check", "about:blank"], { stdio: "ignore", detached: false });
+    const token = (async () => {
+        const page = await connectToPage(port, opts.maxWaitMs);
+        try {
+            await page.send("Network.enable");
+            // Drop a token left in the profile so the user really signs in and ITFin issues a fresh one.
+            await page.send("Network.deleteCookies", { name: TOKEN_COOKIE, url: opts.workspaceUrl });
+            await page.send("Page.navigate", { url: opts.workspaceUrl });
+            const deadline = Date.now() + opts.maxWaitMs;
+            while (Date.now() < deadline) {
+                const { cookies } = (await page.send("Network.getCookies", { urls: [opts.workspaceUrl] }));
+                const cookie = cookies.find((c) => c.name === TOKEN_COOKIE);
+                if (cookie?.value)
+                    return decodeURIComponent(cookie.value).replace(/^Bearer\s+/i, "");
+                await sleep(1000);
+            }
+            throw new Error("Timed out waiting for the ITFin login.");
+        }
+        finally {
+            page.close();
+            closeBrowser(child, port);
+        }
+    })();
+    return { token };
+}
+async function connectToPage(port, maxWaitMs) {
+    const deadline = Date.now() + Math.min(maxWaitMs, 30_000);
+    let wsUrl;
+    while (!wsUrl) {
+        try {
+            const targets = (await (await fetch(`http://127.0.0.1:${port}/json/list`)).json());
+            wsUrl = targets.find((t) => t.type === "page")?.webSocketDebuggerUrl;
+        }
+        catch {
+            // Browser still starting.
+        }
+        if (!wsUrl) {
+            if (Date.now() > deadline)
+                throw new Error("The login browser did not start.");
+            await sleep(250);
+        }
+    }
+    const ws = new WebSocket(wsUrl);
+    await new Promise((resolve, reject) => {
+        ws.addEventListener("open", () => resolve(), { once: true });
+        ws.addEventListener("error", () => reject(new Error("Could not connect to the login browser.")), { once: true });
+    });
+    let nextId = 1;
+    const pending = new Map();
+    ws.addEventListener("message", (ev) => {
+        const msg = JSON.parse(String(ev.data));
+        if (msg.id === undefined)
+            return;
+        const p = pending.get(msg.id);
+        pending.delete(msg.id);
+        if (msg.error)
+            p?.reject(new Error(msg.error.message));
+        else
+            p?.resolve(msg.result);
+    });
+    ws.addEventListener("close", () => {
+        for (const p of pending.values())
+            p.reject(new Error("The login browser was closed."));
+        pending.clear();
+    });
+    return {
+        send(method, params = {}) {
+            const id = nextId++;
+            return new Promise((resolve, reject) => {
+                pending.set(id, { resolve, reject });
+                ws.send(JSON.stringify({ id, method, params }));
+            });
+        },
+        close: () => ws.close(),
+    };
+}
+function closeBrowser(child, port) {
+    fetch(`http://127.0.0.1:${port}/json/version`)
+        .then((r) => r.json())
+        .then(({ webSocketDebuggerUrl }) => {
+        const ws = new WebSocket(webSocketDebuggerUrl);
+        ws.addEventListener("open", () => ws.send(JSON.stringify({ id: 1, method: "Browser.close" })));
+    })
+        .catch(() => child.kill());
+}
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.unref();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const { port } = srv.address();
+            srv.close(() => resolve(port));
+        });
+    });
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/reminders.js

@@ -0,0 +1,61 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+/** One-shot relogin reminders as per-user launchd jobs that remove themselves after firing. */
+export class LaunchdReminderScheduler {
+    async schedule(at, workspaceUrl) {
+        const slug = createHash("sha1").update(workspaceUrl).digest("hex").slice(0, 10);
+        const label = `com.itfin-mcp.relogin.${slug}`;
+        const dir = join(homedir(), "Library", "LaunchAgents");
+        const plist = join(dir, `${label}.plist`);
+        const domain = `gui/${userInfo().uid}`;
+        await run("launchctl", ["bootout", `${domain}/${label}`]).catch(() => undefined);
+        rmSync(plist, { force: true });
+        if (at.getTime() - Date.now() < 60_000) {
+            await this.notify("ITFin", reminderText(workspaceUrl));
+            return;
+        }
+        // launchd calendar intervals use the Mac's local time.
+        const script = [
+            notificationCommand("ITFin", reminderText(workspaceUrl)),
+            `launchctl bootout ${domain}/${label}`,
+            `rm -f '${plist}'`,
+        ].join("; ");
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(plist, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key>
+  <array><string>/bin/sh</string><string>-c</string><string>${escapeXml(script)}</string></array>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Month</key><integer>${at.getMonth() + 1}</integer>
+    <key>Day</key><integer>${at.getDate()}</integer>
+    <key>Hour</key><integer>${at.getHours()}</integer>
+    <key>Minute</key><integer>${at.getMinutes()}</integer>
+  </dict>
+</dict>
+</plist>
+`);
+        await run("launchctl", ["bootstrap", domain, plist]);
+    }
+    async notify(title, message) {
+        await run("/bin/sh", ["-c", notificationCommand(title, message)]).catch(() => undefined);
+    }
+}
+function reminderText(workspaceUrl) {
+    return `Your ITFin token for ${new URL(workspaceUrl).host} expires soon. Ask Claude to log in to ITFin.`;
+}
+function notificationCommand(title, message) {
+    const q = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/'/g, "");
+    return `osascript -e 'display notification "${q(message)}" with title "${q(title)}"'`;
+}
+function escapeXml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}