@togglhq/mcp 1.5.19

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@togglhq/mcp",
+  "version": "1.5.19",
+  "description": "Toggl Focus MCP server — @toggl/mcp on npm, @toggl/mcp-internal on GitHub Packages",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toggl/toggl-mcp.git"
+  },
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "skills/**",
+    "README.md"
+  ],
+  "bin": {
+    "mcp": "./build/index.js",
+    "toggl-mcp": "./build/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "import": "./build/index.js",
+      "default": "./build/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:public": "tsdown",
+    "build:internal": "tsdown --config tsdown.config.internal.ts",
+    "build:watch": "tsdown --watch",
+    "typecheck": "tsgo -p tsconfig.json --noEmit",
+    "build:mcpb": "node scripts/build-mcpb-node.cjs",
+    "build:mcpb:node": "node scripts/build-mcpb-node.cjs",
+    "build:mcpb:binary": "node scripts/build-mcpb-binary.cjs",
+    "start": "node build/index.js",
+    "lint": "oxlint --deny-warnings src/**/*.ts tsdown.config.ts tsdown.config.internal.ts",
+    "lint:fix": "oxlint --deny-warnings --fix src/**/*.ts tsdown.config.ts tsdown.config.internal.ts",
+    "format": "oxfmt --write src skills package.json tsconfig.json tsdown.config.ts tsdown.config.internal.ts vitest.config.ts README.md",
+    "format:check": "oxfmt --check src skills package.json tsconfig.json tsdown.config.ts tsdown.config.internal.ts vitest.config.ts README.md",
+    "test": "pnpm --filter @toggl/operations run build && vitest run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "date-fns": "4.1.0"
+  },
+  "devDependencies": {
+    "@sentry/node": "10.47.0",
+    "@toggl/cli-core": "workspace:^",
+    "@toggl/focus-queries": "workspace:^",
+    "@toggl/operations": "workspace:^",
+    "@types/node": "22.19.11",
+    "tsdown": "0.21.8",
+    "vitest": "3.2.4"
+  }
+}

package/skills/toggl-mcp/INTERNAL.md

@@ -0,0 +1,37 @@
+# Internal Toggl MCP Workflows
+
+Install `@toggl/mcp-internal` from **GitHub Packages** for internal builds that include staging, MS environments, and telemetry (`toggl-mcp-internal` / `mcp-internal` bins).
+
+## Environments
+
+Use the public npm build by default. Use the GitHub internal build only when a Toggl engineer asks for staging or a named MS environment.
+
+Run against staging:
+
+```bash
+ENV=staging toggl-mcp-internal
+```
+
+Run against a named MS environment:
+
+```bash
+MS=<name> toggl-mcp-internal
+```
+
+Explicit URL overrides still take precedence:
+
+```bash
+TOGGL_FOCUS_API_URL=<url> TOGGL_ACCOUNTS_API_URL=<url> toggl-mcp-internal
+```
+
+## Telemetry
+
+The GitHub internal build enables Sentry tracing by default with the internal DSN. Tool inputs and outputs are not recorded unless `SENTRY_RECORD_TOOL_IO=true`.
+
+Disable telemetry:
+
+```bash
+SENTRY_DSN=off toggl-mcp-internal
+```
+
+Burst detection is enabled when telemetry is enabled. It attaches retry metadata to Sentry spans and logs warnings when an MCP client repeats the same tool rapidly.

package/skills/toggl-mcp/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: toggl-mcp
+description: Use the Toggl Focus MCP server to read and mutate Focus data (tasks, projects, time blocks, time entries, saved views, custom fields, attachments, organization and org-* domains, org-time-off-me, shared-status/holidays/working-hours tools), manage workspaces and saved profiles, authenticate, and mirror CLI-style workflows from an MCP client. Trigger when the user connects through Model Context Protocol tools rather than the terminal, or asks how to use toggl-focus MCP tools, confirm_token, dry_run, file uploads/downloads, workspace refresh, or profile switching.
+---
+
+# Toggl Focus MCP
+
+The MCP server exposes **entity tools** (one tool per domain, for example `tasks`, `projects`) plus **workspace**, **profile**, and **auth** tools. Behavior aligns with the shared `@toggl/operations` catalog used by `toggl` CLI—see the `toggl-cli` skill for terminal equivalents (`toggl --json`, `--dry-run`, etc.).
+
+## Operating rules
+
+- Prefer **list** / **get** before mutating when IDs are unknown.
+- Entity calls use **`action`** plus optional **`data`** shaped for that action. Tool schemas list valid `action` values.
+- **`dry_run: true`** validates input and returns `{ dry_run, operation, input }` without calling the API (like CLI `--dry-run`).
+- **Mutations** (non-read operations): first call returns **`confirm_required`** and **`confirm_token`**; repeat the same arguments with **`confirm_token`** to execute once. **`dry_run: true`** skips the API and does not require a token.
+- Use **`workspace-list`** with **`refresh: true`** when a workspace is missing from cache (same idea as `toggl workspace list --refresh`).
+- **`profile-list`**, **`profile-switch`**, **`profile-remove`** control **`active.mcp`** in `~/.toggl/focus-tools.json`. Profiles are shared with the CLI; removing a profile removes it for both.
+- **`profile-remove`** is destructive: first call returns **`confirm_required`** + **`confirm_token`**; call again with the same **`profile_name`** and **`confirm_token`** (same pattern as entity mutations).
+- After **`auth`**, credentials use the same derived profile naming as CLI (`environment-userId`). **`logout`** clears the MCP active profile row only when **`active.mcp`** and that profile exist in **`~/.toggl/focus-tools.json`**. Older setups may still load **`~/.toggl-focus-mcp/config.json`** via compatibility—if logout says nothing was cleared, run **`auth`** once to migrate into the unified file, or delete the legacy path manually if discarding that session.
+- **Files cross the tool boundary as local paths** (the server runs on the user's machine): upload attachments with `attachments-create` / `attachments-bulk-create` passing **`file_path`** / **`file_paths`** (mime inferred from extension, 20 MB cap); download with `attachments-view` passing **`save_to`** (refuses to replace an existing file unless **`overwrite: true`**).
+- **List actions paginate** with `page` / `per_page` where the API supports it; request a page size instead of walking every page when summarizing large workspaces.
+- Some mutations need elevated rights: **custom-fields mutations are workspace-admin-only** (expect 403 otherwise).
+
+## Tools overview
+
+- **Entity domains**: tool names match `@toggl/operations` `mcp.entityTool` strings (examples: **`tasks`**, **`projects`**, **`saved-views`**, **`custom-fields`**, **`organization`**, **`org-invitations`**, **`shared-working-hours`**). Each tool accepts **`action`** values surfaced in server instructions and tool descriptions (hyphenated multi-word actions such as `bulk-patch`, `attachments-list`). Curated routing may group endpoints under the most helpful domain (for example composite flows and attachments under **`projects`** / **`tasks`**).
+- **Workspace/auth**: **workspace-list** (optional `refresh`), **workspace-switch**, **profile-list**, **profile-switch**, **profile-remove**, **auth**, **logout**.
+- Catalog entries marked hidden (e.g. calendar integrations, scheduler helpers, utilization targets) are omitted—parity with `visibleOperations()` in the CLI.
+
+## Installing from GitHub (`.mcpb`)
+
+Releases ship **per-platform** binary bundles (no Node on `PATH`): pick `darwin-arm64`, `darwin-x64`, `linux-x64`, or `win32-x64` from the `@toggl/mcp@<version>` release assets—see [packages/mcp/README.md](https://github.com/toggl/toggl-mcp/blob/main/packages/mcp/README.md).
+
+## Read next
+
+- Repository reference: [packages/mcp/README.md](https://github.com/toggl/toggl-mcp/blob/main/packages/mcp/README.md)
+- Terminal parity: `toggl-cli` skill (`packages/cli/skills/toggl-cli/SKILL.md` in this repo)