viviscape-mcp 2.2.0 → 2.3.0

package/README.md

@@ -144,6 +144,12 @@ 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`,

package/dist/index.js

@@ -7,7 +7,7 @@ import { 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';
-import { FILE_FIELDS, NOTE_FIELDS, PROJECT_FIELDS, TASK_FIELDS, filterTasks, shape, } from './projection.js';
+import { FILE_FIELDS, NOTE_FIELDS, PROJECT_FIELDS, TASK_FIELDS, annotateTasks, filterTasks, shape, } from './projection.js';
 import { baseUrl } from './config.js';
 // quiet: dotenv's banner goes to stdout, which is the MCP protocol channel.
 config({ quiet: true });
@@ -336,11 +336,11 @@ server.tool('project_tasks', 'Get all tasks for a project. Returns a page of tri
     // project_id is the query, not a filter -- re-filtering on it would drop
     // every row if the response names the column differently.
     const rows = Array.isArray(result)
-        ? filterTasks(result, { ...params, project_id: undefined })
+        ? annotateTasks(filterTasks(result, { ...params, project_id: undefined }))
         : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
-server.tool('tasks_open', 'Get open tasks across projects. company_id and only_mine filter server-side; the rest filter in-process. Returns a page of trimmed rows.', {
+server.tool('tasks_open', 'Get open tasks across projects. company_id and only_mine filter server-side; the rest filter in-process. Returns a page of trimmed rows with computed due_date / due_in_days / overdue -- read those, not the API deadline string, which is unreliable.', {
     only_mine: z.boolean().optional().describe('Only tasks assigned to the signed-in user (server-side)'),
     team: z.string().optional().describe('Team filter passed through to the API'),
     ...taskFilterArgs,
@@ -351,7 +351,7 @@ server.tool('tasks_open', 'Get open tasks across projects. company_id and only_m
         only_mine: params.only_mine,
         team: params.team,
     });
-    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
 server.tool('task_add', 'Add a task to a project. The API requires a full Group_Task payload; this tool builds it from simplified params.', {
@@ -394,7 +394,7 @@ server.tool('tasks_pending', 'Get pending tasks for a user. Returns a page of tr
     ...taskFilterArgs,
 }, async (params) => {
     const result = await requireClient().getPendingTasks(params.user_id);
-    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
 server.tool('tasks_by_milestone', 'Get tasks for a milestone. Returns a page of trimmed rows; see fields/limit/offset.', {
@@ -403,7 +403,7 @@ server.tool('tasks_by_milestone', 'Get tasks for a milestone. Returns a page of
     ...taskFilterArgs,
 }, async (params) => {
     const result = await requireClient().getTasksByMilestone(params.milestone_id);
-    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
 server.tool('tasks_by_group_user', 'Get tasks by project group and user. Returns a page of trimmed rows; see fields/limit/offset.', {
@@ -413,7 +413,7 @@ server.tool('tasks_by_group_user', 'Get tasks by project group and user. Returns
     ...taskFilterArgs,
 }, async (params) => {
     const result = await requireClient().getTasksByGroupAndUser(params.group_id, params.user_id);
-    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
 server.tool('tasks_by_company', 'Get tasks for a company. Returns a page of trimmed rows; see fields/limit/offset.', {
@@ -423,7 +423,7 @@ server.tool('tasks_by_company', 'Get tasks for a company. Returns a page of trim
 }, async (params) => {
     const result = await requireClient().getCompanyTasks(params.company_id);
     const rows = Array.isArray(result)
-        ? filterTasks(result, { ...params, company_id: undefined })
+        ? annotateTasks(filterTasks(result, { ...params, company_id: undefined }))
         : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });

package/dist/projection.d.ts

@@ -8,7 +8,16 @@
  * read. These helpers trim to a PM-relevant default, page the result, and tell
  * the caller what was left out so it can ask for more deliberately.
  */
-/** Task fields worth returning by default, of roughly 90 available. */
+/**
+ * Task fields worth returning by default, of roughly 90 available.
+ *
+ * `deadline` is deliberately excluded. It is a server-rendered string that does
+ * not track the task's own due date: measured against six live tasks it read
+ * "In 2 Days" for one 39 days overdue, and gave "In 4 Days" for tasks at both
+ * -9 and +2 days. `end` is the real due date, and `pastdue` agrees with it on
+ * every row, so annotateTasks() derives due_date / due_in_days / overdue from
+ * `end` and those are what callers should read.
+ */
 export declare const TASK_FIELDS: string[];
 /** Project (group) fields worth returning by default, of 87 available. */
 export declare const PROJECT_FIELDS: string[];
@@ -38,6 +47,17 @@ export interface TaskFilters {
 }
 /** Apply the filters the backend does not support, in-process. */
 export declare function filterTasks(rows: unknown[], f: TaskFilters): unknown[];
+/**
+ * Add an unambiguous due-date signal to task rows.
+ *
+ * The API ships three overlapping fields: `end` (the real due date), `pastdue`
+ * (a boolean that matches it), and `deadline` (a human string that does not).
+ * Rather than make every caller know which to trust, derive the answer from
+ * `end` and pass `deadline` through only when explicitly requested.
+ *
+ * due_in_days is negative for overdue work, 0 for due today.
+ */
+export declare function annotateTasks(rows: unknown[], now?: number): unknown[];
 /**
  * Trim, page, and annotate a list response. Non-array payloads (a single record,
  * or an error object) pass through untouched.

package/dist/projection.js

@@ -8,12 +8,22 @@
  * read. These helpers trim to a PM-relevant default, page the result, and tell
  * the caller what was left out so it can ask for more deliberately.
  */
-/** Task fields worth returning by default, of roughly 90 available. */
+/**
+ * Task fields worth returning by default, of roughly 90 available.
+ *
+ * `deadline` is deliberately excluded. It is a server-rendered string that does
+ * not track the task's own due date: measured against six live tasks it read
+ * "In 2 Days" for one 39 days overdue, and gave "In 4 Days" for tasks at both
+ * -9 and +2 days. `end` is the real due date, and `pastdue` agrees with it on
+ * every row, so annotateTasks() derives due_date / due_in_days / overdue from
+ * `end` and those are what callers should read.
+ */
 export const TASK_FIELDS = [
     'task_id', 'task', 'status', 'percentage', 'priority',
     'company_id', 'company_name', 'group_id', 'group_name',
     'milestone_id', 'milestone', 'estimated_time', 'total_duration_str',
-    'deadline', 'start', 'end', 'staff_assignees', 'total_comments', 'unread_for_me',
+    'start', 'due_date', 'due_in_days', 'overdue', 'pastdue',
+    'staff_assignees', 'total_comments', 'unread_for_me',
 ];
 /** Project (group) fields worth returning by default, of 87 available. */
 export const PROJECT_FIELDS = [
@@ -92,6 +102,32 @@ export function filterTasks(rows, f) {
         return true;
     });
 }
+/**
+ * Add an unambiguous due-date signal to task rows.
+ *
+ * The API ships three overlapping fields: `end` (the real due date), `pastdue`
+ * (a boolean that matches it), and `deadline` (a human string that does not).
+ * Rather than make every caller know which to trust, derive the answer from
+ * `end` and pass `deadline` through only when explicitly requested.
+ *
+ * due_in_days is negative for overdue work, 0 for due today.
+ */
+export function annotateTasks(rows, now = Date.now()) {
+    return rows.map((row) => {
+        if (!isRecord(row))
+            return row;
+        const due = Date.parse(String(row.end ?? ''));
+        if (!Number.isFinite(due)) {
+            return { ...row, due_date: null, due_in_days: null, overdue: null };
+        }
+        return {
+            ...row,
+            due_date: new Date(due).toISOString(),
+            due_in_days: Math.round((due - now) / 86_400_000),
+            overdue: due < now,
+        };
+    });
+}
 function pick(row, fields) {
     if (!isRecord(row))
         return row;

package/package.json

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