viviscape-mcp 2.4.0 → 2.6.0

package/README.md

@@ -107,6 +107,8 @@ The server exposes tools across these domains:
 - **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), 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)
@@ -126,7 +128,7 @@ 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 |
+| 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 |
@@ -136,6 +138,56 @@ Two traps: tasks complete as `completed` while projects complete as
 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`).
+- Tags are per task. There is no tag-search route, and list rows from
+  `tasks_open` / `project_tasks` carry `tags: null`, so read a task's tags with
+  `task_tags` or `task_get`.
+- 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

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,30 @@ 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>;
+    /**
+     * 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,57 @@ 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}`);
+    }
+    // -- 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,40 @@ 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. Tags are per task -- there is no tag search route, and list rows from tasks_open / project_tasks carry tags: null, so read a task tag set here or with task_get.', {
+    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_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.0",
+  "version": "2.6.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",