viviscape-mcp 2.0.2 → 2.2.0

package/README.md

@@ -105,12 +105,54 @@ 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`
+- **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`
 
+### 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

@@ -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>;
@@ -52,15 +62,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>;
@@ -69,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>;