viviscape-mcp 2.2.0 → 2.4.0

package/README.md

@@ -110,6 +110,8 @@ The server exposes tools across these domains:
 - **Milestones** - `milestone_list`, `milestones_active`, `milestones_by_company`, `milestones_by_user`, `milestone_get`, `milestone_add`, `milestone_update`, `milestone_clone`, `milestone_remove`
 - **Project writes** - `project_add`, `project_update`, `project_set_status`, `project_user_add`, `project_user_remove`
 - **Reference** - `enums` (the status, priority, and group-type values the platform accepts)
+- **Lookup** - `services` (resolve service_id to a name), `user_lookup` (id, email, team, groups)
+- **Bulk** - `tasks_bulk_add` (many tasks in one request)
 - **Time logs** - `timelog_add`, `timelog_update`
 - **Notes** - `note_add`, `note_get`, `note_update`, `note_remove`, `notes_mine`, `notes_query`, `notes_account`, `note_revisions`
 - **Note filing** - `note_companies`, `note_users`, `note_tags`, `note_attachments`, `notebook`, `notebook_users` (each takes an `action`)
@@ -134,6 +136,26 @@ 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.
 
+### Repeat-safe creates
+
+No create route accepts an idempotency key, so a retried agent step silently
+creates a second record. `task_add`, `note_add`, `timelog_add`,
+`prospect_add`, and `tasks_bulk_add` accept an optional
+`idempotency_key`: calling again with the same key replays the first result
+instead of writing again.
+
+The record is local (`~/.viviscape/mcp-idempotency.json`, 7-day expiry), so it
+stops the common case -- the same agent retrying the same step -- and does not
+make the server idempotent. Two machines running the same plan will still
+duplicate.
+
+### Delta queries
+
+List tools accept `updated_since` (ISO 8601) and return only rows touched at
+or after that time, so a recurring agent does not re-read the whole working set.
+It is filtered in-process (no list route supports a modified-since filter), and
+rows carrying no usable timestamp are kept rather than dropped.
+
 ### Paging and field selection
 
 List tools (`tasks_open`, `project_list_active`, `project_tasks`, and the rest)
@@ -144,6 +166,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/api-client.d.ts

@@ -223,6 +223,35 @@ export declare class ViviScapeClient {
     getActiveServices(): Promise<unknown>;
     getAllServices(): Promise<unknown>;
     getUsers(): Promise<unknown>;
+    getServices(activeOnly?: boolean): Promise<unknown>;
+    /**
+     * service/id answers 500 for ids that plainly exist (356 is "Feature
+     * Request"), so fall back to picking the row out of the account catalogue,
+     * which works.
+     */
+    getService(serviceId: number): Promise<any>;
+    getCompanyServices(companyId: number): Promise<unknown>;
+    getUserById(userId: number): Promise<unknown>;
+    getUserByEmail(email: string): Promise<unknown>;
+    userExists(username: string): Promise<unknown>;
+    getUserTeam(userId?: number): Promise<unknown>;
+    getUserGroups(userId?: number): Promise<unknown>;
+    /**
+     * Create many tasks in one request. The route builds each Group_Task
+     * server-side from a compact row, so this is both faster and less
+     * error-prone than looping task_add.
+     */
+    bulkImportTasks(opts: {
+        project_id: number;
+        status?: string;
+        tasks: Array<{
+            task: string;
+            description?: string;
+            estimate?: string;
+            priority?: string;
+            service_id?: number;
+        }>;
+    }): Promise<unknown>;
     getHoursByPerson(data: Record<string, unknown>): Promise<unknown>;
     getTimeLogsByDateRange(data: Record<string, unknown>): Promise<unknown>;
     getPersonStats(data: Record<string, unknown>): Promise<unknown>;

package/dist/api-client.js

@@ -908,6 +908,77 @@ export class ViviScapeClient {
     async getUsers() {
         return this.get(`account/users/${this.accountId}`);
     }
+    // -- Services (resolves the opaque service_id on tasks) ------
+    async getServices(activeOnly = false) {
+        return activeOnly
+            ? this.get(`services/${this.accountId}/active`)
+            : this.get(`services/${this.accountId}`);
+    }
+    /**
+     * service/id answers 500 for ids that plainly exist (356 is "Feature
+     * Request"), so fall back to picking the row out of the account catalogue,
+     * which works.
+     */
+    async getService(serviceId) {
+        try {
+            return await this.get(`service/id?serviceid=${serviceId}`);
+        }
+        catch (err) {
+            if (!(err instanceof ApiError))
+                throw err;
+            const all = await this.getServices(false);
+            const hit = Array.isArray(all)
+                ? all.find((s) => Number(s.intServiceID) === serviceId)
+                : undefined;
+            if (!hit)
+                throw err;
+            return hit;
+        }
+    }
+    async getCompanyServices(companyId) {
+        return this.get(`services/account?companyid=${companyId}`);
+    }
+    // -- Identity lookup -----------------------------------------
+    async getUserById(userId) {
+        return this.get(`user/id?userid=${userId}`);
+    }
+    async getUserByEmail(email) {
+        return this.get(`user/email?email=${encodeURIComponent(email)}`);
+    }
+    async userExists(username) {
+        return this.get(`user/exist?username=${encodeURIComponent(username)}`);
+    }
+    async getUserTeam(userId = 0) {
+        return this.get(`user/team?user_id=${userId || this.userId}`);
+    }
+    async getUserGroups(userId = 0) {
+        return this.get(`user/groups?user_id=${userId || this.userId}&account_id=${this.accountId}`);
+    }
+    // -- Bulk ----------------------------------------------------
+    /**
+     * Create many tasks in one request. The route builds each Group_Task
+     * server-side from a compact row, so this is both faster and less
+     * error-prone than looping task_add.
+     */
+    async bulkImportTasks(opts) {
+        return this.post('bulk/task/import', {
+            account_id: this.accountId,
+            project_id: opts.project_id,
+            user_id: this.userId,
+            status: opts.status || 'new',
+            tasks: opts.tasks.map((t) => ({
+                task: t.task,
+                description: t.description || '',
+                estimate: t.estimate || '',
+                priority: t.priority || 'low',
+                service_id: t.service_id ?? 0,
+                users: [],
+                user_id: this.userId,
+                name: '',
+                selected: false,
+            })),
+        });
+    }
     // -- Insights -----------------------------------------------
     async getHoursByPerson(data) {
         const userId = Number(data.user_id) || this.userId;

package/dist/idempotency.d.ts

@@ -0,0 +1,14 @@
+export declare class IdempotencyStore {
+    private path;
+    private cache;
+    constructor(path?: string);
+    private load;
+    private save;
+    get(tool: string, key: string): unknown | undefined;
+    put(tool: string, key: string, result: unknown): void;
+}
+/**
+ * Run a create exactly once per key. Without a key it just runs, so existing
+ * callers are unaffected.
+ */
+export declare function once(tool: string, key: string | undefined, fn: () => Promise<unknown>): Promise<unknown>;

package/dist/idempotency.js

@@ -0,0 +1,92 @@
+/**
+ * Idempotency for create tools -- phase 5 of docs/AGENT-CAPABILITY-SPEC.md.
+ *
+ * None of the create routes accept an idempotency key, so a retried or
+ * re-planned agent step silently creates a second task, note, or time log. This
+ * keeps a small local record of (tool, key) -> result so a repeat call replays
+ * the first result instead of writing again.
+ *
+ * Scope and limits, stated plainly because they matter:
+ *  - The record is local to this machine and this user, in ~/.viviscape.
+ *    Two machines running the same plan will still duplicate.
+ *  - It cannot detect a duplicate that was created without a key.
+ *  - Entries expire after 7 days; the file is capped so it cannot grow without
+ *    bound.
+ *  - Nothing here makes the server idempotent. It stops the common failure --
+ *    the same agent retrying the same step -- and no more.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_ENTRIES = 500;
+export class IdempotencyStore {
+    path;
+    cache = null;
+    constructor(path) {
+        this.path = path || join(homedir(), '.viviscape', 'mcp-idempotency.json');
+    }
+    load() {
+        if (this.cache)
+            return this.cache;
+        let raw = {};
+        try {
+            if (existsSync(this.path))
+                raw = JSON.parse(readFileSync(this.path, 'utf8'));
+        }
+        catch {
+            raw = {}; // a corrupt file must not break writes
+        }
+        const cutoff = Date.now() - TTL_MS;
+        for (const [k, v] of Object.entries(raw)) {
+            if (!v || typeof v.at !== 'number' || v.at < cutoff)
+                delete raw[k];
+        }
+        this.cache = raw;
+        return raw;
+    }
+    save() {
+        const data = this.load();
+        const keys = Object.keys(data);
+        if (keys.length > MAX_ENTRIES) {
+            // Drop oldest first.
+            keys.sort((a, b) => data[a].at - data[b].at);
+            for (const k of keys.slice(0, keys.length - MAX_ENTRIES))
+                delete data[k];
+        }
+        try {
+            mkdirSync(join(homedir(), '.viviscape'), { recursive: true });
+            writeFileSync(this.path, JSON.stringify(data), { encoding: 'utf8', mode: 0o600 });
+        }
+        catch {
+            // A failed write costs deduplication, not correctness -- stay quiet.
+        }
+    }
+    get(tool, key) {
+        return this.load()[`${tool}:${key}`]?.result;
+    }
+    put(tool, key, result) {
+        this.load()[`${tool}:${key}`] = { at: Date.now(), result };
+        this.save();
+    }
+}
+const store = new IdempotencyStore();
+/**
+ * Run a create exactly once per key. Without a key it just runs, so existing
+ * callers are unaffected.
+ */
+export async function once(tool, key, fn) {
+    if (!key)
+        return fn();
+    const hit = store.get(tool, key);
+    if (hit !== undefined) {
+        return {
+            idempotent_replay: true,
+            note: `Replayed the result of an earlier ${tool} call with idempotency_key "${key}". Nothing was created.`,
+            result: hit,
+        };
+    }
+    const result = await fn();
+    store.put(tool, key, result);
+    return result;
+}

package/dist/index.js

@@ -7,7 +7,8 @@ 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, SERVICE_FIELDS, annotateTasks, filterTasks, filterUpdatedSince, shape, } from './projection.js';
+import { once } from './idempotency.js';
 import { baseUrl } from './config.js';
 // quiet: dotenv's banner goes to stdout, which is the MCP protocol channel.
 config({ quiet: true });
@@ -44,7 +45,17 @@ function json(data) {
  * list tool takes a page window and an optional field list. Defaults keep the
  * response inside a tool-result budget; fields:["all"] opts out.
  */
+/**
+ * Phase 5: a key makes a create replay its first result instead of writing
+ * twice. Local to this machine -- see src/idempotency.ts for the limits.
+ */
+const idempotencyArg = {
+    idempotency_key: z.string().optional()
+        .describe('Repeat-safety token. Calling again with the same key replays the first result instead of creating a second record.'),
+};
 const pageArgs = {
+    updated_since: z.string().optional()
+        .describe('Only rows touched at or after this time (ISO 8601). Filtered in-process; rows with no timestamp are kept.'),
     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)'),
@@ -72,6 +83,13 @@ function paging(p) {
         offset: p.offset,
     };
 }
+/** Apply updated_since before paging, so the window is over matching rows. */
+function since(rows, p) {
+    const s = p.updated_since;
+    if (!s || !Array.isArray(rows))
+        return rows;
+    return filterUpdatedSince(rows, s);
+}
 // ============================================================
 // AUTH
 // ============================================================
@@ -148,8 +166,9 @@ server.tool('prospect_add', 'Add a new prospect/lead to the ViviScape CRM', {
     source_url: z.string().optional().describe('URL where the lead came from'),
     referred_by: z.string().optional().describe('Referral source'),
     status: z.enum(PROSPECT_STATUSES).optional().describe('Pipeline stage (platform values)'),
+    ...idempotencyArg,
 }, async (params) => {
-    const result = await requireClient().addProspect(params);
+    const result = await once('prospect_add', params.idempotency_key, () => requireClient().addProspect(params));
     return { content: [{ type: 'text', text: json(result) }] };
 });
 server.tool('prospect_update', 'Update an existing prospect in the CRM', {
@@ -311,13 +330,13 @@ server.tool('project_list', 'Get all projects for current user. Returns a page o
     ...pageArgs,
 }, async (params) => {
     const result = await requireClient().getMyProjects();
-    return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
+    return { content: [{ type: 'text', text: json(shape(since(result, params), PROJECT_FIELDS, paging(params))) }] };
 });
 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(shape(result, PROJECT_FIELDS, paging(params))) }] };
+    return { content: [{ type: 'text', text: json(shape(since(result, params), 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);
@@ -336,11 +355,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))) }] };
+    return { content: [{ type: 'text', text: json(shape(since(rows, params), 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,8 +370,8 @@ 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;
-    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
+    return { content: [{ type: 'text', text: json(shape(since(rows, params), 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)'),
@@ -368,8 +387,9 @@ 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'),
+    ...idempotencyArg,
 }, async (params) => {
-    const result = await requireClient().addTask(params);
+    const result = await once('task_add', params.idempotency_key, () => requireClient().addTask(params));
     return { content: [{ type: 'text', text: json(result) }] };
 });
 server.tool('task_update', 'Update a task. Fetches existing task first and merges changes.', {
@@ -394,8 +414,8 @@ 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;
-    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
+    return { content: [{ type: 'text', text: json(shape(since(rows, params), 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'),
@@ -403,8 +423,8 @@ 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;
-    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
+    return { content: [{ type: 'text', text: json(shape(since(rows, params), 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'),
@@ -413,8 +433,8 @@ 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;
-    return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
+    return { content: [{ type: 'text', text: json(shape(since(rows, params), 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'),
@@ -423,9 +443,9 @@ 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))) }] };
+    return { content: [{ type: 'text', text: json(shape(since(rows, params), 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'),
@@ -433,14 +453,14 @@ server.tool('projects_by_company', 'Get user projects filtered by company. Retur
     ...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))) }] };
+    return { content: [{ type: 'text', text: json(shape(since(result, params), 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))) }] };
+    return { content: [{ type: 'text', text: json(shape(since(result, params), PROJECT_FIELDS, paging(params))) }] };
 });
 // ============================================================
 // DOCUMENTATION: NOTE RELATIONS, TAGS, REVISIONS, ATTACHMENTS
@@ -463,7 +483,7 @@ server.tool('notes_account', 'List notes across the account, newest-first as the
     ...pageArgs,
 }, async (params) => {
     const result = await requireClient().getAccountNotes(params.company_id ?? 0, params.user_id ?? 0);
-    return { content: [{ type: 'text', text: json(shape(result, NOTE_FIELDS, paging(params))) }] };
+    return { content: [{ type: 'text', text: json(shape(since(result, params), NOTE_FIELDS, paging(params))) }] };
 });
 server.tool('note_revisions', 'Get the edit history of a note. Use before rewriting a shared note so human edits are not silently clobbered.', { note_id: z.string().describe('Note ID (GUID)') }, async ({ note_id }) => {
     const result = await requireClient().getNoteRevisions(note_id);
@@ -577,7 +597,7 @@ server.tool('project_files', 'List, upload, update, delete, or resolve the downl
     const { action } = params;
     if (action === 'list') {
         const result = await c.getProjectFiles(need(action, 'project_id', params.project_id));
-        return { content: [{ type: 'text', text: json(shape(result, FILE_FIELDS, paging(params))) }] };
+        return { content: [{ type: 'text', text: json(shape(since(result, params), FILE_FIELDS, paging(params))) }] };
     }
     const result = action === 'upload' ? await c.uploadProjectFile({
         project_id: need(action, 'project_id', params.project_id),
@@ -596,7 +616,57 @@ server.tool('task_files', 'List files attached to a task. Use this to read conte
     ...pageArgs,
 }, async (params) => {
     const result = await requireClient().getTaskFiles(params.task_id);
-    return { content: [{ type: 'text', text: json(shape(result, FILE_FIELDS, paging(params))) }] };
+    return { content: [{ type: 'text', text: json(shape(since(result, params), FILE_FIELDS, paging(params))) }] };
+});
+// ============================================================
+// LOOKUP AND BULK
+// ============================================================
+server.tool('services', 'Resolve service ids to names. Task rows carry a service_id and frequently a null service_name, so this is how a caller turns 356 into "Feature Request". Actions: list (all), active, get (one by id), by_company.', {
+    action: z.enum(['list', 'active', 'get', 'by_company']).describe('What to look up'),
+    service_id: z.number().optional().describe('Service ID (get)'),
+    company_id: z.number().optional().describe('Company ID (by_company)'),
+    ...pageArgs,
+}, async (params) => {
+    const c = requireClient();
+    const { action } = params;
+    const result = action === 'list' ? await c.getServices(false)
+        : action === 'active' ? await c.getServices(true)
+            : action === 'get' ? await c.getService(need(action, 'service_id', params.service_id))
+                : await c.getCompanyServices(need(action, 'company_id', params.company_id));
+    return { content: [{ type: 'text', text: json(shape(since(result, params), SERVICE_FIELDS, paging(params))) }] };
+});
+server.tool('user_lookup', 'Resolve a user id, email, or team. Assignees arrive as bare ids (210, 230, 264), so use this rather than guessing who they are. Actions: by_id, by_email, exists, team (companies a user belongs to), groups (their projects).', {
+    action: z.enum(['by_id', 'by_email', 'exists', 'team', 'groups']).describe('What to look up'),
+    user_id: z.number().optional().describe('User ID (by_id; optional for team and groups, defaults to signed-in user)'),
+    email: z.string().optional().describe('Email address (by_email)'),
+    username: z.string().optional().describe('Username or email to test (exists)'),
+}, async ({ action, user_id, email, username }) => {
+    const c = requireClient();
+    const result = action === 'by_id' ? await c.getUserById(need(action, 'user_id', user_id))
+        : action === 'by_email' ? await c.getUserByEmail(need(action, 'email', email))
+            : action === 'exists' ? await c.userExists(need(action, 'username', username))
+                : action === 'team' ? await c.getUserTeam(user_id ?? 0)
+                    : await c.getUserGroups(user_id ?? 0);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('tasks_bulk_add', 'Create many tasks in one request. Prefer this over looping task_add: the API builds each task server-side, so it is one round trip and one failure surface. All tasks land in the same project with the same starting status.', {
+    project_id: z.number().describe('Project ID all tasks belong to'),
+    status: z.enum(TASK_STATUSES).optional().describe('Starting status for every task (default new)'),
+    tasks: z.array(z.object({
+        task: z.string().describe('Task title'),
+        description: z.string().optional(),
+        estimate: z.string().optional().describe('Estimate in shorthand, e.g. 4h'),
+        priority: z.enum(PRIORITIES).optional().describe('Defaults to low'),
+        service_id: z.number().optional(),
+    })).describe('Tasks to create'),
+    ...idempotencyArg,
+}, async (params) => {
+    const result = await once('tasks_bulk_add', params.idempotency_key, () => requireClient().bulkImportTasks({
+        project_id: params.project_id,
+        status: params.status,
+        tasks: params.tasks,
+    }));
+    return { content: [{ type: 'text', text: json(result) }] };
 });
 // ============================================================
 // REFERENCE
@@ -801,8 +871,9 @@ server.tool('timelog_add', 'Log time against a task. Duration uses shorthand for
     log_date: z.string().optional().describe('Date of the work (ISO 8601)'),
     description: z.string().optional().describe('Description of work performed'),
     billable: z.boolean().optional().describe('Whether this time is billable'),
+    ...idempotencyArg,
 }, async (params) => {
-    const result = await requireClient().addTimeLog(params);
+    const result = await once('timelog_add', params.idempotency_key, () => requireClient().addTimeLog(params));
     return { content: [{ type: 'text', text: json(result) }] };
 });
 server.tool('timelog_update', 'Update an existing time log entry. Builds full LOG_Time payload.', {
@@ -834,8 +905,9 @@ server.tool('note_get', 'Get a note by ID', { note_id: z.string().describe('Note
 server.tool('note_add', 'Create a new note', {
     note: z.string().describe('Note content'),
     title: z.string().optional().describe('Note title'),
+    ...idempotencyArg,
 }, async (params) => {
-    const result = await requireClient().addNote(params);
+    const result = await once('note_add', params.idempotency_key, () => requireClient().addNote(params));
     return { content: [{ type: 'text', text: json(result) }] };
 });
 server.tool('note_update', 'Update a note', {

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[];
@@ -20,6 +29,8 @@ export declare const PROJECT_FIELDS: string[];
 export declare const NOTE_FIELDS: string[];
 /** Project/task file fields worth returning by default. */
 export declare const FILE_FIELDS: string[];
+/** Service catalogue fields worth returning by default. */
+export declare const SERVICE_FIELDS: string[];
 export declare const DEFAULT_LIMIT = 50;
 export interface ShapeOpts {
     fields?: string[];
@@ -38,6 +49,24 @@ 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[];
+/**
+ * Keep rows touched at or after `since`. Applied in-process: no list route
+ * accepts a modified-since filter, so this saves the caller's context but not
+ * the transfer. Rows with no usable timestamp are kept, on the grounds that
+ * dropping work because its metadata is thin is the worse failure.
+ */
+export declare function filterUpdatedSince(rows: unknown[], since: string): 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 = [
@@ -38,6 +48,11 @@ export const FILE_FIELDS = [
     'file_size_friendly', 'author', 'user_id', 'post_date', 'url_path',
     'is_public', 'is_private',
 ];
+/** Service catalogue fields worth returning by default. */
+export const SERVICE_FIELDS = [
+    'intServiceID', 'strService', 'bitActive', 'strDesc',
+    'decCost', 'decListPrice', 'intType', 'intSort',
+];
 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. */
@@ -92,6 +107,65 @@ 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,
+        };
+    });
+}
+/**
+ * Timestamp fields the API uses across row types, newest-meaning first. There is
+ * no single modified column, so take the latest of whatever the row carries.
+ */
+const STAMP_FIELDS = [
+    'last_update', 'last_log_date', 'complete_date', 'post_date',
+    'creation_date', 'create_date',
+];
+/**
+ * Keep rows touched at or after `since`. Applied in-process: no list route
+ * accepts a modified-since filter, so this saves the caller's context but not
+ * the transfer. Rows with no usable timestamp are kept, on the grounds that
+ * dropping work because its metadata is thin is the worse failure.
+ */
+export function filterUpdatedSince(rows, since) {
+    const cutoff = Date.parse(since);
+    if (!Number.isFinite(cutoff))
+        return rows;
+    return rows.filter((row) => {
+        if (!isRecord(row))
+            return true;
+        let newest = NaN;
+        for (const f of STAMP_FIELDS) {
+            const t = Date.parse(String(row[f] ?? ''));
+            // 0001-01-01 sentinels parse fine but mean "never".
+            if (Number.isFinite(t) && t > -6e13 && (!Number.isFinite(newest) || t > newest))
+                newest = t;
+        }
+        if (!Number.isFinite(newest))
+            return true;
+        return newest >= cutoff;
+    });
+}
 function pick(row, fields) {
     if (!isRecord(row))
         return row;
@@ -115,7 +189,10 @@ export function shape(payload, defaults, opts = {}) {
     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);
+    // An empty defaults list means the caller has no curated subset for this row
+    // type -- return everything rather than projecting every row down to {}.
+    const fallback = defaults.length ? defaults : null;
+    const fields = all ? null : (opts.fields?.length ? opts.fields : fallback);
     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;

package/package.json

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