itfin-mcp 0.1.2 → 0.1.4

package/README.md

@@ -12,19 +12,34 @@ You need macOS, Node.js 22+ and Chrome, Edge, Brave, Arc or Chromium.
    ```bash
    npx itfin-mcp@latest install
    ```
-2. Pick the apps: Claude Code, Codex, Claude Desktop. Space ticks or unticks one, Enter confirms.
+2. Pick the apps and, for Claude Code and Codex, the [mode](#mcp-or-cli-mode). 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.
+Run the same command again. It installs the latest version from npm, keeps your apps, modes 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).
 
+## MCP or CLI mode
+
+Each app uses ITFin in one of two modes:
+
+- **MCP** (default): the app runs ITFin as an MCP server and the agent calls its tools.
+- **CLI**: the agent runs the `itfin` command in its shell, guided by an `itfin` skill. It can pipe the JSON output into `jq`, loop over days or combine it with `git` in one command.
+
+Claude Desktop has no shell, so it is always MCP. To switch an app, run the install with `--mode`, e.g. `npx itfin-mcp@latest install --mode claude=cli`. Switching removes what the old mode installed.
+
+CLI mode installs:
+
+- `~/.local/bin/itfin`, the command (`itfin --help` lists the commands, `itfin <command> --help` their flags);
+- the `itfin` skill in `~/.claude/skills` (Claude Code) or `~/.agents/skills` (Codex);
+- permission to run read-only commands without asking: allow rules in `~/.claude/settings.json`, or `~/.codex/rules/itfin.rules` for Codex, which also lets them reach ITFin from the Codex sandbox. Writes, leave and reopen requests and `itfin login` still ask. `--no-permissions` skips this, and updates remember it until you pass `--permissions`.
+
 ## Log in (once a week)
 
 1. Say **"log in to ITFin"**.
@@ -34,7 +49,7 @@ ITFin tokens last 7 days and can't be extended. A macOS notification reminds you
 
 ## Settings
 
-Add flags to the install command to change a setting:
+Settings live in `~/.itfin-mcp/config.json`. Add flags to the install command to change a setting:
 
 ```bash
 npx itfin-mcp@latest install --browser brave --work-start 09:00
@@ -43,6 +58,8 @@ npx itfin-mcp@latest install --browser brave --work-start 09:00
 | Flag | Default | Sets |
 |---|---|---|
 | `--clients claude,codex,desktop` | asked | Apps to install for |
+| `--mode claude=cli,codex=mcp` | `mcp` | Mode per app: `mcp` or `cli` |
+| `--no-permissions` / `--permissions` | `--permissions` | Whether CLI mode allows read-only `itfin` commands without asking |
 | `--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 |
@@ -52,6 +69,8 @@ npx itfin-mcp@latest install --browser brave --work-start 09:00
 
 ## Tools
 
+In CLI mode each tool is a command without the `itfin_` prefix: `itfin_get_entries` is `itfin get-entries`.
+
 | Tool | Does |
 |---|---|
 | `itfin_login` / `itfin_auth_status` | Log in; check when the token expires |
@@ -59,7 +78,7 @@ npx itfin-mcp@latest install --browser brave --work-start 09:00
 | `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_request_reopen` / `itfin_list_reopen_requests` / `itfin_cancel_reopen_request` | Ask a manager to reopen closed days; see or cancel 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 |

package/dist/cli.js

@@ -0,0 +1,188 @@
+/** `itfin_get_entries` → `get-entries`. */
+export function commandName(tool) {
+    return tool.replace(/^itfin_/, "").replaceAll("_", "-");
+}
+const kebab = (s) => s.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+function schemaTypes(s) {
+    const own = s.type === undefined ? [] : Array.isArray(s.type) ? s.type : [s.type];
+    return [...own, ...(s.anyOf ?? []).flatMap(schemaTypes), ...(s.oneOf ?? []).flatMap(schemaTypes)];
+}
+/** Turns a flag's text into the JSON value its schema expects; the server still validates it. */
+function coerce(raw, s) {
+    const types = schemaTypes(s);
+    if (raw === "null" && types.includes("null"))
+        return null;
+    if (types.includes("boolean") && (raw === "true" || raw === "false"))
+        return raw === "true";
+    if (types.includes("string"))
+        return raw;
+    if ((types.includes("integer") || types.includes("number")) && raw.trim() !== "" && !Number.isNaN(Number(raw)))
+        return Number(raw);
+    return raw;
+}
+class UsageError extends Error {
+}
+/** Parses `--flag value`, `--flag=value` and `--json '{...}'` against a tool's input schema. */
+function parseArgs(tool, argv) {
+    const schema = tool.inputSchema;
+    const props = schema.properties ?? {};
+    const byFlag = new Map(Object.keys(props).flatMap((p) => [[kebab(p), p], [p, p]]));
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith("--"))
+            throw new UsageError(`Unexpected argument: ${arg}`);
+        const eq = arg.indexOf("=");
+        const flag = arg.slice(2, eq === -1 ? undefined : eq);
+        let raw = eq === -1 ? undefined : arg.slice(eq + 1);
+        if (flag === "json") {
+            raw ??= argv[++i];
+            if (raw === undefined)
+                throw new UsageError("--json needs a JSON object.");
+            try {
+                Object.assign(args, JSON.parse(raw));
+            }
+            catch {
+                throw new UsageError("--json is not valid JSON.");
+            }
+            continue;
+        }
+        const prop = byFlag.get(flag);
+        if (!prop)
+            throw new UsageError(`Unknown flag --${flag} for ${commandName(tool.name)}. See itfin ${commandName(tool.name)} --help.`);
+        const propSchema = props[prop];
+        if (raw === undefined) {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                if (!schemaTypes(propSchema).includes("boolean"))
+                    throw new UsageError(`--${flag} needs a value.`);
+                raw = "true";
+            }
+            else {
+                raw = next;
+                i++;
+            }
+        }
+        args[prop] = coerce(raw, propSchema);
+    }
+    return args;
+}
+function flagLines(tool) {
+    const schema = tool.inputSchema;
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties ?? {}).map(([name, s]) => {
+        const types = schemaTypes(s).filter((t) => t !== "null");
+        const type = s.pattern === "^\\d{4}-\\d{2}-\\d{2}$" ? "YYYY-MM-DD" : [...new Set(types)].join(" | ");
+        const notes = [type, required.has(name) ? "required" : "optional"].filter(Boolean).join(", ");
+        return `--${kebab(name)} (${notes})${s.description ? `: ${s.description}` : ""}`;
+    });
+}
+function commandHelp(tool) {
+    const flags = flagLines(tool);
+    return [`itfin ${commandName(tool.name)}`, "", tool.description ?? "", "", ...(flags.length ? ["Flags:", ...flags.map((f) => `  ${f}`)] : ["No flags."])].join("\n");
+}
+function overview(tools) {
+    const width = Math.max(...tools.map((t) => commandName(t.name).length));
+    return [
+        "Usage: itfin <command> [--flag value ...]",
+        "",
+        "Commands:",
+        ...tools.map((t) => `  ${commandName(t.name).padEnd(width)}  ${t.annotations?.title ?? t.title ?? ""}`),
+        "",
+        "itfin <command> --help shows a command's flags. Output is JSON on stdout; errors are JSON on stderr with exit code 1.",
+    ].join("\n");
+}
+/** Read-only commands, which installers may allow without asking. */
+export function readOnlyCommands(tools) {
+    return tools.filter((t) => t.annotations?.readOnlyHint === true).map((t) => commandName(t.name));
+}
+/** The agent skill for CLI mode: the server instructions, how to call the CLI, and every command. */
+export function skillMarkdown(tools, instructions) {
+    return [
+        "---",
+        "name: itfin",
+        "description: Read and change the user's ITFin data with the `itfin` command (time entries, reportable projects, reopen requests for closed days, leave requests, ITFin login). Use it for any ITFin work, including instructions that name itfin_* tools.",
+        "---",
+        "",
+        "# ITFin",
+        "",
+        "<!-- Generated by itfin-mcp install. Changes are overwritten on the next update. -->",
+        "",
+        instructions,
+        "",
+        "## Calling it",
+        "",
+        "- Run `itfin <command> --flag value`. Flags are the parameters below; `--json '{...}'` passes them all at once.",
+        "- Success prints JSON on stdout with exit code 0, so pipe it into `jq`, loop over days or save it to a file as needed. Failure prints `{\"error\":{\"code\":...,\"message\":...}}` on stderr with exit code 1.",
+        "- Instructions that name an ITFin MCP tool mean the matching command: `itfin_get_entries` is `itfin get-entries`.",
+        "- Read commands can be combined and looped freely. Time entry writes can be looped too, but only for changes the user asked for.",
+        "- `request-leave` and `request-reopen` go to the user's manager: one request per command, never in a loop or script, and only when the user asked for that request.",
+        "- `login` opens the sign-in window and returns at once. The user gets a notification after signing in; check with `itfin auth-status`.",
+        "",
+        "## Commands",
+        "",
+        ...tools.flatMap((t) => {
+            const flags = flagLines(t);
+            return [`### itfin ${commandName(t.name)}`, "", t.description ?? "", "", ...(flags.length ? [...flags.map((f) => `- \`${f.slice(0, f.indexOf(" "))}\`${f.slice(f.indexOf(" "))}`), ""] : [])];
+        }),
+    ].join("\n");
+}
+function errorJson(code, message) {
+    return JSON.stringify({ error: { code, message } });
+}
+/** Runs one CLI invocation and returns its exit code. */
+export async function runCli(argv, deps) {
+    const { tools } = await deps.client.listTools();
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
+        deps.out(overview(tools));
+        return 0;
+    }
+    if (command === "__skill") {
+        deps.out(skillMarkdown(tools, deps.client.getInstructions() ?? ""));
+        return 0;
+    }
+    if (command === "__read-only") {
+        deps.out(readOnlyCommands(tools).join("\n"));
+        return 0;
+    }
+    const tool = tools.find((t) => commandName(t.name) === command || t.name === command);
+    if (!tool) {
+        deps.err(errorJson("USAGE", `Unknown command: ${command}. Run itfin --help.`));
+        return 1;
+    }
+    if (rest.includes("--help") || rest.includes("-h")) {
+        deps.out(commandHelp(tool));
+        return 0;
+    }
+    let args;
+    try {
+        args = parseArgs(tool, rest);
+    }
+    catch (err) {
+        if (!(err instanceof UsageError))
+            throw err;
+        deps.err(errorJson("USAGE", err.message));
+        return 1;
+    }
+    if (tool.name === "itfin_login") {
+        deps.out(JSON.stringify(await deps.startLogin()));
+        return 0;
+    }
+    const res = (await deps.client.callTool({ name: tool.name, arguments: args }));
+    const text = res.content.find((c) => c.type === "text")?.text ?? "";
+    if (!res.isError) {
+        deps.out(text);
+        return 0;
+    }
+    // Tool errors are already JSON; argument validation errors from the SDK are plain text.
+    let isJson = true;
+    try {
+        JSON.parse(text);
+    }
+    catch {
+        isJson = false;
+    }
+    deps.err(isJson ? text : errorJson("VALIDATION", text));
+    return 1;
+}

package/dist/config.js

@@ -1,14 +1,37 @@
-export function loadConfig(env = process.env) {
-    const workspaceUrl = env.ITFIN_URL?.trim().replace(/\/+$/, "");
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Where the installer keeps the settings, unless ITFIN_CONFIG points elsewhere. */
+export const DEFAULT_CONFIG_FILE = join(homedir(), ".itfin-mcp", "config.json");
+function readConfigFile(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return {};
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${file} is not valid JSON. Run npx itfin-mcp@latest install to rewrite it.`);
+    }
+}
+/** Settings come from the config file; ITFIN_* env vars override single values. */
+export function loadConfig(env = process.env, file = env.ITFIN_CONFIG?.trim() || DEFAULT_CONFIG_FILE) {
+    const saved = readConfigFile(file);
+    const value = (name, fromFile) => env[name]?.trim() || fromFile?.trim() || undefined;
+    const workspaceUrl = value("ITFIN_URL", saved.url)?.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";
+        throw new Error("No ITFin workspace configured. Run npx itfin-mcp@latest install, or set ITFIN_URL, e.g. https://acme.itfin.io");
+    const workStart = value("ITFIN_WORK_START", saved.workStart) ?? "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",
+        browser: value("ITFIN_BROWSER", saved.browser) ?? "chrome",
         workStart,
-        timezone: env.ITFIN_TIMEZONE?.trim() || Intl.DateTimeFormat().resolvedOptions().timeZone,
+        timezone: value("ITFIN_TIMEZONE", saved.timezone) ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
     };
 }

package/dist/index.js

@@ -1,22 +1,89 @@
 #!/usr/bin/env node
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { runCli } from "./cli.js";
 import { systemClock } from "./clock.js";
-import { loadConfig } from "./config.js";
+import { DEFAULT_CONFIG_FILE, loadConfig } from "./config.js";
+import { LaunchdReminderScheduler } from "./reminders.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.
+// `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") {
     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 reminders = new LaunchdReminderScheduler();
 const server = createItfinServer({
     config,
     clock: systemClock,
     tokenStore: new KeychainTokenStore("itfin-mcp", config.workspaceUrl),
+    reminders,
 });
-await server.connect(new StdioServerTransport());
+if (process.argv[2] !== "cli") {
+    await server.connect(new StdioServerTransport());
+}
+else {
+    const client = new Client({ name: "itfin-cli", version: "0" });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    const argv = process.argv.slice(3);
+    if (argv[0] === "__login-wait")
+        await waitForLogin(client);
+    else
+        process.exitCode = await runCli(argv, { client, out: (t) => console.log(t), err: (t) => console.error(t), startLogin: startLoginWaiter });
+}
+/** Marks a running background login, so a second `itfin login` doesn't open another window. */
+function loginPidFile() {
+    return join(dirname(process.env.ITFIN_CONFIG?.trim() || DEFAULT_CONFIG_FILE), "login.pid");
+}
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Shell tools time out long before a person signs in, so the login waits in a detached process. */
+async function startLoginWaiter() {
+    const pidFile = loginPidFile();
+    const pid = Number(readFileSafe(pidFile));
+    if (pid && isRunning(pid))
+        return { status: "waiting", message: "The login window is already open. The user will get a notification once they have signed in." };
+    const child = spawn(process.execPath, [fileURLToPath(import.meta.url), "cli", "__login-wait"], { detached: true, stdio: "ignore", env: process.env });
+    child.unref();
+    mkdirSync(dirname(pidFile), { recursive: true });
+    writeFileSync(pidFile, String(child.pid));
+    return { status: "waiting", message: "A login window is opening. The user will get a notification once they have signed in; check with itfin auth-status." };
+}
+async function waitForLogin(client) {
+    const pidFile = loginPidFile();
+    process.on("exit", () => {
+        if (readFileSafe(pidFile) === String(process.pid))
+            rmSync(pidFile, { force: true });
+    });
+    const res = (await client.callTool({ name: "itfin_login", arguments: {} }));
+    const data = JSON.parse(res.content[0]?.text ?? "{}");
+    // "waiting": the server keeps watching and notifies on its own.
+    if (res.isError)
+        await reminders.notify("ITFin", `Login failed: ${data.error?.message ?? "unknown error"}`);
+    else if (data.status === "logged_in")
+        await reminders.notify("ITFin", "Logged in to ITFin.");
+}
+function readFileSafe(file) {
+    try {
+        return readFileSync(file, "utf8").trim();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/server.js

@@ -146,7 +146,9 @@ export function createItfinServer(deps) {
         return me.Id;
     }
     async function reopenRequests() {
-        return itfin.get("/v1/requests/my", { "filter[requestType]": "OpenReporting", page: 1, size: 50 });
+        const requests = await itfin.get("/v1/requests/my", { "filter[requestType]": "OpenReporting", page: 1, size: 50 });
+        // Also filtered here, so itfin_cancel_reopen_request can't reach a leave request if ITFin ignores the filter.
+        return requests.filter((r) => (r.RequestType ?? "OpenReporting") === "OpenReporting");
     }
     async function reopenRequestsCovering(date) {
         return (await reopenRequests()).map(toReopenRequest).filter((r) => r.from <= date && date <= r.to);
@@ -348,6 +350,23 @@ export function createItfinServer(deps) {
         }
         return fileReopenRequest({ from: args.from, to: args.to, reason: args.reason });
     }));
+    server.registerTool("itfin_cancel_reopen_request", {
+        title: "Cancel a reopen request",
+        description: "Cancels (deletes) one of the user's reopen requests by id (from itfin_list_reopen_requests). Only call this when the user asked to cancel that request. " +
+            "Works for pending requests; whether an approved one can still be cancelled is up to ITFin.",
+        inputSchema: { id: z.number().int() },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, ({ id }) => handle(async () => {
+        // Look the id up among the user's reopen requests, so this tool can't cancel other kinds of requests.
+        const request = (await reopenRequests()).find((r) => r.Id === id);
+        if (!request)
+            throw new ToolError("NOT_FOUND", `No reopen request ${id} among the user's recent reopen requests.`);
+        if ([...CLOSED_REQUEST_STATUSES, "Declined"].includes(request.Status)) {
+            throw new ToolError("VALIDATION", `Reopen request ${id} is already ${request.Status}.`, { request: toReopenRequest(request) });
+        }
+        await itfin.request("DELETE", `/v1/requests/${id}`);
+        return { cancelled: id, request: toReopenRequest(request) };
+    }));
     /** Leave types the user can request, as the web app's "Request time off" form offers them. */
     async function leaveTypes() {
         const [types, settings] = await Promise.all([

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "itfin-mcp",
-  "version": "0.1.2",
-  "description": "Local MCP server for ITFin: projects, time entries and ITFin token lifecycle",
+  "version": "0.1.4",
+  "description": "ITFin for AI agents, as a local MCP server or a CLI: projects, time entries, leave and reopen requests",
   "keywords": [
     "mcp",
     "itfin",

package/scripts/install-helpers.mjs

@@ -0,0 +1,70 @@
+// JSON edits for install.sh. Usage: node install-helpers.mjs <command> ...
+//   read-config <config>                     prints url, browser, workStart, timezone, permissions and apps as KEY=value
+//   write-config <config> <url> <browser> <workStart> <timezone> <permissions yes|no> <id=mode>...
+//                                            saves settings, app modes and the permissions choice; keeps what the installer added
+//   claude-permissions <settings> <config> [command...]
+//                                            replaces the Bash(itfin <command>:*) allow rules this installer
+//                                            added before with rules for the given commands; prints the new ones
+//   desktop-register <desktop config> <node> <entry> [KEY=value...]
+//                                            sets mcpServers.itfin and keeps the rest of the file (old one as .bak)
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+const [command, ...args] = process.argv.slice(2);
+
+function readJson(file) {
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  return { text, json: text.trim() ? JSON.parse(text) : {} };
+}
+
+function writeJson(file, json) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(json, null, 2) + "\n");
+}
+
+switch (command) {
+  case "read-config": {
+    const { json } = readJson(args[0]);
+    for (const key of ["url", "browser", "workStart", "timezone"]) if (json[key]) console.log(`${key}=${json[key]}`);
+    if (typeof json.allowReadOnlyCommands === "boolean") console.log(`permissions=${json.allowReadOnlyCommands ? "yes" : "no"}`);
+    console.log(`apps=${Object.entries(json.apps ?? {}).map(([app, mode]) => `${app}=${mode}`).join(" ")}`);
+    break;
+  }
+  case "write-config": {
+    const [file, url, browser, workStart, timezone, permissions, ...apps] = args;
+    const { json } = readJson(file);
+    const settings = Object.fromEntries(Object.entries({ url, browser, workStart, timezone }).filter(([, v]) => v));
+    writeJson(file, { ...settings, apps: Object.fromEntries(apps.map((a) => a.split("="))), allowReadOnlyCommands: permissions !== "no", added: json.added ?? {} });
+    break;
+  }
+  case "claude-permissions": {
+    const [settingsFile, configFile, ...commands] = args;
+    const config = readJson(configFile).json;
+    const previous = new Set(config.added?.claudePermissions ?? []);
+    const wanted = commands.map((c) => `Bash(itfin ${c}:*)`);
+    if (previous.size || wanted.length) {
+      const { text, json: settings } = readJson(settingsFile);
+      if (text) writeFileSync(settingsFile + ".bak", text);
+      const allow = (settings.permissions?.allow ?? []).filter((rule) => !previous.has(rule));
+      const added = wanted.filter((rule) => !allow.includes(rule));
+      settings.permissions = { ...settings.permissions, allow: [...allow, ...added] };
+      writeJson(settingsFile, settings);
+      config.added = { ...config.added, claudePermissions: added };
+      writeJson(configFile, config);
+      for (const rule of added) console.log(rule);
+    }
+    break;
+  }
+  case "desktop-register": {
+    const [file, node, entry, ...pairs] = args;
+    const { text, json } = readJson(file);
+    if (text) writeFileSync(file + ".bak", text);
+    const env = Object.fromEntries(pairs.map((p) => [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]));
+    json.mcpServers = { ...json.mcpServers, itfin: { command: node, args: [entry], env } };
+    writeJson(file, json);
+    break;
+  }
+  default:
+    console.error(`Unknown command: ${command}`);
+    process.exit(1);
+}

package/scripts/install.sh

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
-# Quick install for itfin-mcp: installs or updates the npm package in ~/.itfin-mcp and registers the
-# MCP server with Claude Code, Codex and Claude Desktop. Usage:
-#   npx itfin-mcp install [--company acme] [--clients claude,codex,desktop] [--browser chrome] [--work-start 10:00] [--timezone Europe/Kyiv]
+# Quick install for itfin-mcp: installs or updates the npm package in ~/.itfin-mcp and sets up
+# Claude Code, Codex and Claude Desktop, each in one mode: MCP (the app runs the MCP server) or CLI
+# (the agent runs the `itfin` command, guided by an `itfin` skill). Claude Desktop is always MCP. Usage:
+#   npx itfin-mcp install [--company acme] [--clients claude,codex,desktop] [--mode claude=cli,codex=mcp]
+#                         [--no-permissions | --permissions] [--browser chrome] [--work-start 10:00] [--timezone Europe/Kyiv]
 #   curl -fsSL https://raw.githubusercontent.com/steven-tailor/itfin-mcp/main/scripts/install.sh | bash -s -- [same flags]
-# The first install asks which apps to install for and the company name. Updates reuse the apps and
-# settings of the previous install.
+# The first install asks which apps to install for, in which mode, and the company name. Updates
+# reuse the apps, modes and settings of the previous install, kept in <dir>/config.json.
 set -euo pipefail
 
 DIR="${ITFIN_MCP_DIR:-$HOME/.itfin-mcp}"
@@ -12,13 +14,21 @@ DIR="${ITFIN_MCP_DIR:-$HOME/.itfin-mcp}"
 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"
-URL="" BROWSER="" WORK_START="" TIMEZONE="" CLIENTS=""
+CLAUDE_SETTINGS="$HOME/.claude/settings.json"
+CLAUDE_SKILL="$HOME/.claude/skills/itfin"
+CODEX_SKILL="$HOME/.agents/skills/itfin"
+CODEX_RULES="${CODEX_HOME:-$HOME/.codex}/rules/itfin.rules"
+BIN="$HOME/.local/bin/itfin"
+URL="" BROWSER="" WORK_START="" TIMEZONE="" CLIENTS="" MODES="" PERMISSIONS=""
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --company) URL="https://$2.itfin.io"; shift 2 ;;
     --url) URL="$2"; shift 2 ;;
     --clients) CLIENTS="${2//,/ }"; shift 2 ;;
+    --mode) MODES="${2//,/ }"; shift 2 ;;
+    --no-permissions) PERMISSIONS=no; shift ;;
+    --permissions) PERMISSIONS=yes; shift ;;
     --browser) BROWSER="$2"; shift 2 ;;
     --work-start) WORK_START="$2"; shift 2 ;;
     --timezone) TIMEZONE="$2"; shift 2 ;;
@@ -78,33 +88,76 @@ if [[ -n "$STALE" ]]; then
   kill $STALE 2>/dev/null || true
 fi
 
-# Apps to register with: claude (Claude Code), codex, desktop (Claude Desktop).
-# Updates keep the apps of the previous install. A first install asks, with every app found checked.
-if [[ -z "$CLIENTS" ]]; then
-  command -v claude >/dev/null && claude mcp get itfin >/dev/null 2>&1 && CLIENTS+="claude "
-  [[ -f "$CODEX_CONFIG" ]] && grep -q '^\[mcp_servers\.itfin\]$' "$CODEX_CONFIG" && CLIENTS+="codex "
-  [[ -f "$DESKTOP_CONFIG" ]] && grep -q '"itfin"' "$DESKTOP_CONFIG" && CLIENTS+="desktop "
+CONFIG="$DIR/config.json"
+HELPERS="$PKG/scripts/install-helpers.mjs"
+SAVED=""
+if [[ -f "$CONFIG" ]]; then SAVED="$(node "$HELPERS" read-config "$CONFIG")" || fail "$CONFIG is not valid JSON. Fix or delete it, then run the install again."; fi
+saved() { printf '%s\n' "$SAVED" | sed -n "s/^$1=//p" | head -1; }
+# Mode of app $2 in a list like "claude=cli desktop=mcp".
+mode_in() { local pair; for pair in $1; do [[ "${pair%%=*}" == "$2" ]] && echo "${pair#*=}"; done; return 0; }
+# Sets app $1 to mode $2 in APPS.
+set_mode() { local pair out=""; for pair in $APPS; do [[ "${pair%%=*}" == "$1" ]] || out+="$pair "; done; APPS="$out$1=$2"; }
+
+# Apps and their modes: claude (Claude Code), codex, desktop (Claude Desktop); mcp or cli.
+# Updates keep the apps and modes of the previous install. Installs from before config.json are MCP.
+PREV_APPS="$(saved apps)"
+if [[ -z "$PREV_APPS" ]]; then
+  command -v claude >/dev/null && claude mcp get itfin >/dev/null 2>&1 && PREV_APPS+="claude=mcp "
+  [[ -f "$CODEX_CONFIG" ]] && grep -q '^\[mcp_servers\.itfin\]$' "$CODEX_CONFIG" && PREV_APPS+="codex=mcp "
+  [[ -f "$DESKTOP_CONFIG" ]] && grep -q '"itfin"' "$DESKTOP_CONFIG" && PREV_APPS+="desktop=mcp "
+fi
+APPS=""
+if [[ -n "$CLIENTS$MODES" ]]; then
+  for client in $CLIENTS; do mode="$(mode_in "$PREV_APPS" "$client")"; set_mode "$client" "${mode:-mcp}"; done
+  for pair in $MODES; do [[ "$pair" == *=* ]] || fail "Use --mode app=mode, e.g. --mode claude=cli."; set_mode "${pair%%=*}" "${pair#*=}"; done
+else
+  APPS="$PREV_APPS"
 fi
-if [[ -z "$CLIENTS" ]]; then
+if [[ -z "$APPS" ]]; then
   FOUND=()
-  command -v claude >/dev/null && FOUND+=("claude=Claude Code")
-  command -v codex >/dev/null && FOUND+=("codex=Codex")
-  [[ -d /Applications/Claude.app || -f "$DESKTOP_CONFIG" ]] && FOUND+=("desktop=Claude Desktop")
+  command -v claude >/dev/null && FOUND+=("claude=Claude Code=mcp,cli")
+  command -v codex >/dev/null && FOUND+=("codex=Codex=mcp,cli")
+  [[ -d /Applications/Claude.app || -f "$DESKTOP_CONFIG" ]] && FOUND+=("desktop=Claude Desktop=mcp")
   [[ ${#FOUND[@]} -gt 0 ]] || fail "Install Claude Code, Codex or Claude Desktop first."
   if (: </dev/tty) 2>/dev/null; then
-    CLIENTS="$(node "$PKG/scripts/pick-clients.mjs" "${FOUND[@]}")" || fail "Cancelled."
+    APPS="$(node "$PKG/scripts/pick-clients.mjs" "${FOUND[@]}")" || fail "Cancelled."
   else
-    for found in "${FOUND[@]}"; do CLIENTS+="${found%%=*} "; done
+    for found in "${FOUND[@]}"; do APPS+="${found%%=*}=mcp "; done
   fi
 fi
-CLIENTS=" $(echo $CLIENTS) "
-for client in $CLIENTS; do
-  [[ "$client" =~ ^(claude|codex|desktop)$ ]] || fail "Unknown app: $client. Use claude, codex or desktop."
+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."
+  [[ "$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
+# Apps of the previous install that this run doesn't name keep their mode, and are set up again too,
+# so every registration points at the new code and the shared config.json.
+ALL_APPS="$APPS"
+for pair in $PREV_APPS; do [[ -n "$(mode_in "$APPS" "${pair%%=*}")" ]] || ALL_APPS+=" $pair"; done
+mode_of() { mode_in "$ALL_APPS" "$1"; }
+uses_cli() { [[ " $ALL_APPS " == *"=cli "* ]]; }
+
+# The itfin command for CLI mode. Never replace an itfin command that isn't ours.
+WRAPPER_MARK="# itfin-mcp CLI wrapper"
+if uses_cli && [[ -e "$BIN" ]] && ! grep -qF "$WRAPPER_MARK" "$BIN"; then
+  fail "$BIN already exists and is not the itfin-mcp CLI. Remove or rename it, or keep every app in MCP mode."
+fi
+# Likewise the skill and the Codex rules file: only files this installer wrote are replaced or removed.
+SKILL_MARK="Generated by itfin-mcp install"
+RULES_MARK="# Written by itfin-mcp install"
+ours() { [[ ! -e "$1" ]] || grep -qF "$2" "$1" 2>/dev/null; }
+for pair in "claude=$CLAUDE_SKILL" "codex=$CODEX_SKILL"; do
+  skill="${pair#*=}"
+  [[ "$(mode_of "${pair%%=*}")" != cli || ! -e "$skill" ]] || { [[ -f "$skill/SKILL.md" ]] && ours "$skill/SKILL.md" "$SKILL_MARK"; } \
+    || fail "$skill already exists and is not the itfin-mcp skill. Remove or rename it, or keep that app in MCP mode."
 done
-wants() { [[ "$CLIENTS" == *" $1 "* ]]; }
+[[ "$(mode_of codex)" != cli ]] || ours "$CODEX_RULES" "$RULES_MARK" \
+  || fail "$CODEX_RULES already exists and was not written by itfin-mcp. Remove or rename it."
 
-# Settings of the previous install, from the Claude Code registration, the Codex config or the
-# Claude Desktop config.
+# Settings: flags, then config.json, then (for installs from before config.json) the env of the
+# previous MCP registrations in Claude Code, Codex or Claude Desktop.
 PREV=""
 if command -v claude >/dev/null; then PREV+="$(claude mcp get itfin 2>/dev/null || true)"$'\n'; fi
 if [[ -f "$CODEX_CONFIG" ]]; then PREV+="$(cat "$CODEX_CONFIG")"$'\n'; fi
@@ -124,10 +177,17 @@ prev() {
   }'
 }
 
+[[ -n "$URL" ]] || URL="$(saved url)"
 [[ -n "$URL" ]] || URL="$(prev ITFIN_URL)"
+[[ -n "$BROWSER" ]] || BROWSER="$(saved browser)"
 [[ -n "$BROWSER" ]] || BROWSER="$(prev ITFIN_BROWSER)"
+[[ -n "$WORK_START" ]] || WORK_START="$(saved workStart)"
 [[ -n "$WORK_START" ]] || WORK_START="$(prev ITFIN_WORK_START)"
+[[ -n "$TIMEZONE" ]] || TIMEZONE="$(saved timezone)"
 [[ -n "$TIMEZONE" ]] || TIMEZONE="$(prev ITFIN_TIMEZONE)"
+# Whether CLI mode may allow read-only commands without asking: a flag, else the previous choice.
+[[ -n "$PERMISSIONS" ]] || PERMISSIONS="$(saved permissions)"
+[[ -n "$PERMISSIONS" ]] || PERMISSIONS=yes
 
 if [[ -z "$URL" ]]; then
   COMPANY="$(ask "Company name in ITFin (acme for https://acme.itfin.io)")"
@@ -141,58 +201,101 @@ URL="${URL%/}"
 [[ "$URL" =~ ^https?://[^/]+$ ]] || fail "Workspace address must look like https://acme.itfin.io"
 echo "→ Workspace: $URL"
 
+# Both modes read the settings from config.json. Settings left empty use the defaults (chrome,
+# 10:00, system timezone).
+node "$HELPERS" write-config "$CONFIG" "$URL" "$BROWSER" "$WORK_START" "$TIMEZONE" "$PERMISSIONS" $ALL_APPS
+
 ENTRY="$PKG/dist/index.js"
 # Absolute path, because Claude Desktop does not see version-manager shims on PATH.
 NODE="$(command -v node)"
-# Settings left empty are not passed, so the server uses its defaults (chrome, 10:00, system timezone).
-ENV_PAIRS=()
-for pair in "ITFIN_URL=$URL" "ITFIN_BROWSER=$BROWSER" "ITFIN_WORK_START=$WORK_START" "ITFIN_TIMEZONE=$TIMEZONE"; do
-  [[ -n "${pair#*=}" ]] && ENV_PAIRS+=("$pair")
-done
-ENV_ARGS=()
-for pair in "${ENV_PAIRS[@]}"; do ENV_ARGS+=(-e "$pair"); done
+ENV_PAIRS=("ITFIN_CONFIG=$CONFIG")
+ENV_ARGS=(-e "ITFIN_CONFIG=$CONFIG")
+cli() { ITFIN_CONFIG="$CONFIG" "$NODE" "$ENTRY" cli "$@"; }
+
+# The CLI skill in folder $1. Removing it deletes only our SKILL.md, and the folder if nothing else is left.
+install_skill() { mkdir -p "$1"; cli __skill >"$1/SKILL.md"; }
+remove_skill() { [[ -f "$1/SKILL.md" ]] && ours "$1/SKILL.md" "$SKILL_MARK" && rm -f "$1/SKILL.md" && rmdir "$1" 2>/dev/null; return 0; }
+# Removes the Codex rules file if this installer wrote it.
+remove_rules() { [[ -f "$CODEX_RULES" ]] && ours "$CODEX_RULES" "$RULES_MARK" && rm -f "$CODEX_RULES"; return 0; }
+READ_ONLY=()
+if uses_cli && [[ "$PERMISSIONS" == yes ]]; then
+  while IFS= read -r command; do [[ -n "$command" ]] && READ_ONLY+=("$command"); done < <(cli __read-only)
+fi
 
-if wants claude; then
+if [[ -n "$(mode_of claude)" ]]; then
   command -v claude >/dev/null || fail "The claude CLI was not found."
-  echo "→ Registering the MCP server with Claude Code (user scope)"
   claude mcp remove itfin --scope user >/dev/null 2>&1 || true
-  claude mcp add itfin --scope user "${ENV_ARGS[@]}" -- "$NODE" "$ENTRY"
+  if [[ "$(mode_of claude)" == cli ]]; then
+    echo "→ Setting up Claude Code in CLI mode (skill $CLAUDE_SKILL)"
+    install_skill "$CLAUDE_SKILL"
+    PERMS="$(node "$HELPERS" claude-permissions "$CLAUDE_SETTINGS" "$CONFIG" ${READ_ONLY[@]+"${READ_ONLY[@]}"})" \
+      || echo "! Could not update $CLAUDE_SETTINGS (is it valid JSON?), so Claude Code will ask before every itfin command."
+    [[ -n "$PERMS" ]] && echo "→ Allowed read-only itfin commands in $CLAUDE_SETTINGS: $(echo $PERMS)"
+  else
+    echo "→ Registering the MCP server with Claude Code (user scope)"
+    remove_skill "$CLAUDE_SKILL"
+    node "$HELPERS" claude-permissions "$CLAUDE_SETTINGS" "$CONFIG" >/dev/null || true
+    claude mcp add itfin --scope user "${ENV_ARGS[@]}" -- "$NODE" "$ENTRY"
+  fi
 fi
 
-if wants codex; then
+if [[ -n "$(mode_of codex)" ]]; then
   command -v codex >/dev/null || fail "The codex CLI was not found."
-  echo "→ Registering the MCP server with Codex"
   codex mcp remove itfin >/dev/null 2>&1 || true
-  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\
+  if [[ "$(mode_of codex)" == cli ]]; then
+    echo "→ Setting up Codex in CLI mode (skill $CODEX_SKILL)"
+    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.
+      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
+      } >"$CODEX_RULES"
+      echo "→ Allowed read-only itfin commands in $CODEX_RULES"
+    fi
+  else
+    echo "→ Registering the MCP server with Codex"
+    remove_skill "$CODEX_SKILL"
+    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\
 tool_timeout_sec = 240
 ' "$CODEX_CONFIG"
+  fi
 fi
 
 DESKTOP=""
-if wants desktop; then
+if [[ -n "$(mode_of desktop)" ]]; then
   echo "→ Registering the MCP server with Claude Desktop"
   # Replaces only mcpServers.itfin and keeps the rest of the file. The old file is kept as .bak.
-  if node -e '
-    const fs = require("fs");
-    const [file, command, entry, ...pairs] = process.argv.slice(1);
-    const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
-    const config = text.trim() ? JSON.parse(text) : {};
-    if (text) fs.writeFileSync(file + ".bak", text);
-    const env = Object.fromEntries(pairs.map((p) => [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]));
-    config.mcpServers = { ...config.mcpServers, itfin: { command, args: [entry], env } };
-    fs.mkdirSync(require("path").dirname(file), { recursive: true });
-    fs.writeFileSync(file, JSON.stringify(config, null, 2) + "\n");
-  ' "$DESKTOP_CONFIG" "$NODE" "$ENTRY" "${ENV_PAIRS[@]}"; then
+  if node "$HELPERS" desktop-register "$DESKTOP_CONFIG" "$NODE" "$ENTRY" "${ENV_PAIRS[@]}"; then
     DESKTOP=1
   else
     echo "! Could not update $DESKTOP_CONFIG (is it valid JSON?), so Claude Desktop was not registered."
   fi
 fi
 
+PATH_HINT=""
+if uses_cli; then
+  echo "→ Installing the itfin command in $BIN"
+  mkdir -p "$(dirname "$BIN")"
+  printf '#!/bin/sh\n%s, written by npx itfin-mcp install.\nITFIN_CONFIG="${ITFIN_CONFIG:-%s}" exec "%s" "%s" cli "$@"\n' "$WRAPPER_MARK" "$CONFIG" "$NODE" "$ENTRY" >"$BIN"
+  chmod +x "$BIN"
+  [[ ":$PATH:" == *":$(dirname "$BIN"):"* ]] || PATH_HINT=1
+elif [[ -f "$BIN" ]] && grep -qF "$WRAPPER_MARK" "$BIN"; then
+  rm -f "$BIN"
+fi
+
 echo
-echo "✓ itfin-mcp $NEW_VERSION is installed in $DIR"
+SUMMARY=""
+for pair in $ALL_APPS; do
+  case "${pair%%=*}" in claude) name="Claude Code" ;; codex) name="Codex" ;; desktop) name="Claude Desktop" ;; esac
+  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"
 # 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."

package/scripts/pick-clients.mjs

@@ -1,22 +1,36 @@
-// Checkbox list for install.sh: which apps to register the MCP server with.
-// Usage: node pick-clients.mjs id=Label ... Prints the chosen ids, one per line.
+// Checkbox list for install.sh: which apps to install for, and in which mode.
+// Usage: node pick-clients.mjs id=Label=modes=current ... (modes: comma-separated, e.g. mcp,cli)
+// Prints the chosen apps as id=mode, one per line.
 // Talks to /dev/tty, because install.sh itself usually comes from a pipe (curl | bash).
 import { openSync } from "node:fs";
 import { ReadStream, WriteStream } from "node:tty";
 import checkbox from "@inquirer/checkbox";
 
+const MODE_LABELS = { mcp: "MCP", cli: "CLI" };
+
 const input = new ReadStream(openSync("/dev/tty", "r"));
 const output = new WriteStream(openSync("/dev/tty", "w"));
 
+const choices = process.argv.slice(2).flatMap((arg) => {
+  const [id, name, modes, current] = arg.split("=");
+  const list = modes.split(",");
+  return list.map((mode) => ({
+    value: `${id}=${mode}`,
+    name: list.length > 1 ? `${name} (${MODE_LABELS[mode]})` : name,
+    checked: mode === (current || "mcp"),
+  }));
+});
+
 try {
   const chosen = await checkbox(
     {
-      message: "Install for",
-      choices: process.argv.slice(2).map((arg) => {
-        const [value, name] = arg.split("=");
-        return { value, name, checked: true };
-      }),
+      message: "Install for (MCP: the app runs ITFin tools; CLI: the agent runs the itfin command in its shell)",
+      choices,
       required: true,
+      validate: (picked) => {
+        const apps = picked.map((c) => c.value.split("=")[0]);
+        return new Set(apps).size === apps.length || "Pick one mode per app.";
+      },
     },
     { input, output },
   );