viviscape-mcp 2.1.0 → 2.3.0

package/README.md

@@ -111,7 +111,9 @@ The server exposes tools across these domains:
 - **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`
+- **Notes** - `note_add`, `note_get`, `note_update`, `note_remove`, `notes_mine`, `notes_query`, `notes_account`, `note_revisions`
+- **Note filing** - `note_companies`, `note_users`, `note_tags`, `note_attachments`, `notebook`, `notebook_users` (each takes an `action`)
+- **Files** - `project_files` (list/upload/update/delete/download), `task_files`
 - **Insights** - hours by person/service/project, AI summary, person stats, time totals
 - **Account** - `account_info`, `account_services`, `account_users`
 - **Auth** - `auth_login`, `auth_status`, `auth_logout`
@@ -142,6 +144,12 @@ work, so each list tool accepts:
 - `fields` - columns to return; omit for a curated default, or pass `["all"]`
 - `limit` / `offset` - page window, default 50 rows
 
+Task rows also carry computed `due_date`, `due_in_days` (negative when
+overdue), and `overdue`, derived from the task's `end` date. Read those rather
+than the API's `deadline` string, which does not track the due date -- it
+reported "In 2 Days" for a task 39 days overdue. `deadline` is excluded from the
+default field set; ask for it explicitly if you need to see what the UI shows.
+
 Responses are wrapped as `{ total, returned, offset, next_offset, fields, items }`
 so a caller can tell when more rows exist. Task lists also accept
 `company_id`, `project_id`, `assignee_id`, `status`, `priority`,

package/dist/api-client.d.ts

@@ -21,6 +21,16 @@ export declare class ViviScapeClient {
     get session(): Credentials;
     private get ctx();
     private request;
+    /**
+     * Shared response handling for the binary upload paths, which cannot go
+     * through request() because that always sends JSON.
+     */
+    private send;
+    private authHeaders;
+    /** multipart/form-data upload; fetch sets the boundary, so no Content-Type here. */
+    private postMultipart;
+    /** Raw-body upload with metadata in headers (the groups/file/add contract). */
+    private postBytes;
     private get;
     private post;
     addProspect(data: Record<string, unknown>): Promise<unknown>;
@@ -162,6 +172,53 @@ export declare class ViviScapeClient {
     updateNote(data: Record<string, unknown>): Promise<unknown>;
     removeNote(noteId: number | string): Promise<unknown>;
     queryNotes(data: Record<string, unknown>): Promise<unknown>;
+    getAccountNotes(companyId?: number, userId?: number): Promise<unknown>;
+    getNoteRevisions(noteId: string): Promise<unknown>;
+    getNoteCompanies(noteId: string): Promise<unknown>;
+    addNoteCompany(noteId: string, companyId: number): Promise<unknown>;
+    removeNoteCompany(assignmentId: string): Promise<unknown>;
+    getNoteUsers(noteId: string): Promise<unknown>;
+    addNoteUser(noteId: string, userId: number, permission?: string): Promise<unknown>;
+    updateNoteUser(assignmentId: string, noteId: string, userId: number, permission: string): Promise<unknown>;
+    removeNoteUser(assignmentId: string): Promise<unknown>;
+    getNoteTags(noteId: string): Promise<unknown>;
+    addNoteTag(noteId: string, tag: string): Promise<unknown>;
+    removeNoteTag(tagId: string): Promise<unknown>;
+    getNoteAttachments(noteId: string): Promise<unknown>;
+    /** Uploads a local file as a note attachment. knowledge=true marks it for extraction. */
+    uploadNoteAttachment(noteId: string, filePath: string, knowledge?: boolean): Promise<unknown>;
+    removeNoteAttachment(attachmentId: string): Promise<unknown>;
+    /** Flag an attachment as knowledge-base material (drives text extraction). */
+    setNoteAttachmentKnowledge(attachment: Record<string, unknown>): Promise<unknown>;
+    getNotebooks(userId?: number): Promise<unknown>;
+    getNotebookNotes(bookId: string): Promise<unknown>;
+    addNotebook(name: string, description?: string): Promise<unknown>;
+    updateNotebook(bookId: string, changes: Record<string, unknown>): Promise<unknown>;
+    removeNotebook(bookId: string): Promise<unknown>;
+    /** Add or remove notes from a notebook in one call. */
+    assignNotesToBook(bookId: string, noteIds: string[], assign?: boolean): Promise<unknown>;
+    getNotebookUsers(bookId: string): Promise<unknown>;
+    addNotebookUser(bookId: string, userId: number, permission?: string): Promise<unknown>;
+    updateNotebookUser(assignmentId: string, bookId: string, userId: number, permission: string): Promise<unknown>;
+    removeNotebookUser(assignmentId: string): Promise<unknown>;
+    getProjectFiles(projectId: number, userId?: number): Promise<unknown>;
+    getTaskFiles(taskId: number): Promise<unknown>;
+    /**
+     * Upload a file to a project. This route takes the raw bytes as the body and
+     * every piece of metadata as a header, and the handler reads each header
+     * without a null check -- so all of them must be sent, even when empty.
+     */
+    uploadProjectFile(opts: {
+        project_id: number;
+        file_path: string;
+        title?: string;
+        task_id?: number;
+        notify?: boolean;
+    }): Promise<unknown>;
+    updateProjectFile(file: Record<string, unknown>): Promise<unknown>;
+    deleteProjectFile(fileId: number): Promise<unknown>;
+    /** Returns whatever the download route serves; usually a redirect target or URL. */
+    downloadProjectFile(fileId: number): Promise<unknown>;
     getAccountInfo(): Promise<unknown>;
     getActiveServices(): Promise<unknown>;
     getAllServices(): Promise<unknown>;

package/dist/api-client.js

@@ -255,6 +255,51 @@ export class ViviScapeClient {
             return text;
         }
     }
+    /**
+     * Shared response handling for the binary upload paths, which cannot go
+     * through request() because that always sends JSON.
+     */
+    async send(method, path, init) {
+        requireFeature(featureForPath(path), this.creds);
+        const url = `${this.baseUrl}${API_PREFIX}/${path.replace(/^\//, '')}`;
+        const res = await fetch(url, { method, redirect: 'manual', ...init });
+        const text = await res.text();
+        if (res.status === 401 || res.status === 403)
+            throw new SessionExpiredError();
+        if (res.status >= 300 && res.status < 400)
+            throw new SessionExpiredError();
+        if (!res.ok) {
+            const snippet = text.length > 400 ? `${text.slice(0, 400)}...` : text;
+            throw new ApiError(res.status, `API ${method} ${path} returned ${res.status}: ${snippet}`);
+        }
+        if (!text.trim())
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    authHeaders(extra = {}) {
+        return {
+            'Authorization': `Bearer ${this.creds.access_token}`,
+            'user_id': String(this.creds.user_id),
+            'pid': String(this.creds.pid),
+            ...extra,
+        };
+    }
+    /** multipart/form-data upload; fetch sets the boundary, so no Content-Type here. */
+    async postMultipart(path, form) {
+        return this.send('POST', path, { headers: this.authHeaders(), body: form });
+    }
+    /** Raw-body upload with metadata in headers (the groups/file/add contract). */
+    async postBytes(path, bytes, extra) {
+        return this.send('POST', path, {
+            headers: this.authHeaders({ 'Content-Type': 'application/octet-stream', ...extra }),
+            body: bytes,
+        });
+    }
     get(path) {
         return this.request('GET', path);
     }
@@ -683,6 +728,173 @@ export class ViviScapeClient {
             module: 'notes',
         });
     }
+    // -- Note relations, tags, revisions -------------------------
+    async getAccountNotes(companyId = 0, userId = 0) {
+        return this.post('notes/account', {
+            account_id: this.accountId,
+            company_id: companyId,
+            user_id: userId,
+        });
+    }
+    async getNoteRevisions(noteId) {
+        return this.get(`note/revisions/${noteId}`);
+    }
+    async getNoteCompanies(noteId) {
+        return this.get(`note/companies/${noteId}`);
+    }
+    async addNoteCompany(noteId, companyId) {
+        return this.post('note/company/add', {
+            assignment_id: EMPTY_GUID,
+            note_id: noteId,
+            assign_user_id: this.userId,
+            company_id: companyId,
+        });
+    }
+    async removeNoteCompany(assignmentId) {
+        return this.get(`note/company/remove/${assignmentId}`);
+    }
+    async getNoteUsers(noteId) {
+        return this.get(`note/users/${noteId}`);
+    }
+    async addNoteUser(noteId, userId, permission = 'read') {
+        return this.post('note/user/add', {
+            assignment_id: EMPTY_GUID,
+            note_id: noteId,
+            user_id: userId,
+            permission,
+        });
+    }
+    async updateNoteUser(assignmentId, noteId, userId, permission) {
+        return this.post('note/user/update', {
+            assignment_id: assignmentId,
+            note_id: noteId,
+            user_id: userId,
+            permission,
+        });
+    }
+    async removeNoteUser(assignmentId) {
+        return this.get(`note/user/remove/${assignmentId}`);
+    }
+    async getNoteTags(noteId) {
+        return this.get(`note/tags/${noteId}`);
+    }
+    async addNoteTag(noteId, tag) {
+        return this.post('note/tags/add', { tag_id: EMPTY_GUID, note_id: noteId, tag });
+    }
+    async removeNoteTag(tagId) {
+        return this.get(`note/tag/remove/${tagId}`);
+    }
+    // -- Note attachments ----------------------------------------
+    async getNoteAttachments(noteId) {
+        return this.get(`note/attachments/${noteId}`);
+    }
+    /** Uploads a local file as a note attachment. knowledge=true marks it for extraction. */
+    async uploadNoteAttachment(noteId, filePath, knowledge = false) {
+        const { readFileSync } = await import('node:fs');
+        const { basename } = await import('node:path');
+        const form = new FormData();
+        form.append('knowledge', String(knowledge));
+        form.append('file', new Blob([readFileSync(filePath)]), basename(filePath));
+        return this.postMultipart(`note/attachment/upload/${noteId}`, form);
+    }
+    async removeNoteAttachment(attachmentId) {
+        return this.get(`note/attachment/remove/${attachmentId}`);
+    }
+    /** Flag an attachment as knowledge-base material (drives text extraction). */
+    async setNoteAttachmentKnowledge(attachment) {
+        return this.post('note/attachment/knowledge', attachment);
+    }
+    // -- Notebooks -----------------------------------------------
+    async getNotebooks(userId = 0) {
+        return this.get(`note/books/user/${userId || this.userId}`);
+    }
+    async getNotebookNotes(bookId) {
+        return this.get(`note/book/notes/${bookId}`);
+    }
+    async addNotebook(name, description = '') {
+        return this.post('note/book/add', {
+            book_id: EMPTY_GUID,
+            name,
+            description,
+            creator_id: this.userId,
+            account_id: this.accountId,
+        });
+    }
+    async updateNotebook(bookId, changes) {
+        return this.post('note/book/update', {
+            book_id: bookId,
+            creator_id: this.userId,
+            account_id: this.accountId,
+            ...changes,
+        });
+    }
+    async removeNotebook(bookId) {
+        return this.get(`note/book/remove/${bookId}`);
+    }
+    /** Add or remove notes from a notebook in one call. */
+    async assignNotesToBook(bookId, noteIds, assign = true) {
+        return this.post('note/book/assign', { book_id: bookId, note_ids: noteIds, assign });
+    }
+    async getNotebookUsers(bookId) {
+        return this.get(`note/book/users/${bookId}`);
+    }
+    async addNotebookUser(bookId, userId, permission = 'read') {
+        return this.post('note/book/user/add', {
+            assignment_id: EMPTY_GUID,
+            book_id: bookId,
+            user_id: userId,
+            permission,
+        });
+    }
+    async updateNotebookUser(assignmentId, bookId, userId, permission) {
+        return this.post('note/book/user/update', {
+            assignment_id: assignmentId,
+            book_id: bookId,
+            user_id: userId,
+            permission,
+        });
+    }
+    async removeNotebookUser(assignmentId) {
+        return this.get(`note/book/user/remove/${assignmentId}`);
+    }
+    // -- Project and task files ----------------------------------
+    async getProjectFiles(projectId, userId = 0) {
+        return this.get(`groups/files?groupid=${projectId}&userid=${userId || this.userId}`);
+    }
+    async getTaskFiles(taskId) {
+        return this.get(`groups/task/files?taskid=${taskId}`);
+    }
+    /**
+     * Upload a file to a project. This route takes the raw bytes as the body and
+     * every piece of metadata as a header, and the handler reads each header
+     * without a null check -- so all of them must be sent, even when empty.
+     */
+    async uploadProjectFile(opts) {
+        const { readFileSync } = await import('node:fs');
+        const { basename } = await import('node:path');
+        const name = basename(opts.file_path);
+        return this.postBytes('groups/file/add', readFileSync(opts.file_path), {
+            userid: String(this.userId),
+            groupid: String(opts.project_id),
+            filename: name,
+            title: opts.title || name,
+            youtube: '',
+            notify: String(opts.notify ?? false),
+            taskid: String(opts.task_id ?? 0),
+            lat: '0',
+            lng: '0',
+        });
+    }
+    async updateProjectFile(file) {
+        return this.post('groups/file/update', file);
+    }
+    async deleteProjectFile(fileId) {
+        return this.get(`groups/file/delete?fileid=${fileId}`);
+    }
+    /** Returns whatever the download route serves; usually a redirect target or URL. */
+    async downloadProjectFile(fileId) {
+        return this.get(`groups/file/download/${fileId}`);
+    }
     // -- Account ------------------------------------------------
     async getAccountInfo() {
         return this.get(`account/id/${this.accountId}`);

package/dist/index.js

@@ -7,7 +7,7 @@ import { ViviScapeClient } from './api-client.js';
 import { AuthService } from './auth/auth-service.js';
 import { describe } from './auth/credentials.js';
 import { PRIORITIES, PROJECT_STATUSES, PROSPECT_STATUSES, TASK_STATUSES, enumReference, } from './enums.js';
-import { PROJECT_FIELDS, TASK_FIELDS, filterTasks, shape, } from './projection.js';
+import { FILE_FIELDS, NOTE_FIELDS, PROJECT_FIELDS, TASK_FIELDS, annotateTasks, filterTasks, shape, } from './projection.js';
 import { baseUrl } from './config.js';
 // quiet: dotenv's banner goes to stdout, which is the MCP protocol channel.
 config({ quiet: true });
@@ -336,11 +336,11 @@ server.tool('project_tasks', 'Get all tasks for a project. Returns a page of tri
     // project_id is the query, not a filter -- re-filtering on it would drop
     // every row if the response names the column differently.
     const rows = Array.isArray(result)
-        ? filterTasks(result, { ...params, project_id: undefined })
+        ? annotateTasks(filterTasks(result, { ...params, project_id: undefined }))
         : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
-server.tool('tasks_open', 'Get open tasks across projects. company_id and only_mine filter server-side; the rest filter in-process. Returns a page of trimmed rows.', {
+server.tool('tasks_open', 'Get open tasks across projects. company_id and only_mine filter server-side; the rest filter in-process. Returns a page of trimmed rows with computed due_date / due_in_days / overdue -- read those, not the API deadline string, which is unreliable.', {
     only_mine: z.boolean().optional().describe('Only tasks assigned to the signed-in user (server-side)'),
     team: z.string().optional().describe('Team filter passed through to the API'),
     ...taskFilterArgs,
@@ -351,7 +351,7 @@ server.tool('tasks_open', 'Get open tasks across projects. company_id and only_m
         only_mine: params.only_mine,
         team: params.team,
     });
-    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
 server.tool('task_add', 'Add a task to a project. The API requires a full Group_Task payload; this tool builds it from simplified params.', {
@@ -394,7 +394,7 @@ server.tool('tasks_pending', 'Get pending tasks for a user. Returns a page of tr
     ...taskFilterArgs,
 }, async (params) => {
     const result = await requireClient().getPendingTasks(params.user_id);
-    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
 server.tool('tasks_by_milestone', 'Get tasks for a milestone. Returns a page of trimmed rows; see fields/limit/offset.', {
@@ -403,7 +403,7 @@ server.tool('tasks_by_milestone', 'Get tasks for a milestone. Returns a page of
     ...taskFilterArgs,
 }, async (params) => {
     const result = await requireClient().getTasksByMilestone(params.milestone_id);
-    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
 server.tool('tasks_by_group_user', 'Get tasks by project group and user. Returns a page of trimmed rows; see fields/limit/offset.', {
@@ -413,7 +413,7 @@ server.tool('tasks_by_group_user', 'Get tasks by project group and user. Returns
     ...taskFilterArgs,
 }, async (params) => {
     const result = await requireClient().getTasksByGroupAndUser(params.group_id, params.user_id);
-    const rows = Array.isArray(result) ? filterTasks(result, params) : result;
+    const rows = Array.isArray(result) ? annotateTasks(filterTasks(result, params)) : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
 server.tool('tasks_by_company', 'Get tasks for a company. Returns a page of trimmed rows; see fields/limit/offset.', {
@@ -423,7 +423,7 @@ server.tool('tasks_by_company', 'Get tasks for a company. Returns a page of trim
 }, async (params) => {
     const result = await requireClient().getCompanyTasks(params.company_id);
     const rows = Array.isArray(result)
-        ? filterTasks(result, { ...params, company_id: undefined })
+        ? annotateTasks(filterTasks(result, { ...params, company_id: undefined }))
         : result;
     return { content: [{ type: 'text', text: json(shape(rows, TASK_FIELDS, paging(params))) }] };
 });
@@ -443,6 +443,162 @@ server.tool('projects_active_by_user', 'Get active projects for a specific user.
     return { content: [{ type: 'text', text: json(shape(result, PROJECT_FIELDS, paging(params))) }] };
 });
 // ============================================================
+// DOCUMENTATION: NOTE RELATIONS, TAGS, REVISIONS, ATTACHMENTS
+// ============================================================
+//
+// These tools take an `action` rather than splitting every verb into its own
+// tool: the server already registers ~90 tools, and past roughly 100 the tool
+// list itself starts costing more than it returns. Each action names exactly
+// which arguments it needs, and a missing one is reported by name.
+/** Fail with a message that names the action and the argument it wanted. */
+function need(action, name, value) {
+    if (value === undefined || value === null || value === '') {
+        throw new Error(`action "${action}" requires ${name}`);
+    }
+    return value;
+}
+server.tool('notes_account', 'List notes across the account, newest-first as the API returns them. Bodies are omitted by default (hundreds of rows); pass fields:["note_id","title","note"] to read content.', {
+    company_id: z.number().optional().describe('Restrict to notes linked to this company'),
+    user_id: z.number().optional().describe('Restrict to notes for this user'),
+    ...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))) }] };
+});
+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);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_companies', 'Link a note to a company, list its links, or remove one. This is how a generated document gets filed against a client. NOTE: add returns an echo with zeroed ids, so call list afterward to get the assignment_id you need for remove.', {
+    action: z.enum(['list', 'add', 'remove']).describe('What to do'),
+    note_id: z.string().optional().describe('Note ID (list, add)'),
+    company_id: z.number().optional().describe('Company ID (add)'),
+    assignment_id: z.string().optional().describe('Link ID from list (remove)'),
+}, async ({ action, note_id, company_id, assignment_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNoteCompanies(need(action, 'note_id', note_id))
+        : action === 'add' ? await c.addNoteCompany(need(action, 'note_id', note_id), need(action, 'company_id', company_id))
+            : await c.removeNoteCompany(need(action, 'assignment_id', assignment_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_users', 'Share a note with a user, list who it is shared with, change a permission, or unshare. NOTE: add returns an echo with zeroed ids; call list to get the assignment_id.', {
+    action: z.enum(['list', 'add', 'update', 'remove']).describe('What to do'),
+    note_id: z.string().optional().describe('Note ID (list, add, update)'),
+    user_id: z.number().optional().describe('User ID (add, update)'),
+    permission: z.string().optional().describe('Permission, e.g. read or write (add, update)'),
+    assignment_id: z.string().optional().describe('Share ID from list (update, remove)'),
+}, async ({ action, note_id, user_id, permission, assignment_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNoteUsers(need(action, 'note_id', note_id))
+        : action === 'add' ? await c.addNoteUser(need(action, 'note_id', note_id), need(action, 'user_id', user_id), permission || 'read')
+            : action === 'update' ? await c.updateNoteUser(need(action, 'assignment_id', assignment_id), need(action, 'note_id', note_id), need(action, 'user_id', user_id), need(action, 'permission', permission))
+                : await c.removeNoteUser(need(action, 'assignment_id', assignment_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_tags', 'List, add, or remove tags on a note -- the only way to categorise notes for later retrieval. NOTE: remove answers false even when it succeeds; re-list to confirm.', {
+    action: z.enum(['list', 'add', 'remove']).describe('What to do'),
+    note_id: z.string().optional().describe('Note ID (list, add)'),
+    tag: z.string().optional().describe('Tag text (add)'),
+    tag_id: z.string().optional().describe('Tag ID from list (remove)'),
+}, async ({ action, note_id, tag, tag_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNoteTags(need(action, 'note_id', note_id))
+        : action === 'add' ? await c.addNoteTag(need(action, 'note_id', note_id), need(action, 'tag', tag))
+            : await c.removeNoteTag(need(action, 'tag_id', tag_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('note_attachments', 'List, upload, or remove note attachments, or flag one as knowledge-base material. upload takes a path to a local file.', {
+    action: z.enum(['list', 'upload', 'remove', 'set_knowledge']).describe('What to do'),
+    note_id: z.string().optional().describe('Note ID (list, upload)'),
+    file_path: z.string().optional().describe('Local file to upload (upload)'),
+    knowledge: z.boolean().optional().describe('Mark for text extraction (upload, set_knowledge)'),
+    attachment_id: z.string().optional().describe('Attachment ID from list (remove, set_knowledge)'),
+}, async ({ action, note_id, file_path, knowledge, attachment_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNoteAttachments(need(action, 'note_id', note_id))
+        : action === 'upload' ? await c.uploadNoteAttachment(need(action, 'note_id', note_id), need(action, 'file_path', file_path), knowledge ?? false)
+            : action === 'remove' ? await c.removeNoteAttachment(need(action, 'attachment_id', attachment_id))
+                : await c.setNoteAttachmentKnowledge({
+                    attachment_id: need(action, 'attachment_id', attachment_id),
+                    note_id: note_id ?? undefined,
+                    knowledge: knowledge ?? true,
+                });
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('notebook', 'Notebooks group notes into a per-client or per-project documentation space. Actions: list, add, update, remove, notes (list a book contents), assign / unassign notes. WARNING: remove is broken server-side (400 even for an empty book) -- delete notebooks in the ViviScape Work UI.', {
+    action: z.enum(['list', 'add', 'update', 'remove', 'notes', 'assign', 'unassign']).describe('What to do'),
+    book_id: z.string().optional().describe('Notebook ID (update, remove, notes, assign, unassign)'),
+    name: z.string().optional().describe('Notebook name (add, update)'),
+    description: z.string().optional().describe('Notebook description (add, update)'),
+    note_ids: z.array(z.string()).optional().describe('Note IDs (assign, unassign)'),
+    user_id: z.number().optional().describe('Owner to list for (list; defaults to signed-in user)'),
+}, async ({ action, book_id, name, description, note_ids, user_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNotebooks(user_id ?? 0)
+        : action === 'add' ? await c.addNotebook(need(action, 'name', name), description || '')
+            : action === 'update' ? await c.updateNotebook(need(action, 'book_id', book_id), {
+                ...(name ? { name } : {}),
+                ...(description !== undefined ? { description } : {}),
+            })
+                : action === 'remove' ? await c.removeNotebook(need(action, 'book_id', book_id))
+                    : action === 'notes' ? await c.getNotebookNotes(need(action, 'book_id', book_id))
+                        : await c.assignNotesToBook(need(action, 'book_id', book_id), need(action, 'note_ids', note_ids), action === 'assign');
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('notebook_users', 'List, add, update, or remove the users a notebook is shared with', {
+    action: z.enum(['list', 'add', 'update', 'remove']).describe('What to do'),
+    book_id: z.string().optional().describe('Notebook ID (list, add, update)'),
+    user_id: z.number().optional().describe('User ID (add, update)'),
+    permission: z.string().optional().describe('Permission, e.g. read, write, owner (add, update)'),
+    assignment_id: z.string().optional().describe('Share ID from list (update, remove)'),
+}, async ({ action, book_id, user_id, permission, assignment_id }) => {
+    const c = requireClient();
+    const result = action === 'list' ? await c.getNotebookUsers(need(action, 'book_id', book_id))
+        : action === 'add' ? await c.addNotebookUser(need(action, 'book_id', book_id), need(action, 'user_id', user_id), permission || 'read')
+            : action === 'update' ? await c.updateNotebookUser(need(action, 'assignment_id', assignment_id), need(action, 'book_id', book_id), need(action, 'user_id', user_id), need(action, 'permission', permission))
+                : await c.removeNotebookUser(need(action, 'assignment_id', assignment_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// PROJECT AND TASK FILES
+// ============================================================
+server.tool('project_files', 'List, upload, update, delete, or resolve the download URL of files attached to a project. upload takes a path to a local file; delete is by file_id from list.', {
+    action: z.enum(['list', 'upload', 'update', 'delete', 'download']).describe('What to do'),
+    project_id: z.number().optional().describe('Project ID (list, upload)'),
+    file_path: z.string().optional().describe('Local file to upload (upload)'),
+    title: z.string().optional().describe('Title for the uploaded file (upload; defaults to the filename)'),
+    task_id: z.number().optional().describe('Attach the upload to a task as well (upload)'),
+    notify: z.boolean().optional().describe('Notify project members (upload; default false)'),
+    file_id: z.number().optional().describe('File ID from list (delete, download)'),
+    file: z.record(z.string(), z.unknown()).optional().describe('Full file record with changes applied (update)'),
+    ...pageArgs,
+}, async (params) => {
+    const c = requireClient();
+    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))) }] };
+    }
+    const result = action === 'upload' ? await c.uploadProjectFile({
+        project_id: need(action, 'project_id', params.project_id),
+        file_path: need(action, 'file_path', params.file_path),
+        title: params.title,
+        task_id: params.task_id,
+        notify: params.notify,
+    })
+        : action === 'update' ? await c.updateProjectFile(need(action, 'file', params.file))
+            : action === 'delete' ? await c.deleteProjectFile(need(action, 'file_id', params.file_id))
+                : await c.downloadProjectFile(need(action, 'file_id', params.file_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('task_files', 'List files attached to a task. Use this to read context humans already attached before generating anything new.', {
+    task_id: z.number().describe('Task ID'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getTaskFiles(params.task_id);
+    return { content: [{ type: 'text', text: json(shape(result, FILE_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()) }] }));

package/dist/projection.d.ts

@@ -8,10 +8,27 @@
  * 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[];
+/**
+ * Note fields worth returning by default. Excludes `note` (the full body) and
+ * `firefly_transcript_id`: the account list runs to hundreds of rows and the
+ * bodies dominate the payload. Ask for fields:["note"] to read one.
+ */
+export declare const NOTE_FIELDS: string[];
+/** Project/task file fields worth returning by default. */
+export declare const FILE_FIELDS: string[];
 export declare const DEFAULT_LIMIT = 50;
 export interface ShapeOpts {
     fields?: string[];
@@ -30,6 +47,17 @@ export interface TaskFilters {
 }
 /** Apply the filters the backend does not support, in-process. */
 export declare function filterTasks(rows: unknown[], f: TaskFilters): unknown[];
+/**
+ * Add an unambiguous due-date signal to task rows.
+ *
+ * The API ships three overlapping fields: `end` (the real due date), `pastdue`
+ * (a boolean that matches it), and `deadline` (a human string that does not).
+ * Rather than make every caller know which to trust, derive the answer from
+ * `end` and pass `deadline` through only when explicitly requested.
+ *
+ * due_in_days is negative for overdue work, 0 for due today.
+ */
+export declare function annotateTasks(rows: unknown[], now?: number): unknown[];
 /**
  * Trim, page, and annotate a list response. Non-array payloads (a single record,
  * or an error object) pass through untouched.

package/dist/projection.js

@@ -8,12 +8,22 @@
  * read. These helpers trim to a PM-relevant default, page the result, and tell
  * the caller what was left out so it can ask for more deliberately.
  */
-/** Task fields worth returning by default, of roughly 90 available. */
+/**
+ * Task fields worth returning by default, of roughly 90 available.
+ *
+ * `deadline` is deliberately excluded. It is a server-rendered string that does
+ * not track the task's own due date: measured against six live tasks it read
+ * "In 2 Days" for one 39 days overdue, and gave "In 4 Days" for tasks at both
+ * -9 and +2 days. `end` is the real due date, and `pastdue` agrees with it on
+ * every row, so annotateTasks() derives due_date / due_in_days / overdue from
+ * `end` and those are what callers should read.
+ */
 export const TASK_FIELDS = [
     'task_id', 'task', 'status', 'percentage', 'priority',
     'company_id', 'company_name', 'group_id', 'group_name',
     'milestone_id', 'milestone', 'estimated_time', 'total_duration_str',
-    'deadline', 'start', 'end', 'staff_assignees', 'total_comments', 'unread_for_me',
+    'start', 'due_date', 'due_in_days', 'overdue', 'pastdue',
+    'staff_assignees', 'total_comments', 'unread_for_me',
 ];
 /** Project (group) fields worth returning by default, of 87 available. */
 export const PROJECT_FIELDS = [
@@ -22,6 +32,22 @@ export const PROJECT_FIELDS = [
     'total_tasks', 'total_tasks_open', 'total_tasks_completed',
     'target_date', 'complete_date', 'total_estimated_str', 'total_duration_str',
 ];
+/**
+ * Note fields worth returning by default. Excludes `note` (the full body) and
+ * `firefly_transcript_id`: the account list runs to hundreds of rows and the
+ * bodies dominate the payload. Ask for fields:["note"] to read one.
+ */
+export const NOTE_FIELDS = [
+    'note_id', 'title', 'book_id', 'creator', 'creator_id',
+    'summary', 'tags', 'assigned_users', 'knowledge', 'is_public',
+    'last_update', 'create_date',
+];
+/** Project/task file fields worth returning by default. */
+export const FILE_FIELDS = [
+    'file_id', 'group_id', 'task_id', 'title', 'file_name', 'file_type',
+    'file_size_friendly', 'author', 'user_id', 'post_date', 'url_path',
+    'is_public', 'is_private',
+];
 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. */
@@ -76,6 +102,32 @@ export function filterTasks(rows, f) {
         return true;
     });
 }
+/**
+ * Add an unambiguous due-date signal to task rows.
+ *
+ * The API ships three overlapping fields: `end` (the real due date), `pastdue`
+ * (a boolean that matches it), and `deadline` (a human string that does not).
+ * Rather than make every caller know which to trust, derive the answer from
+ * `end` and pass `deadline` through only when explicitly requested.
+ *
+ * due_in_days is negative for overdue work, 0 for due today.
+ */
+export function annotateTasks(rows, now = Date.now()) {
+    return rows.map((row) => {
+        if (!isRecord(row))
+            return row;
+        const due = Date.parse(String(row.end ?? ''));
+        if (!Number.isFinite(due)) {
+            return { ...row, due_date: null, due_in_days: null, overdue: null };
+        }
+        return {
+            ...row,
+            due_date: new Date(due).toISOString(),
+            due_in_days: Math.round((due - now) / 86_400_000),
+            overdue: due < now,
+        };
+    });
+}
 function pick(row, fields) {
     if (!isRecord(row))
         return row;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viviscape-mcp",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "MCP server for the ViviScape API — CRM, projects, companies, notes, and insights, authenticated as the signed-in ViviScape user",
   "type": "module",
   "main": "dist/index.js",