itfin-mcp 0.1.5 → 0.1.6

package/README.md

@@ -6,7 +6,9 @@ An unofficial tool. It is not made, endorsed or supported by ITFin.
 
 ## Install (about 2 minutes)
 
-You need macOS, Node.js 22+ and Chrome, Edge, Brave, Arc or Chromium.
+You need macOS or Linux, Node.js 22+ and Chrome, Edge, Brave or Chromium (Arc on macOS only).
+
+On Linux you also need `secret-tool` (Debian/Ubuntu: `sudo apt install libsecret-tools`) with a keyring such as GNOME Keyring. Reminders use `systemd-run` and `notify-send`. Claude Desktop has no Linux build, so use Claude Code or Codex.
 
 1. Run:
    ```bash
@@ -45,7 +47,7 @@ CLI mode installs:
 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.
+ITFin tokens last 7 days and can't be extended. A desktop notification reminds you at the start of your working day before yours expires.
 
 ## Settings
 

package/dist/index.js

@@ -9,9 +9,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { runCli } from "./cli.js";
 import { systemClock } from "./clock.js";
 import { DEFAULT_CONFIG_FILE, loadConfig } from "./config.js";
-import { LaunchdReminderScheduler } from "./reminders.js";
+import { createReminderScheduler } from "./reminders.js";
 import { createItfinServer } from "./server.js";
-import { KeychainTokenStore } from "./tokenStore.js";
+import { createTokenStore } from "./tokenStore.js";
 // `npx itfin-mcp install [flags]` runs the installer shipped in the package. `itfin-mcp cli ...` is
 // CLI mode (the installer's `itfin` command runs it). Without arguments this is the MCP server.
 if (process.argv[2] === "install") {
@@ -20,11 +20,11 @@ if (process.argv[2] === "install") {
     process.exit(result.status ?? 1);
 }
 const config = loadConfig();
-const reminders = new LaunchdReminderScheduler();
+const reminders = createReminderScheduler();
 const server = createItfinServer({
     config,
     clock: systemClock,
-    tokenStore: new KeychainTokenStore("itfin-mcp", config.workspaceUrl),
+    tokenStore: createTokenStore("itfin-mcp", config.workspaceUrl),
     reminders,
 });
 if (process.argv[2] !== "cli") {

package/dist/login.js

@@ -2,14 +2,36 @@ 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 = {
+import { delimiter, join } from "node:path";
+const MAC_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",
 };
+/** Linux browsers are commands on PATH; the first one found wins. */
+const LINUX_BROWSERS = {
+    chrome: ["google-chrome", "google-chrome-stable"],
+    edge: ["microsoft-edge", "microsoft-edge-stable"],
+    brave: ["brave-browser", "brave"],
+    chromium: ["chromium", "chromium-browser"],
+};
+const IS_MAC = process.platform === "darwin";
+function findOnPath(command) {
+    return (process.env.PATH ?? "").split(delimiter).map((dir) => join(dir, command)).find((file) => existsSync(file));
+}
+function resolveBrowser(name) {
+    if (IS_MAC)
+        return MAC_BROWSERS[name.toLowerCase()] ?? name;
+    const commands = LINUX_BROWSERS[name.toLowerCase()];
+    return (commands && commands.map(findOnPath).find(Boolean)) || name;
+}
+function defaultProfileDir() {
+    if (IS_MAC)
+        return join(homedir(), "Library", "Application Support", "itfin-mcp", "browser-profile");
+    return join(process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "itfin-mcp", "browser-profile");
+}
 const TOKEN_COOKIE = "itfin-jwt";
 /**
  * Opens the workspace in a Chromium-based browser with a dedicated profile and watches, over the
@@ -17,10 +39,10 @@ const TOKEN_COOKIE = "itfin-jwt";
  * Nothing is clicked or typed: the user signs in themselves.
  */
 export async function startBrowserLogin(opts) {
-    const executable = BROWSERS[opts.browser.toLowerCase()] ?? opts.browser;
+    const executable = resolveBrowser(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");
+        throw new Error(`Browser not found: ${executable}. Set ITFIN_BROWSER to ${IS_MAC ? "chrome, edge, brave, arc, chromium" : "chrome, edge, brave, chromium"} or a path.`);
+    const profileDir = opts.profileDir ?? defaultProfileDir();
     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 });

package/dist/reminders.js

@@ -49,6 +49,32 @@ export class LaunchdReminderScheduler {
         await run("/bin/sh", ["-c", notificationCommand(title, message)]).catch(() => undefined);
     }
 }
+/** One-shot relogin reminders as transient systemd user timers that remove themselves after firing. */
+export class SystemdReminderScheduler {
+    async schedule(at, workspaceUrl) {
+        const slug = createHash("sha1").update(workspaceUrl).digest("hex").slice(0, 10);
+        const unit = `itfin-mcp-relogin-${slug}`;
+        // Stop the old timer and its service, and clear failed state, so systemd-run can reuse the unit names.
+        for (const name of [`${unit}.timer`, `${unit}.service`]) {
+            await run("systemctl", ["--user", "stop", name]).catch(() => undefined);
+            await run("systemctl", ["--user", "reset-failed", name]).catch(() => undefined);
+        }
+        if (at.getTime() - Date.now() < 60_000) {
+            await this.notify("ITFin", reminderText(workspaceUrl));
+            return;
+        }
+        // UTC, so the time does not depend on which TZ the server process and the systemd manager each see.
+        const when = `${at.toISOString().slice(0, 16).replace("T", " ")}:00 UTC`;
+        await run("systemd-run", ["--user", `--unit=${unit}`, `--on-calendar=${when}`, "--timer-property=AccuracySec=1s", "--collect", "--quiet", "notify-send", "ITFin", reminderText(workspaceUrl)]);
+    }
+    async notify(title, message) {
+        await run("notify-send", [title, message]).catch(() => undefined);
+    }
+}
+/** The OS reminder scheduler: launchd on macOS, systemd user timers on Linux. */
+export function createReminderScheduler() {
+    return process.platform === "darwin" ? new LaunchdReminderScheduler() : new SystemdReminderScheduler();
+}
 function reminderText(workspaceUrl) {
     return `Your ITFin token for ${new URL(workspaceUrl).host} expires soon. Ask Claude to log in to ITFin.`;
 }

package/dist/server.js

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { ToolError } from "./errors.js";
 import { ItfinClient } from "./itfinClient.js";
 import { startBrowserLogin } from "./login.js";
-import { LaunchdReminderScheduler } from "./reminders.js";
+import { createReminderScheduler } from "./reminders.js";
 import { decodeToken } from "./jwt.js";
 import { ADDITIONAL_REASONS_SETTING, CLOSED_REQUEST_STATUSES, formatHours, LEAVE_REQUEST_TYPES, leaveReasons, sameLeaveTypeId, toLeaveRequest, } from "./leave.js";
 import { reloginReminderAt, todayIn } from "./workingTime.js";
@@ -100,7 +100,7 @@ export function createItfinServer(deps) {
             await tokenStore.save(token, { ...stored, rejected: true });
     }
     const itfin = new ItfinClient(config.workspaceUrl, validToken, deps.retryDelayMs ?? 500, markRejected);
-    const reminders = deps.reminders ?? new LaunchdReminderScheduler();
+    const reminders = deps.reminders ?? createReminderScheduler();
     const startLogin = deps.startLogin ?? ((maxWaitMs) => startBrowserLogin({ workspaceUrl: config.workspaceUrl, browser: config.browser, maxWaitMs }));
     let loginInProgress;
     /** Stores a freshly issued ITFin token and replaces the relogin reminder. */
@@ -109,9 +109,17 @@ export function createItfinServer(deps) {
         const expiresAt = new Date(claims.exp * 1000);
         await tokenStore.save(token);
         const reminder = await nextReminder(expiresAt, clock.now());
-        if (reminder)
-            await reminders.schedule(reminder, config.workspaceUrl);
-        return { email: claims.Email, expiresAt: expiresAt.toISOString(), nextReminderAt: reminder?.toISOString() };
+        // The token is saved, so a scheduler failure (e.g. no systemd user bus) must not fail the login.
+        let scheduled = reminder;
+        if (reminder) {
+            try {
+                await reminders.schedule(reminder, config.workspaceUrl);
+            }
+            catch {
+                scheduled = undefined;
+            }
+        }
+        return { email: claims.Email, expiresAt: expiresAt.toISOString(), nextReminderAt: scheduled?.toISOString() };
     }
     async function getDays(from, to) {
         const res = await itfin.get("/v1/tracking", { includes: "log", "filter[from]": from, "filter[to]": to });

package/dist/tokenStore.js

@@ -35,6 +35,46 @@ export class KeychainTokenStore {
         await run("security", ["delete-generic-password", "-s", this.service, "-a", this.account]).catch(() => undefined);
     }
 }
+/** A locked keyring makes secret-tool wait for an unlock prompt; give up instead of blocking every tool call. */
+const SECRET_TOOL_TIMEOUT_MS = 15_000;
+/** Keeps the ITFin token in the Linux Secret Service (GNOME Keyring, KWallet) through `secret-tool`. */
+export class SecretToolTokenStore {
+    service;
+    account;
+    constructor(service, account) {
+        this.service = service;
+        this.account = account;
+    }
+    async load() {
+        try {
+            const { stdout } = await run("secret-tool", ["lookup", "service", this.service, "account", this.account], { timeout: SECRET_TOOL_TIMEOUT_MS });
+            return JSON.parse(stdout.trim());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async save(token, extra = {}) {
+        const value = JSON.stringify({ token, ...extra });
+        // secret-tool reads the secret from stdin, so it never shows up in the process list.
+        await new Promise((resolve, reject) => {
+            const child = spawn("secret-tool", ["store", "--label", `ITFin (${this.account})`, "service", this.service, "account", this.account], { stdio: ["pipe", "ignore", "pipe"], timeout: SECRET_TOOL_TIMEOUT_MS });
+            let stderr = "";
+            child.stderr.on("data", (d) => (stderr += d));
+            child.on("error", reject);
+            child.stdin.on("error", reject); // secret-tool may exit before it reads the secret
+            child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`Keyring write failed: ${stderr.trim() || code}`))));
+            child.stdin.end(value);
+        });
+    }
+    async clear() {
+        await run("secret-tool", ["clear", "service", this.service, "account", this.account], { timeout: SECRET_TOOL_TIMEOUT_MS }).catch(() => undefined);
+    }
+}
+/** The OS keychain: macOS Keychain, or the Secret Service on Linux. */
+export function createTokenStore(service, account) {
+    return process.platform === "darwin" ? new KeychainTokenStore(service, account) : new SecretToolTokenStore(service, account);
+}
 function quote(s) {
     return `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itfin-mcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "ITFin for AI agents, as a local MCP server or a CLI: projects, time entries, leave and reopen requests",
   "keywords": [
     "mcp",
@@ -26,7 +26,8 @@
     "scripts"
   ],
   "os": [
-    "darwin"
+    "darwin",
+    "linux"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/scripts/install.sh

@@ -13,7 +13,9 @@ DIR="${ITFIN_MCP_DIR:-$HOME/.itfin-mcp}"
 # What npm installs. Override it to try a local build: ITFIN_MCP_PACKAGE=./itfin-mcp-0.1.0.tgz
 PACKAGE="${ITFIN_MCP_PACKAGE:-itfin-mcp@latest}"
 CODEX_CONFIG="${CODEX_HOME:-$HOME/.codex}/config.toml"
-DESKTOP_CONFIG="$HOME/Library/Application Support/Claude/claude_desktop_config.json"
+# Claude Desktop only exists for macOS (and Windows), so Linux has no Desktop config.
+DESKTOP_CONFIG=""
+[[ "$(uname)" == "Darwin" ]] && DESKTOP_CONFIG="$HOME/Library/Application Support/Claude/claude_desktop_config.json"
 CLAUDE_SETTINGS="$HOME/.claude/settings.json"
 CLAUDE_SKILL="$HOME/.claude/skills/itfin"
 CODEX_SKILL="$HOME/.agents/skills/itfin"
@@ -41,7 +43,14 @@ fail() { echo "✗ $*" >&2; exit 1; }
 # Read answers from the terminal even when the script itself comes from a pipe.
 ask() { local prompt="$1" default="${2:-}" answer; read -r -p "$prompt${default:+ [$default]}: " answer </dev/tty || true; echo "${answer:-$default}"; }
 
-[[ "$(uname)" == "Darwin" ]] || fail "itfin-mcp needs macOS (Keychain, launchd and notifications)."
+case "$(uname)" in
+  Darwin) ;;
+  Linux)
+    command -v secret-tool >/dev/null || fail "On Linux itfin-mcp stores the token with secret-tool. Install it (Debian/Ubuntu: sudo apt install libsecret-tools; Fedora: sudo dnf install libsecret) and a keyring such as GNOME Keyring."
+    command -v systemd-run >/dev/null || echo "! systemd-run was not found, so the relogin reminder is off."
+    ;;
+  *) fail "itfin-mcp needs macOS or Linux." ;;
+esac
 command -v node >/dev/null || fail "Node.js 22+ is required: https://nodejs.org"
 [[ "$(node -p 'process.versions.node.split(".")[0]')" -ge 22 ]] || fail "Node.js 22+ is required (found $(node -v))."
 command -v npm >/dev/null || fail "npm is required. It comes with Node.js: https://nodejs.org"
@@ -129,6 +138,7 @@ APPS="$(echo $APPS)"
 for pair in $APPS; do
   app="${pair%%=*}" mode="${pair#*=}"
   [[ "$app" =~ ^(claude|codex|desktop)$ ]] || fail "Unknown app: $app. Use claude, codex or desktop."
+  [[ "$app" != desktop || "$(uname)" == "Darwin" ]] || fail "Claude Desktop is not available on Linux."
   [[ "$mode" =~ ^(mcp|cli)$ ]] || fail "Unknown mode for $app: $mode. Use mcp or cli."
   [[ "$pair" != "desktop=cli" ]] || fail "Claude Desktop has no shell, so it can only use MCP mode."
 done
@@ -247,7 +257,7 @@ if [[ -n "$(mode_of codex)" ]]; then
     install_skill "$CODEX_SKILL"
     remove_rules
     if [[ ${#READ_ONLY[@]} -gt 0 ]]; then
-      # Allowed commands run outside the Codex sandbox, which blocks the network and the Keychain.
+      # Allowed commands run outside the Codex sandbox, which blocks the network and the keychain.
       mkdir -p "$(dirname "$CODEX_RULES")"
       { echo "$RULES_MARK: read-only itfin commands. Rewritten on every update."
         for command in "${READ_ONLY[@]}"; do echo "prefix_rule(pattern=[\"itfin\", \"$command\"], decision=\"allow\")"; done
@@ -260,9 +270,19 @@ if [[ -n "$(mode_of codex)" ]]; then
     remove_rules
     codex mcp add itfin "${ENV_ARGS[@]/#-e/--env}" -- "$NODE" "$ENTRY"
     # itfin_login waits up to 3 minutes; Codex gives up on tool calls after 60 seconds by default.
-    sed -i '' '/^\[mcp_servers\.itfin\]$/a\
+    # -i.bak works with both BSD (macOS) and GNU (Linux) sed.
+    sed -i.bak '/^\[mcp_servers\.itfin\]$/a\
 tool_timeout_sec = 240
 ' "$CODEX_CONFIG"
+    rm -f "$CODEX_CONFIG.bak"
+    if [[ "$(uname)" == Linux ]]; then
+      # Codex passes MCP servers only a short list of variables. The browser, secret-tool and
+      # systemctl need the desktop session ones.
+      sed -i.bak '/^\[mcp_servers\.itfin\]$/a\
+env_vars = ["DISPLAY", "WAYLAND_DISPLAY", "XAUTHORITY", "XDG_RUNTIME_DIR", "XDG_DATA_HOME", "DBUS_SESSION_BUS_ADDRESS"]
+' "$CODEX_CONFIG"
+      rm -f "$CODEX_CONFIG.bak"
+    fi
   fi
 fi
 
@@ -295,7 +315,7 @@ for pair in $ALL_APPS; do
   SUMMARY+="${SUMMARY:+, }$name: $(echo "${pair#*=}" | tr '[:lower:]' '[:upper:]')"
 done
 echo "✓ itfin-mcp $NEW_VERSION is installed in $DIR ($SUMMARY)"
-[[ -n "$PATH_HINT" ]] && echo "! $(dirname "$BIN") is not on your PATH. Add it: echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.zshrc"
+[[ -n "$PATH_HINT" ]] && echo "! $(dirname "$BIN") is not on your PATH. Add it: echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.$([[ "$(uname)" == Darwin ]] && echo zshrc || echo bashrc)"
 # Claude Desktop reads its config only at startup. Not quit here: it may be running this script.
 [[ -n "$DESKTOP" ]] && echo "Restart Claude Desktop (Cmd+Q, then open it) to load the server."
 [[ -n "${STALE:-}" ]] && echo "Open sessions lost the ITFin tools: start a new session, or reconnect itfin with /mcp in Claude Code."