viviscape-mcp 2.4.1 → 2.7.0

package/README.md

@@ -1,195 +1,253 @@
-# 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`
-- **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`
-- **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, 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.
-
-### 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
+# 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`
+- **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.
+
+### 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

package/dist/api-client.d.ts

@@ -7,6 +7,12 @@ export declare class ApiError extends Error {
     status: number;
     constructor(status: number, message: string);
 }
+/**
+ * Tag colours the ViviScape Work task board offers (tasks.js \$scope.tagPalette).
+ * The API takes any hex string; staying inside the palette keeps agent-written
+ * tags visually consistent with the ones people add by hand. First is default.
+ */
+export declare const TAG_PALETTE: readonly ["#00325e", "#13B955", "#EFA31D", "#FF5757", "#009CDC", "#6610f2", "#fd7e14", "#e83e8c", "#20c997", "#868e96"];
 /**
  * Client for the ViviScape Work core API. Authenticates exactly like the
  * ViviScape CLI: the signed-in user's bearer token plus the user_id / pid
@@ -147,6 +153,43 @@ 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>;
+    getTaskTags(taskId: number): Promise<unknown>;
+    /**
+     * Tag a task. The web app upper-cases the label and always sends a colour, so
+     * match it: tags written by an agent then look and sort like the human ones.
+     * Returns the persisted Group_Task_Tag, including its tag_id.
+     */
+    addTaskTag(taskId: number, tag: string, color?: string): Promise<unknown>;
+    /** Takes the tag_id from getTaskTags, not the label. */
+    removeTaskTag(tagId: string): Promise<unknown>;
+    /**
+     * Tasks carrying one or more tags. Labels are matched trimmed and case
+     * insensitively; match 'all' narrows to tasks carrying every label, 'any'
+     * (the default) returns tasks carrying at least one. Each hit carries its
+     * whole tag set, so a task's other labels come back with it.
+     */
+    searchTasksByTags(tags: string[], opts?: {
+        match?: 'any' | 'all';
+        status?: string[];
+        max?: number;
+    }): Promise<unknown>;
+    /** Every distinct task tag on the account, with the task count per label. */
+    getAccountTaskTags(): Promise<unknown>;
+    /**
+     * Cross references between tasks. The link is symmetric: adding A -> B makes
+     * the pair visible from both tasks, and each row describes the OTHER task
+     * (related_task_id, its title and status), so no second fetch is needed.
+     */
+    getTaskReferences(taskId: number): Promise<unknown>;
+    /** Idempotent per pair: re-adding an existing link returns that link. */
+    addTaskReference(taskId: number, relatedTaskId: number, note?: string): Promise<unknown>;
+    /** Takes the reference_id from getTaskReferences, not a task id. */
+    removeTaskReference(referenceId: string): Promise<unknown>;
+    /** Keyword search over the account's tasks -- matches title, description and task id. */
+    searchTasks(query: string, opts?: {
+        exclude_task_id?: number;
+        max?: number;
+    }): Promise<unknown>;
     getMilestones(projectId: number): Promise<unknown>;
     getActiveMilestones(): Promise<unknown>;
     getMilestonesByCompany(companyId: number): Promise<unknown>;

package/dist/api-client.js

@@ -106,6 +106,8 @@ function buildTaskUpdatePayload(data) {
         mapped.task = data.title;
     if (data.description !== undefined)
         mapped.description = data.description;
+    if (data.notes !== undefined)
+        mapped.notes = data.notes;
     if (data.status !== undefined)
         mapped.status = data.status;
     if (data.priority !== undefined) {
@@ -181,6 +183,16 @@ function buildTimeLogPayload(data, ctx) {
 }
 const EPOCH = '2000-01-01T00:00:00';
 const EMPTY_GUID = '00000000-0000-0000-0000-000000000000';
+/**
+ * Tag colours the ViviScape Work task board offers (tasks.js \$scope.tagPalette).
+ * The API takes any hex string; staying inside the palette keeps agent-written
+ * tags visually consistent with the ones people add by hand. First is default.
+ */
+export const TAG_PALETTE = [
+    '#00325e', '#13B955', '#EFA31D', '#FF5757',
+    '#009CDC', '#6610f2', '#fd7e14', '#e83e8c',
+    '#20c997', '#868e96',
+];
 function isoDate(value, fallback) {
     if (typeof value === 'string' && value.trim())
         return value;
@@ -621,6 +633,76 @@ export class ViviScapeClient {
     async mergeTasks(fromTaskId, toTaskId) {
         return this.post('tasks/merge', { task_from_id: fromTaskId, task_to_id: toTaskId });
     }
+    // -- Task tags ----------------------------------------------
+    async getTaskTags(taskId) {
+        return this.get(`grouptask/tags/${taskId}`);
+    }
+    /**
+     * Tag a task. The web app upper-cases the label and always sends a colour, so
+     * match it: tags written by an agent then look and sort like the human ones.
+     * Returns the persisted Group_Task_Tag, including its tag_id.
+     */
+    async addTaskTag(taskId, tag, color) {
+        return this.post('grouptask/tags/add', {
+            tag_id: EMPTY_GUID,
+            task_id: taskId,
+            tag: tag.trim().toUpperCase(),
+            color: color || TAG_PALETTE[0],
+        });
+    }
+    /** Takes the tag_id from getTaskTags, not the label. */
+    async removeTaskTag(tagId) {
+        return this.get(`grouptask/tag/remove/${tagId}`);
+    }
+    /**
+     * Tasks carrying one or more tags. Labels are matched trimmed and case
+     * insensitively; match 'all' narrows to tasks carrying every label, 'any'
+     * (the default) returns tasks carrying at least one. Each hit carries its
+     * whole tag set, so a task's other labels come back with it.
+     */
+    async searchTasksByTags(tags, opts = {}) {
+        const params = new URLSearchParams({
+            tags: tags.map((t) => t.trim()).filter(Boolean).join(','),
+            match: opts.match ?? 'any',
+            status: (opts.status ?? []).map((s) => s.trim()).filter(Boolean).join(','),
+            max: String(opts.max ?? 25),
+        });
+        return this.get(`grouptask/tags/search?${params.toString()}`);
+    }
+    /** Every distinct task tag on the account, with the task count per label. */
+    async getAccountTaskTags() {
+        return this.get('grouptask/tags/all');
+    }
+    // -- Task references ----------------------------------------
+    /**
+     * Cross references between tasks. The link is symmetric: adding A -> B makes
+     * the pair visible from both tasks, and each row describes the OTHER task
+     * (related_task_id, its title and status), so no second fetch is needed.
+     */
+    async getTaskReferences(taskId) {
+        return this.get(`grouptask/references/${taskId}`);
+    }
+    /** Idempotent per pair: re-adding an existing link returns that link. */
+    async addTaskReference(taskId, relatedTaskId, note) {
+        return this.post('grouptask/references/add', {
+            task_id: taskId,
+            related_task_id: relatedTaskId,
+            note: note || '',
+        });
+    }
+    /** Takes the reference_id from getTaskReferences, not a task id. */
+    async removeTaskReference(referenceId) {
+        return this.get(`grouptask/reference/remove/${referenceId}`);
+    }
+    /** Keyword search over the account's tasks -- matches title, description and task id. */
+    async searchTasks(query, opts = {}) {
+        const params = new URLSearchParams({
+            query,
+            exclude_task_id: String(opts.exclude_task_id ?? 0),
+            max: String(opts.max ?? 25),
+        });
+        return this.get(`grouptask/search?${params.toString()}`);
+    }
     // -- Milestones ---------------------------------------------
     async getMilestones(projectId) {
         return this.get(`milestones/list/${projectId}`);

package/dist/auth/permissions.js

@@ -66,5 +66,8 @@ export function featureForPath(path) {
         return 'comment';
     if (p.startsWith('task'))
         return 'tasks';
+    // Task tags live under grouptask/*, which would otherwise fall through to auth.
+    if (p.startsWith('grouptask'))
+        return 'tasks';
     return 'auth';
 }

package/dist/enums.d.ts

@@ -12,7 +12,7 @@
  *    low/medium/high, which is what this server's task_add used to claim.
  */
 /** Task status values, in board order. */
-export declare const TASK_STATUSES: readonly ["backlog", "new", "research", "inprogress", "pendingreview", "inreview", "testing", "waitingcustomer", "waitingteammember", "onhold", "cancelled", "completed"];
+export declare const TASK_STATUSES: readonly ["backlog", "new", "research", "discussion", "inprogress", "pendingreview", "inreview", "testing", "waitingcustomer", "waitingteammember", "onhold", "cancelled", "completed"];
 /** Task and project priority values, ascending. */
 export declare const PRIORITIES: readonly ["low", "moderate", "important", "urgent", "critical"];
 /**
@@ -34,7 +34,7 @@ export type Priority = (typeof PRIORITIES)[number];
 export type ProjectStatus = (typeof PROJECT_STATUSES)[number];
 /** Payload for the enums tool, so callers can discover these without guessing. */
 export declare function enumReference(): {
-    task_status: readonly ["backlog", "new", "research", "inprogress", "pendingreview", "inreview", "testing", "waitingcustomer", "waitingteammember", "onhold", "cancelled", "completed"];
+    task_status: readonly ["backlog", "new", "research", "discussion", "inprogress", "pendingreview", "inreview", "testing", "waitingcustomer", "waitingteammember", "onhold", "cancelled", "completed"];
     priority: readonly ["low", "moderate", "important", "urgent", "critical"];
     project_status: readonly ["new", "inprogress", "complete"];
     prospect_status: readonly ["new", "firstcontact", "negotiation", "pending", "won", "lost", "spam"];

package/dist/enums.js

@@ -16,6 +16,7 @@ export const TASK_STATUSES = [
     'backlog',
     'new',
     'research',
+    'discussion',
     'inprogress',
     'pendingreview',
     'inreview',

package/dist/index.js

@@ -3,7 +3,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { config } from 'dotenv';
-import { ViviScapeClient } from './api-client.js';
+import { TAG_PALETTE, ViviScapeClient } from './api-client.js';
 import { AuthService } from './auth/auth-service.js';
 import { describe } from './auth/credentials.js';
 import { PRIORITIES, PROJECT_STATUSES, PROSPECT_STATUSES, TASK_STATUSES, enumReference, } from './enums.js';
@@ -387,15 +387,40 @@ server.tool('task_add', 'Add a task to a project. The API requires a full Group_
     start_date: z.string().optional().describe('Start date (ISO 8601)'),
     due_date: z.string().optional().describe('Due date (ISO 8601)'),
     milestone_id: z.number().optional().describe('Milestone ID'),
+    tags: z.array(z.string()).optional().describe('Tag labels to apply to the new task (stored upper-case). Applied after creation, in the board default colour; use task_tags to pick a colour.'),
     ...idempotencyArg,
 }, async (params) => {
-    const result = await once('task_add', params.idempotency_key, () => requireClient().addTask(params));
+    const result = await once('task_add', params.idempotency_key, async () => {
+        const c = requireClient();
+        const task = await c.addTask(params);
+        if (!params.tags?.length)
+            return task;
+        const row = task && typeof task === 'object' ? task : null;
+        const taskId = Number(row?.task_id ?? 0);
+        if (!taskId) {
+            return { task, tags_skipped: 'The create response carried no task_id; tag the task with task_tags.' };
+        }
+        // A tag failure must not throw: the task already exists, and an error here
+        // would leave the idempotency key unrecorded, so a retry would create a
+        // second task. Report per-tag outcomes as data instead.
+        const tags = [];
+        for (const label of params.tags) {
+            try {
+                tags.push(await c.addTaskTag(taskId, label));
+            }
+            catch (err) {
+                tags.push({ tag: label, error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        return { ...row, tags };
+    });
     return { content: [{ type: 'text', text: json(result) }] };
 });
 server.tool('task_update', 'Update a task. Fetches existing task first and merges changes.', {
     task_id: z.number().describe('Task ID to update'),
     title: z.string().optional().describe('Task title'),
     description: z.string().optional(),
+    notes: z.string().optional().describe('Task notes -- the free-form working notes on the task Overview tab, held in HTML by the editor. Replaces the field outright, so read the current value with task_get and send the merged text rather than only the new lines.'),
     assigned_to: z.number().optional().describe('User ID to assign to'),
     priority: z.enum(PRIORITIES).optional().describe('Priority (platform values)'),
     status: z.enum(TASK_STATUSES).optional().describe('Task status (platform values)'),
@@ -408,6 +433,53 @@ server.tool('task_get', 'Get a single task by ID', { task_id: z.number().describ
     const result = await requireClient().getTask(task_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
+server.tool('task_tags', 'List, add, or remove tags on a task -- the categorisation primitive of the task board, and the way to mark work an agent created or touched. Labels are stored upper-case, and add is idempotent per label: re-adding one returns the existing tag rather than a duplicate. add returns the persisted tag including its tag_id; remove takes that tag_id, not the label, and answers true. This tool is per task -- list rows from tasks_open / project_tasks carry tags: null, so read a task tag set here or with task_get. To go the other way, from a label to the tasks carrying it, use tasks_by_tag.', {
+    action: z.enum(['list', 'add', 'remove']).describe('What to do'),
+    task_id: z.number().optional().describe('Task ID (list, add)'),
+    tag: z.string().optional().describe('Tag label (add). Stored upper-case.'),
+    color: z.string().optional().describe(`Hex colour for the tag (add). Defaults to ${TAG_PALETTE[0]}; the board palette is ${TAG_PALETTE.join(' ')}.`),
+    tag_id: z.string().optional().describe('Tag ID from list (remove)'),
+}, async ({ action, task_id, tag, color, tag_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getTaskTags(need(action, 'task_id', task_id))
+        : action === 'add' ? await c.addTaskTag(need(action, 'task_id', task_id), need(action, 'tag', tag), color)
+            : await c.removeTaskTag(need(action, 'tag_id', tag_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_references', 'List, add, or remove cross references between tasks -- the way related work is linked so one task points at another (a duplicate, a blocker, the ticket a task came from). Links are SYMMETRIC: adding A -> B makes the pair visible from both tasks, so link once and never mirror it by hand. list rows describe the OTHER task -- related_task_id plus its title, status and project -- so no second task_get is needed to report them. add is idempotent per pair and returns the persisted link including its reference_id; remove takes that reference_id, not a task id, and answers true. Both tasks must belong to the signed-in account. Use task_search to find the id to link when only a keyword is known.', {
+    action: z.enum(['list', 'add', 'remove']).describe('What to do'),
+    task_id: z.number().optional().describe('Task ID whose references are read or extended (list, add)'),
+    related_task_id: z.number().optional().describe('Task ID to link to task_id (add)'),
+    note: z.string().optional().describe('Optional note describing why the two are linked (add)'),
+    reference_id: z.string().optional().describe('Reference ID from list (remove)'),
+}, async ({ action, task_id, related_task_id, note, reference_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getTaskReferences(need(action, 'task_id', task_id))
+        : action === 'add' ? await c.addTaskReference(need(action, 'task_id', task_id), need(action, 'related_task_id', related_task_id), note)
+            : await c.removeTaskReference(need(action, 'reference_id', reference_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_search', 'Keyword search over the account tasks and tickets -- matches the title, the description, and, for a numeric query, the task id itself. Returns light rows (task_id, title, status, project, company), enough to pick an id for task_get or task_references without pulling a full task feed.', {
+    query: z.string().describe('Keyword or task id to search for'),
+    exclude_task_id: z.number().optional().describe('Task ID to leave out of the results (e.g. the task being linked from)'),
+    max: z.number().optional().describe('Maximum rows to return (default 25, cap 100)'),
+}, async ({ query, exclude_task_id, max }) => {
+    const result = await requireClient().searchTasks(query, { exclude_task_id, max });
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('tasks_by_tag', 'Find the account tasks carrying given tags -- the reverse of task_tags, and the way a tag-driven queue is read (every task an agent marked, everything labelled RELEASE-BLOCKER, and so on). Labels match trimmed and case insensitively, so DEVOPS, devops and " DevOps " are the same tag. match "any" (default) returns a task carrying at least one label; match "all" narrows to tasks carrying every one. Rows are light (task_id, title, status, project, company) and carry the task whole tag set, so the other labels come back with the hit -- no follow-up task_tags call. Pass no tags to list instead the account tag vocabulary: every distinct label with the number of tasks using it, which is how to discover what is worth filtering on.', {
+    tags: z.array(z.string()).optional().describe('Tag labels to match. Omit or leave empty to list the account tag vocabulary instead.'),
+    match: z.enum(['any', 'all']).optional().describe('any = tasks carrying at least one of the tags (default); all = tasks carrying every one'),
+    status: z.array(z.enum(TASK_STATUSES)).optional().describe('Optional status filter, e.g. ["new","inprogress"]. Omit to include every status, completed and cancelled included.'),
+    max: z.number().optional().describe('Maximum rows to return (default 25, cap 100)'),
+}, async ({ tags, match, status, max }) => {
+    const c = requireClient();
+    const labels = (tags ?? []).map((t) => t.trim()).filter(Boolean);
+    const result = labels.length
+        ? await c.searchTasksByTags(labels, { match, status, max })
+        : await c.getAccountTaskTags();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
 server.tool('tasks_pending', 'Get pending tasks for a user. Returns a page of trimmed rows; see fields/limit/offset.', {
     user_id: z.number().describe('User ID'),
     ...pageArgs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viviscape-mcp",
-  "version": "2.4.1",
+  "version": "2.7.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",