@togglhq/mcp 1.13.140 → 1.13.141

package/README.md

@@ -100,6 +100,10 @@ One tool per domain (for example `tasks`, `projects`, `time-entries`, `organizat
 
 **Mutation confirmation:** mutating tools return `confirm_required` with a `confirm_token` on the first call; repeat with `confirm_token` to execute.
 
+### Deep links
+
+- **deep-links** — read-only, no API calls. `action: "get"` returns the Toggl 2.0 web URL for a `task`, `project`, `time_entry`, `calendar_day`, `report` or `member` in the active organization and workspace, on the profile's environment (production or staging). It also returns a Track URL where the IDs map (members, by organization user ID); otherwise `track.url` is `null` with a `note` saying why. A time entry needs `task_id` to open directly; `calendar_day` opens the calendar on the week of its `date`. Example: `{ "action": "get", "data": { "entity": "report", "report_type": "detailed", "period": "prevMonth" } }`.
+
 ### Workspace, profiles, and auth
 
 - **workspace-list** — list workspaces (`refresh: true` refetches from Accounts)

package/build/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as PUBLIC_SENTRY_PRIVACY_OPTIONS, c as initProductAnalytics, d as shutdownProductAnalytics, i as runMcpCli, l as resolveProductAnalyticsDistinctId, o as captureToolInvocation, s as getProductAnalyticsDistinctId, u as resolvePublicSentryDsn } from "./src-D5fshNIt.js";
+import { a as PUBLIC_SENTRY_PRIVACY_OPTIONS, c as initProductAnalytics, d as shutdownProductAnalytics, i as runMcpCli, l as resolveProductAnalyticsDistinctId, o as captureToolInvocation, s as getProductAnalyticsDistinctId, u as resolvePublicSentryDsn } from "./src-ZNZfSwsi.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.13.140";
+const packageVersion = "1.13.141";
 let sentryEnabled = false;
 let productAnalyticsEnabled = false;
 runMcpCli({

package/build/index.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { i as runMcpCli, n as MCP_MAX_TOOL_INPUT_ELEMENTS, r as bootstrapServer, t as MCP_CACHE_TTL_MS } from "./src-D5fshNIt.js";
+import { i as runMcpCli, n as MCP_MAX_TOOL_INPUT_ELEMENTS, r as bootstrapServer, t as MCP_CACHE_TTL_MS } from "./src-ZNZfSwsi.js";
 export { MCP_CACHE_TTL_MS, MCP_MAX_TOOL_INPUT_ELEMENTS, bootstrapServer, runMcpCli };

package/build/{src-D5fshNIt.js → src-ZNZfSwsi.js}

@@ -38671,7 +38671,7 @@ async function deleteMyWorkingHours(httpClient, organization_id, data, signal) {
 	return response.json();
 }
 //#endregion
-//#region ../cli-core/build/focus-client-CGUlmnDg.js
+//#region ../cli-core/build/focus-client-CGpMYUFy.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`. */
@@ -38908,9 +38908,12 @@ var FocusClient = class {
 	organizationIdNum;
 	workspaceId;
 	workspaceIdNum;
+	/** Focus origin without the `/api` suffix, e.g. `https://focus.toggl.com`. */
+	focusBaseUrl;
 	constructor(config) {
 		let baseUrl = config.baseUrl.replace(/\/+$/, "");
 		if (!baseUrl.endsWith("/api")) baseUrl += "/api";
+		this.focusBaseUrl = baseUrl.slice(0, -4);
 		this.tokenProvider = config.tokenProvider;
 		this.clientSurface = config.clientSurface;
 		this.userId = config.userId;
@@ -39825,7 +39828,7 @@ function parseIdEnv(env, name) {
 	if (id <= 0 || id > Number.MAX_SAFE_INTEGER) throw new ApiTokenAuthError(`${name} must be a positive integer.`);
 	return id;
 }
-function positiveId(value) {
+function positiveId$1(value) {
 	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : void 0;
 }
 function focusApiBase(focusApiUrl) {
@@ -39887,12 +39890,12 @@ async function resolveApiTokenIdentity(options) {
 	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);
+		userId = positiveId$1(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);
+	const hostedMcpWorkspaceId = positiveId$1(settings.body.mcp_active_workspace_id);
+	const hostedMcpOrganizationId = positiveId$1(settings.body.mcp_active_organization_id);
 	let workspaceId;
 	let workspaceSource;
 	if (options.workspaceIdOverride !== void 0) {
@@ -39902,7 +39905,7 @@ async function resolveApiTokenIdentity(options) {
 		workspaceId = envWorkspaceId;
 		workspaceSource = "env";
 	} else {
-		workspaceId = positiveId(settings.body.current_workspace_id) ?? hostedMcpWorkspaceId;
+		workspaceId = positiveId$1(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}.`);
@@ -41085,7 +41088,8 @@ const AUTH_ERROR = {
 const FOCUS_CLIENT_SYNC_PASSTHROUGH_PROP_KEYS = [
 	"httpClient",
 	"organizationId",
-	"workspaceIdNumber"
+	"workspaceIdNumber",
+	"focusBaseUrl"
 ];
 function readFocusClientSyncPassthroughProp(client, prop) {
 	if (!client) return;
@@ -41171,7 +41175,7 @@ function createAuthenticatedClientProxy() {
 	} });
 }
 //#endregion
-//#region ../operations/build/validation-Cl22AQf7.js
+//#region ../operations/build/validation-CQfYPZ9x.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);
@@ -42209,6 +42213,226 @@ const versionOverrides = { "focus.version.service": {
 	description: "MCP package version plus the Focus API service revision.",
 	agentGuidance: "mcp.package is this published MCP package version (e.g. 1.8.0). focus_api is the Focus API process revision (git SHA / build number) — it does not change when you update the npm MCP package."
 } };
+const DEEP_LINK_ENTITIES = [
+	"task",
+	"project",
+	"time_entry",
+	"calendar_day",
+	"report",
+	"member"
+];
+const DEEP_LINK_REPORT_TYPES = [
+	"summary",
+	"detailed",
+	"profitability",
+	"utilization",
+	"workload",
+	"time-accounting",
+	"time-off"
+];
+const DEEP_LINK_REPORT_PERIODS = [
+	"today",
+	"yesterday",
+	"thisWeek",
+	"nextWeek",
+	"weekToDate",
+	"prevWeek",
+	"last2Weeks",
+	"thisMonth",
+	"nextMonth",
+	"prevMonth",
+	"monthToDate",
+	"thisQuarter",
+	"nextQuarter",
+	"quarterToDate",
+	"thisSemester",
+	"semesterToDate",
+	"last30Days",
+	"last90Days",
+	"lastQuarter",
+	"lastSemester",
+	"last12Months",
+	"thisYear",
+	"yearToDate",
+	"prevYear",
+	"allTime"
+];
+const PROJECT_TABS = [
+	"tasks",
+	"board",
+	"timeline",
+	"dashboard",
+	"members",
+	"period"
+];
+const MEMBER_TABS = ["time-off"];
+const DEEP_LINK_TABS = [...PROJECT_TABS, ...MEMBER_TABS];
+const PERIOD_REPORT_TYPES = new Set(DEEP_LINK_REPORT_TYPES.filter((type) => type !== "time-off"));
+const positiveId = /* @__PURE__ */ pipe$2(/* @__PURE__ */ number$2(), /* @__PURE__ */ integer(), /* @__PURE__ */ minValue$1(1));
+const isoDay = /* @__PURE__ */ pipe$2(/* @__PURE__ */ string$1(), /* @__PURE__ */ isoDate$1("must be YYYY-MM-DD"));
+const DeepLinkInputSchema = /* @__PURE__ */ object$2({
+	entity: /* @__PURE__ */ picklist$1(DEEP_LINK_ENTITIES),
+	id: /* @__PURE__ */ optional$1(positiveId),
+	task_id: /* @__PURE__ */ optional$1(positiveId),
+	project_id: /* @__PURE__ */ optional$1(positiveId),
+	date: /* @__PURE__ */ optional$1(isoDay),
+	report_type: /* @__PURE__ */ optional$1(/* @__PURE__ */ picklist$1(DEEP_LINK_REPORT_TYPES)),
+	period: /* @__PURE__ */ optional$1(/* @__PURE__ */ picklist$1(DEEP_LINK_REPORT_PERIODS)),
+	from: /* @__PURE__ */ optional$1(isoDay),
+	to: /* @__PURE__ */ optional$1(isoDay),
+	tab: /* @__PURE__ */ optional$1(/* @__PURE__ */ picklist$1(DEEP_LINK_TABS))
+});
+const ENTITIES_WITH_ID = new Set([
+	"task",
+	"project",
+	"time_entry",
+	"member"
+]);
+/** Cross-field rules the schema cannot carry; returns the first violation. */
+function deepLinkInputError(input) {
+	if (input.id === void 0 && ENTITIES_WITH_ID.has(input.entity)) return "id is required for task, project, time_entry and member (member id is the organization user ID)";
+	if (input.tab !== void 0 && !(input.entity === "project" && PROJECT_TABS.includes(input.tab)) && !(input.entity === "member" && MEMBER_TABS.includes(input.tab))) return `tab is ${PROJECT_TABS.join("|")} for project, or ${MEMBER_TABS.join("|")} for member`;
+	if (input.from === void 0 !== (input.to === void 0)) return "from and to must be passed together";
+	if (input.period !== void 0 && input.from !== void 0) return "pass either period or from/to, not both";
+	if ((input.period !== void 0 || input.from !== void 0) && !(input.entity === "report" && PERIOD_REPORT_TYPES.has(input.report_type ?? "summary"))) return "period and from/to apply only to report entities other than time-off";
+	if (input.from !== void 0 && input.to !== void 0 && input.from > input.to) return "from must not be after to";
+}
+const FOCUS_HOST_PATTERN = /^focus\.((?:[a-z0-9-]+\.)*toggl\.(?:com|space))$/i;
+const APP_HOST_PATTERN = /^app\.(toggl\.(?:com|space)|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.ms\.toggl\.space)$/i;
+function trackBaseUrlFor(focusBaseUrl) {
+	const hostname = new URL(focusBaseUrl).hostname.toLowerCase();
+	const base = FOCUS_HOST_PATTERN.exec(hostname)?.[1] ?? APP_HOST_PATTERN.exec(hostname)?.[1];
+	return base ? `https://track.${base}` : null;
+}
+function withQuery(url, params) {
+	const search = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) if (value !== void 0) search.set(key, value);
+	const query = search.toString();
+	return query ? `${url}?${query}` : url;
+}
+function trackUnmapped(input) {
+	switch (input.entity) {
+		case "calendar_day":
+		case "report": return {
+			url: null,
+			note: "Track calendar and reports are scoped to a Track workspace; a Toggl 2.0 workspace ID is not a Track workspace ID."
+		};
+		default: return {
+			url: null,
+			note: `Toggl 2.0 ${input.entity.replace("_", " ")} IDs are not Track IDs (imports and Track sync create new records), so no Track URL maps.`
+		};
+	}
+}
+/** Builds the links for input that already passed `deepLinkInputError`. */
+function buildDeepLinks(input, context) {
+	const origin = context.focusBaseUrl.replace(/\/+$/, "");
+	const workspaceRoot = `${origin}/${context.organizationId}/workspaces/${context.workspaceId}`;
+	const trackBase = trackBaseUrlFor(origin);
+	let focus;
+	let track = trackUnmapped(input);
+	switch (input.entity) {
+		case "task":
+			focus = {
+				url: withQuery(input.project_id !== void 0 ? `${workspaceRoot}/projects/${input.project_id}` : `${workspaceRoot}/calendar`, { tid: String(input.id) }),
+				note: input.project_id !== void 0 ? "Opens the task editor over its project." : "Opens the task editor over the calendar; pass project_id to open it over the project instead."
+			};
+			break;
+		case "project":
+			focus = { url: `${workspaceRoot}/projects/${input.id}${input.tab ? `/${input.tab}` : ""}` };
+			break;
+		case "time_entry":
+			if (input.task_id !== void 0) focus = {
+				url: withQuery(`${workspaceRoot}/calendar`, {
+					tid: String(input.task_id),
+					teid: String(input.id)
+				}),
+				note: "Opens the time entry inside its task's editor."
+			};
+			else focus = {
+				url: `${workspaceRoot}/calendar`,
+				note: "A time entry is only addressable through its task; pass task_id to open it directly. Without it this is the calendar."
+			};
+			break;
+		case "calendar_day":
+			focus = {
+				url: withQuery(`${workspaceRoot}/calendar`, { d: input.date }),
+				note: input.date ? `Opens the week of ${input.date}.` : "Opens the current week."
+			};
+			break;
+		case "report": {
+			const reportType = input.report_type ?? "summary";
+			const period = input.period !== void 0 ? { preset: input.period } : input.from !== void 0 ? {
+				from: input.from,
+				to: input.to
+			} : void 0;
+			focus = { url: withQuery(`${workspaceRoot}/reports/${reportType}`, { pe: period ? JSON.stringify(period) : void 0 }) };
+			break;
+		}
+		case "member":
+			focus = { url: `${workspaceRoot}/members/${input.id}${input.tab ? `/${input.tab}` : ""}` };
+			track = trackBase ? {
+				url: `${trackBase}/organization/${context.organizationId}/members/${input.id}/time-off`,
+				note: input.tab === "time-off" ? void 0 : "Track has no member profile page; this is the member's Track time-off page."
+			} : {
+				url: null,
+				note: `No Track host is known for ${new URL(origin).hostname}.`
+			};
+			break;
+	}
+	return {
+		entity: input.entity,
+		organization_id: context.organizationId,
+		workspace_id: context.workspaceId,
+		focus,
+		track
+	};
+}
+const deepLinkOperations = [{
+	id: "focus.deep-links.get",
+	family: "focus",
+	resource: "deep-links",
+	action: "get",
+	title: "Get deep links",
+	description: "Build Toggl 2.0 web URLs (and Track URLs where IDs map) for a task, project, time entry, calendar day, report or member. Read-only; makes no API calls.",
+	agentGuidance: "member id is the organization user ID. time_entry needs task_id to open the entry itself. report_type defaults to summary; set period (preset) or from/to (YYYY-MM-DD) for a date range. track.url is null with a note when the IDs do not map to Track.",
+	safety: "read",
+	destructive: false,
+	cli: {
+		group: [],
+		command: "deep-link",
+		interactive: "hidden",
+		examples: [{
+			description: "Link to a task",
+			data: {
+				entity: "task",
+				id: 123
+			}
+		}, {
+			description: "Link to last month's detailed report",
+			data: {
+				entity: "report",
+				report_type: "detailed",
+				period: "prevMonth"
+			}
+		}]
+	},
+	mcp: { entityTool: "deep-links" },
+	inputSchema: DeepLinkInputSchema,
+	execute: (input, { client }) => {
+		const deepLinkInput = input;
+		const error = deepLinkInputError(deepLinkInput);
+		if (error) return Promise.resolve({
+			ok: false,
+			status: 400,
+			message: error
+		});
+		return client.runGeneratedRequest("getDeepLinks", () => Promise.resolve(buildDeepLinks(deepLinkInput, {
+			focusBaseUrl: client.focusBaseUrl,
+			organizationId: client.organizationId,
+			workspaceId: client.workspaceIdNumber
+		})));
+	}
+}];
 const dateRangeDay = /* @__PURE__ */ pipe$2(/* @__PURE__ */ string$1(), /* @__PURE__ */ regex(/^\d{4}-\d{2}-\d{2}$/, "must be YYYY-MM-DD"));
 const TimeOffMeUpdateInputSchema = /* @__PURE__ */ intersect([/* @__PURE__ */ object$2({ timeoff_id: /* @__PURE__ */ number$2() }), PublicMeEntryRequestSchema]);
 const emptySchema = /* @__PURE__ */ object$2({});
@@ -57889,7 +58113,11 @@ function applyOverrides(operation) {
 		}
 	};
 }
-const operations = [...generatedFocusOperations.map((operation) => applyOverrides(operation)), ...orgSharedOperations];
+const operations = [
+	...generatedFocusOperations.map((operation) => applyOverrides(operation)),
+	...orgSharedOperations,
+	...deepLinkOperations
+];
 function visibleOperations() {
 	return operations.filter((operation) => !operation.hidden);
 }
@@ -59004,7 +59232,7 @@ function registerWorkspaceTools(server) {
 //#region src/package-version.ts
 function mcpPackageVersion() {
 	try {
-		return "1.13.140";
+		return "1.13.141";
 	} catch {
 		return "unknown";
 	}
@@ -59185,7 +59413,7 @@ import_main.default.config({
 	quiet: true,
 	ignore: ["MISSING_ENV_FILE"]
 });
-const packageVersion = "1.13.140";
+const packageVersion = "1.13.141";
 const MCP_CACHE_TTL_MS = 300 * 1e3;
 const MCP_MAX_TOOL_INPUT_ELEMENTS = 1e4;
 function resolvePublicUrls() {
@@ -59305,4 +59533,4 @@ function bootstrapServer(options = {}) {
 //#endregion
 export { PUBLIC_SENTRY_PRIVACY_OPTIONS as a, initProductAnalytics as c, shutdownProductAnalytics as d, runMcpCli as i, resolveProductAnalyticsDistinctId as l, MCP_MAX_TOOL_INPUT_ELEMENTS as n, captureToolInvocation as o, bootstrapServer as r, getProductAnalyticsDistinctId as s, MCP_CACHE_TTL_MS as t, resolvePublicSentryDsn as u };
 
-//# sourceMappingURL=src-D5fshNIt.js.map
+//# sourceMappingURL=src-ZNZfSwsi.js.map

package/package.json

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