@togglhq/mcp 1.5.19 → 1.5.21

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) Toggl. All rights reserved.
+
+This software is proprietary to Toggl. Installation and use are permitted only
+under applicable Toggl product terms, agreements, and policies.
+
+See https://toggl.com/legal/ for current legal terms and policies.

package/README.md

@@ -1,33 +1,15 @@
-# Toggl Focus MCP Server
+# Toggl 2.0 MCP Server
 
-A local MCP (Model Context Protocol) server that connects to the Toggl Focus API. Works with any MCP client including Claude Code and Claude Desktop. Exposes generated entity-domain tools (`tasks`, `projects`, `time-blocks`, `time-entries`, and related domains), workspace/auth tools, and Focus query artifacts from [`packages/focus-queries`](../focus-queries).
+A local MCP (Model Context Protocol) server that connects to the Toggl 2.0 API. Works with any MCP client including Claude Code and Claude Desktop.
 
-Published publicly as **`@togglhq/mcp`** on **npmjs.org**. Internal builds publish as **`@toggl/mcp-internal`** on GitHub Packages.
-
-Each GitHub release also includes **per-platform `.mcpb` bundles** (standalone executables; no Node.js on `PATH`) so users can install without registry access.
-
-## Install from npm (public)
+## Install
 
 ```bash
 npm install @togglhq/mcp
 # or: pnpm add @togglhq/mcp
 ```
 
-No GitHub Packages token is required.
-
-## Install from GitHub Packages (Toggl staff)
-
-Internal builds publish as **`@toggl/mcp-internal`**. You need a GitHub token with **`read:packages`** and access to the Toggl org, or installs can return 404.
-
-1. Copy [`.npmrc.example`](.npmrc.example) into your project or `~/.npmrc` and replace `<GH_NPM_TOKEN>` with a PAT.
-2. Install:
-
-```bash
-npm install @toggl/mcp-internal
-# or: pnpm add @toggl/mcp-internal
-```
-
-Run the CLI (after install):
+Authenticate:
 
 ```bash
 npx @togglhq/mcp auth
@@ -35,50 +17,15 @@ npx @togglhq/mcp auth
 
 For one-off runs without a local install: `npx -y @togglhq/mcp auth`.
 
-## Install from GitHub Release (`.mcpb`)
-
-If you do not have access to the private package registry, install from the release bundle instead:
-
-1. Open the latest [GitHub release](https://github.com/toggl/toggl-mcp/releases).
-2. Download the `.mcpb` for **your OS and CPU** (and the matching `.sha256` if you verify checksums):
-   - **Apple Silicon macOS:** `toggl-focus-mcp-<version>-darwin-arm64.mcpb`
-   - **Intel macOS:** `toggl-focus-mcp-<version>-darwin-x64.mcpb`
-   - **Linux x64:** `toggl-focus-mcp-<version>-linux-x64.mcpb`
-   - **Windows x64:** `toggl-focus-mcp-<version>-win32-x64.mcpb`
-
-3. Open the `.mcpb` file in a compatible MCP client (for example, Claude Desktop) to install.
-
-These bundles embed a compiled server and **do not require Node.js** or `@toggl/mcp` registry access.
-
-For development or debugging you can still package a **Node-based** MCPB (requires end users to have Node 20+): `pnpm run build:mcpb:node` from this package (outputs `toggl-focus-mcp-<version>.mcpb`).
-
-## Setup (from source)
-
-```bash
-git clone https://github.com/toggl/toggl-mcp.git
-cd toggl-mcp
-pnpm install
-pnpm run build
-node build/index.js auth
-```
-
-This will:
-
-1. Open your browser to sign in with your Toggl account
-2. Automatically discover your workspaces
-3. Let you select your workspace (if you have multiple)
+## Add to your MCP client
 
-Authentication uses OAuth2 with PKCE — no API keys or passwords are entered in the terminal. Access tokens refresh automatically (1-hour access token, 4-week refresh token).
-
-### Add to your MCP client
-
-#### Claude Code
+### Claude Code
 
 ```bash
-claude mcp add toggl-focus -- npx @toggl/mcp
+claude mcp add toggl-focus -- npx @togglhq/mcp
 ```
 
-#### Claude Desktop
+### Claude Desktop
 
 Add to your Claude Desktop config file:
 
@@ -89,26 +36,24 @@ Add to your Claude Desktop config file:
 {
   "mcpServers": {
     "toggl-focus": {
-      "command": "node",
-      "args": ["/absolute/path/to/toggl-mcp/build/index.js"]
+      "command": "npx",
+      "args": ["@togglhq/mcp"]
     }
   }
 }
 ```
 
-Replace `/absolute/path/to/toggl-mcp` with the actual path to your clone, or use `npx` with `command`/`args` pointing at `@toggl/mcp` if installed from GitHub Packages (with `.npmrc` configured). Restart Claude Desktop to pick up the change.
+Restart Claude Desktop after saving.
 
 ## Authentication
 
-Uses **OAuth2 with PKCE** via the Toggl Accounts service. Credentials are stored in `~/.toggl/focus-tools.json` (mode 0600). Access tokens refresh automatically — re-run `npx @toggl/mcp auth` only to switch workspaces or if your refresh token expires (after 4 weeks of inactivity).
+Uses **OAuth2 with PKCE** via the Toggl Accounts service. Credentials are stored in `~/.toggl/focus-tools.json` (mode 0600). Access tokens refresh automatically — re-run `npx @togglhq/mcp auth` to switch workspaces or if your refresh token expires (after 4 weeks of inactivity).
 
 > **Upgrading from an older version?** Sessions previously stored at `~/.toggl-focus-mcp/config.json` are still read automatically — no re-authentication needed.
 
-> **Unified config vs legacy file:** MCP **logout** (and config cleanup helpers) only remove credentials when there is a matching profile row under **`~/.toggl/focus-tools.json`** with **`active.mcp`** set. If you authenticate solely via the legacy read shim and nothing was written to the unified file yet, logout may report that nothing was cleared—run **`npx @toggl/mcp auth`** once so tokens land in `focus-tools.json`, or remove the legacy file manually if you intend to discard that session.
-
-### Alternative: Environment Variables
+> **Unified config vs legacy file:** MCP **logout** only removes credentials when there is a matching profile row under **`~/.toggl/focus-tools.json`** with **`active.mcp`** set. Run **`npx @togglhq/mcp auth`** once to migrate into the unified file if logout reports nothing was cleared.
 
-For CI or headless environments where browser-based OAuth is not available:
+### CI or headless environments
 
 ```bash
 claude mcp add toggl-focus \
@@ -117,228 +62,31 @@ claude mcp add toggl-focus \
   -e TOGGL_API_TOKEN=<your-api-token> \
   -e TOGGL_ORGANIZATION_ID=<your-org-id> \
   -e TOGGL_USER_ID=<your-user-id> \
-  -- npx @toggl/mcp
+  -- npx @togglhq/mcp
 ```
 
 ## Tools
 
 ### Entity tools
 
-MCP exposes **one tool per catalog entity domain** — the tool id equals `mcp.entityTool` from `@toggl/operations` (for example `tasks`, `projects`, `time-blocks`, `organization`, `org-invitations`, `shared-working-hours`). Each tool accepts:
-
-- **`action`** (required) — discriminator for the operation
-- **`data`** (optional) — payload for that action
-- **`confirm_token`** (optional) — second step for mutating operations (see below)
-- **`dry_run`** (optional) — when `true`, validates `data` and returns `{ dry_run, operation, input }` without calling the API (CLI `--dry-run` parity)
-
-CLI bulk mutations are nested (`toggl tasks bulk patch`, etc.); MCP uses hyphenated `action` values such as `bulk-patch` on the same entity tools.
-
-**Mutation confirmation:** mutating tools use a two-step flow. First call returns `confirm_required` with `confirm_token`; call the same tool again with `confirm_token` to execute once. `dry_run: true` skips execution and does not consume a token.
-
-### Tool inventory (full action list)
-
-The server builds MCP **instructions** at startup from `@toggl/operations`, so clients always see the current domains and actions. CI checks durable inventory invariants in [`packages/mcp/src/__tests__/tool-inventory-invariants.test.ts`](src/__tests__/tool-inventory-invariants.test.ts) instead of snapshotting the full generated action list.
-
-### Workspaces, profiles & auth
-
-- **workspace-list** — List cached workspaces; pass `{ "refresh": true }` to refetch from Accounts first (CLI `workspace list --refresh` parity)
-- **workspace-switch** — Switch the active workspace for MCP
-- **profile-list** — List rows in `~/.toggl/focus-tools.json` with MCP active flag (`active.mcp`)
-- **profile-switch** — Set `active.mcp` to an existing profile name (shared with CLI profiles)
-- **profile-remove** — Remove a profile row (shared storage; affects CLI too if it used that row). Same **`confirm_token`** two-step flow as entity mutations: first call returns `confirm_required`, second call passes `confirm_token` with the same `profile_name`.
-- **auth** — Authenticate the MCP server via OAuth
-- **logout** — Clear the current MCP active profile credentials
-
-Agent-oriented guidance: [`skills/toggl-mcp/SKILL.md`](skills/toggl-mcp/SKILL.md) (bundled in the npm package under `skills/`).
-
-### Maintainers: regenerate Focus API coverage
-
-```bash
-pnpm run generate:focus-queries
-pnpm run generate:focus-operations
-```
-
-Set `GH_AUTH_TOKEN` in `packages/focus-queries/.env` before generation (see [`packages/focus-queries/README.md`](../focus-queries/README.md)). Querygen refreshes Focus request/type/schema artifacts first; the operations generator then exposes most generated endpoints to CLI/MCP by default, excluding internal, deprecated, unsafe, file-upload, and unsupported-signature endpoints blocklisted in `packages/operations/src/focus/blocklist.ts`.
-
-## Architecture
-
-```
-src/
-├── index.ts                    # Entry point — CLI auth handler + MCP server bootstrap
-├── instructions.ts             # MCP server instructions + tool inventory from @toggl/operations
-├── auth.ts                     # OAuth2 PKCE auth flow, token refresh, config file management
-├── client.ts                   # Re-export of @toggl/cli-core FocusClient
-├── authenticated-client.ts
-├── utils.ts                    # Date helpers (@toggl/stdlib + cli-core), markdown tables, MCP response helpers
-├── runtime/
-│   └── safety/                 # Mutation confirmation gate
-└── tools/
-    ├── generated-entity-tools.ts # Registers MCP entity tools from @toggl/operations
-    ├── mcp-schema.ts
-    ├── focus-tool-utils.ts
-    ├── payload-helpers.ts
-    └── workspace.ts            # Workspace/auth tools
-packages/
-├── cli-core/                   # Auth/config/token primitives and FocusClient
-├── operations/                 # Shared operation catalog used by CLI and MCP
-└── focus-queries/              # Querygen mirror for Focus API types, schemas, and requests
-```
-
-### How it works
-
-The server runs as a **stdio MCP process**. Claude Code spawns it as a subprocess and communicates via JSON-RPC over stdin/stdout (stderr is used for logging).
-
-**Startup flow:**
-
-1. `index.ts` checks for the `auth` CLI argument — if present, runs the auth flow and exits.
-2. Otherwise, it loads credentials from `~/.toggl/focus-tools.json` when available (falls back to `~/.toggl-focus-mcp/config.json` for sessions created by older versions).
-3. Creates an auth-aware `FocusClient` proxy that resolves credentials lazily per tool call.
-4. Creates an `McpServer` and registers entity tools from `@toggl/operations`, plus workspace/auth tools.
-5. Connects via `StdioServerTransport` and waits for tool calls.
-
-**Environment configuration:**
-
-The server reads an optional `.env` file from the project root and defaults to production (`focus.toggl.com`). You can override URLs directly via `TOGGL_FOCUS_API_URL` and `TOGGL_ACCOUNTS_API_URL` environment variables.
-
-### Authentication details
-
-The auth flow (`auth.ts`) uses **OAuth2 Authorization Code with PKCE**:
-
-1. Generates a PKCE code verifier and challenge (SHA-256, base64url).
-2. Starts a local HTTP callback server on `localhost:8716`.
-3. Opens the browser to `accounts.toggl.com/focus/login/` with OAuth parameters.
-4. User logs in via the browser — the callback receives the authorization code.
-5. Exchanges the code for access + refresh tokens via `POST /api/oauth/token`.
-6. Fetches user info (`GET /api/me`) and workspaces (`GET /org/api/organizations/me`).
-7. Saves tokens and workspace info to `~/.toggl/focus-tools.json` (mode 0600).
-
-**Token refresh** happens automatically: before each API request, the client checks the access token's expiry and refreshes it if it expires within 60 seconds. The refresh token is valid for 4 weeks.
-
-The stored config looks like:
-
-```json
-{
-  "access_token": "<OAuth access token>",
-  "refresh_token": "<OAuth refresh token>",
-  "expires_at": 1700000000,
-  "user_id": 1234567,
-  "organization_id": 12345,
-  "workspace_id": 67890,
-  "workspace_name": "My Workspace",
-  "accounts_api_url": "https://accounts.toggl.com",
-  "focus_api_url": "https://focus.toggl.com",
-  "authenticated_at": "2025-01-15T10:00:00.000Z",
-  "workspaces": [...]
-}
-```
-
-### HTTP client (`@toggl/cli-core/focus-client`)
-
-The MCP package re-exports `FocusClient` from `@toggl/cli-core`. That client uses generated request functions from `@toggl/focus-queries` and `@toggl/queries` where available, and handles:
-
-- **Auth**: Resolves a fresh token via the token provider before each request (handles OAuth2 refresh transparently).
-- **Required headers**: Includes `X-Toggl-PostHog-Data: {"platform_origin":"web"}` on all requests — the Focus API rejects write operations without this header.
-- **Generated request execution**: Calls generated request helpers for Focus, org, and shared-data endpoints instead of hand-building paths in the MCP package.
-- **Validation**: Validates outgoing mutation payloads with generated Valibot schemas and soft-validates responses for typed callers.
-- **Error handling**: Returns a discriminated union (`ApiResponse<T>`) — callers check `.ok` before accessing `.data`.
-
-### Runtime design
-
-- **Entity tool handlers** are generated at startup from the shared `@toggl/operations` catalog.
-- **Input schemas** come from operation metadata; most payload schemas are generated Valibot schemas from query packages, with small hand-written wrappers for route IDs and curated list filters.
-- **Mutation gate** (`src/runtime/safety/mutation-gate.ts`) issues `confirm_token` values until the caller re-invokes the same mutating tool with that token.
-
-### Key Focus API concepts
-
-| Concept        | Description                                                                                                                      |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| **Task**       | Core work item. Has name, priority, status, project, assignees, dates, description, notes.                                       |
-| **Project**    | Groups tasks. Has name, color, dates, estimated time.                                                                            |
-| **Time Block** | A scheduled calendar slot for a task (planned time). Has start time + duration in seconds.                                       |
-| **Time Entry** | Actual tracked time. Created by start/stop tracking. Types: `activity` or `break`.                                               |
-| **Status**     | Workflow state (e.g. Todo, Doing, Done). Workspace-level, fetched from `/workspaces/{id}/statuses`.                              |
-| **User ID**    | `user_account_id` from the workspace API response. Used as `assignee_user_id` in tasks and for the `toggl_user_id` query filter. |
-
-### Maintenance model
-
-The intended maintenance direction is to keep MCP and CLI surfaces driven by generated API artifacts:
-
-1. Regenerate `@toggl/focus-queries` when the Focus API changes.
-2. Prefer generated request functions, generated Valibot payload schemas, and generated response schemas over hand-written HTTP/path/payload logic.
-3. Keep `@toggl/operations` as the curated exposure layer for now: it defines which generated endpoints become public CLI/MCP operations, plus safety flags, command grouping, descriptions, and examples.
-4. When exposing new endpoints, add operation metadata and `FocusClient` bindings only where the generated request layer cannot be consumed directly yet.
-
-Longer term, the main low-maintenance opportunity is generating the base operation catalog from querygen output and applying a small override map for visibility, safety, names, examples, and agent guidance.
-
-## MCP Apps (inline UI)
-
-Cursor **2.6+**, Claude Desktop, and other MCP App hosts can render **view tools** inline in chat. The stdio server is unchanged; view tools are additive alongside entity tools (`tasks`, `projects`, …).
-
-- **Resource**: `ui://toggl-focus/app.html` (single React iframe bundled with `@toggl/design-system`)
-- **When to use**: Prefer view tools when the user asks to **show**, **see**, or **visualize** Focus data. Use entity tools for mutations, scripting, and non-UI hosts.
-- **Refresh**: The iframe re-calls the **same** view tool via `app.callServerTool` — there are no separate `*-refresh` tools.
-
-### View tools
-
-| Tool                           | Use when                     |
-| ------------------------------ | ---------------------------- |
-| `focus-tasks-inbox`            | Task list / backlog          |
-| `focus-task-detail`            | Single task deep-dive        |
-| `focus-status-board`           | Kanban-style status snapshot |
-| `focus-projects-overview`      | Project list                 |
-| `focus-project-detail`         | Single project overview      |
-| `focus-milestones-roadmap`     | Milestones by due date       |
-| `focus-search-results`         | Search across entities       |
-| `focus-week-at-a-glance`       | Week plan vs tracked time    |
-| `focus-day-today`              | Today's schedule             |
-| `focus-time-log`               | Time entries table           |
-| `focus-time-blocks`            | Scheduled blocks             |
-| `focus-report-workload`        | Team workload / utilization  |
-| `focus-report-time-by-project` | Time grouped by project      |
-| `focus-report-time-by-member`  | Time grouped by member       |
-| `focus-report-billable`        | Billable summary             |
-| `focus-report-task-throughput` | Task completion throughput   |
-| `focus-team-roster`            | Workspace members            |
-| `focus-clients-directory`      | Client list                  |
-| `focus-time-off-calendar`      | Time off in range            |
-| `focus-holidays-calendar`      | Public holidays              |
-| `focus-mutation-review`        | Confirm pending mutation     |
-| `focus-dry-run-preview`        | Preview dry-run payload      |
-
-Hosts without MCP App support still receive the same JSON tool results as entity tools.
-
-### Adding a new entity action
-
-1. Regenerate `@toggl/focus-queries` if the endpoint or schema is new.
-2. Reuse the generated request function and Valibot schemas in `@toggl/cli-core` / `@toggl/operations`.
-3. Add or update operation metadata in `packages/operations/src`.
-4. Rebuild (`pnpm run build`) and update docs/skill guidance if the user-facing workflow changes.
-
-### Development
-
-```bash
-pnpm install         # Install dependencies
-pnpm run build       # Build MCP App iframe + compile TypeScript → build/
-pnpm run build:mcpb       # Node-based .mcpb (same as build:mcpb:node)
-pnpm run build:mcpb:binary -- --target darwin-arm64   # Binary .mcpb (requires Bun); targets: darwin-arm64, darwin-x64, linux-x64, win32-x64
-pnpm run lint        # Run Oxlint checks
-pnpm run lint:fix    # Auto-fix lint issues when possible
-node build/index.js auth   # (Re-)authenticate
-```
+One tool per domain (for example `tasks`, `projects`, `time-blocks`, `time-entries`, `organization`). Each tool accepts:
 
-Releases use [Changesets](https://github.com/changesets/changesets): run `pnpm run changeset` on a branch when you need a version bump, merge to `main`, and CI publishes to GitHub Packages when pending changesets exist.
+- **`action`** (required)
+- **`data`** (optional)
+- **`confirm_token`** (optional) — second step for mutating operations
+- **`dry_run`** (optional) — validates input without calling the API
 
-The project uses TypeScript with ES2022 target and Node16 module resolution. Output goes to `build/`. Package tests: `pnpm --filter @toggl/mcp test` (tool inventory invariants vs `@toggl/operations`).
+**Mutation confirmation:** mutating tools return `confirm_required` with a `confirm_token` on the first call; repeat with `confirm_token` to execute.
 
-### Publishing
+### Workspace, profiles, and auth
 
-CI publishes `@toggl/mcp` to [GitHub Packages](https://github.com/features/packages) when pending Changesets are merged to `main`.
+- **workspace-list** — list workspaces (`refresh: true` refetches from Accounts)
+- **workspace-switch** — set the active workspace
+- **profile-list**, **profile-switch**, **profile-remove** — manage `active.mcp` in `~/.toggl/focus-tools.json`
+- **auth**, **logout** — sign in or clear the active MCP profile
 
-The same publish workflow also cross-compiles **binary** MCP bundles with Bun and attaches, per platform:
+Agent-oriented guidance ships in `skills/toggl-mcp/SKILL.md` inside this package.
 
-- `toggl-focus-mcp-<version>-darwin-arm64.mcpb` (+ `.sha256`)
-- `toggl-focus-mcp-<version>-darwin-x64.mcpb` (+ `.sha256`)
-- `toggl-focus-mcp-<version>-linux-x64.mcpb` (+ `.sha256`)
-- `toggl-focus-mcp-<version>-win32-x64.mcpb` (+ `.sha256`)
+## License
 
-These assets are attached to the GitHub release tag `@toggl/mcp@<version>`.
+Proprietary Toggl software. See [LICENSE](LICENSE) and [Toggl legal terms](https://toggl.com/legal/).