viviscape-mcp 2.0.2 → 2.1.0

package/README.md

@@ -105,12 +105,52 @@ The server exposes tools across these domains:
 - **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)
 - **Time logs** - `timelog_add`, `timelog_update`
 - **Notes** - `note_add`, `note_get`, `note_update`, `note_remove`, `notes_mine`, `notes_query`
 - **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.
+
+### 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
+
+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

package/dist/api-client.d.ts

@@ -52,15 +52,108 @@ export declare class ViviScapeClient {
     getProjectStaff(projectId: number): Promise<unknown>;
     getProjectsByCompany(userId: number, companyId: number): Promise<unknown>;
     getActiveProjectsByUser(userId: number): Promise<unknown>;
+    /**
+     * Create a project (group). GEN_Group has ~40 fields; live rows for this
+     * tenant show account_id 0, platform_account_id = pid, and group type 5
+     * (PROJECT), so those are the defaults here.
+     *
+     * There is no delete route for projects -- a created project can only be
+     * archived or renamed afterward.
+     */
+    addProject(data: {
+        company_id: number;
+        name: string;
+        short_description?: string;
+        description?: string;
+        status?: string;
+        is_public?: boolean;
+        staff?: number[];
+    }): Promise<unknown>;
+    /** Update a project by merging changes onto the row the API already has. */
+    updateProject(projectId: number, changes: Record<string, unknown>): Promise<unknown>;
+    /** Status-only update; leaves budget and approved time untouched. */
+    setProjectStatus(projectId: number, status: string, billable?: boolean): Promise<unknown>;
+    addProjectUser(projectId: number, userId: number, opts?: {
+        is_contact?: boolean;
+        is_lead?: boolean;
+    }): Promise<unknown>;
+    removeProjectUser(projectId: number, userId: number): Promise<unknown>;
     addTask(data: Record<string, unknown>): Promise<unknown>;
     updateTask(data: Record<string, unknown>): Promise<unknown>;
     getProjectTasks(projectId: number): Promise<unknown>;
-    getOpenTasks(): Promise<unknown>;
+    /**
+     * The account/tasks/open route filters server-side on company, ownership, and
+     * a date window; pass them through instead of hardcoding "everything".
+     */
+    getOpenTasks(opts?: {
+        company_id?: number;
+        only_mine?: boolean;
+        team?: string;
+        start?: string;
+        end?: string;
+    }): Promise<unknown>;
     getTask(taskId: number): Promise<unknown>;
     getPendingTasks(userId: number): Promise<unknown>;
     getTasksByMilestone(milestoneId: number): Promise<unknown>;
     getTasksByGroupAndUser(groupId: number, userId: number): Promise<unknown>;
     getCompanyTasks(companyId: number): Promise<unknown>;
+    getTaskComments(taskId: number): Promise<unknown>;
+    getTaskComment(commentId: string): Promise<unknown>;
+    /**
+     * NOTE: on platform account 1, the backend fires a client-notification webhook
+     * for comments on tasks whose client_id > 0. Adding a comment can therefore
+     * reach the customer -- the tool description says so too.
+     */
+    addTaskComment(data: {
+        task_id: number;
+        comment: string;
+        client_id?: number;
+        source?: string;
+    }): Promise<unknown>;
+    updateTaskComment(data: {
+        comment_id: string;
+        task_id: number;
+        comment: string;
+    }): Promise<unknown>;
+    /**
+     * The backend's remove proxy answers 500 even on success: it returns 400 when
+     * the upstream delete fails, so a 500 means it crashed deserializing an empty
+     * success body (res.data.ToString() on null). Verify by re-reading the thread
+     * rather than reporting a failure that did not happen.
+     */
+    removeTaskComment(commentId: string, taskId?: number): Promise<unknown>;
+    markTaskRead(taskId: number): Promise<unknown>;
+    addTaskAssignee(data: {
+        task_id: number;
+        user_id: number;
+        leader?: boolean;
+        attention?: boolean;
+        notify?: boolean;
+    }): Promise<unknown>;
+    /** Takes the assignee_id from the task's staff_assignees, not a user_id. */
+    removeTaskAssignee(assigneeId: number): Promise<unknown>;
+    setTaskLeader(taskId: number, userId: number): Promise<unknown>;
+    setTaskAttention(taskId: number, userId: number, flag: boolean): Promise<unknown>;
+    deleteTask(taskId: number): Promise<unknown>;
+    /** Fold one task into another; the source task is consumed. */
+    mergeTasks(fromTaskId: number, toTaskId: number): Promise<unknown>;
+    getMilestones(projectId: number): Promise<unknown>;
+    getActiveMilestones(): Promise<unknown>;
+    getMilestonesByCompany(companyId: number): Promise<unknown>;
+    getMilestonesByUser(userId: number): Promise<unknown>;
+    getMilestone(milestoneId: number): Promise<unknown>;
+    addMilestone(data: Record<string, unknown>): Promise<unknown>;
+    updateMilestone(data: Record<string, unknown>): Promise<unknown>;
+    /** Copy a milestone (and its task template) into a project. */
+    cloneMilestone(milestoneId: number, projectId: number, title?: string): Promise<unknown>;
+    /**
+     * Known broken upstream: milestone/remove answers 500 and the milestone
+     * survives. The proxy returns 400 with detail when the upstream delete fails,
+     * so the 500 is a crash in its own success branch (Convert.ToBoolean on a
+     * non-boolean data payload) -- but unlike the comment-remove case the record
+     * is genuinely still there. Verify and say so plainly instead of pretending.
+     */
+    removeMilestone(milestoneId: number): Promise<unknown>;
     addTimeLog(data: Record<string, unknown>): Promise<unknown>;
     updateTimeLog(data: Record<string, unknown>): Promise<unknown>;
     getMyNotes(): Promise<unknown>;

package/dist/api-client.js

@@ -1,4 +1,5 @@
-import { API_PREFIX, baseUrl } from './config.js';
+import { API_PREFIX, APP_NAME, baseUrl } from './config.js';
+import { GROUP_TYPES } from './enums.js';
 import { featureForPath, requireFeature } from './auth/permissions.js';
 /** Raised when the stored session is rejected or bounced to the login page. */
 export class SessionExpiredError extends Error {
@@ -13,6 +14,25 @@ export class ApiError extends Error {
         this.status = status;
     }
 }
+/**
+ * GroupMilestone payload. The API wants the whole record, so fill the fields it
+ * computes with neutral values and let an update merge over the existing row.
+ */
+function buildMilestonePayload(data, ctx, existing) {
+    const est = data.estimated_hours ? parseShorthandDuration(String(data.estimated_hours)).duration : '';
+    return {
+        milestone_id: Number(data.milestone_id ?? existing?.milestone_id ?? 0),
+        group_id: Number(data.project_id ?? existing?.group_id ?? 0),
+        user_id: ctx.userId,
+        milestone: (data.title ?? existing?.milestone ?? ''),
+        sequence: Number(data.sequence ?? existing?.sequence ?? 0),
+        start_date: isoDate(data.start_date, String(existing?.start_date ?? nowIso())),
+        due_date: isoDate(data.due_date, String(existing?.due_date ?? nowIso())),
+        estimated_time: est || existing?.estimated_time || '',
+        complete: Boolean(data.complete ?? existing?.complete ?? false),
+        progress: Number(data.progress ?? existing?.progress ?? 0),
+    };
+}
 /**
  * Parse shorthand duration (e.g., "3h", "1h30m", "45m") to HH:MM:SS TimeSpan format.
  */
@@ -33,74 +53,47 @@ function parseShorthandDuration(input) {
 /**
  * Build a full Group_Task payload from simplified MCP tool params.
  */
+/**
+ * Group_Task create payload.
+ *
+ * Modelled on what the ViviScape Work UI actually posts to tasks/add
+ * (ClockWyzWeb/Scripts/app/tasks.js, \$scope.nt): fourteen fields, ids as
+ * strings, estimated_time as shorthand text, and assignment expressed as
+ * staff_assignees [{user_id, attention}].
+ *
+ * The previous version sent a 37-field row with estimated_ticks and a
+ * hand-computed priority_rank, which the API rejected outright ("Invalid Server
+ * Request"). priority_rank is server-computed -- the UI never sends it, and the
+ * live values are not ordinal (low=3, moderate=27, important=86).
+ */
 function buildTaskPayload(data, ctx) {
-    const now = new Date().toISOString();
-    const assignees = [];
-    const userId = data.assigned_to ?? ctx.userId;
-    assignees.push({
-        assignee_id: 0,
-        task_id: 0,
-        user_id: userId,
-        client_id: 0,
-        leader: true,
-        attention: false,
-        promoting: false,
-        pinned: false,
-        notify: true,
-        active: false,
-        activitys: [],
-        duration: '00:00:00',
-        duration_friendly: '-',
-    });
-    // Convert estimated_hours shorthand to ticks (1 tick = 100ns, 1h = 36_000_000_000 ticks)
-    let estimatedTicks = 0;
-    if (data.estimated_hours) {
-        const parsed = parseShorthandDuration(String(data.estimated_hours));
-        const [h, m] = parsed.duration.split(':').map(Number);
-        estimatedTicks = ((h * 60 + m) * 60) * 10_000_000;
-    }
-    const priorityMap = { low: 1, medium: 2, high: 3, critical: 4 };
-    const priorityStr = String(data.priority || 'medium');
-    const priorityRank = priorityMap[priorityStr] ?? 2;
-    return {
-        task_id: 0,
-        group_id: data.project_id ?? 0,
-        company_id: data.company_id ?? 0,
-        service_id: data.service_id ?? 0,
+    const start = isoDate(data.start_date, nowIso());
+    const payload = {
+        status: data.status || 'new',
+        account_id: ctx.accountId,
+        service_id: String(data.service_id ?? 0),
+        estimated_time: data.estimated_hours ? String(data.estimated_hours) : '8h',
+        group_id: String(data.project_id ?? 0),
+        milestone_id: String(data.milestone_id ?? 0),
         task: data.title ?? '',
+        review_required: '0',
         description: data.description ?? '',
-        notes: data.notes ?? '',
-        status: data.status ?? 'new',
-        priority: priorityStr,
-        priority_rank: priorityRank,
-        start: data.start_date ?? now,
-        end: data.due_date ?? now,
-        creation_date: now,
-        complete_date: '1901-01-01T00:00:00+00:00',
-        estimated_ticks: estimatedTicks,
-        task_type: data.task_type ?? 'task',
-        isbillable: data.isbillable ?? false,
-        creator_id: userId,
-        milestone_id: data.milestone_id ?? 0,
-        client_id: 0,
-        event_id: 0,
-        account_id: ctx.accountId,
-        percentage: 0,
-        attention: false,
-        pinned: false,
-        assign_all_staff: false,
-        agg_cost: 0,
-        agg_rate: 0,
-        predecessor_id: 0,
-        predecessor_complete: false,
-        predecessor_name: '',
-        review_required: false,
-        parts: '',
-        staff_assignees: assignees,
-        client_assignees: [],
-        task_files: [],
-        logs: [],
+        priority: data.priority || 'low',
+        // The signed-in user creates the task. Assignment is separate -- see
+        // staff_assignees below and the task_assignee_* tools.
+        creator_id: ctx.userId,
+        start,
+        end: isoDate(data.due_date, start),
+        focus: false,
     };
+    if (data.notes)
+        payload.notes = data.notes;
+    if (data.company_id)
+        payload.company_id = data.company_id;
+    if (data.assigned_to) {
+        payload.staff_assignees = [{ user_id: Number(data.assigned_to), attention: false }];
+    }
+    return payload;
 }
 /**
  * Build update fields for a Group_Task, mapping friendly names to API names.
@@ -187,6 +180,7 @@ function buildTimeLogPayload(data, ctx) {
     };
 }
 const EPOCH = '2000-01-01T00:00:00';
+const EMPTY_GUID = '00000000-0000-0000-0000-000000000000';
 function isoDate(value, fallback) {
     if (typeof value === 'string' && value.trim())
         return value;
@@ -371,6 +365,68 @@ export class ViviScapeClient {
     async getActiveProjectsByUser(userId) {
         return this.get(`user/groups/active?user_id=${userId || this.userId}&account_id=${this.accountId}`);
     }
+    /**
+     * Create a project (group). GEN_Group has ~40 fields; live rows for this
+     * tenant show account_id 0, platform_account_id = pid, and group type 5
+     * (PROJECT), so those are the defaults here.
+     *
+     * There is no delete route for projects -- a created project can only be
+     * archived or renamed afterward.
+     */
+    async addProject(data) {
+        return this.post('groups/add', {
+            intGroupId: 0,
+            intGroupTypeId: GROUP_TYPES.PROJECT,
+            intCompanyId: data.company_id,
+            intPostPermission: 0,
+            intEventId: 0,
+            intGroupBeacon: 0,
+            decBalance: 0,
+            strImage: '',
+            strImageThumb: '',
+            strGroupName: data.name,
+            strGroupShortDescription: data.short_description || '',
+            strGroupDescription: data.description || '',
+            strGroupLink: '',
+            bitActive: true,
+            bitPublic: data.is_public ?? false,
+            intCapacity: 0,
+            intStaff: 0,
+            intMembers: 0,
+            intPayoutAccountId: 0,
+            Clients: [],
+            Staff: data.staff && data.staff.length ? data.staff : [this.userId],
+            account_id: 0,
+            platform_account_id: this.accountId,
+            user_id: this.userId,
+            status: data.status || 'new',
+            enabledWelcome: false,
+            enabledGoodbye: false,
+            showClients: false,
+            welcomeMessage: '',
+            goodbyeMessage: '',
+        });
+    }
+    /** Update a project by merging changes onto the row the API already has. */
+    async updateProject(projectId, changes) {
+        const existing = await this.getProjectById(projectId);
+        const row = Array.isArray(existing) ? existing[0] : existing;
+        if (!row || typeof row !== 'object') {
+            throw new ApiError(404, `Project ${projectId} not found, cannot update.`);
+        }
+        return this.post('groups/update', { ...row, ...changes });
+    }
+    /** Status-only update; leaves budget and approved time untouched. */
+    async setProjectStatus(projectId, status, billable = true) {
+        return this.get(`groups/update/status?groupid=${projectId}&status=${encodeURIComponent(status)}&billable=${billable}`);
+    }
+    async addProjectUser(projectId, userId, opts = {}) {
+        return this.get(`groups/user/add?userid=${userId}&groupid=${projectId}` +
+            `&iscontact=${opts.is_contact ?? false}&islead=${opts.is_lead ?? false}`);
+    }
+    async removeProjectUser(projectId, userId) {
+        return this.get(`groups/user/remove?groupid=${projectId}&userid=${userId}`);
+    }
     // -- Tasks --------------------------------------------------
     async addTask(data) {
         return this.post('tasks/add', buildTaskPayload(data, this.ctx));
@@ -385,15 +441,19 @@ export class ViviScapeClient {
     async getProjectTasks(projectId) {
         return this.get(`tasks/group?group_id=${projectId}`);
     }
-    async getOpenTasks() {
+    /**
+     * The account/tasks/open route filters server-side on company, ownership, and
+     * a date window; pass them through instead of hardcoding "everything".
+     */
+    async getOpenTasks(opts = {}) {
         return this.post('account/tasks/open', {
             account_id: this.accountId,
             user_id: this.userId,
-            start: EPOCH,
-            end: nowIso(),
-            company_id: 0,
-            teamfilter: '',
-            onlymytasks: false,
+            start: opts.start || EPOCH,
+            end: opts.end || nowIso(),
+            company_id: opts.company_id ?? 0,
+            teamfilter: opts.team || '',
+            onlymytasks: opts.only_mine ?? false,
         });
     }
     async getTask(taskId) {
@@ -411,6 +471,178 @@ export class ViviScapeClient {
     async getCompanyTasks(companyId) {
         return this.get(`company/tasks?company_id=${companyId}&user_id=${this.userId}`);
     }
+    // -- Task comments ------------------------------------------
+    async getTaskComments(taskId) {
+        return this.get(`task/comments/${taskId}`);
+    }
+    async getTaskComment(commentId) {
+        return this.get(`task/comment/id/${commentId}`);
+    }
+    /**
+     * NOTE: on platform account 1, the backend fires a client-notification webhook
+     * for comments on tasks whose client_id > 0. Adding a comment can therefore
+     * reach the customer -- the tool description says so too.
+     */
+    async addTaskComment(data) {
+        return this.post('task/comment/add', {
+            comment_id: EMPTY_GUID,
+            task_id: data.task_id,
+            user_id: this.userId,
+            client_id: data.client_id ?? 0,
+            creator: this.creds.name || this.creds.email || String(this.userId),
+            comment: data.comment,
+            attachment_file: '',
+            attachment_url: '',
+            source: data.source || APP_NAME,
+            comment_date: nowIso(),
+        });
+    }
+    async updateTaskComment(data) {
+        return this.post('task/comment/update', {
+            comment_id: data.comment_id,
+            task_id: data.task_id,
+            user_id: this.userId,
+            client_id: 0,
+            creator: this.creds.name || this.creds.email || String(this.userId),
+            comment: data.comment,
+            attachment_file: '',
+            attachment_url: '',
+            source: APP_NAME,
+            comment_date: nowIso(),
+        });
+    }
+    /**
+     * The backend's remove proxy answers 500 even on success: it returns 400 when
+     * the upstream delete fails, so a 500 means it crashed deserializing an empty
+     * success body (res.data.ToString() on null). Verify by re-reading the thread
+     * rather than reporting a failure that did not happen.
+     */
+    async removeTaskComment(commentId, taskId) {
+        try {
+            return await this.get(`task/comment/remove/${commentId}`);
+        }
+        catch (err) {
+            if (!(err instanceof ApiError) || err.status !== 500)
+                throw err;
+            if (!taskId) {
+                throw new ApiError(500, `API returned 500 removing comment ${commentId}. This backend answers 500 even when the ` +
+                    'delete succeeds; pass task_id so the removal can be verified by re-reading the thread.');
+            }
+            const rows = await this.getTaskComments(taskId);
+            const present = Array.isArray(rows)
+                && rows.some((r) => String(r.comment_id).toLowerCase() === commentId.toLowerCase());
+            if (present)
+                throw err;
+            return {
+                removed: true,
+                comment_id: commentId,
+                task_id: taskId,
+                note: 'Backend returned 500 while serializing its response; verified removed by re-reading the thread.',
+            };
+        }
+    }
+    async markTaskRead(taskId) {
+        return this.post('task/read/mark', { task_id: taskId, user_id: this.userId });
+    }
+    // -- Task assignment and lifecycle --------------------------
+    async addTaskAssignee(data) {
+        return this.post('tasks/assignee/add', {
+            assignee_id: 0,
+            task_id: data.task_id,
+            user_id: data.user_id,
+            client_id: 0,
+            active: true,
+            leader: data.leader ?? false,
+            attention: data.attention ?? false,
+            promoting: false,
+            pinned: false,
+            notify: data.notify ?? true,
+        });
+    }
+    /** Takes the assignee_id from the task's staff_assignees, not a user_id. */
+    async removeTaskAssignee(assigneeId) {
+        return this.get(`tasks/assignee/remove?assignee_id=${assigneeId}`);
+    }
+    async setTaskLeader(taskId, userId) {
+        return this.get(`task/assign/leader/${taskId}/${userId}`);
+    }
+    async setTaskAttention(taskId, userId, flag) {
+        return this.get(`task/assign/attention/${taskId}/${userId}/${flag}`);
+    }
+    async deleteTask(taskId) {
+        return this.get(`tasks/delete?task_id=${taskId}`);
+    }
+    /** Fold one task into another; the source task is consumed. */
+    async mergeTasks(fromTaskId, toTaskId) {
+        return this.post('tasks/merge', { task_from_id: fromTaskId, task_to_id: toTaskId });
+    }
+    // -- Milestones ---------------------------------------------
+    async getMilestones(projectId) {
+        return this.get(`milestones/list/${projectId}`);
+    }
+    async getActiveMilestones() {
+        return this.get(`milestones/active/account/${this.accountId}`);
+    }
+    async getMilestonesByCompany(companyId) {
+        return this.get(`milestones/account/${this.accountId}/${companyId}`);
+    }
+    async getMilestonesByUser(userId) {
+        return this.get(`milestones/user/active/account/${this.accountId}/${userId || this.userId}`);
+    }
+    async getMilestone(milestoneId) {
+        return this.get(`milestone/id/${milestoneId}`);
+    }
+    async addMilestone(data) {
+        return this.post('milestone/add', buildMilestonePayload(data, this.ctx));
+    }
+    async updateMilestone(data) {
+        if (data.milestone_id) {
+            const existing = await this.getMilestone(Number(data.milestone_id));
+            const row = Array.isArray(existing) ? existing[0] : existing;
+            if (row && typeof row === 'object') {
+                return this.post('milestone/update', { ...row, ...buildMilestonePayload(data, this.ctx, row) });
+            }
+        }
+        return this.post('milestone/update', buildMilestonePayload(data, this.ctx));
+    }
+    /** Copy a milestone (and its task template) into a project. */
+    async cloneMilestone(milestoneId, projectId, title) {
+        const existing = await this.getMilestone(milestoneId);
+        const row = (Array.isArray(existing) ? existing[0] : existing);
+        if (!row || typeof row !== 'object') {
+            throw new ApiError(404, `Milestone ${milestoneId} not found, cannot clone.`);
+        }
+        return this.post('milestone/clone', {
+            ...row,
+            milestone_id: milestoneId,
+            group_id: projectId,
+            user_id: this.userId,
+            ...(title ? { milestone: title } : {}),
+        });
+    }
+    /**
+     * Known broken upstream: milestone/remove answers 500 and the milestone
+     * survives. The proxy returns 400 with detail when the upstream delete fails,
+     * so the 500 is a crash in its own success branch (Convert.ToBoolean on a
+     * non-boolean data payload) -- but unlike the comment-remove case the record
+     * is genuinely still there. Verify and say so plainly instead of pretending.
+     */
+    async removeMilestone(milestoneId) {
+        try {
+            return await this.get(`milestone/remove/${milestoneId}`);
+        }
+        catch (err) {
+            if (!(err instanceof ApiError) || err.status !== 500)
+                throw err;
+            const still = await this.getMilestone(milestoneId).catch(() => null);
+            const row = Array.isArray(still) ? still[0] : still;
+            if (row && typeof row === 'object' && row.milestone_id) {
+                throw new ApiError(500, `milestone/remove/${milestoneId} returned 500 and the milestone still exists. ` +
+                    'This route is broken server-side; delete the milestone in the ViviScape Work UI.');
+            }
+            return { removed: true, milestone_id: milestoneId, note: 'Backend returned 500 but the milestone is gone.' };
+        }
+    }
     // -- Time logs ----------------------------------------------
     async addTimeLog(data) {
         return this.post('logs/add', buildTimeLogPayload(data, this.ctx));

package/dist/auth/permissions.js

@@ -62,6 +62,8 @@ export function featureForPath(path) {
         return 'logs';
     if (p.startsWith('prospect'))
         return 'crm';
+    if (p.startsWith('task/comment'))
+        return 'comment';
     if (p.startsWith('task'))
         return 'tasks';
     return 'auth';

package/dist/enums.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Status and priority vocabularies as the platform actually defines them.
+ *
+ * Source of truth is the ViviScape Work UI, not guesswork:
+ *   ClockWyzWeb/Views/App/Tasks.cshtml     -- task status + priority selects
+ *   ClockWyzWeb/Views/App/Projects.cshtml  -- task editor and project status selects
+ * Cross-checked against live rows from account 1 (211 projects, 6 open tasks).
+ *
+ * Two traps worth knowing:
+ *  - Tasks complete as "completed"; projects complete as "complete".
+ *  - Priority is low/moderate/important/urgent/critical. It is NOT
+ *    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"];
+/** Task and project priority values, ascending. */
+export declare const PRIORITIES: readonly ["low", "moderate", "important", "urgent", "critical"];
+/**
+ * Project (group) status values. Narrower than task status, and note "complete"
+ * rather than "completed". An empty status reads as "Undetermined" in the UI.
+ */
+export declare const PROJECT_STATUSES: readonly ["new", "inprogress", "complete"];
+/** Prospect pipeline stages, from the CRM tools. */
+export declare const PROSPECT_STATUSES: readonly ["new", "firstcontact", "negotiation", "pending", "won", "lost", "spam"];
+/** Group type ids; 5 (PROJECT) is what project tools create and expect. */
+export declare const GROUP_TYPES: {
+    readonly GENERAL: 1;
+    readonly TEAM: 3;
+    readonly SUPPORT: 4;
+    readonly PROJECT: 5;
+};
+export type TaskStatus = (typeof TASK_STATUSES)[number];
+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"];
+    priority: readonly ["low", "moderate", "important", "urgent", "critical"];
+    project_status: readonly ["new", "inprogress", "complete"];
+    prospect_status: readonly ["new", "firstcontact", "negotiation", "pending", "won", "lost", "spam"];
+    group_types: {
+        readonly GENERAL: 1;
+        readonly TEAM: 3;
+        readonly SUPPORT: 4;
+        readonly PROJECT: 5;
+    };
+    notes: string[];
+};

package/dist/enums.js

@@ -0,0 +1,67 @@
+/**
+ * Status and priority vocabularies as the platform actually defines them.
+ *
+ * Source of truth is the ViviScape Work UI, not guesswork:
+ *   ClockWyzWeb/Views/App/Tasks.cshtml     -- task status + priority selects
+ *   ClockWyzWeb/Views/App/Projects.cshtml  -- task editor and project status selects
+ * Cross-checked against live rows from account 1 (211 projects, 6 open tasks).
+ *
+ * Two traps worth knowing:
+ *  - Tasks complete as "completed"; projects complete as "complete".
+ *  - Priority is low/moderate/important/urgent/critical. It is NOT
+ *    low/medium/high, which is what this server's task_add used to claim.
+ */
+/** Task status values, in board order. */
+export const TASK_STATUSES = [
+    'backlog',
+    'new',
+    'research',
+    'inprogress',
+    'pendingreview',
+    'inreview',
+    'testing',
+    'waitingcustomer',
+    'waitingteammember',
+    'onhold',
+    'cancelled',
+    'completed',
+];
+/** Task and project priority values, ascending. */
+export const PRIORITIES = ['low', 'moderate', 'important', 'urgent', 'critical'];
+/**
+ * Project (group) status values. Narrower than task status, and note "complete"
+ * rather than "completed". An empty status reads as "Undetermined" in the UI.
+ */
+export const PROJECT_STATUSES = ['new', 'inprogress', 'complete'];
+/** Prospect pipeline stages, from the CRM tools. */
+export const PROSPECT_STATUSES = [
+    'new',
+    'firstcontact',
+    'negotiation',
+    'pending',
+    'won',
+    'lost',
+    'spam',
+];
+/** Group type ids; 5 (PROJECT) is what project tools create and expect. */
+export const GROUP_TYPES = {
+    GENERAL: 1,
+    TEAM: 3,
+    SUPPORT: 4,
+    PROJECT: 5,
+};
+/** Payload for the enums tool, so callers can discover these without guessing. */
+export function enumReference() {
+    return {
+        task_status: TASK_STATUSES,
+        priority: PRIORITIES,
+        project_status: PROJECT_STATUSES,
+        prospect_status: PROSPECT_STATUSES,
+        group_types: GROUP_TYPES,
+        notes: [
+            'Tasks use "completed"; projects use "complete".',
+            'Priority is low/moderate/important/urgent/critical -- not low/medium/high.',
+            'An empty project status displays as "Undetermined".',
+        ],
+    };
+}

package/dist/index.js

@@ -6,6 +6,8 @@ import { config } from 'dotenv';
 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 { PROJECT_FIELDS, TASK_FIELDS, 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 });
@@ -37,6 +39,39 @@ const server = new McpServer({
 function json(data) {
     return JSON.stringify(data, null, 2);
 }
+/**
+ * Phase 2 (docs/AGENT-CAPABILITY-SPEC.md): list rows carry ~90 columns, so every
+ * list tool takes a page window and an optional field list. Defaults keep the
+ * response inside a tool-result budget; fields:["all"] opts out.
+ */
+const pageArgs = {
+    fields: z.array(z.string()).optional()
+        .describe('Columns to return. Omit for a PM-relevant default; ["all"] for every column.'),
+    limit: z.number().optional().describe('Max rows to return (default 50)'),
+    offset: z.number().optional().describe('Rows to skip, for paging (default 0)'),
+};
+const taskFilterArgs = {
+    company_id: z.number().optional().describe('Only tasks for this company'),
+    project_id: z.number().optional().describe('Only tasks in this project (group_id)'),
+    assignee_id: z.number().optional().describe('Only tasks assigned to this user id'),
+    status: z.string().optional().describe('Exact status match, e.g. new, inprogress'),
+    priority: z.string().optional().describe('Exact priority match, e.g. low, moderate, important, critical'),
+    due_before: z.string().optional().describe('Only tasks due on or before this date (ISO 8601)'),
+    due_after: z.string().optional().describe('Only tasks due on or after this date (ISO 8601)'),
+    search: z.string().optional().describe('Case-insensitive substring match on title, description, notes'),
+};
+// Variants that drop the key a given tool already takes as a required arg,
+// so the spread cannot overwrite it with an optional one.
+const { project_id: _omitProject, ...taskFilterArgsNoProject } = taskFilterArgs;
+const { company_id: _omitCompany, ...taskFilterArgsNoCompany } = taskFilterArgs;
+/** Split a tool's params into page options and everything else. */
+function paging(p) {
+    return {
+        fields: p.fields,
+        limit: p.limit,
+        offset: p.offset,
+    };
+}
 // ============================================================
 // AUTH
 // ============================================================
@@ -112,7 +147,7 @@ server.tool('prospect_add', 'Add a new prospect/lead to the ViviScape CRM', {
     source: z.string().optional().describe('Lead source (e.g., "Website", "ROI Calculator")'),
     source_url: z.string().optional().describe('URL where the lead came from'),
     referred_by: z.string().optional().describe('Referral source'),
-    status: z.string().optional().describe('Status: new, firstcontact, negotiation, pending, won, lost, spam'),
+    status: z.enum(PROSPECT_STATUSES).optional().describe('Pipeline stage (platform values)'),
 }, async (params) => {
     const result = await requireClient().addProspect(params);
     return { content: [{ type: 'text', text: json(result) }] };
@@ -127,7 +162,7 @@ server.tool('prospect_update', 'Update an existing prospect in the CRM', {
     org: z.string().optional(),
     note: z.string().optional(),
     source: z.string().optional(),
-    status: z.string().optional().describe('Status: new, firstcontact, negotiation, pending, won, lost, spam'),
+    status: z.enum(PROSPECT_STATUSES).optional().describe('Pipeline stage (platform values)'),
     priority: z.number().optional().describe('Priority level'),
 }, async (params) => {
     const result = await requireClient().updateProspect(params);
@@ -272,13 +307,17 @@ server.tool('clients_by_company', 'Get all clients for a company', { company_id:
 // ============================================================
 // PROJECTS & TASKS
 // ============================================================
-server.tool('project_list', 'Get all projects for current user', {}, async () => {
+server.tool('project_list', 'Get all projects for current user. Returns a page of trimmed rows; see fields/limit/offset.', {
+    ...pageArgs,
+}, async (params) => {
     const result = await requireClient().getMyProjects();
-    return { content: [{ type: 'text', text: json(result) }] };
+    return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
 });
-server.tool('project_list_active', 'Get active projects for current user', {}, async () => {
+server.tool('project_list_active', 'Get active projects for current user. Returns a page of trimmed rows; see fields/limit/offset.', {
+    ...pageArgs,
+}, async (params) => {
     const result = await requireClient().getActiveProjects();
-    return { content: [{ type: 'text', text: json(result) }] };
+    return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
 });
 server.tool('project_get', 'Get a project by ID', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
     const result = await requireClient().getProjectById(project_id);
@@ -288,23 +327,43 @@ server.tool('project_staff', 'Get staff members assigned to a project', { projec
     const result = await requireClient().getProjectStaff(project_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('project_tasks', 'Get all tasks for a project', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
-    const result = await requireClient().getProjectTasks(project_id);
-    return { content: [{ type: 'text', text: json(result) }] };
-});
-server.tool('tasks_open', 'Get all open tasks across projects', {}, async () => {
-    const result = await requireClient().getOpenTasks();
-    return { content: [{ type: 'text', text: json(result) }] };
+server.tool('project_tasks', 'Get all tasks for a project. Returns a page of trimmed rows; see fields/limit/offset.', {
+    project_id: z.number().describe('Project ID'),
+    ...pageArgs,
+    ...taskFilterArgsNoProject,
+}, async (params) => {
+    const result = await requireClient().getProjectTasks(params.project_id);
+    // 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 })
+        : 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.', {
+    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,
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getOpenTasks({
+        company_id: params.company_id,
+        only_mine: params.only_mine,
+        team: params.team,
+    });
+    const rows = Array.isArray(result) ? 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.', {
     project_id: z.number().describe('Project ID (group_id)'),
     title: z.string().describe('Task title'),
     description: z.string().optional().describe('Task description'),
     notes: z.string().optional().describe('Task notes'),
-    assigned_to: z.number().optional().describe('User ID to assign to (also sets creator). Defaults to Art Hicks (210)'),
+    assigned_to: z.number().optional().describe('User ID to assign the task to. The signed-in user is always recorded as creator.'),
     company_id: z.number().optional().describe('Company ID associated with the project'),
     service_id: z.number().optional().describe('Service ID classifying the work type'),
-    priority: z.string().optional().describe('Priority: low, medium, high, critical'),
+    priority: z.enum(PRIORITIES).optional().describe('Priority (platform values)'),
+    status: z.enum(TASK_STATUSES).optional().describe('Task status (platform values)'),
     estimated_hours: z.string().optional().describe('Estimated time in shorthand (e.g., 6h, 2h30m)'),
     start_date: z.string().optional().describe('Start date (ISO 8601)'),
     due_date: z.string().optional().describe('Due date (ISO 8601)'),
@@ -318,8 +377,8 @@ server.tool('task_update', 'Update a task. Fetches existing task first and merge
     title: z.string().optional().describe('Task title'),
     description: z.string().optional(),
     assigned_to: z.number().optional().describe('User ID to assign to'),
-    priority: z.string().optional().describe('Priority: low, medium, high, critical'),
-    status: z.string().optional().describe('Status: new, inprogress, complete, onhold'),
+    priority: z.enum(PRIORITIES).optional().describe('Priority (platform values)'),
+    status: z.enum(TASK_STATUSES).optional().describe('Task status (platform values)'),
     due_date: z.string().optional().describe('Due date (ISO 8601)'),
 }, async (params) => {
     const result = await requireClient().updateTask(params);
@@ -329,34 +388,248 @@ 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('tasks_pending', 'Get pending tasks for a user', { user_id: z.number().describe('User ID') }, async ({ user_id }) => {
-    const result = await requireClient().getPendingTasks(user_id);
+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,
+    ...taskFilterArgs,
+}, async (params) => {
+    const result = await requireClient().getPendingTasks(params.user_id);
+    const rows = Array.isArray(result) ? 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.', {
+    milestone_id: z.number().describe('Milestone ID'),
+    ...pageArgs,
+    ...taskFilterArgs,
+}, async (params) => {
+    const result = await requireClient().getTasksByMilestone(params.milestone_id);
+    const rows = Array.isArray(result) ? 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.', {
+    group_id: z.number().describe('Project group ID'),
+    user_id: z.number().describe('User ID'),
+    ...pageArgs,
+    ...taskFilterArgs,
+}, async (params) => {
+    const result = await requireClient().getTasksByGroupAndUser(params.group_id, params.user_id);
+    const rows = Array.isArray(result) ? 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.', {
+    company_id: z.number().describe('Company ID'),
+    ...pageArgs,
+    ...taskFilterArgsNoCompany,
+}, async (params) => {
+    const result = await requireClient().getCompanyTasks(params.company_id);
+    const rows = Array.isArray(result)
+        ? filterTasks(result, { ...params, company_id: undefined })
+        : result;
+    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+});
+server.tool('projects_by_company', 'Get user projects filtered by company. Returns a page of trimmed rows; see fields/limit/offset.', {
+    user_id: z.number().describe('User ID'),
+    company_id: z.number().describe('Company ID'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getProjectsByCompany(params.user_id, params.company_id);
+    return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
+});
+server.tool('projects_active_by_user', 'Get active projects for a specific user. Returns a page of trimmed rows; see fields/limit/offset.', {
+    user_id: z.number().describe('User ID'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getActiveProjectsByUser(params.user_id);
+    return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
+});
+// ============================================================
+// REFERENCE
+// ============================================================
+server.tool('enums', 'List the status, priority, and group-type values the platform actually accepts. Read this before setting a status or priority; tasks complete as "completed" while projects complete as "complete", and priority is low/moderate/important/urgent/critical.', {}, async () => ({ content: [{ type: 'text', text: json(enumReference()) }] }));
+// ============================================================
+// PROJECT WRITES
+// ============================================================
+server.tool('project_add', 'Create a project for a company. NOTE: the API has no project-delete route, so a project created here can only be archived or renamed afterward.', {
+    company_id: z.number().describe('Company ID the project belongs to'),
+    name: z.string().describe('Project name'),
+    short_description: z.string().optional().describe('One-line summary'),
+    description: z.string().optional().describe('Full description'),
+    status: z.enum(PROJECT_STATUSES).optional().describe('Initial status (default new)'),
+    is_public: z.boolean().optional().describe('Visible to clients (default false)'),
+    staff: z.array(z.number()).optional().describe('User ids to staff; defaults to the signed-in user'),
+}, async (params) => {
+    const result = await requireClient().addProject(params);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('tasks_by_milestone', 'Get tasks for a milestone', { milestone_id: z.number().describe('Milestone ID') }, async ({ milestone_id }) => {
-    const result = await requireClient().getTasksByMilestone(milestone_id);
+server.tool('project_update', 'Update a project. Reads the current row and merges your changes onto it, so only pass what changes. Field names are the raw GEN_Group ones (strGroupName, strGroupDescription, bitPublic, target_date, ...).', {
+    project_id: z.number().describe('Project ID (intGroupId)'),
+    changes: z.record(z.string(), z.unknown()).describe('Fields to overwrite, e.g. {"strGroupName":"New name"}'),
+}, async ({ project_id, changes }) => {
+    const result = await requireClient().updateProject(project_id, changes);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('tasks_by_group_user', 'Get tasks by project group and user', {
-    group_id: z.number().describe('Project group ID'),
-    user_id: z.number().describe('User ID'),
-}, async ({ group_id, user_id }) => {
-    const result = await requireClient().getTasksByGroupAndUser(group_id, user_id);
+server.tool('project_set_status', 'Set a project status without touching its budget or approved time. Project status values are new, inprogress, complete -- note "complete", not "completed".', {
+    project_id: z.number().describe('Project ID'),
+    status: z.enum(PROJECT_STATUSES).describe('New status'),
+    billable: z.boolean().optional().describe('Billable flag (default true)'),
+}, async ({ project_id, status, billable }) => {
+    const result = await requireClient().setProjectStatus(project_id, status, billable ?? true);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('project_user_add', 'Add a staff member to a project, optionally as lead or client contact', {
+    project_id: z.number().describe('Project ID'),
+    user_id: z.number().describe('User ID to add'),
+    is_lead: z.boolean().optional().describe('Make this user the project lead'),
+    is_contact: z.boolean().optional().describe('Mark as the client contact'),
+}, async ({ project_id, user_id, is_lead, is_contact }) => {
+    const result = await requireClient().addProjectUser(project_id, user_id, { is_lead, is_contact });
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('project_user_remove', 'Remove a staff member from a project', {
+    project_id: z.number().describe('Project ID'),
+    user_id: z.number().describe('User ID to remove'),
+}, async ({ project_id, user_id }) => {
+    const result = await requireClient().removeProjectUser(project_id, user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// MILESTONES
+// ============================================================
+server.tool('milestone_list', 'List milestones for a project', { project_id: z.number().describe('Project ID') }, async ({ project_id }) => {
+    const result = await requireClient().getMilestones(project_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('tasks_by_company', 'Get tasks for a company', { company_id: z.number().describe('Company ID') }, async ({ company_id }) => {
-    const result = await requireClient().getCompanyTasks(company_id);
+server.tool('milestones_active', 'List active milestones across the account', {}, async () => {
+    const result = await requireClient().getActiveMilestones();
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('projects_by_company', 'Get user projects filtered by company', {
+server.tool('milestones_by_company', 'List milestones for a company', { company_id: z.number().describe('Company ID') }, async ({ company_id }) => {
+    const result = await requireClient().getMilestonesByCompany(company_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestones_by_user', 'List active milestones for a user (defaults to the signed-in user)', { user_id: z.number().optional().describe('User ID') }, async ({ user_id }) => {
+    const result = await requireClient().getMilestonesByUser(user_id ?? 0);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestone_get', 'Get a milestone by ID', { milestone_id: z.number().describe('Milestone ID') }, async ({ milestone_id }) => {
+    const result = await requireClient().getMilestone(milestone_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestone_add', 'Create a milestone in a project. Use this to give tasks a phase to hang off; tasks reference it via milestone_id.', {
+    project_id: z.number().describe('Project ID the milestone belongs to'),
+    title: z.string().describe('Milestone name'),
+    sequence: z.number().optional().describe('Order within the project'),
+    start_date: z.string().optional().describe('Start date (ISO 8601)'),
+    due_date: z.string().optional().describe('Due date (ISO 8601)'),
+    estimated_hours: z.string().optional().describe('Estimate in shorthand (e.g., 40h, 2h30m)'),
+}, async (params) => {
+    const result = await requireClient().addMilestone(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestone_update', 'Update a milestone. Reads the current record and merges your changes onto it.', {
+    milestone_id: z.number().describe('Milestone ID'),
+    title: z.string().optional().describe('New name'),
+    sequence: z.number().optional().describe('Order within the project'),
+    start_date: z.string().optional().describe('Start date (ISO 8601)'),
+    due_date: z.string().optional().describe('Due date (ISO 8601)'),
+    estimated_hours: z.string().optional().describe('Estimate in shorthand'),
+    progress: z.number().optional().describe('Percent complete (0-100)'),
+    complete: z.boolean().optional().describe('Mark complete'),
+}, async (params) => {
+    const result = await requireClient().updateMilestone(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestone_clone', 'Copy an existing milestone into a project. Useful for repeatable delivery templates.', {
+    milestone_id: z.number().describe('Milestone ID to copy'),
+    project_id: z.number().describe('Project ID to copy it into'),
+    title: z.string().optional().describe('Name for the copy (defaults to the original name)'),
+}, async ({ milestone_id, project_id, title }) => {
+    const result = await requireClient().cloneMilestone(milestone_id, project_id, title);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('milestone_remove', 'Delete a milestone', { milestone_id: z.number().describe('Milestone ID') }, async ({ milestone_id }) => {
+    const result = await requireClient().removeMilestone(milestone_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// TASK ASSIGNMENT AND LIFECYCLE
+// ============================================================
+server.tool('task_assignee_add', 'Assign a user to a task', {
+    task_id: z.number().describe('Task ID'),
+    user_id: z.number().describe('User ID to assign'),
+    leader: z.boolean().optional().describe('Make this user the task leader'),
+    attention: z.boolean().optional().describe('Flag the task for this user\'s attention'),
+    notify: z.boolean().optional().describe('Notify the user (default true)'),
+}, async (params) => {
+    const result = await requireClient().addTaskAssignee(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_assignee_remove', 'Unassign a user from a task. Takes the assignee_id from the task staff_assignees list, NOT a user_id.', { assignee_id: z.number().describe('Assignee record ID (from staff_assignees)') }, async ({ assignee_id }) => {
+    const result = await requireClient().removeTaskAssignee(assignee_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_set_leader', 'Make a user the leader on a task', {
+    task_id: z.number().describe('Task ID'),
+    user_id: z.number().describe('User ID to make leader'),
+}, async ({ task_id, user_id }) => {
+    const result = await requireClient().setTaskLeader(task_id, user_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_set_attention', 'Set or clear the attention flag for a user on a task', {
+    task_id: z.number().describe('Task ID'),
     user_id: z.number().describe('User ID'),
-    company_id: z.number().describe('Company ID'),
-}, async ({ user_id, company_id }) => {
-    const result = await requireClient().getProjectsByCompany(user_id, company_id);
+    flag: z.boolean().describe('true to flag, false to clear'),
+}, async ({ task_id, user_id, flag }) => {
+    const result = await requireClient().setTaskAttention(task_id, user_id, flag);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_delete', 'Delete a task permanently. There is no undo; prefer setting status to cancelled unless the task was created in error.', { task_id: z.number().describe('Task ID') }, async ({ task_id }) => {
+    const result = await requireClient().deleteTask(task_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_merge', 'Merge one task into another. The source task is consumed by the target; use this to clean up duplicates.', {
+    from_task_id: z.number().describe('Task to merge from (consumed)'),
+    to_task_id: z.number().describe('Task to merge into (kept)'),
+}, async ({ from_task_id, to_task_id }) => {
+    const result = await requireClient().mergeTasks(from_task_id, to_task_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// TASK COMMENTS
+// ============================================================
+server.tool('task_comments', 'Get all comments on a task. Task rows report total_comments and unread_for_me; this reads the thread itself.', { task_id: z.number().describe('Task ID') }, async ({ task_id }) => {
+    const result = await requireClient().getTaskComments(task_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_comment_get', 'Get a single task comment by ID', { comment_id: z.string().describe('Comment ID (GUID)') }, async ({ comment_id }) => {
+    const result = await requireClient().getTaskComment(comment_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_comment_add', 'Add a comment to a task. WARNING: on this platform account the backend fires a client-notification webhook for comments on tasks whose client_id > 0, so a comment can reach the customer. Check the task client_id first if that matters.', {
+    task_id: z.number().describe('Task ID'),
+    comment: z.string().describe('Comment text'),
+    client_id: z.number().optional().describe('Client ID to attribute the comment to (default 0 = staff comment)'),
+}, async (params) => {
+    const result = await requireClient().addTaskComment(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_comment_update', 'Update the text of an existing task comment', {
+    comment_id: z.string().describe('Comment ID (GUID)'),
+    task_id: z.number().describe('Task ID the comment belongs to'),
+    comment: z.string().describe('Replacement comment text'),
+}, async (params) => {
+    const result = await requireClient().updateTaskComment(params);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_comment_remove', 'Remove a task comment by ID. Pass task_id: the backend answers 500 even when the delete succeeds, and task_id lets the removal be verified instead of reported as a failure.', {
+    comment_id: z.string().describe('Comment ID (GUID)'),
+    task_id: z.number().optional().describe('Task the comment belongs to, used to verify removal'),
+}, async ({ comment_id, task_id }) => {
+    const result = await requireClient().removeTaskComment(comment_id, task_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('projects_active_by_user', 'Get active projects for a specific user', { user_id: z.number().describe('User ID') }, async ({ user_id }) => {
-    const result = await requireClient().getActiveProjectsByUser(user_id);
+server.tool('task_mark_read', 'Mark a task read for the signed-in user, clearing unread_for_me', { task_id: z.number().describe('Task ID') }, async ({ task_id }) => {
+    const result = await requireClient().markTaskRead(task_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
 // ============================================================

package/dist/projection.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Response shaping for list tools -- phase 2 of docs/AGENT-CAPABILITY-SPEC.md.
+ *
+ * The core API returns every column it has: a task row carries ~90 fields
+ * (including fleet columns like vin and unit_class) and a project row carries 87
+ * (including video-conference config and welcome messages). Six open tasks came
+ * back as 102 KB; 211 active projects as 487 KB, which no caller can afford to
+ * 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. */
+export declare const TASK_FIELDS: string[];
+/** Project (group) fields worth returning by default, of 87 available. */
+export declare const PROJECT_FIELDS: string[];
+export declare const DEFAULT_LIMIT = 50;
+export interface ShapeOpts {
+    fields?: string[];
+    limit?: number;
+    offset?: number;
+}
+export interface TaskFilters {
+    company_id?: number;
+    project_id?: number;
+    assignee_id?: number;
+    status?: string;
+    priority?: string;
+    due_before?: string;
+    due_after?: string;
+    search?: string;
+}
+/** Apply the filters the backend does not support, in-process. */
+export declare function filterTasks(rows: unknown[], f: TaskFilters): unknown[];
+/**
+ * Trim, page, and annotate a list response. Non-array payloads (a single record,
+ * or an error object) pass through untouched.
+ *
+ * Pass fields: ['all'] to opt out of projection and get every column.
+ */
+export declare function shape(payload: unknown, defaults: string[], opts?: ShapeOpts): unknown;

package/dist/projection.js

@@ -0,0 +1,116 @@
+/**
+ * Response shaping for list tools -- phase 2 of docs/AGENT-CAPABILITY-SPEC.md.
+ *
+ * The core API returns every column it has: a task row carries ~90 fields
+ * (including fleet columns like vin and unit_class) and a project row carries 87
+ * (including video-conference config and welcome messages). Six open tasks came
+ * back as 102 KB; 211 active projects as 487 KB, which no caller can afford to
+ * 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. */
+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',
+];
+/** Project (group) fields worth returning by default, of 87 available. */
+export const PROJECT_FIELDS = [
+    'intGroupId', 'strGroupName', 'intCompanyId', 'strCompany',
+    'status', 'bitActive', 'group_type', 'percentage',
+    'total_tasks', 'total_tasks_open', 'total_tasks_completed',
+    'target_date', 'complete_date', 'total_estimated_str', 'total_duration_str',
+];
+export const DEFAULT_LIMIT = 50;
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Parse the staff_assignees blob, which arrives as JSON text or as an array. */
+function assigneeIds(row) {
+    const raw = row.staff_assignees;
+    let arr = raw;
+    if (typeof raw === 'string') {
+        try {
+            arr = JSON.parse(raw);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(arr))
+        return [];
+    return arr
+        .map((u) => (isRecord(u) ? Number(u.user_id) : Number(u)))
+        .filter((n) => Number.isFinite(n));
+}
+const lower = (v) => String(v ?? '').toLowerCase();
+/** Apply the filters the backend does not support, in-process. */
+export function filterTasks(rows, f) {
+    return rows.filter((row) => {
+        if (!isRecord(row))
+            return true;
+        if (f.company_id && Number(row.company_id) !== f.company_id)
+            return false;
+        if (f.project_id && Number(row.group_id) !== f.project_id)
+            return false;
+        if (f.status && lower(row.status) !== f.status.toLowerCase())
+            return false;
+        if (f.priority && lower(row.priority) !== f.priority.toLowerCase())
+            return false;
+        if (f.assignee_id && !assigneeIds(row).includes(f.assignee_id))
+            return false;
+        if (f.search) {
+            const hay = `${lower(row.task)} ${lower(row.description)} ${lower(row.notes)}`;
+            if (!hay.includes(f.search.toLowerCase()))
+                return false;
+        }
+        // `end` is the task's own due date; `deadline` is a human string ("In 2 Days").
+        if (f.due_before || f.due_after) {
+            const due = Date.parse(String(row.end ?? ''));
+            if (!Number.isFinite(due))
+                return false;
+            if (f.due_before && due > Date.parse(f.due_before))
+                return false;
+            if (f.due_after && due < Date.parse(f.due_after))
+                return false;
+        }
+        return true;
+    });
+}
+function pick(row, fields) {
+    if (!isRecord(row))
+        return row;
+    const out = {};
+    for (const f of fields)
+        if (f in row)
+            out[f] = row[f];
+    return out;
+}
+/**
+ * Trim, page, and annotate a list response. Non-array payloads (a single record,
+ * or an error object) pass through untouched.
+ *
+ * Pass fields: ['all'] to opt out of projection and get every column.
+ */
+export function shape(payload, defaults, opts = {}) {
+    if (!Array.isArray(payload))
+        return payload;
+    const total = payload.length;
+    const offset = Math.max(0, opts.offset ?? 0);
+    const limit = Math.max(1, opts.limit ?? DEFAULT_LIMIT);
+    const page = payload.slice(offset, offset + limit);
+    const all = opts.fields?.length === 1 && opts.fields[0] === 'all';
+    const fields = all ? null : (opts.fields?.length ? opts.fields : defaults);
+    const items = fields ? page.map((r) => pick(r, fields)) : page;
+    const available = isRecord(payload[0]) ? Object.keys(payload[0]).length : 0;
+    const next = offset + page.length;
+    return {
+        total,
+        returned: page.length,
+        offset,
+        ...(next < total ? { next_offset: next } : {}),
+        fields: fields
+            ? `${fields.length} of ${available} columns; pass fields:["all"] or a specific list for more`
+            : `all ${available} columns`,
+        items,
+    };
+}

package/package.json

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