@yakirmar/mcp-toggl 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Very Good Plugins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,268 @@
+# MCP Toggl
+
+> Talk to your time tracking. Pull reports, start timers, inspect desktop activity, and turn raw Toggl data into useful recaps from Claude or any MCP-compatible client.
+
+[![npm](https://img.shields.io/npm/v/@yakirmar/mcp-toggl)](https://www.npmjs.com/package/@yakirmar/mcp-toggl)
+[![MCP](https://img.shields.io/badge/MCP-server-blueviolet)](https://modelcontextprotocol.io)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Toggl API](https://img.shields.io/badge/Toggl-API%20v9-red)](https://developers.track.toggl.com/docs/)
+
+> **This is a fork** of [`@verygoodplugins/mcp-toggl`](https://github.com/verygoodplugins/mcp-toggl), published as `@yakirmar/mcp-toggl`. It adds full **write and cleanup** support for time entries — see [Fork Additions](#fork-additions).
+
+## Fork Additions
+
+Upstream can read entries and start/stop timers, but it cannot log past work or remove a mistaken entry. This fork adds three tools that close that loop:
+
+| Tool | Why it exists |
+| --- | --- |
+| `toggl_create_entry` | Log work you already did — a completed entry on a project or client, with a start time plus either an end time or a length in minutes. Upstream could only start a *running* timer. |
+| `toggl_search_entries` | Find entries (and, crucially, their `id`) by description, project name, client name, tag, time window, or duration. The `id` is what you need to delete something. |
+| `toggl_delete_entry` | Remove an entry by `id`. Pair with `toggl_search_entries` when you don't already know it. |
+
+Together these let you say things like *"log 2 hours on the Website project for yesterday's client call"* or *"find the duplicate standup entry from last week and delete it"*.
+
+**Timezone handling:** datetimes accept an explicit offset (`2026-07-11T09:00:00Z`, `...+03:00`) for an absolute time. Without an offset — including a bare `YYYY-MM-DD` — the time is interpreted in **the timezone of the machine running the server**.
+
+## See What Your Week Actually Looked Like
+
+> You ask: "Give me the recap of my week"
+
+The MCP server returns hydrated time entries with project, workspace, client, tag, and running-timer context. Your client can turn that into a readable recap:
+
+> 32.7 hours across 31 entries and 7 projects. Monday was a light planning day, Tuesday had the long implementation block, Wednesday stayed focused on one project, and Friday turned into a shipping run. The top project took 27% of the week, with two smaller projects close behind.
+
+![Weekly recap chart](docs/images/weekly-recap.svg)
+
+The server does not hard-code this prose or chart. It exposes structured Toggl data in a shape that makes synthesis easy.
+
+## Catch the Drift
+
+> You ask: "Did I actually work on what I said I worked on for that PR review entry?"
+
+`toggl_get_timeline` can compare a tracked entry boundary with Toggl Track Desktop activity:
+
+> The entry ran 1h 33m. About 67 minutes were in review tools, 5 minutes were scattered across chat apps, and the rest was idle or trimmed timeline space. The entry mostly checks out.
+
+![Drift detection chart](docs/images/drift-detection.svg)
+
+This is useful before invoicing, after long context-switching days, or whenever a vague entry like "admin" starts hiding too much Slack and browser time.
+
+## See Patterns Over Time
+
+> You ask: "Show me last month at a glance"
+
+Daily and weekly report tools make it straightforward for the client to render heatmaps, spot streaks, and surface intensity changes:
+
+![Monthly heatmap](docs/images/monthly-heatmap.svg)
+
+Toggl is still the source of truth. The MCP layer makes the data easier for an agent to inspect, summarize, and visualize.
+
+## Things You Can Ask
+
+```text
+What am I currently tracking?
+How much time did I spend on the website project this month?
+Start a timer for "PR review" on the Platform project
+Log 2 hours yesterday on the Website project for "client call"
+Find the entries I logged for "standup" last week
+Delete the duplicate entry I created this morning
+Show me yesterday's hours as a chart
+What apps did I use most today?
+Generate a daily report for last Friday
+Compare this week to last week by project
+Which day this month had the most billable work?
+```
+
+Chart prompts depend on your MCP client. The server returns the structured data; clients such as Claude decide how to render it.
+
+## What Makes This Useful
+
+**Hydrated responses**: time entries are enriched with `project_name`, `client_name`, `workspace_name`, `tag_names`, and normalized running-timer fields so the client does not need a second lookup for ordinary reporting.
+
+**Smart caching**: workspaces, projects, clients, tasks, and tags are cached after first read. `toggl_cache_stats` shows hits, misses, loaded entities, and hit rate.
+
+**Desktop activity timeline**: `toggl_get_timeline` summarizes app usage from Toggl Track Desktop and can return raw events when you need sequence analysis.
+
+**Privacy controls**: timeline calls support summary-only output with `include_events: false` and title redaction with `redact_titles: true`.
+
+**Period shortcuts**: `today`, `yesterday`, `week`, `lastWeek`, `month`, and `lastMonth` are supported on the tools where those periods make sense.
+
+**Recoverable errors**: workspace resolution errors include `available_workspaces`, and Toggl quota/rate-limit errors include structured retry hints.
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js `^20.19.0` or `>=22.12.0`
+- A Toggl Track account
+- Your Toggl API token from [track.toggl.com/profile](https://track.toggl.com/profile)
+
+### Claude Desktop
+
+Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-toggl": {
+      "command": "npx",
+      "args": ["-y", "@yakirmar/mcp-toggl@latest"],
+      "env": {
+        "TOGGL_API_KEY": "your_api_key_here",
+        "TOGGL_DEFAULT_WORKSPACE_ID": "123456"
+      }
+    }
+  }
+}
+```
+
+`TOGGL_DEFAULT_WORKSPACE_ID` is optional. If you have exactly one Toggl workspace, the server can resolve it automatically. If you have multiple workspaces and do not set a default, workspace-scoped tools return the available workspace IDs so the client can retry with `workspace_id`.
+
+Restart Claude Desktop, then ask:
+
+```text
+What am I currently tracking?
+```
+
+### Global Install
+
+```bash
+npm install -g @yakirmar/mcp-toggl
+mcp-toggl --help
+```
+
+## Tools
+
+### Reports and Insights
+
+| Tool | What it does |
+| --- | --- |
+| `toggl_daily_report` | Hours by project and workspace for a date. Use `format: "text"` for display text or `"json"` for structured output. |
+| `toggl_weekly_report` | 7-day breakdown with daily totals and project rollups. Use `week_offset: -1` for last week. |
+| `toggl_get_time_entries` | Raw hydrated entries by period, date range, workspace, or project. |
+| `toggl_get_timeline` | Toggl Track Desktop app usage summary with optional raw events. |
+
+### Timer Control
+
+| Tool | What it does |
+| --- | --- |
+| `toggl_get_current_entry` | Returns the running timer, elapsed seconds, and hydrated project/workspace context. |
+| `toggl_start_timer` | Starts a timer with description, optional project/task, and tags. |
+| `toggl_stop_timer` | Stops the currently running timer. |
+
+### Entry Management
+
+Added by this fork. See [Fork Additions](#fork-additions).
+
+| Tool | What it does |
+| --- | --- |
+| `toggl_create_entry` | Creates a completed (past) entry. Takes `start` plus exactly one of `end` or `duration_minutes`, with optional `description`, `project_id`, `client_id`, `task_id`, `tags`, and `billable`. |
+| `toggl_search_entries` | Searches entries and returns matches **with their `id`**. Filters combine with AND and include `description`, `project_name`, `client_name`, `tag`, `project_id`, `client_id`, `workspace_id`, `billable`, `start_after`/`start_before`, and `min_duration_minutes`/`max_duration_minutes`. |
+| `toggl_delete_entry` | Deletes an entry by `time_entry_id`. `workspace_id` is optional — it is resolved from the entry when omitted. Irreversible. |
+
+**Attaching to a project or client:** Toggl attaches entries to a *project*, not a client directly. If you pass a `client_id` without a `project_id`, the client must have exactly one project (it is resolved for you); when a client has several projects, the tool returns the candidates and asks for a `project_id`.
+
+**Searching:** the date window defaults to roughly the last 31 days. Widen it with `period` (`today`, `week`, `lastMonth`, …) or explicit `start_date`/`end_date`. Results are hydrated with names and sorted newest-first (`limit` defaults to 50, max 1000).
+
+### Lookups
+
+| Tool | What it does |
+| --- | --- |
+| `toggl_check_auth` | Verifies token access and lists available workspaces without exposing the token. |
+| `toggl_list_workspaces` | Lists all accessible workspaces. |
+| `toggl_list_projects` | Lists projects for a workspace using cache-backed reads after first fetch. |
+| `toggl_list_clients` | Lists clients for a workspace using cache-backed reads after first fetch. |
+
+### Cache Management
+
+| Tool | What it does |
+| --- | --- |
+| `toggl_warm_cache` | Pre-fetches workspace, project, client, and tag data before a heavy reporting session. |
+| `toggl_cache_stats` | Returns hits, misses, hit rate, loaded entity counts, and warm-cache state. |
+| `toggl_clear_cache` | Clears cached data. Useful after creating or renaming Toggl entities. |
+
+### Summaries
+
+| Tool | What it does |
+| --- | --- |
+| `toggl_project_summary` | Total hours per project for a period or date range. |
+| `toggl_workspace_summary` | Total hours per workspace for a period or date range. |
+
+## Timeline Privacy
+
+Toggl Track Desktop activity can include window titles. Those titles may contain document names, email subjects, chat text, URLs, OAuth pages, or database names.
+
+Summary-only mode returns app totals without raw events:
+
+```json
+{
+  "period": "today",
+  "include_events": false
+}
+```
+
+Events with redacted titles preserve sequence and duration but remove titles:
+
+```json
+{
+  "period": "today",
+  "redact_titles": true,
+  "limit": 50
+}
+```
+
+Full event mode is the default:
+
+```json
+{
+  "period": "today"
+}
+```
+
+When in doubt, use `include_events: false`.
+
+## Configuration Reference
+
+| Env var | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `TOGGL_API_KEY` | Yes | - | Preferred env var for your Toggl API token. |
+| `TOGGL_API_TOKEN` | No | - | Supported alias for backwards compatibility. `TOGGL_API_KEY` is preferred. |
+| `TOGGL_TOKEN` | No | - | Supported alias for backwards compatibility. `TOGGL_API_KEY` is preferred. |
+| `TOGGL_DEFAULT_WORKSPACE_ID` | No | - | Used when a tool requires a workspace and none is passed. |
+| `TOGGL_CACHE_TTL` | No | `3600000` | Cache TTL in milliseconds. Default is 1 hour. |
+| `TOGGL_CACHE_SIZE` | No | `1000` | Maximum cached entity budget. |
+| `TOGGL_BATCH_SIZE` | No | `100` | Batch size used by API pagination helpers. |
+
+## Caveats
+
+**Toggl rate limits and quotas**: Toggl may return rate-limit or quota errors during chatty sessions. The server returns structured retry information when Toggl provides it. Warm the cache before large reporting sessions to avoid repeated project/client/tag fetches.
+
+**Running timer duration**: Toggl uses negative duration values for running entries. Read `running` and `elapsed_seconds` from the hydrated response instead.
+
+**Timeline availability**: `toggl_get_timeline` requires Toggl Track Desktop timeline sync. If it is not enabled or has not uploaded data yet, the tool returns `enabled: false` with setup guidance.
+
+**Timeline totals**: `limit` only limits returned raw events. `summary`, `total_seconds`, and `total_hours` are calculated from all matching events.
+
+## Local Development
+
+```bash
+git clone https://github.com/yakirmar/mcp-toggl.git
+cd mcp-toggl
+npm install
+npm run build
+npm test
+```
+
+Useful commands:
+
+```bash
+npm run dev
+npm run lint
+npm run format
+```
+
+## License
+
+MIT.
+
+Originally built by [Very Good Plugins](https://verygoodplugins.com). This fork is maintained at [yakirmar/mcp-toggl](https://github.com/yakirmar/mcp-toggl).

package/dist/cache-manager.d.ts

@@ -0,0 +1,43 @@
+import type { Workspace, Project, Client, Task, User, Tag, TimeEntry, HydratedTimeEntry, CacheStats, CacheConfig } from './types.js';
+export declare class CacheManager {
+    private workspaces;
+    private projects;
+    private clients;
+    private tasks;
+    private users;
+    private tags;
+    private workspaceList;
+    private projectsByWorkspace;
+    private clientsByWorkspace;
+    private tagsByWorkspace;
+    private stats;
+    private config;
+    private api;
+    constructor(config: CacheConfig);
+    setAPI(api: any): void;
+    private isValid;
+    private getCached;
+    private getCachedCollection;
+    private cacheBucketLimit;
+    private setCached;
+    private setCachedCollection;
+    private setWorkspaceList;
+    getWorkspace(id: number | undefined): Promise<Workspace | null>;
+    getWorkspaces(): Promise<Workspace[]>;
+    getProject(id: number, workspaceId?: number): Promise<Project | null>;
+    getProjects(workspaceId: number): Promise<Project[]>;
+    getClient(id: number, workspaceId?: number): Promise<Client | null>;
+    getClients(workspaceId: number): Promise<Client[]>;
+    getTask(id: number, workspaceId: number, projectId: number): Promise<Task | null>;
+    getTasks(workspaceId: number, projectId: number): Promise<Task[]>;
+    getUser(id: number): Promise<User | null>;
+    getTag(id: number, workspaceId: number): Promise<Tag | null>;
+    getTags(workspaceId: number): Promise<Tag[]>;
+    warmCache(workspaceId?: number): Promise<void>;
+    private normalizeTimeEntry;
+    hydrateTimeEntries(entries: TimeEntry[]): Promise<HydratedTimeEntry[]>;
+    clearCache(): void;
+    getStats(): CacheStats;
+    pruneExpired(): void;
+}
+//# sourceMappingURL=cache-manager.d.ts.map

package/dist/cache-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../src/cache-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,OAAO,EACP,MAAM,EACN,IAAI,EACJ,IAAI,EACJ,GAAG,EACH,SAAS,EACT,iBAAiB,EAEjB,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,qBAAa,YAAY;IACvB,OAAO,CAAC,UAAU,CAAiD;IACnE,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,IAAI,CAA2C;IACvD,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,mBAAmB,CAAiD;IAC5E,OAAO,CAAC,kBAAkB,CAAgD;IAC1E,OAAO,CAAC,eAAe,CAA6C;IAGpE,OAAO,CAAC,KAAK,CAIX;IAEF,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,GAAG,CAAM;gBAEL,MAAM,EAAE,WAAW;IAI/B,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI;IAKtB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,gBAAgB;IAYlB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAmB/D,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAqBrC,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAuBrE,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAqBpD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAuBnE,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAqBlD,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAkBjF,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAiBjE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAmBzC,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAe5D,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAqB5C,SAAS,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6BpD,OAAO,CAAC,kBAAkB;IA0BpB,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAsD5E,UAAU,IAAI,IAAI;IAmBlB,QAAQ,IAAI,UAAU;IAetB,YAAY,IAAI,IAAI;CAmCrB"}