viviscape-mcp 2.0.1 → 2.1.0

package/README.md

@@ -1,10 +1,10 @@
 # viviscape-mcp
 
-MCP server for the [ViviScape](https://viviscape.io) API — exposes CRM, projects, companies, tasks, time tracking, notes, and insights as tools for Claude and other MCP clients.
+MCP server for the [ViviScape](https://viviscape.io) API - exposes CRM, projects, companies, tasks, time tracking, notes, and insights as tools for Claude and other MCP clients.
 
 ## Installation
 
-No install needed — run via `npx`:
+No install needed - run via `npx`:
 
 ```bash
 npx viviscape-mcp
@@ -18,7 +18,7 @@ npm install -g viviscape-mcp
 
 ## Sign in
 
-Authentication is per-user, the same browser flow the ViviScape CLI uses — no
+Authentication is per-user, the same browser flow the ViviScape CLI uses - no
 API keys. Sign in once:
 
 ```bash
@@ -74,7 +74,7 @@ args = ["-y", "viviscape-mcp"]
 
 ## ChatGPT (Developer Mode / Apps SDK)
 
-ChatGPT only accepts **remote HTTP** MCP servers — it does not run local stdio
+ChatGPT only accepts **remote HTTP** MCP servers - it does not run local stdio
 processes. Bridge this server to an HTTP endpoint with
 [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) or
 [`supergateway`](https://www.npmjs.com/package/supergateway), then expose it
@@ -88,11 +88,11 @@ npx -y supergateway --stdio "npx -y viviscape-mcp" --port 8000
 ```
 
 The gateway shares the host's stored session, so everyone reaching that endpoint
-acts as the signed-in user — put your own auth in front of it.
+acts as the signed-in user - put your own auth in front of it.
 
 Expose `http://localhost:8000/sse` publicly, then in ChatGPT:
 
-**Settings → Connectors → Create → Custom MCP server**
+**Settings -> Connectors -> Create -> Custom MCP server**
 - **URL:** `https://your-public-host/sse`
 - **Auth:** none (or bearer, depending on your gateway)
 
@@ -100,16 +100,56 @@ Expose `http://localhost:8000/sse` publicly, then in ChatGPT:
 
 The server exposes tools across these domains:
 
-- **Prospects** — `prospect_add`, `prospect_get`, `prospect_update`, `prospect_query`, follow-ups, notes
-- **Clients** — `client_add`, `client_get`, `client_get_by_email`, `clients_by_company`
-- **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`
-- **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`
+- **Prospects** - `prospect_add`, `prospect_get`, `prospect_update`, `prospect_query`, follow-ups, notes
+- **Clients** - `client_add`, `client_get`, `client_get_by_email`, `clients_by_company`
+- **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
 

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>;