@togglhq/mcp 1.11.227 → 1.12.0

package/README.md

@@ -62,16 +62,29 @@ Uses **OAuth2 with PKCE** via the Toggl Accounts service. Credentials are stored
 
 ### CI or headless environments
 
+Set `TOGGL_API_TOKEN` to a personal Toggl API key (`toggl_sk_…`, from Toggl 2.0 **Settings → API token**). It takes precedence over any OAuth profile: no browser opens, nothing refreshes, and nothing is written to `~/.toggl/focus-tools.json`.
+
 ```bash
 claude mcp add toggl-focus \
   -s user \
-  -e TOGGL_WORKSPACE_ID=<your-workspace-id> \
-  -e TOGGL_API_TOKEN=<your-api-token> \
+  -e TOGGL_API_TOKEN=<your-api-key> \
   -e TOGGL_ORGANIZATION_ID=<your-org-id> \
-  -e TOGGL_USER_ID=<your-user-id> \
   -- npx @togglhq/mcp
 ```
 
+| Variable                | Required | Default when unset                                                                                        |
+| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
+| `TOGGL_API_TOKEN`       | Yes      | OAuth profile from `auth`                                                                                 |
+| `TOGGL_ORGANIZATION_ID` | Usually  | The organization last selected in Toggl's hosted MCP, if it is for the same workspace; otherwise an error |
+| `TOGGL_WORKSPACE_ID`    | No       | Your current Toggl 2.0 workspace                                                                          |
+| `TOGGL_USER_ID`         | No       | Looked up from the API key                                                                                |
+
+API keys cannot list organizations, so set `TOGGL_ORGANIZATION_ID` unless the default above applies. App URLs read `focus.toggl.com/<organization_id>/workspaces/<workspace_id>/…`. The server checks the key and the organization/workspace pair at startup and reports a revoked key or a missing org membership by name.
+
+API keys only reach the Toggl 2.0 API. Tools that call Toggl Accounts return `requires OAuth sign-in (run auth)` in this mode: `org-invitations`, `org-members`, `org-time-off-me`, `org-workspaces`, `shared-holidays`, `shared-status`, `shared-working-hours`, and `workspace-list` with `refresh: true`. `workspace-switch`, `profile-switch` and `profile-remove` are disabled, and `auth`, `logout` and `profile-list` report token mode instead of touching saved profiles. To use those tools, unset `TOGGL_API_TOKEN` and run `npx @togglhq/mcp auth`.
+
+The `toggl` CLI (`@togglhq/cli`) honours the same variables; `--workspace-id` overrides `TOGGL_WORKSPACE_ID` there. The key is never logged and is redacted from error reports.
+
 ## Tools
 
 ### Entity tools

package/build/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as getProductAnalyticsDistinctId, c as resolvePublicSentryDsn, i as captureToolInvocation, l as shutdownProductAnalytics, n as runMcpCli, o as initProductAnalytics, r as PUBLIC_SENTRY_PRIVACY_OPTIONS, s as resolveProductAnalyticsDistinctId } from "./src-CStKKXpP.js";
+import { a as getProductAnalyticsDistinctId, c as resolvePublicSentryDsn, i as captureToolInvocation, l as shutdownProductAnalytics, n as runMcpCli, o as initProductAnalytics, r as PUBLIC_SENTRY_PRIVACY_OPTIONS, s as resolveProductAnalyticsDistinctId } from "./src-Cw_5Hvfl.js";
 import * as Sentry from "@sentry/node";
 //#region src/analytics-tool-metadata.ts
 /**
@@ -162,7 +162,7 @@ function wrapServerWithProductAnalytics(server) {
 }
 //#endregion
 //#region src/cli.ts
-const packageVersion = "1.11.227";
+const packageVersion = "1.12.0";
 let sentryEnabled = false;
 let productAnalyticsEnabled = false;
 runMcpCli({

package/build/index.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { n as runMcpCli, t as bootstrapServer } from "./src-CStKKXpP.js";
+import { n as runMcpCli, t as bootstrapServer } from "./src-Cw_5Hvfl.js";
 export { bootstrapServer, runMcpCli };

package/build/{src-CStKKXpP.js → src-Cw_5Hvfl.js}

@@ -1,11 +1,11 @@
 import { createRequire } from "node:module";
 import * as crypto$1 from "node:crypto";
 import process$1 from "node:process";
-import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { basename, extname } from "node:path";
 import { readFile, stat, writeFile } from "node:fs/promises";
+import * as fs from "node:fs";
+import * as os from "node:os";
 import { createInterface } from "node:readline/promises";
 import { exec } from "node:child_process";
 import * as http from "node:http";
@@ -32484,102 +32484,6 @@ function parseAuthCliArgs(argv) {
 	};
 }
 //#endregion
-//#region ../cli-core/build/profile-Empu4JWK.js
-const CONFIG_DIR = path.join(os.homedir(), ".toggl");
-const CONFIG_FILE = path.join(CONFIG_DIR, "focus-tools.json");
-const LEGACY_MCP_CONFIG_FILE = path.join(os.homedir(), ".toggl-focus-mcp", "config.json");
-function readJsonFile(filePath) {
-	if (!fs.existsSync(filePath)) return null;
-	try {
-		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		throw new Error(`Failed to read ${filePath}: ${msg}`, { cause: err });
-	}
-}
-function saveLegacyAuthConfig(config) {
-	const dir = path.dirname(LEGACY_MCP_CONFIG_FILE);
-	fs.mkdirSync(dir, { recursive: true });
-	const tmp = `${LEGACY_MCP_CONFIG_FILE}.${process.pid}.tmp`;
-	fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
-	fs.renameSync(tmp, LEGACY_MCP_CONFIG_FILE);
-}
-function loadDeveloperToolsConfig() {
-	const config = readJsonFile(CONFIG_FILE);
-	if (!config || !config.profiles) return null;
-	return config;
-}
-function loadProfile(scope = "cli", profile) {
-	const config = loadDeveloperToolsConfig();
-	if (config) {
-		const activeProfile = profile ?? config.active[scope];
-		if (activeProfile && config.profiles[activeProfile]) return config.profiles[activeProfile];
-	}
-	const legacy = readJsonFile(LEGACY_MCP_CONFIG_FILE);
-	if (!legacy?.access_token || !legacy.workspace_id) return null;
-	return legacy;
-}
-function saveDeveloperToolsConfig(config) {
-	fs.mkdirSync(CONFIG_DIR, { recursive: true });
-	const tmp = `${CONFIG_FILE}.${process.pid}.tmp`;
-	fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
-	fs.renameSync(tmp, CONFIG_FILE);
-}
-function profileEnvironment(focusApiUrl) {
-	const hostname = new URL(focusApiUrl).hostname;
-	if (hostname === "focus.toggl.com") return "production";
-	return hostname.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase();
-}
-function profileSlug(value, fallback) {
-	return (value?.split("@")[0] ?? fallback).normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase() || fallback;
-}
-function deriveCliProfileName(options) {
-	return `${profileSlug(options.email, "user")}-${options.userId}`;
-}
-function toProfileRow(name, auth, activeProfile) {
-	const workspace = auth.workspaces?.find((candidate) => candidate.workspace_id === auth.workspace_id);
-	return {
-		name,
-		active: name === activeProfile,
-		environment: profileEnvironment(auth.focus_api_url),
-		user_id: auth.user_id,
-		organization_id: auth.organization_id,
-		organization_name: workspace?.organization_name,
-		workspace_id: auth.workspace_id,
-		workspace_name: auth.workspace_name,
-		focus_api_url: auth.focus_api_url,
-		accounts_api_url: auth.accounts_api_url,
-		authenticated_at: auth.authenticated_at,
-		expires_at: auth.expires_at,
-		token_expired: auth.expires_at <= Date.now() / 1e3
-	};
-}
-function listMcpProfiles() {
-	const config = loadDeveloperToolsConfig();
-	if (!config?.profiles) return [];
-	return Object.entries(config.profiles).map(([name, auth]) => toProfileRow(name, auth, config.active.mcp)).sort((a, b) => a.name.localeCompare(b.name));
-}
-function switchMcpProfile(profileName) {
-	const config = loadDeveloperToolsConfig();
-	if (!config?.profiles?.[profileName]) throw new Error(`Profile '${profileName}' not found. Use profile-list to see profiles saved in ~/.toggl/focus-tools.json.`);
-	config.active.mcp = profileName;
-	saveDeveloperToolsConfig(config);
-	return toProfileRow(profileName, config.profiles[profileName], profileName);
-}
-function removeMcpProfile(profileName) {
-	const config = loadDeveloperToolsConfig();
-	if (!config?.profiles?.[profileName]) throw new Error(`Profile '${profileName}' not found. Use profile-list to see profiles saved in ~/.toggl/focus-tools.json.`);
-	const removed = toProfileRow(profileName, config.profiles[profileName], config.active.mcp);
-	delete config.profiles[profileName];
-	if (config.active.mcp === profileName) {
-		const next = Object.keys(config.profiles).sort()[0];
-		if (next) config.active.mcp = next;
-		else delete config.active.mcp;
-	}
-	saveDeveloperToolsConfig(config);
-	return removed;
-}
-//#endregion
 //#region ../cli-core/build/env-CiVJIUnv.js
 const PRODUCTION_URLS = {
 	focusApiUrl: "https://focus.toggl.com",
@@ -38447,7 +38351,7 @@ async function deleteMyWorkingHours(httpClient, organization_id, data, signal) {
 	return response.json();
 }
 //#endregion
-//#region ../cli-core/build/focus-client-D9JzuIl3.js
+//#region ../cli-core/build/focus-client-CGUlmnDg.js
 /** Request header the API reads to attribute traffic to MCP or CLI. */
 const TOGGL_CLIENT_HEADER = "X-Toggl-Client";
 /** Header the Focus API reads for analytics and presence `platform_origin`. */
@@ -39427,7 +39331,311 @@ var FocusClient = class {
 	}
 };
 //#endregion
+//#region ../cli-core/build/profile-BNQd2PG5.js
+const CONFIG_DIR = path.join(os.homedir(), ".toggl");
+const CONFIG_FILE = path.join(CONFIG_DIR, "focus-tools.json");
+const LEGACY_MCP_CONFIG_FILE = path.join(os.homedir(), ".toggl-focus-mcp", "config.json");
+function readJsonFile(filePath) {
+	if (!fs.existsSync(filePath)) return null;
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`Failed to read ${filePath}: ${msg}`, { cause: err });
+	}
+}
+function saveLegacyAuthConfig(config) {
+	const dir = path.dirname(LEGACY_MCP_CONFIG_FILE);
+	fs.mkdirSync(dir, { recursive: true });
+	const tmp = `${LEGACY_MCP_CONFIG_FILE}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
+	fs.renameSync(tmp, LEGACY_MCP_CONFIG_FILE);
+}
+function loadDeveloperToolsConfig() {
+	const config = readJsonFile(CONFIG_FILE);
+	if (!config || !config.profiles) return null;
+	return config;
+}
+function loadProfile(scope = "cli", profile) {
+	const config = loadDeveloperToolsConfig();
+	if (config) {
+		const activeProfile = profile ?? config.active[scope];
+		if (activeProfile && config.profiles[activeProfile]) return config.profiles[activeProfile];
+	}
+	const legacy = readJsonFile(LEGACY_MCP_CONFIG_FILE);
+	if (!legacy?.access_token || !legacy.workspace_id) return null;
+	return legacy;
+}
+function saveDeveloperToolsConfig(config) {
+	fs.mkdirSync(CONFIG_DIR, { recursive: true });
+	const tmp = `${CONFIG_FILE}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
+	fs.renameSync(tmp, CONFIG_FILE);
+}
+function profileEnvironment(focusApiUrl) {
+	const hostname = new URL(focusApiUrl).hostname;
+	if (hostname === "focus.toggl.com") return "production";
+	return hostname.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function profileSlug(value, fallback) {
+	return (value?.split("@")[0] ?? fallback).normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-|-$/g, "").toLowerCase() || fallback;
+}
+function deriveCliProfileName(options) {
+	return `${profileSlug(options.email, "user")}-${options.userId}`;
+}
+function toProfileRow(name, auth, activeProfile) {
+	const workspace = auth.workspaces?.find((candidate) => candidate.workspace_id === auth.workspace_id);
+	return {
+		name,
+		active: name === activeProfile,
+		environment: profileEnvironment(auth.focus_api_url),
+		user_id: auth.user_id,
+		organization_id: auth.organization_id,
+		organization_name: workspace?.organization_name,
+		workspace_id: auth.workspace_id,
+		workspace_name: auth.workspace_name,
+		focus_api_url: auth.focus_api_url,
+		accounts_api_url: auth.accounts_api_url,
+		authenticated_at: auth.authenticated_at,
+		expires_at: auth.expires_at,
+		token_expired: auth.expires_at <= Date.now() / 1e3
+	};
+}
+function listMcpProfiles() {
+	const config = loadDeveloperToolsConfig();
+	if (!config?.profiles) return [];
+	return Object.entries(config.profiles).map(([name, auth]) => toProfileRow(name, auth, config.active.mcp)).sort((a, b) => a.name.localeCompare(b.name));
+}
+function switchMcpProfile(profileName) {
+	const config = loadDeveloperToolsConfig();
+	if (!config?.profiles?.[profileName]) throw new Error(`Profile '${profileName}' not found. Use profile-list to see profiles saved in ~/.toggl/focus-tools.json.`);
+	config.active.mcp = profileName;
+	saveDeveloperToolsConfig(config);
+	return toProfileRow(profileName, config.profiles[profileName], profileName);
+}
+function removeMcpProfile(profileName) {
+	const config = loadDeveloperToolsConfig();
+	if (!config?.profiles?.[profileName]) throw new Error(`Profile '${profileName}' not found. Use profile-list to see profiles saved in ~/.toggl/focus-tools.json.`);
+	const removed = toProfileRow(profileName, config.profiles[profileName], config.active.mcp);
+	delete config.profiles[profileName];
+	if (config.active.mcp === profileName) {
+		const next = Object.keys(config.profiles).sort()[0];
+		if (next) config.active.mcp = next;
+		else delete config.active.mcp;
+	}
+	saveDeveloperToolsConfig(config);
+	return removed;
+}
+//#endregion
 //#region ../cli-core/build/index.js
+/**
+* Headless auth with a personal Toggl API key (`toggl_sk_…`).
+*
+* When `TOGGL_API_TOKEN` is set it wins over any OAuth profile: no browser, no
+* refresh, and nothing is written to `~/.toggl/focus-tools.json`. The key is sent
+* to the Toggl 2.0 API as `Authorization: Bearer toggl_sk_…`. The API never falls
+* back to session auth once a key is presented, so a bad key is a hard 401.
+*
+* API-key requests carry no Accounts session. Toggl Accounts itself only accepts
+* OAuth/session credentials, so anything that calls Accounts directly (the `org`
+* and `shared` operation families) needs an OAuth sign-in instead.
+*/
+const TOGGL_API_TOKEN_ENV = "TOGGL_API_TOKEN";
+const TOGGL_USER_ID_ENV = "TOGGL_USER_ID";
+const TOGGL_WORKSPACE_ID_ENV = "TOGGL_WORKSPACE_ID";
+const TOGGL_ORGANIZATION_ID_ENV = "TOGGL_ORGANIZATION_ID";
+/** Matches `apikey.KeyPrefix` in toggl/pkg. */
+const TOGGL_API_KEY_PREFIX = "toggl_sk_";
+const REDACTED_API_TOKEN = `${TOGGL_API_KEY_PREFIX}[REDACTED]`;
+var ApiTokenAuthError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "ApiTokenAuthError";
+		this.status = status;
+	}
+};
+/** The raw `TOGGL_API_TOKEN` value, trimmed; blank counts as unset. */
+function readApiTokenFromEnv(env = process.env) {
+	const value = env[TOGGL_API_TOKEN_ENV]?.trim();
+	return value ? value : void 0;
+}
+/** True whenever `TOGGL_API_TOKEN` is set, valid or not: a bad key must fail, not fall back to OAuth. */
+function isApiTokenMode(env = process.env) {
+	return readApiTokenFromEnv(env) !== void 0;
+}
+/** Returns the key, or throws without ever echoing the value back. */
+function requireApiToken(env = process.env) {
+	const token = readApiTokenFromEnv(env);
+	if (!token) throw new ApiTokenAuthError(`${TOGGL_API_TOKEN_ENV} is not set.`);
+	if (!token.startsWith("toggl_sk_")) throw new ApiTokenAuthError(`${TOGGL_API_TOKEN_ENV} is not a Toggl API key: keys start with "${TOGGL_API_KEY_PREFIX}". Create one in Toggl 2.0 under Settings → API token.`);
+	return token;
+}
+const API_KEY_PATTERN = new RegExp(`${TOGGL_API_KEY_PREFIX}[^\\s"'\`,;)}\\]]*`, "g");
+/** Replace every `toggl_sk_…` key, plus the configured token verbatim, in free text. */
+function redactApiTokens(text, env = process.env) {
+	let redacted = text.replace(API_KEY_PATTERN, REDACTED_API_TOKEN);
+	const token = readApiTokenFromEnv(env);
+	if (token && token.length >= 8) redacted = redacted.split(token).join(REDACTED_API_TOKEN);
+	return redacted;
+}
+/** Deep-redact API keys in every string of a JSON-like value, in place where possible. */
+function redactApiTokensDeep(value, env = process.env) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const visit = (node) => {
+		if (typeof node === "string") return redactApiTokens(node, env);
+		if (!node || typeof node !== "object") return node;
+		if (seen.has(node)) return node;
+		seen.add(node);
+		if (Array.isArray(node)) {
+			for (let i = 0; i < node.length; i++) node[i] = visit(node[i]);
+			return node;
+		}
+		const record = node;
+		for (const key of Object.keys(record)) record[key] = visit(record[key]);
+		return node;
+	};
+	return visit(value);
+}
+function parseIdEnv(env, name) {
+	const raw = env[name]?.trim();
+	if (!raw) return void 0;
+	if (!/^\d+$/.test(raw)) throw new ApiTokenAuthError(`${name} must be a positive integer.`);
+	const id = Number(raw);
+	if (id <= 0 || id > Number.MAX_SAFE_INTEGER) throw new ApiTokenAuthError(`${name} must be a positive integer.`);
+	return id;
+}
+function positiveId(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : void 0;
+}
+function focusApiBase(focusApiUrl) {
+	const trimmed = focusApiUrl.replace(/\/+$/, "");
+	return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;
+}
+const INVALID_KEY_MESSAGE = `Toggl rejected ${TOGGL_API_TOKEN_ENV} (401). The key may have been revoked or replaced — creating a new key invalidates the previous one. Create a fresh key in Toggl 2.0 under Settings → API token.`;
+async function getJson(url, token, options) {
+	const doFetch = options.fetch ?? fetch;
+	const timeoutMs = options.timeoutMs ?? 1e4;
+	const origin = new URL(url).origin;
+	try {
+		const response = await doFetch(url, {
+			headers: {
+				Authorization: `Bearer ${token}`,
+				Accept: "application/json",
+				...togglClientHeaders(options.clientSurface)
+			},
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+		if (!response.ok) return { status: response.status };
+		return {
+			status: response.status,
+			body: await response.json()
+		};
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "TimeoutError") throw new ApiTokenAuthError(`The Toggl 2.0 API at ${origin} did not answer within ${Math.round(timeoutMs / 1e3)}s.`);
+		if (error instanceof SyntaxError) throw new ApiTokenAuthError(`The Toggl 2.0 API at ${origin} returned a response that is not JSON.`);
+		throw new ApiTokenAuthError(`Could not reach the Toggl 2.0 API at ${origin}: ${redactApiTokens(error instanceof Error ? error.message : String(error), options.env)}`);
+	}
+}
+/**
+* Work out the user, workspace and organization the key acts in.
+*
+* Explicit values win (`--workspace-id`, then `TOGGL_*_ID`). Otherwise:
+* - user: `GET /api/accounts/me` → `user_account_id`
+* - workspace: `GET /api/users/me/settings` → `current_workspace_id`, then the
+*   workspace last picked in Toggl's hosted MCP
+* - organization: the hosted-MCP selection when it names the same workspace.
+*   The Toggl 2.0 API has no "my organizations" endpoint an API key can read,
+*   so any other case needs `TOGGL_ORGANIZATION_ID`.
+*
+* The settings call always runs, so a revoked key fails here rather than on the
+* first tool call. The chosen pair is then checked with one org+workspace-scoped
+* read, which is what turns a wrong or foreign organization into a clear error.
+*/
+async function resolveApiTokenIdentity(options) {
+	const env = options.env ?? process.env;
+	const token = requireApiToken(env);
+	const api = focusApiBase(options.focusApiUrl);
+	const envUserId = parseIdEnv(env, TOGGL_USER_ID_ENV);
+	const envWorkspaceId = parseIdEnv(env, TOGGL_WORKSPACE_ID_ENV);
+	const envOrganizationId = parseIdEnv(env, TOGGL_ORGANIZATION_ID_ENV);
+	const settings = await getJson(`${api}/users/me/settings`, token, options);
+	if (settings.status === 401) throw new ApiTokenAuthError(INVALID_KEY_MESSAGE, 401);
+	if (!settings.body) throw new ApiTokenAuthError(`Could not read your Toggl 2.0 user settings (${settings.status}).`, settings.status);
+	let userId = envUserId;
+	let userSource = "env";
+	if (userId === void 0) {
+		const me = await getJson(`${api}/accounts/me`, token, options);
+		if (me.status === 401) throw new ApiTokenAuthError(INVALID_KEY_MESSAGE, 401);
+		userId = positiveId(me.body?.user_account_id);
+		if (userId === void 0) throw new ApiTokenAuthError(`Could not determine your Toggl user ID (${me.status}). Set ${TOGGL_USER_ID_ENV}.`, me.status);
+		userSource = "api";
+	}
+	const hostedMcpWorkspaceId = positiveId(settings.body.mcp_active_workspace_id);
+	const hostedMcpOrganizationId = positiveId(settings.body.mcp_active_organization_id);
+	let workspaceId;
+	let workspaceSource;
+	if (options.workspaceIdOverride !== void 0) {
+		workspaceId = options.workspaceIdOverride;
+		workspaceSource = "flag";
+	} else if (envWorkspaceId !== void 0) {
+		workspaceId = envWorkspaceId;
+		workspaceSource = "env";
+	} else {
+		workspaceId = positiveId(settings.body.current_workspace_id) ?? hostedMcpWorkspaceId;
+		workspaceSource = "api";
+	}
+	if (workspaceId === void 0) throw new ApiTokenAuthError(`Could not determine a workspace: your Toggl 2.0 settings have no current workspace. Set ${TOGGL_WORKSPACE_ID_ENV}.`);
+	let organizationId = envOrganizationId;
+	let organizationSource = "env";
+	if (organizationId === void 0) if (hostedMcpOrganizationId !== void 0 && hostedMcpWorkspaceId === workspaceId) {
+		organizationId = hostedMcpOrganizationId;
+		organizationSource = "api";
+	} else throw new ApiTokenAuthError(`Could not determine the organization for workspace ${workspaceId}: API keys cannot list organizations. Set ${TOGGL_ORGANIZATION_ID_ENV} (app URLs read focus.toggl.com/<organization_id>/workspaces/<workspace_id>/…).`);
+	const probe = await getJson(`${api}/organizations/${organizationId}/workspaces/${workspaceId}/custom-fields`, token, options);
+	if (probe.status === 401) throw new ApiTokenAuthError(INVALID_KEY_MESSAGE, 401);
+	if (probe.status === 403 || probe.status === 404) throw new ApiTokenAuthError(`This API key has no access to workspace ${workspaceId} in organization ${organizationId}. Check ${TOGGL_ORGANIZATION_ID_ENV} and ${TOGGL_WORKSPACE_ID_ENV}.`, probe.status);
+	if (probe.status >= 400) throw new ApiTokenAuthError(`Could not verify access to workspace ${workspaceId} in organization ${organizationId} (${probe.status}).`, probe.status);
+	return {
+		user_id: userId,
+		organization_id: organizationId,
+		workspace_id: workspaceId,
+		focus_api_url: options.focusApiUrl,
+		accounts_api_url: options.accountsApiUrl,
+		sources: {
+			user_id: userSource,
+			organization_id: organizationSource,
+			workspace_id: workspaceSource
+		}
+	};
+}
+function createApiTokenIdentityCache(options) {
+	let resolved;
+	let pending;
+	let failure;
+	return {
+		resolve() {
+			if (resolved) return Promise.resolve(resolved);
+			pending ??= resolveApiTokenIdentity(options()).then((identity) => {
+				resolved = identity;
+				failure = void 0;
+				return identity;
+			}).catch((error) => {
+				failure = error instanceof Error ? error.message : String(error);
+				throw error;
+			}).finally(() => {
+				pending = void 0;
+			});
+			return pending;
+		},
+		peek: () => resolved,
+		lastError: () => failure
+	};
+}
+/** Text every OAuth-only surface returns while `TOGGL_API_TOKEN` is set. */
+function oauthRequiredMessage(subject, authCommand) {
+	return `${subject} requires OAuth sign-in (run auth): it calls Toggl Accounts, which does not accept API keys. Unset ${TOGGL_API_TOKEN_ENV} and run \`${authCommand}\` to use it.`;
+}
 function openAuthBrowser(url) {
 	const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start \"\"" : "xdg-open";
 	exec(`${cmd} "${url}"`, (err) => {
@@ -39995,6 +40203,7 @@ async function refreshTokens(accountsApiUrl, refreshToken, clientSurface, client
 	return response.json();
 }
 async function getValidToken$1(scope = "cli", profile) {
+	if (isApiTokenMode()) return requireApiToken();
 	const authConfig = loadProfile(scope, profile);
 	if (!authConfig) throw new Error(scope === "cli" ? "Not authenticated. Run `toggl auth` to sign in." : `Not authenticated. Run \`${npxMcpAuthCommand()}\` to sign in.`);
 	const now = Date.now() / 1e3;
@@ -40202,7 +40411,7 @@ function scrubSpan(span) {
 /**
 * Last word on every event the public build sends: messages reduced to fixed
 * categories, no hostname, no breadcrumbs, no dependency list, no request data,
-* package-relative stack paths, and no query strings on spans.
+* package-relative stack paths, no query strings on spans, and no API keys.
 */
 function scrubPublicSentryEvent(event) {
 	redactUnsafeSentryMessages(event);
@@ -40214,7 +40423,7 @@ function scrubPublicSentryEvent(event) {
 	for (const thread of event.threads?.values ?? []) scrubStacktrace(thread.stacktrace);
 	for (const span of event.spans ?? []) scrubSpan(span);
 	scrubSpan(event.contexts?.trace);
-	return event;
+	return redactApiTokensDeep(event);
 }
 /**
 * Privacy options shared by `initCliTelemetry` and `initPublicSentry`.
@@ -40399,6 +40608,7 @@ function decodeAccessTokenSubject(token) {
 * from every other identity we already have for the same user.
 */
 function resolveProductAnalyticsDistinctId(scope) {
+	if (isApiTokenMode()) return null;
 	try {
 		return decodeAccessTokenSubject(loadProfile(scope)?.access_token);
 	} catch {
@@ -40517,6 +40727,35 @@ async function runAuthFlow(accountsApiUrl = "https://accounts.toggl.com", focusA
 	};
 }
 //#endregion
+//#region src/api-token-session.ts
+let cache = null;
+/** Process-wide identity for `TOGGL_API_TOKEN`; URLs come from the env the bootstrap resolved. */
+function apiTokenIdentity() {
+	cache ??= createApiTokenIdentityCache(() => {
+		const urls = resolveEnvironmentUrls();
+		return {
+			focusApiUrl: urls.focusApiUrl,
+			accountsApiUrl: urls.accountsApiUrl,
+			clientSurface: "mcp"
+		};
+	});
+	return cache;
+}
+function mcpOAuthRequiredMessage(subject) {
+	return oauthRequiredMessage(subject, npxMcpAuthCommand());
+}
+/** Shape `auth`, `profile-list` and the bootstrap report for token mode. Never includes the key. */
+function describeApiTokenIdentity(identity) {
+	return {
+		auth_mode: "api_token",
+		user_id: identity.user_id,
+		organization_id: identity.organization_id,
+		workspace_id: identity.workspace_id,
+		focus_api_url: identity.focus_api_url,
+		id_sources: identity.sources
+	};
+}
+//#endregion
 //#region src/authenticated-client.ts
 const AUTH_ERROR = {
 	ok: false,
@@ -40545,11 +40784,16 @@ function clientKey(clientConfig) {
 		clientConfig.user_id
 	].join(":");
 }
+/** Token mode reads the resolved API-key identity; OAuth mode reads the saved profile. */
+function currentClientConfig() {
+	if (isApiTokenMode()) return apiTokenIdentity().peek() ?? null;
+	return loadConfig();
+}
 function createAuthenticatedClientProxy() {
 	let cachedClient = null;
 	let cachedKey = null;
 	const resolveClient = () => {
-		const config = loadConfig();
+		const config = currentClientConfig();
 		if (!config) return null;
 		const key = clientKey(config);
 		if (cachedClient && cachedKey === key) return cachedClient;
@@ -40569,6 +40813,20 @@ function createAuthenticatedClientProxy() {
 		cachedKey = key;
 		return cachedClient;
 	};
+	/** Token mode resolves the identity lazily (and retries after a failure) before the first call. */
+	const resolveClientForCall = async () => {
+		if (isApiTokenMode() && !apiTokenIdentity().peek()) try {
+			await apiTokenIdentity().resolve();
+		} catch (error) {
+			return { error: {
+				ok: false,
+				status: 401,
+				message: `TOGGL_API_TOKEN sign-in failed: ${error instanceof Error ? error.message : String(error)}`
+			} };
+		}
+		const client = resolveClient();
+		return client ? { client } : { error: AUTH_ERROR };
+	};
 	return new Proxy({}, { get(_target, prop, receiver) {
 		if (prop === "userId") return resolveClient()?.userId ?? 0;
 		if (prop === "workspaceId") return resolveClient()?.workspaceId ?? "";
@@ -40579,8 +40837,9 @@ function createAuthenticatedClientProxy() {
 		}
 		if (FOCUS_CLIENT_SYNC_PASSTHROUGH_PROP_KEYS.includes(prop)) return readFocusClientSyncPassthroughProp(resolveClient(), prop);
 		return async (...args) => {
-			const client = resolveClient();
-			if (!client) return AUTH_ERROR;
+			const resolved = await resolveClientForCall();
+			if ("error" in resolved) return resolved.error;
+			const { client } = resolved;
 			const method = client[prop];
 			if (typeof method !== "function") return {
 				ok: false,
@@ -40592,7 +40851,7 @@ function createAuthenticatedClientProxy() {
 	} });
 }
 //#endregion
-//#region ../operations/build/validation-Byte2z0O.js
+//#region ../operations/build/validation-Cl22AQf7.js
 const optionalNumber = /* @__PURE__ */ optional$1(/* @__PURE__ */ number$2());
 const perPageField = (max) => /* @__PURE__ */ optional$1(/* @__PURE__ */ pipe$2(/* @__PURE__ */ number$2(), /* @__PURE__ */ integer(), /* @__PURE__ */ minValue$1(1), /* @__PURE__ */ maxValue$1(max), /* @__PURE__ */ description$1(`Results per page (1-${max})`)));
 const perPageSchema = perPageField(100);
@@ -41988,6 +42247,14 @@ const orgSharedOperations = [
 function operationRequiresConfirmation(operation) {
 	return operation.destructive || operation.safety !== "read";
 }
+/**
+* `org` and `shared` operations call Toggl Accounts directly, and Accounts only
+* accepts OAuth/session credentials. With `TOGGL_API_TOKEN` they cannot work, so
+* both surfaces short-circuit them with a sign-in message instead of a 401.
+*/
+function operationRequiresOAuth(operation) {
+	return operation.family === "org" || operation.family === "shared";
+}
 const MAX_ERROR_LENGTH = 200;
 const MAX_RECEIVED_LENGTH = 40;
 function formatIssueMessage(issue) {
@@ -55186,6 +55453,16 @@ function buildToolInventoryMarkdown() {
 	const record = buildToolInventoryRecord();
 	return Object.entries(record).map(([tool, actions]) => `- **${tool}** — actions: ${actions.join(", ")}`).join("\n");
 }
+/** Entity tools whose every action calls Toggl Accounts, so they need OAuth even when a key is set. */
+function oauthOnlyEntityTools() {
+	return entityToolNames().filter((tool) => operationsByEntityTool(tool).every(operationRequiresOAuth)).sort((a, b) => a.localeCompare(b));
+}
+function apiTokenSection() {
+	return `## API token mode
+
+This server authenticates with TOGGL_API_TOKEN. These tools need an OAuth sign-in and return "requires OAuth sign-in (run auth)" instead: ${oauthOnlyEntityTools().join(", ")}, plus \`workspace-list\` with \`refresh: true\`. Workspace and profile switching are disabled; the workspace comes from TOGGL_WORKSPACE_ID / TOGGL_ORGANIZATION_ID.
+`;
+}
 function buildMcpServerInstructions(options) {
 	const core = `## Entity tools
 
@@ -55210,6 +55487,10 @@ Entity mutations and \`profile-remove\` issue a \`confirm_token\` on the first c
 - Task priority levels when setting priority: \`none\`, \`low\`, \`medium\`, \`high\`.
 - Time entries are tracked time.
 `;
+	if (options.authMode === "api_token") return `${options.authenticated ? `You are connected to the Toggl 2.0 ${options.workspaceLabel ?? "workspace"}.` : `Toggl 2.0 MCP could not sign in with TOGGL_API_TOKEN: ${options.apiTokenError ?? "unknown error"}`}
+
+${apiTokenSection()}
+${core}`;
 	if (options.authenticated) return `You are connected to the Toggl 2.0 workspace ${options.workspaceLabel ?? "your workspace"}.
 
 ${core}`;
@@ -55955,8 +56236,34 @@ const profileRemoveInput = /* @__PURE__ */ object({
 	profile_name: profileNameField,
 	confirm_token: optionalConfirmToken
 });
+const API_TOKEN_PROFILES_MESSAGE = "Saved profiles are not used while TOGGL_API_TOKEN is set: every call authenticates with the API key. Remove TOGGL_API_TOKEN from the MCP server config to use OAuth profiles again.";
+const API_TOKEN_WORKSPACE_MESSAGE = "While TOGGL_API_TOKEN is set the workspace comes from TOGGL_WORKSPACE_ID and TOGGL_ORGANIZATION_ID (or your Toggl 2.0 current workspace). Change them and restart the MCP server to switch.";
+async function apiTokenStatus() {
+	try {
+		return {
+			ok: true,
+			identity: await apiTokenIdentity().resolve()
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			message: `TOGGL_API_TOKEN sign-in failed: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+}
 function registerWorkspaceTools(server) {
+	const runApiTokenAuth = async () => {
+		const status = await apiTokenStatus();
+		if (!status.ok) return mcpFailure(status.message);
+		return mcpText(JSON.stringify({
+			authenticated: true,
+			requires_workspace_selection: false,
+			...describeApiTokenIdentity(status.identity),
+			message: "Signed in with TOGGL_API_TOKEN. No browser sign-in runs and nothing is saved to ~/.toggl/focus-tools.json."
+		}, null, 2));
+	};
 	const runAuth = async ({ workspace_id, accounts_api_url, focus_api_url }) => {
+		if (isApiTokenMode()) return runApiTokenAuth();
 		try {
 			const continuation = pendingAuthContext && workspace_id !== void 0 ? pendingAuthContext : void 0;
 			const authResult = await runAuthFlow(accounts_api_url ?? process.env.TOGGL_ACCOUNTS_API_URL, focus_api_url ?? process.env.TOGGL_FOCUS_API_URL, {
@@ -56011,6 +56318,12 @@ function registerWorkspaceTools(server) {
 	};
 	const runLogout = async () => {
 		pendingAuthContext = null;
+		if (isApiTokenMode()) return mcpText(JSON.stringify({
+			logged_out: false,
+			auth_mode: "api_token",
+			removed_config: false,
+			message: "This server authenticates with TOGGL_API_TOKEN, so there is no stored session to clear. Remove TOGGL_API_TOKEN from the MCP server config to sign out. Saved OAuth profiles were left untouched."
+		}, null, 2));
 		const removed = clearConfig();
 		return { content: [{
 			type: "text",
@@ -56032,6 +56345,17 @@ function registerWorkspaceTools(server) {
 		},
 		inputSchema: toolObject(workspaceListInput)
 	}, async (params, _ctx) => {
+		if (isApiTokenMode()) {
+			if (params.refresh) return mcpFailure(mcpOAuthRequiredMessage("workspace-list refresh"));
+			const status = await apiTokenStatus();
+			if (!status.ok) return mcpFailure(status.message);
+			return mcpText(JSON.stringify([{
+				workspace_id: status.identity.workspace_id,
+				organization_id: status.identity.organization_id,
+				active: true,
+				auth_mode: "api_token"
+			}], null, 2));
+		}
 		try {
 			if (params.refresh) await refreshMcpWorkspaces();
 		} catch (error) {
@@ -56078,6 +56402,7 @@ function registerWorkspaceTools(server) {
 		},
 		inputSchema: toolObject(workspaceSwitchToolInput)
 	}, async (params, _ctx) => {
+		if (isApiTokenMode()) return mcpFailure(API_TOKEN_WORKSPACE_MESSAGE);
 		const { workspace_id } = params;
 		const config = loadConfig();
 		if (!config) return {
@@ -56114,6 +56439,14 @@ function registerWorkspaceTools(server) {
 			openWorldHint: false
 		}
 	}, async (_ctx) => {
+		if (isApiTokenMode()) {
+			const status = await apiTokenStatus();
+			return mcpText(JSON.stringify({
+				auth_mode: "api_token",
+				active: status.ok ? describeApiTokenIdentity(status.identity) : { error: status.message },
+				message: API_TOKEN_PROFILES_MESSAGE
+			}, null, 2));
+		}
 		const payload = listMcpProfiles().map((row) => ({
 			name: row.name,
 			active_for_mcp: row.active,
@@ -56141,6 +56474,7 @@ function registerWorkspaceTools(server) {
 		},
 		inputSchema: toolObject(profileNameInput)
 	}, async (params, _ctx) => {
+		if (isApiTokenMode()) return mcpFailure(API_TOKEN_PROFILES_MESSAGE);
 		try {
 			const row = switchMcpProfile(params.profile_name);
 			return { content: [{
@@ -56173,6 +56507,7 @@ function registerWorkspaceTools(server) {
 		},
 		inputSchema: toolObject(profileRemoveInput)
 	}, async (params, _ctx) => {
+		if (isApiTokenMode()) return mcpFailure(API_TOKEN_PROFILES_MESSAGE);
 		return withMutationApproval({ confirm_token: params.confirm_token }, async (approvalScope) => {
 			approvalScope.requireMutationApproval("profile-remove", mutationFingerprint({ profile_name: params.profile_name }), () => JSON.stringify({ profile_name: params.profile_name }));
 			try {
@@ -56197,7 +56532,7 @@ function registerWorkspaceTools(server) {
 	});
 	server.registerTool("auth", {
 		title: "Authenticate MCP",
-		description: "Authenticate this MCP server with Toggl 2.0 via OAuth. Opens browser login and stores credentials locally. Optionally pass workspace_id to pick a specific workspace when multiple are available.",
+		description: "Authenticate this MCP server with Toggl 2.0 via OAuth. Opens browser login and stores credentials locally. Optionally pass workspace_id to pick a specific workspace when multiple are available. When the server runs with TOGGL_API_TOKEN, reports the API-key identity instead and never opens a browser.",
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: false,
@@ -56225,7 +56560,7 @@ function registerWorkspaceTools(server) {
 //#region src/package-version.ts
 function mcpPackageVersion() {
 	try {
-		return "1.11.227";
+		return "1.12.0";
 	} catch {
 		return "unknown";
 	}
@@ -56340,6 +56675,7 @@ async function runOperation(operation, data, client, confirmToken, dryRun) {
 		status: 403,
 		message: `Operation '${operation.id}' is not available in this build.`
 	});
+	if (isApiTokenMode() && operationRequiresOAuth(operation)) return mcpFailure(mcpOAuthRequiredMessage(`${operation.mcp?.entityTool ?? operation.id} action '${operation.action}'`));
 	const parseResult = /* @__PURE__ */ safeParse(operation.inputSchema, coercePayload(data) ?? {});
 	if (!parseResult.success) return mcpFailure(`Invalid input: ${formatValibotError(parseResult.issues)}`);
 	const input = parseResult.output;
@@ -56348,6 +56684,11 @@ async function runOperation(operation, data, client, confirmToken, dryRun) {
 		operation: operation.id,
 		input
 	}, null, 2));
+	if (isApiTokenMode()) try {
+		await apiTokenIdentity().resolve();
+	} catch (error) {
+		return mcpFailure(`TOGGL_API_TOKEN sign-in failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
 	if (!operationRequiresConfirmation(operation)) return apiResult(await executeDecorated(operation, input, client));
 	return withMutationApproval({ confirm_token: confirmToken }, async (approvalScope) => {
 		approvalScope.requireMutationApproval(operation.id, mutationFingerprint(input), () => JSON.stringify({
@@ -56400,7 +56741,7 @@ import_main.default.config({
 	quiet: true,
 	ignore: ["MISSING_ENV_FILE"]
 });
-const packageVersion = "1.11.227";
+const packageVersion = "1.12.0";
 function resolvePublicUrls() {
 	return {
 		focusApiUrl: process.env.TOGGL_FOCUS_API_URL ?? "https://focus.toggl.com",
@@ -56417,7 +56758,35 @@ function runMcpCli(options = {}) {
 	if (process.argv[2] === "auth") runAuthCommand(urls);
 	else bootstrapServer(options);
 }
+/** MCP clients abandon `initialize` after a few seconds, so startup never waits on every probe. */
+const API_TOKEN_STARTUP_BUDGET_MS = 1e4;
+/**
+* Bounds how long startup waits for the API-key identity. Past the budget the server
+* starts anyway; the cache keeps resolving and tool calls pick up its result.
+*/
+function resolveApiTokenWithinStartupBudget() {
+	let timer;
+	const budget = new Promise((_resolve, reject) => {
+		timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`the Toggl 2.0 API had not answered after ${API_TOKEN_STARTUP_BUDGET_MS / 1e3}s at startup; tools retry the check on first use.`)), API_TOKEN_STARTUP_BUDGET_MS);
+		timer.unref();
+	});
+	return Promise.race([apiTokenIdentity().resolve(), budget]).finally(() => clearTimeout(timer));
+}
+async function runApiTokenAuthCommand() {
+	try {
+		const identity = await apiTokenIdentity().resolve();
+		console.error("TOGGL_API_TOKEN is set, so no browser sign-in runs and nothing is saved to ~/.toggl/focus-tools.json.");
+		console.error(JSON.stringify(describeApiTokenIdentity(identity), null, 2));
+	} catch (err) {
+		console.error("Auth failed:", err instanceof Error ? err.message : err);
+		process.exit(1);
+	}
+}
 function runAuthCommand(urls) {
+	if (isApiTokenMode()) {
+		runApiTokenAuthCommand();
+		return;
+	}
 	let authOptions;
 	try {
 		authOptions = parseAuthCliArgs(process.argv.slice(3));
@@ -56434,19 +56803,31 @@ function runAuthCommand(urls) {
 function bootstrapServer(options = {}) {
 	const urls = options.resolveUrls?.() ?? resolvePublicUrls();
 	applyResolvedUrls(urls);
-	const config = loadConfig();
-	const authenticated = Boolean(config);
+	const tokenMode = isApiTokenMode();
+	const config = tokenMode ? null : loadConfig();
+	let authenticated = Boolean(config);
 	console.error(`Using Toggl 2.0 API: ${urls.focusApiUrl}`);
 	const client = createAuthenticatedClientProxy();
-	const workspaceLabel = config ? `${config.workspace_name ?? "Workspace"} (ID: ${config.workspace_id})` : void 0;
+	let workspaceLabel = config ? `${config.workspace_name ?? "Workspace"} (ID: ${config.workspace_id})` : void 0;
+	let apiTokenError;
 	async function main() {
+		if (tokenMode) try {
+			const identity = await resolveApiTokenWithinStartupBudget();
+			authenticated = true;
+			workspaceLabel = `workspace ${identity.workspace_id} in organization ${identity.organization_id} (TOGGL_API_TOKEN)`;
+		} catch (err) {
+			apiTokenError = err instanceof Error ? err.message : String(err);
+			console.error(`TOGGL_API_TOKEN sign-in failed: ${apiTokenError}`);
+		}
 		serveStdio(() => {
 			const rawServer = new McpServer({
 				name: "toggl-focus",
 				version: packageVersion
 			}, { instructions: buildMcpServerInstructions({
 				authenticated,
-				workspaceLabel
+				workspaceLabel,
+				authMode: tokenMode ? "api_token" : "oauth",
+				apiTokenError
 			}) });
 			const server = options.beforeRegister?.(rawServer) ?? rawServer;
 			registerWorkspaceTools(server);
@@ -56454,7 +56835,7 @@ function bootstrapServer(options = {}) {
 			options.beforeConnect?.();
 			return server;
 		}, { legacy: "serve" });
-		console.error(config ? `Toggl 2.0 MCP server running on stdio (workspace: ${workspaceLabel})` : "Toggl 2.0 MCP server running on stdio (not authenticated)");
+		console.error(authenticated ? `Toggl 2.0 MCP server running on stdio (workspace: ${workspaceLabel})` : "Toggl 2.0 MCP server running on stdio (not authenticated)");
 	}
 	main().catch((err) => {
 		console.error("Fatal error:", err);
@@ -56465,4 +56846,4 @@ function bootstrapServer(options = {}) {
 //#endregion
 export { getProductAnalyticsDistinctId as a, resolvePublicSentryDsn as c, captureToolInvocation as i, shutdownProductAnalytics as l, runMcpCli as n, initProductAnalytics as o, PUBLIC_SENTRY_PRIVACY_OPTIONS as r, resolveProductAnalyticsDistinctId as s, bootstrapServer as t };
 
-//# sourceMappingURL=src-CStKKXpP.js.map
+//# sourceMappingURL=src-Cw_5Hvfl.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@togglhq/mcp",
-  "version": "1.11.227",
+  "version": "1.12.0",
   "description": "Toggl 2.0 MCP server for Claude Code, Claude Desktop, and other MCP clients.",
   "license": "UNLICENSED",
   "type": "module",