viviscape-mcp 2.8.0 → 2.9.0

package/README.md

@@ -1,200 +1,203 @@
-# viviscape-mcp
-
-MCP server for the [ViviScape](https://viviscape.io) API - exposes CRM, projects, companies, tasks, time tracking, notes, and insights as tools for Claude and other MCP clients.
-
-## Installation
-
-No install needed - run via `npx`:
-
-```bash
-npx viviscape-mcp
-```
-
-Or install globally:
-
-```bash
-npm install -g viviscape-mcp
-```
-
-## Sign in
-
-Authentication is per-user, the same browser flow the ViviScape CLI uses - no
-API keys. Sign in once:
-
-```bash
-npx viviscape-mcp login
-```
-
-A browser tab opens on ViviScape Work; confirm **Allow access** and the session
-is stored in Windows Credential Manager (or `~/.viviscape/mcp-credentials.json`
-on macOS/Linux). Every tool call then runs as *you*: your user id, account,
-role, and plan come from the session, so tools see exactly the data you can see
-in the app.
-
-```bash
-npx viviscape-mcp status    # who am I, which account, role, plan
-npx viviscape-mcp logout    # clear the stored session
-```
-
-If you already ran `vs auth login` with the [ViviScape CLI](https://viviscape.io),
-that session is picked up automatically. Inside an MCP client you can also call
-the `auth_login`, `auth_status`, and `auth_logout` tools. Sessions expire; when
-one does, tools report it and you re-run `login`.
-
-## Configuration
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `VIVISCAPE_BASE_URL` | no | `https://work.viviscape.io` | ViviScape Work base URL |
-
-## Claude Desktop / Claude Code
-
-Add to your MCP client config (e.g. `claude_desktop_config.json` or `.mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "viviscape": {
-      "command": "npx",
-      "args": ["-y", "viviscape-mcp"]
-    }
-  }
-}
-```
-
-## OpenAI Codex CLI
-
-Codex accepts stdio MCP servers directly. Add to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.viviscape]
-command = "npx"
-args = ["-y", "viviscape-mcp"]
-```
-
-## ChatGPT (Developer Mode / Apps SDK)
-
-ChatGPT only accepts **remote HTTP** MCP servers - it does not run local stdio
-processes. Bridge this server to an HTTP endpoint with
-[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) or
-[`supergateway`](https://www.npmjs.com/package/supergateway), then expose it
-publicly (Cloudflare Tunnel, ngrok, or deploy to a host).
-
-Example with `supergateway`:
-
-```bash
-npx viviscape-mcp login   # once, on the host running the gateway
-npx -y supergateway --stdio "npx -y viviscape-mcp" --port 8000
-```
-
-The gateway shares the host's stored session, so everyone reaching that endpoint
-acts as the signed-in user - put your own auth in front of it.
-
-Expose `http://localhost:8000/sse` publicly, then in ChatGPT:
-
-**Settings -> Connectors -> Create -> Custom MCP server**
-- **URL:** `https://your-public-host/sse`
-- **Auth:** none (or bearer, depending on your gateway)
-
-## Tools
-
-The server exposes tools across these domains:
-
-- **Prospects** - `prospect_add`, `prospect_get`, `prospect_update`, `prospect_query`, follow-ups, notes
-- **Clients** - `client_add`, `client_get`, `client_get_by_email`, `clients_by_company`
-- **Companies** - `company_add`, `company_list`, `company_update`
-- **Projects** - `project_get`, `project_list`, `project_list_active`, `project_staff`, `project_tasks`, `projects_by_company`
-- **Tasks** - `task_add`, `task_get`, `task_update`, `tasks_open`, `tasks_pending`, `tasks_by_company`, `tasks_by_milestone`
-- **Task comments** - `task_comments`, `task_comment_get`, `task_comment_add`, `task_comment_update`, `task_comment_remove`, `task_mark_read`
-- **Task assignment** - `task_assignee_add`, `task_assignee_remove`, `task_set_leader`, `task_set_attention`, `task_delete`, `task_merge`
-- **Task tags** - `task_tags` (list/add/remove), `tasks_by_tag` (tasks carrying a label, or the account tag vocabulary), and a `tags` list on `task_add`
-- **Task references** - `task_references` (list/add/remove), `task_search` (find a task by keyword or id)
-- **Milestones** - `milestone_list`, `milestones_active`, `milestones_by_company`, `milestones_by_user`, `milestone_get`, `milestone_add`, `milestone_update`, `milestone_clone`, `milestone_remove`
-- **Project writes** - `project_add`, `project_update`, `project_set_status`, `project_user_add`, `project_user_remove`
-- **Reference** - `enums` (the status, priority, and group-type values the platform accepts)
-- **Lookup** - `services` (resolve service_id to a name), `user_lookup` (id, email, team, groups)
-- **Bulk** - `tasks_bulk_add` (many tasks in one request)
-- **Time logs** - `timelog_add`, `timelog_update`
-- **Notes** - `note_add`, `note_get`, `note_update`, `note_remove`, `notes_mine`, `notes_query`, `notes_account`, `note_revisions`
+# viviscape-mcp
+
+MCP server for the [ViviScape](https://viviscape.io) API - exposes CRM, projects, companies, tasks, time tracking, notes, and insights as tools for Claude and other MCP clients.
+
+## Installation
+
+No install needed - run via `npx`:
+
+```bash
+npx viviscape-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g viviscape-mcp
+```
+
+## Sign in
+
+Authentication is per-user, the same browser flow the ViviScape CLI uses - no
+API keys. Sign in once:
+
+```bash
+npx viviscape-mcp login
+```
+
+A browser tab opens on ViviScape Work; confirm **Allow access** and the session
+is stored in Windows Credential Manager (or `~/.viviscape/mcp-credentials.json`
+on macOS/Linux). Every tool call then runs as *you*: your user id, account,
+role, and plan come from the session, so tools see exactly the data you can see
+in the app.
+
+```bash
+npx viviscape-mcp status    # who am I, which account, role, plan
+npx viviscape-mcp logout    # clear the stored session
+```
+
+If you already ran `vs auth login` with the [ViviScape CLI](https://viviscape.io),
+that session is picked up automatically. Inside an MCP client you can also call
+the `auth_login`, `auth_status`, and `auth_logout` tools. Sessions expire; when
+one does, tools report it and you re-run `login`.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VIVISCAPE_BASE_URL` | no | `https://work.viviscape.io` | ViviScape Work base URL |
+
+## Claude Desktop / Claude Code
+
+Add to your MCP client config (e.g. `claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "viviscape": {
+      "command": "npx",
+      "args": ["-y", "viviscape-mcp"]
+    }
+  }
+}
+```
+
+## OpenAI Codex CLI
+
+Codex accepts stdio MCP servers directly. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.viviscape]
+command = "npx"
+args = ["-y", "viviscape-mcp"]
+```
+
+## ChatGPT (Developer Mode / Apps SDK)
+
+ChatGPT only accepts **remote HTTP** MCP servers - it does not run local stdio
+processes. Bridge this server to an HTTP endpoint with
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) or
+[`supergateway`](https://www.npmjs.com/package/supergateway), then expose it
+publicly (Cloudflare Tunnel, ngrok, or deploy to a host).
+
+Example with `supergateway`:
+
+```bash
+npx viviscape-mcp login   # once, on the host running the gateway
+npx -y supergateway --stdio "npx -y viviscape-mcp" --port 8000
+```
+
+The gateway shares the host's stored session, so everyone reaching that endpoint
+acts as the signed-in user - put your own auth in front of it.
+
+Expose `http://localhost:8000/sse` publicly, then in ChatGPT:
+
+**Settings -> Connectors -> Create -> Custom MCP server**
+- **URL:** `https://your-public-host/sse`
+- **Auth:** none (or bearer, depending on your gateway)
+
+## Tools
+
+The server exposes tools across these domains:
+
+- **Prospects** - `prospect_add`, `prospect_get`, `prospect_update`, `prospect_query`, follow-ups, notes
+- **Clients** - `client_add`, `client_get`, `client_get_by_email`, `clients_by_company`
+- **Companies** - `company_add`, `company_list`, `company_update`
+- **Projects** - `project_get`, `project_list`, `project_list_active`, `project_staff`, `project_tasks`, `projects_by_company`
+- **Tasks** - `task_add`, `task_get`, `task_update`, `tasks_open`, `tasks_pending`, `tasks_by_company`, `tasks_by_milestone`
+- **Task comments** - `task_comments`, `task_comment_get`, `task_comment_add`, `task_comment_update`, `task_comment_remove`, `task_mark_read`
+- **Task assignment** - `task_assignee_add`, `task_assignee_remove`, `task_set_leader`, `task_set_attention`, `task_delete`, `task_merge`, `task_complete`
+- **Task tags** - `task_tags` (list/add/remove), `tasks_by_tag` (tasks carrying a label, or the account tag vocabulary), and a `tags` list on `task_add`
+- **Task references** - `task_references` (list/add/remove), `task_search` (find a task by keyword or id)
+- **Milestones** - `milestone_list`, `milestones_active`, `milestones_by_company`, `milestones_by_user`, `milestone_get`, `milestone_add`, `milestone_update`, `milestone_clone`, `milestone_remove`
+- **Project writes** - `project_add`, `project_update`, `project_set_status`, `project_user_add`, `project_user_remove`
+- **Reference** - `enums` (the status, priority, and group-type values the platform accepts)
+- **Lookup** - `services` (resolve service_id to a name), `user_lookup` (id, email, team, groups)
+- **Bulk** - `tasks_bulk_add` (many tasks in one request)
+- **Time logs** - `timelog_add`, `timelog_update`, `task_log_time` (quick log against a task, or a note-only entry)
+- **Personal logs** - `personal_logs`, `personal_log_add`, `personal_log_remove` (service work that belongs to no task)
+- **Time clock** - `timeclock_punch` (in/out), `timeclock_history`
+- **Tickets** - `tickets_list` (the open, closed, or complete ticket queue; enterprise plan)
+- **Notes** - `note_add`, `note_get`, `note_update`, `note_remove`, `notes_mine`, `notes_query`, `notes_account`, `note_revisions`
 - **Second Brain** - `kb_search` (semantic search over tickets, plans, notes, products, resolutions and SOPs), `kb_sop` (list/get/save an SOP), `kb_status`, `kb_reindex`
-- **Note filing** - `note_companies`, `note_users`, `note_tags`, `note_attachments`, `notebook`, `notebook_users` (each takes an `action`)
-- **Files** - `project_files` (list/upload/update/delete/download), `task_files`
-- **Insights** - hours by person/service/project, AI summary, person stats, time totals
-- **Account** - `account_info`, `account_services`, `account_users`
-- **Auth** - `auth_login`, `auth_status`, `auth_logout`
-
-### Status and priority values
-
-Use the `enums` tool rather than guessing. The platform's vocabularies are:
-
-| field | values |
-|---|---|
-| task status | backlog, new, research, discussion, inprogress, pendingreview, inreview, testing, waitingcustomer, waitingteammember, onhold, cancelled, completed |
-| priority | low, moderate, important, urgent, critical |
-| project status | new, inprogress, complete |
-| prospect status | new, firstcontact, negotiation, pending, won, lost, spam |
-
-Two traps: tasks complete as `completed` while projects complete as
-`complete`, and priority is *not* low/medium/high. Task and project tools
-validate these with `z.enum`, so an invalid value is rejected before it reaches
-the API.
-
-### Task tags
-
-`task_tags` lists, adds, and removes the tags shown on the task board, and
-`task_add` takes a `tags` list so a generated task lands already categorised
-(handy for marking agent-written work).
-
-Verified behaviour, so callers do not have to discover it:
-
-- Labels are stored upper-case, and `add` is idempotent per label - re-adding
-  one returns the existing tag, not a duplicate.
-- `add` returns the persisted tag with its `tag_id`; `remove` takes that
-  `tag_id`, not the label, and answers `true` (unlike `note_tags`, whose remove
-  answers `false` even on success).
-- `color` is any hex string, defaulting to the board palette's first entry
-  (`#00325e`).
-- `task_tags` is per task, and list rows from `tasks_open` / `project_tasks`
-  carry `tags: null`, so read one task's tags with `task_tags` or `task_get`.
-- `tasks_by_tag` goes the other way, from a label to the tasks carrying it.
-  Labels match trimmed and case insensitively; `match: "any"` (default) returns
-  a task carrying at least one label, `match: "all"` only tasks carrying every
-  one. An optional `status` list narrows further. Hits are light rows that
-  carry the task's whole tag set, so the other labels arrive with the hit.
-  Called with no `tags`, it returns the account's tag vocabulary instead -
-  every distinct label with the number of tasks using it.
-- A tag failure inside `task_add` never fails the create: the task is returned
-  with the per-tag error recorded in its `tags` array.
-
-### Task references
-
-`task_references` links related tasks to each other - a duplicate, a blocker,
-the ticket a task came from - and `task_search` finds the id to link when only
-a keyword is known.
-
-Verified behaviour:
-
-- Links are **symmetric**. Adding A to B makes the pair visible from both
-  tasks, so link once; mirroring it by hand just returns the same row.
-- `list` rows describe the *other* task: `related_task_id` plus its title,
-  status, project and company, so a reference list needs no follow-up
-  `task_get`.
-- `add` is idempotent per pair (in either direction) and returns the persisted
-  link with its `reference_id`; `remove` takes that `reference_id`, not a task
-  id, and answers `true`.
-- Both tasks must belong to the signed-in account; a cross-account id comes
-  back as an empty link rather than an error.
-- `task_search` matches the task title, the description, and - for a numeric
-  query - the task id itself. It covers tickets too, so it is the one keyword
-  route that reaches ticket rows `tasks_open` never returns.
-
-### Task notes
-
-`task_update` takes a `notes` field: the free-form working notes on the task's
-Overview tab, stored as HTML by the rich-text editor. It **replaces** the field
-outright, so read the current value with `task_get` and send the merged text
-rather than only the new lines.
-
+- **Note filing** - `note_companies`, `note_users`, `note_tags`, `note_attachments`, `notebook`, `notebook_users` (each takes an `action`)
+- **Files** - `project_files` (list/upload/update/delete/download), `task_files`
+- **Insights** - hours by person/service/project, AI summary, person stats, time totals
+- **Account** - `account_info`, `account_services`, `account_users`
+- **Auth** - `auth_login`, `auth_status`, `auth_logout`
+
+### Status and priority values
+
+Use the `enums` tool rather than guessing. The platform's vocabularies are:
+
+| field | values |
+|---|---|
+| task status | backlog, new, research, discussion, inprogress, pendingreview, inreview, testing, waitingcustomer, waitingteammember, onhold, cancelled, completed |
+| priority | low, moderate, important, urgent, critical |
+| project status | new, inprogress, complete |
+| prospect status | new, firstcontact, negotiation, pending, won, lost, spam |
+
+Two traps: tasks complete as `completed` while projects complete as
+`complete`, and priority is *not* low/medium/high. Task and project tools
+validate these with `z.enum`, so an invalid value is rejected before it reaches
+the API.
+
+### Task tags
+
+`task_tags` lists, adds, and removes the tags shown on the task board, and
+`task_add` takes a `tags` list so a generated task lands already categorised
+(handy for marking agent-written work).
+
+Verified behaviour, so callers do not have to discover it:
+
+- Labels are stored upper-case, and `add` is idempotent per label - re-adding
+  one returns the existing tag, not a duplicate.
+- `add` returns the persisted tag with its `tag_id`; `remove` takes that
+  `tag_id`, not the label, and answers `true` (unlike `note_tags`, whose remove
+  answers `false` even on success).
+- `color` is any hex string, defaulting to the board palette's first entry
+  (`#00325e`).
+- `task_tags` is per task, and list rows from `tasks_open` / `project_tasks`
+  carry `tags: null`, so read one task's tags with `task_tags` or `task_get`.
+- `tasks_by_tag` goes the other way, from a label to the tasks carrying it.
+  Labels match trimmed and case insensitively; `match: "any"` (default) returns
+  a task carrying at least one label, `match: "all"` only tasks carrying every
+  one. An optional `status` list narrows further. Hits are light rows that
+  carry the task's whole tag set, so the other labels arrive with the hit.
+  Called with no `tags`, it returns the account's tag vocabulary instead -
+  every distinct label with the number of tasks using it.
+- A tag failure inside `task_add` never fails the create: the task is returned
+  with the per-tag error recorded in its `tags` array.
+
+### Task references
+
+`task_references` links related tasks to each other - a duplicate, a blocker,
+the ticket a task came from - and `task_search` finds the id to link when only
+a keyword is known.
+
+Verified behaviour:
+
+- Links are **symmetric**. Adding A to B makes the pair visible from both
+  tasks, so link once; mirroring it by hand just returns the same row.
+- `list` rows describe the *other* task: `related_task_id` plus its title,
+  status, project and company, so a reference list needs no follow-up
+  `task_get`.
+- `add` is idempotent per pair (in either direction) and returns the persisted
+  link with its `reference_id`; `remove` takes that `reference_id`, not a task
+  id, and answers `true`.
+- Both tasks must belong to the signed-in account; a cross-account id comes
+  back as an empty link rather than an error.
+- `task_search` matches the task title, the description, and - for a numeric
+  query - the task id itself. It covers tickets too, so it is the one keyword
+  route that reaches ticket rows `tasks_open` never returns.
+
+### Task notes
+
+`task_update` takes a `notes` field: the free-form working notes on the task's
+Overview tab, stored as HTML by the rich-text editor. It **replaces** the field
+outright, so read the current value with `task_get` and send the merged text
+rather than only the new lines.
+
 ### Task plans
 
 `task_add` and `task_update` take a `plan` field: the plan of action for the
@@ -231,60 +234,61 @@ knowledge an agent authors directly, so `kb_sop` save is how a lesson from one
 ticket becomes reusable — search `source_types: ["sop"]` first and update the
 existing SOP rather than filing a near-duplicate.
 
-### Repeat-safe creates
-
-No create route accepts an idempotency key, so a retried agent step silently
-creates a second record. `task_add`, `note_add`, `timelog_add`,
-`prospect_add`, and `tasks_bulk_add` accept an optional
-`idempotency_key`: calling again with the same key replays the first result
-instead of writing again.
-
-The record is local (`~/.viviscape/mcp-idempotency.json`, 7-day expiry), so it
-stops the common case -- the same agent retrying the same step -- and does not
-make the server idempotent. Two machines running the same plan will still
-duplicate.
-
-### Delta queries
-
-List tools accept `updated_since` (ISO 8601) and return only rows touched at
-or after that time, so a recurring agent does not re-read the whole working set.
-It is filtered in-process (no list route supports a modified-since filter), and
-rows carrying no usable timestamp are kept rather than dropped.
-
-### Paging and field selection
-
-List tools (`tasks_open`, `project_list_active`, `project_tasks`, and the rest)
-return a page of trimmed rows rather than every column of every row. A task row
-carries ~94 columns and a project row 87, most of them irrelevant to project
-work, so each list tool accepts:
-
-- `fields` - columns to return; omit for a curated default, or pass `["all"]`
-- `limit` / `offset` - page window, default 50 rows
-
-Task rows also carry computed `due_date`, `due_in_days` (negative when
-overdue), and `overdue`, derived from the task's `end` date. Read those rather
-than the API's `deadline` string, which does not track the due date -- it
-reported "In 2 Days" for a task 39 days overdue. `deadline` is excluded from the
-default field set; ask for it explicitly if you need to see what the UI shows.
-
-Responses are wrapped as `{ total, returned, offset, next_offset, fields, items }`
-so a caller can tell when more rows exist. Task lists also accept
-`company_id`, `project_id`, `assignee_id`, `status`, `priority`,
-`due_before`, `due_after`, and `search`; `tasks_open` pushes `company_id`
-and `only_mine` to the server and filters the rest in-process.
-
-In practice this took `tasks_open` from 97 KB to 6.4 KB and
-`project_list_active` from 375 KB to 19 KB.
-
-## Development
-
-```bash
-npm install
-npm run dev      # run with tsx, hot reload
-npm run build    # compile to dist/
-npm start        # run compiled
-```
-
-## License
-
-MIT
+### Repeat-safe creates
+
+No create route accepts an idempotency key, so a retried agent step silently
+creates a second record. `task_add`, `note_add`, `timelog_add`,
+`task_log_time`, `personal_log_add`, `timeclock_punch`, `task_complete`,
+`prospect_add`, and `tasks_bulk_add` accept an optional
+`idempotency_key`: calling again with the same key replays the first result
+instead of writing again.
+
+The record is local (`~/.viviscape/mcp-idempotency.json`, 7-day expiry), so it
+stops the common case -- the same agent retrying the same step -- and does not
+make the server idempotent. Two machines running the same plan will still
+duplicate.
+
+### Delta queries
+
+List tools accept `updated_since` (ISO 8601) and return only rows touched at
+or after that time, so a recurring agent does not re-read the whole working set.
+It is filtered in-process (no list route supports a modified-since filter), and
+rows carrying no usable timestamp are kept rather than dropped.
+
+### Paging and field selection
+
+List tools (`tasks_open`, `project_list_active`, `project_tasks`, and the rest)
+return a page of trimmed rows rather than every column of every row. A task row
+carries ~94 columns and a project row 87, most of them irrelevant to project
+work, so each list tool accepts:
+
+- `fields` - columns to return; omit for a curated default, or pass `["all"]`
+- `limit` / `offset` - page window, default 50 rows
+
+Task rows also carry computed `due_date`, `due_in_days` (negative when
+overdue), and `overdue`, derived from the task's `end` date. Read those rather
+than the API's `deadline` string, which does not track the due date -- it
+reported "In 2 Days" for a task 39 days overdue. `deadline` is excluded from the
+default field set; ask for it explicitly if you need to see what the UI shows.
+
+Responses are wrapped as `{ total, returned, offset, next_offset, fields, items }`
+so a caller can tell when more rows exist. Task lists also accept
+`company_id`, `project_id`, `assignee_id`, `status`, `priority`,
+`due_before`, `due_after`, and `search`; `tasks_open` pushes `company_id`
+and `only_mine` to the server and filters the rest in-process.
+
+In practice this took `tasks_open` from 97 KB to 6.4 KB and
+`project_list_active` from 375 KB to 19 KB.
+
+## Development
+
+```bash
+npm install
+npm run dev      # run with tsx, hot reload
+npm run build    # compile to dist/
+npm start        # run compiled
+```
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -153,6 +153,25 @@ export declare class ViviScapeClient {
     deleteTask(taskId: number): Promise<unknown>;
     /** Fold one task into another; the source task is consumed. */
     mergeTasks(fromTaskId: number, toTaskId: number): Promise<unknown>;
+    /**
+     * Close a task through the platform's completion route (what `vs tasks done`
+     * calls). This is not the same as posting status "completed": the route also
+     * stamps the completing user and runs the milestone/progress rollup the task
+     * board relies on.
+     */
+    completeTask(taskId: number, userId?: number): Promise<unknown>;
+    /**
+     * The ticket queue, filtered server-side by status set, company and team --
+     * the view behind `vs tickets list`. Closed tickets live on their own route.
+     * Tickets are Group_Tasks, so the rows are task rows and task_get reads one.
+     */
+    lookupTickets(opts?: {
+        status?: 'open' | 'closed' | 'all';
+        statuses?: string[];
+        query?: string;
+        company_id?: number;
+        team?: string;
+    }): Promise<unknown>;
     getTaskTags(taskId: number): Promise<unknown>;
     /**
      * Tag a task. The web app upper-cases the label and always sends a colour, so
@@ -209,6 +228,39 @@ export declare class ViviScapeClient {
     removeMilestone(milestoneId: number): Promise<unknown>;
     addTimeLog(data: Record<string, unknown>): Promise<unknown>;
     updateTimeLog(data: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Log time against a task the short way (`vs tasks log`). The quick route
+     * fills group_id and service_id from the task itself, so only the note, the
+     * duration and the date are needed. A zero duration posts a note-only entry:
+     * it lands on the task's time feed without adding hours.
+     */
+    quickLogTime(data: {
+        task_id: number;
+        note: string;
+        duration?: string;
+        log_date?: string;
+        billable?: boolean;
+    }): Promise<unknown>;
+    /** Personal (non-task) time logs for a user -- the `vs logs list` feed. */
+    getPersonalLogs(userId?: number): Promise<unknown>;
+    /**
+     * Add a personal time log: work that belongs to a service rather than to any
+     * task. start_date and end_date mirror log_date, which is what the web form
+     * posts for a single-day entry.
+     */
+    addPersonalLog(data: {
+        note: string;
+        duration?: string;
+        service_id?: number;
+        log_date?: string;
+    }): Promise<unknown>;
+    removePersonalLog(logId: number | string): Promise<unknown>;
+    /**
+     * Punch the time clock. type "in" opens a punch, "out" closes the open one;
+     * both go to the same route with clocked_in set accordingly.
+     */
+    addPunch(type: 'in' | 'out', note?: string): Promise<unknown>;
+    getPunchHistory(userId?: number): Promise<unknown>;
     getMyNotes(): Promise<unknown>;
     getNoteById(noteId: number | string): Promise<unknown>;
     addNote(data: Record<string, unknown>): Promise<unknown>;

package/dist/api-client.js

@@ -50,6 +50,46 @@ function parseShorthandDuration(input) {
     const mm = String(minutes).padStart(2, '0');
     return { duration: `${hh}:${mm}:00`, log_time: raw };
 }
+/**
+ * Total minutes from shorthand ("1h30m", "45m", "2h", "90"). Used by the quick
+ * log and personal log routes, which want human text ("1h 30m") rather than the
+ * HH:MM:SS TimeSpan the full LOG_Time payload carries.
+ */
+function shorthandToMinutes(input) {
+    const raw = String(input ?? '').trim();
+    if (!raw)
+        return 0;
+    const clock = raw.match(/^(\d{1,2}):(\d{2})(?::\d{2})?$/);
+    if (clock)
+        return parseInt(clock[1], 10) * 60 + parseInt(clock[2], 10);
+    const hMatch = raw.match(/(\d+(?:\.\d+)?)\s*h/i);
+    const mMatch = raw.match(/(\d+)\s*m/i);
+    if (!hMatch && !mMatch) {
+        const bare = Number(raw);
+        return Number.isFinite(bare) ? Math.round(bare) : 0;
+    }
+    const hours = hMatch ? parseFloat(hMatch[1]) : 0;
+    const minutes = mMatch ? parseInt(mMatch[1], 10) : 0;
+    return Math.round(hours * 60) + minutes;
+}
+/** "1h 30m" / "45m" -- the log_time text the quick and personal log routes store. */
+function friendlyDuration(totalMinutes) {
+    if (totalMinutes <= 0)
+        return '';
+    if (totalMinutes < 60)
+        return `${totalMinutes}m`;
+    const h = Math.floor(totalMinutes / 60);
+    const m = totalMinutes % 60;
+    return m ? `${h}h ${m}m` : `${h}h`;
+}
+/** MM/DD/YYYY -- the date format both log routes expect. */
+function usDate(value) {
+    const d = value ? new Date(value) : new Date();
+    const use = Number.isNaN(d.getTime()) ? new Date() : d;
+    const mm = String(use.getMonth() + 1).padStart(2, '0');
+    const dd = String(use.getDate()).padStart(2, '0');
+    return `${mm}/${dd}/${use.getFullYear()}`;
+}
 /**
  * Build a full Group_Task payload from simplified MCP tool params.
  */
@@ -637,6 +677,39 @@ export class ViviScapeClient {
     async mergeTasks(fromTaskId, toTaskId) {
         return this.post('tasks/merge', { task_from_id: fromTaskId, task_to_id: toTaskId });
     }
+    /**
+     * Close a task through the platform's completion route (what `vs tasks done`
+     * calls). This is not the same as posting status "completed": the route also
+     * stamps the completing user and runs the milestone/progress rollup the task
+     * board relies on.
+     */
+    async completeTask(taskId, userId) {
+        return this.get(`complete/task?task_id=${taskId}&user_id=${userId || this.userId}`);
+    }
+    // -- Tickets ------------------------------------------------
+    /**
+     * The ticket queue, filtered server-side by status set, company and team --
+     * the view behind `vs tickets list`. Closed tickets live on their own route.
+     * Tickets are Group_Tasks, so the rows are task rows and task_get reads one.
+     */
+    async lookupTickets(opts = {}) {
+        const state = opts.status ?? 'open';
+        const statuses = opts.statuses?.length
+            ? opts.statuses
+            : state === 'all'
+                ? []
+                : state === 'closed'
+                    ? ['completed', 'cancelled']
+                    : ['backlog', 'new', 'research', 'inprogress', 'testing', 'inreview', 'onhold'];
+        const path = state === 'closed' ? 'tickets/completed/lookup' : 'tickets/lookup';
+        return this.post(path, {
+            company_id: opts.company_id ?? 0,
+            status: '',
+            statuses,
+            query: opts.query ?? '',
+            teamfilter: opts.team ?? '',
+        });
+    }
     // -- Task tags ----------------------------------------------
     async getTaskTags(taskId) {
         return this.get(`grouptask/tags/${taskId}`);
@@ -781,6 +854,70 @@ export class ViviScapeClient {
     async updateTimeLog(data) {
         return this.post('logs/update', buildTimeLogPayload(data, this.ctx));
     }
+    /**
+     * Log time against a task the short way (`vs tasks log`). The quick route
+     * fills group_id and service_id from the task itself, so only the note, the
+     * duration and the date are needed. A zero duration posts a note-only entry:
+     * it lands on the task's time feed without adding hours.
+     */
+    async quickLogTime(data) {
+        const minutes = shorthandToMinutes(data.duration ?? '');
+        return this.post('quick/logs/add', {
+            account_id: this.accountId,
+            user_id: this.userId,
+            task_id: data.task_id,
+            note: data.note,
+            log_time: friendlyDuration(minutes),
+            log_date: usDate(data.log_date),
+            isnoteonly: minutes <= 0,
+            billable: data.billable ?? false,
+        });
+    }
+    // -- Personal logs -------------------------------------------
+    /** Personal (non-task) time logs for a user -- the `vs logs list` feed. */
+    async getPersonalLogs(userId) {
+        return this.get(`personal/logs/user/${userId || this.userId}`);
+    }
+    /**
+     * Add a personal time log: work that belongs to a service rather than to any
+     * task. start_date and end_date mirror log_date, which is what the web form
+     * posts for a single-day entry.
+     */
+    async addPersonalLog(data) {
+        const date = usDate(data.log_date);
+        return this.post('personal/log/add', {
+            account_id: this.accountId,
+            user_id: this.userId,
+            service_id: data.service_id ?? 0,
+            note: data.note,
+            log_time: friendlyDuration(shorthandToMinutes(data.duration ?? '')),
+            log_date: date,
+            start_date: date,
+            end_date: date,
+        });
+    }
+    async removePersonalLog(logId) {
+        return this.get(`personal/log/remove/${logId}`);
+    }
+    // -- Time clock ----------------------------------------------
+    /**
+     * Punch the time clock. type "in" opens a punch, "out" closes the open one;
+     * both go to the same route with clocked_in set accordingly.
+     */
+    async addPunch(type, note = '') {
+        return this.post('user/punch/add', {
+            type,
+            note,
+            user_id: this.userId,
+            account_id: this.accountId,
+            platform_account_id: this.accountId,
+            punch_time: nowIso(),
+            clocked_in: type === 'in',
+        });
+    }
+    async getPunchHistory(userId) {
+        return this.get(`user/punch/history?user_id=${userId || this.userId}&account_id=${this.accountId}`);
+    }
     // -- Notes --------------------------------------------------
     async getMyNotes() {
         return this.get('notes/me');

package/dist/auth/permissions.js

@@ -60,6 +60,16 @@ export function featureForPath(path) {
         return 'insights';
     if (p.startsWith('logs') || p.startsWith('timelog'))
         return 'logs';
+    // Quick task logging and personal logs are the same Pro-tier logging feature.
+    if (p.startsWith('quick/logs') || p.startsWith('personal/log'))
+        return 'logs';
+    if (p.startsWith('ticket'))
+        return 'tickets';
+    if (p.startsWith('user/punch'))
+        return 'time';
+    // Task completion route sits outside the tasks/* prefix.
+    if (p.startsWith('complete/task'))
+        return 'tasks';
     if (p.startsWith('prospect'))
         return 'crm';
     if (p.startsWith('task/comment'))

package/dist/index.js

@@ -35,7 +35,7 @@ function invalidateClient() {
 }
 const server = new McpServer({
     name: 'viviscape',
-    version: '2.0.0',
+    version: '2.9.0',
 });
 function json(data) {
     return JSON.stringify(data, null, 2);
@@ -894,6 +894,35 @@ server.tool('task_merge', 'Merge one task into another. The source task is consu
     const result = await requireClient().mergeTasks(from_task_id, to_task_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
+server.tool('task_complete', 'Close a task through the platform completion route. Prefer this over task_update with status "completed": it also stamps who finished the work and runs the milestone/progress rollup the task board reads.', {
+    task_id: z.number().describe('Task ID to complete'),
+    user_id: z.number().optional().describe('User completing the task. Defaults to the signed-in user.'),
+    ...idempotencyArg,
+}, async ({ task_id, user_id, idempotency_key }) => {
+    const result = await once('task_complete', idempotency_key, () => requireClient().completeTask(task_id, user_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// TICKETS
+// ============================================================
+server.tool('tickets_list', 'The account ticket queue, filtered server-side by status set, company and team. status "open" (default) covers backlog, new, research, inprogress, testing, inreview and onhold; "closed" reads the completed/cancelled route; "all" drops the status filter. Tickets are tasks, so rows are task rows -- read one with task_get and search by keyword with task_search. Requires the enterprise plan.', {
+    status: z.enum(['open', 'closed', 'all']).optional().describe('Which ticket queue to read (default: open)'),
+    statuses: z.array(z.enum(TASK_STATUSES)).optional().describe('Exact status set, overriding the status shorthand'),
+    query: z.string().optional().describe('Search text matched server-side'),
+    company_id: z.number().optional().describe('Only tickets for this company'),
+    team: z.string().optional().describe('Team filter passed through to the API'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().lookupTickets({
+        status: params.status,
+        statuses: params.statuses,
+        query: params.query,
+        company_id: params.company_id,
+        team: params.team,
+    });
+    const rows = Array.isArray(result) ? annotateTasks(result) : result;
+    return { content: [{ type: 'text', text: json(shape(since(rows, params), TASK_FIELDS, paging(params))) }] };
+});
 // ============================================================
 // TASK COMMENTS
 // ============================================================
@@ -965,6 +994,56 @@ server.tool('timelog_update', 'Update an existing time log entry. Builds full LO
     const result = await requireClient().updateTimeLog(params);
     return { content: [{ type: 'text', text: json(result) }] };
 });
+server.tool('task_log_time', 'Log time against a task the short way: the quick route takes the project and service from the task itself, so only the note matters. Omit duration (or pass 0) to post a note-only entry -- it lands on the task time feed without adding hours. Use timelog_add when the entry needs an explicit project, service or user.', {
+    task_id: z.number().describe('Task ID to log against'),
+    note: z.string().describe('What was worked on'),
+    duration: z.string().optional().describe('Duration in shorthand (e.g., 1h30m, 45m, 2h). Omit for a note-only entry.'),
+    log_date: z.string().optional().describe('Date of the work (ISO 8601). Defaults to today.'),
+    billable: z.boolean().optional().describe('Whether this time is billable (default false)'),
+    ...idempotencyArg,
+}, async (params) => {
+    const result = await once('task_log_time', params.idempotency_key, () => requireClient().quickLogTime(params));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// PERSONAL LOGS AND TIME CLOCK
+// ============================================================
+server.tool('personal_logs', 'Personal time logs for a user -- work booked against a service rather than any task.', {
+    user_id: z.number().optional().describe('User whose logs to read. Defaults to the signed-in user.'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getPersonalLogs(params.user_id);
+    return { content: [{ type: 'text', text: json(shape(since(result, params), [], paging(params))) }] };
+});
+server.tool('personal_log_add', 'Add a personal time log: work that belongs to a service rather than to a task. For task work use task_log_time or timelog_add.', {
+    note: z.string().describe('What was worked on'),
+    duration: z.string().optional().describe('Duration in shorthand (e.g., 1h30m, 45m, 2h)'),
+    service_id: z.number().optional().describe('Service ID classifying the work type'),
+    log_date: z.string().optional().describe('Date of the work (ISO 8601). Defaults to today.'),
+    ...idempotencyArg,
+}, async (params) => {
+    const result = await once('personal_log_add', params.idempotency_key, () => requireClient().addPersonalLog(params));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('personal_log_remove', 'Delete a personal time log by its log_id (from personal_logs).', { log_id: z.number().describe('Personal log ID to remove') }, async ({ log_id }) => {
+    const result = await requireClient().removePersonalLog(log_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('timeclock_punch', 'Punch the time clock for the signed-in user. type "in" opens a punch, "out" closes the open one. This is the attendance clock, separate from task time logs.', {
+    type: z.enum(['in', 'out']).describe('Punch direction'),
+    note: z.string().optional().describe('Optional punch note'),
+    ...idempotencyArg,
+}, async ({ type, note, idempotency_key }) => {
+    const result = await once('timeclock_punch', idempotency_key, () => requireClient().addPunch(type, note ?? ''));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('timeclock_history', 'Time clock punch history for a user -- clock-in/clock-out pairs with their notes.', {
+    user_id: z.number().optional().describe('User whose punches to read. Defaults to the signed-in user.'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getPunchHistory(params.user_id);
+    return { content: [{ type: 'text', text: json(shape(since(result, params), [], paging(params))) }] };
+});
 // ============================================================
 // NOTES
 // ============================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viviscape-mcp",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "MCP server for the ViviScape API — CRM, projects, companies, notes, and insights, authenticated as the signed-in ViviScape user",
   "type": "module",
   "main": "dist/index.js",