viviscape-mcp 2.7.0 → 2.9.0

package/README.md

@@ -1,253 +1,294 @@
-# 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.
-
-## Installation
-
-No install needed - run via `npx`:
-
-```bash
-npx viviscape-mcp
-```
-
-Or install globally:
-
-```bash
-npm install -g viviscape-mcp
-```
-
-## Sign in
-
-Authentication is per-user, the same browser flow the ViviScape CLI uses - no
-API keys. Sign in once:
-
-```bash
-npx viviscape-mcp login
-```
-
-A browser tab opens on ViviScape Work; confirm **Allow access** and the session
-is stored in Windows Credential Manager (or `~/.viviscape/mcp-credentials.json`
-on macOS/Linux). Every tool call then runs as *you*: your user id, account,
-role, and plan come from the session, so tools see exactly the data you can see
-in the app.
-
-```bash
-npx viviscape-mcp status    # who am I, which account, role, plan
-npx viviscape-mcp logout    # clear the stored session
-```
-
-If you already ran `vs auth login` with the [ViviScape CLI](https://viviscape.io),
-that session is picked up automatically. Inside an MCP client you can also call
-the `auth_login`, `auth_status`, and `auth_logout` tools. Sessions expire; when
-one does, tools report it and you re-run `login`.
-
-## Configuration
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `VIVISCAPE_BASE_URL` | no | `https://work.viviscape.io` | ViviScape Work base URL |
-
-## Claude Desktop / Claude Code
-
-Add to your MCP client config (e.g. `claude_desktop_config.json` or `.mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "viviscape": {
-      "command": "npx",
-      "args": ["-y", "viviscape-mcp"]
-    }
-  }
-}
-```
-
-## OpenAI Codex CLI
-
-Codex accepts stdio MCP servers directly. Add to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.viviscape]
-command = "npx"
-args = ["-y", "viviscape-mcp"]
-```
-
-## ChatGPT (Developer Mode / Apps SDK)
-
-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
-publicly (Cloudflare Tunnel, ngrok, or deploy to a host).
-
-Example with `supergateway`:
-
-```bash
-npx viviscape-mcp login   # once, on the host running the gateway
-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.
-
-Expose `http://localhost:8000/sse` publicly, then in ChatGPT:
-
-**Settings -> Connectors -> Create -> Custom MCP server**
-- **URL:** `https://your-public-host/sse`
-- **Auth:** none (or bearer, depending on your gateway)
-
-## Tools
-
-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`
-- **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`
-- **Task tags** - `task_tags` (list/add/remove), `tasks_by_tag` (tasks carrying a label, or the account tag vocabulary), and a `tags` list on `task_add`
-- **Task references** - `task_references` (list/add/remove), `task_search` (find a task by keyword or id)
-- **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`)
-- **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, discussion, 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.
-
-### Task tags
-
-`task_tags` lists, adds, and removes the tags shown on the task board, and
-`task_add` takes a `tags` list so a generated task lands already categorised
-(handy for marking agent-written work).
-
-Verified behaviour, so callers do not have to discover it:
-
-- Labels are stored upper-case, and `add` is idempotent per label - re-adding
-  one returns the existing tag, not a duplicate.
-- `add` returns the persisted tag with its `tag_id`; `remove` takes that
-  `tag_id`, not the label, and answers `true` (unlike `note_tags`, whose remove
-  answers `false` even on success).
-- `color` is any hex string, defaulting to the board palette's first entry
-  (`#00325e`).
-- `task_tags` is per task, and list rows from `tasks_open` / `project_tasks`
-  carry `tags: null`, so read one task's tags with `task_tags` or `task_get`.
-- `tasks_by_tag` goes the other way, from a label to the tasks carrying it.
-  Labels match trimmed and case insensitively; `match: "any"` (default) returns
-  a task carrying at least one label, `match: "all"` only tasks carrying every
-  one. An optional `status` list narrows further. Hits are light rows that
-  carry the task's whole tag set, so the other labels arrive with the hit.
-  Called with no `tags`, it returns the account's tag vocabulary instead -
-  every distinct label with the number of tasks using it.
-- A tag failure inside `task_add` never fails the create: the task is returned
-  with the per-tag error recorded in its `tags` array.
-
-### Task references
-
-`task_references` links related tasks to each other - a duplicate, a blocker,
-the ticket a task came from - and `task_search` finds the id to link when only
-a keyword is known.
-
-Verified behaviour:
-
-- Links are **symmetric**. Adding A to B makes the pair visible from both
-  tasks, so link once; mirroring it by hand just returns the same row.
-- `list` rows describe the *other* task: `related_task_id` plus its title,
-  status, project and company, so a reference list needs no follow-up
-  `task_get`.
-- `add` is idempotent per pair (in either direction) and returns the persisted
-  link with its `reference_id`; `remove` takes that `reference_id`, not a task
-  id, and answers `true`.
-- Both tasks must belong to the signed-in account; a cross-account id comes
-  back as an empty link rather than an error.
-- `task_search` matches the task title, the description, and - for a numeric
-  query - the task id itself. It covers tickets too, so it is the one keyword
-  route that reaches ticket rows `tasks_open` never returns.
-
-### Task notes
-
-`task_update` takes a `notes` field: the free-form working notes on the task's
-Overview tab, stored as HTML by the rich-text editor. It **replaces** the field
-outright, so read the current value with `task_get` and send the merged text
-rather than only the new lines.
-
-### 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)
-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
-
-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`,
-`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
-npm install
-npm run dev      # run with tsx, hot reload
-npm run build    # compile to dist/
-npm start        # run compiled
-```
-
-## License
-
-MIT
+# 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.
+
+## Installation
+
+No install needed - run via `npx`:
+
+```bash
+npx viviscape-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g viviscape-mcp
+```
+
+## Sign in
+
+Authentication is per-user, the same browser flow the ViviScape CLI uses - no
+API keys. Sign in once:
+
+```bash
+npx viviscape-mcp login
+```
+
+A browser tab opens on ViviScape Work; confirm **Allow access** and the session
+is stored in Windows Credential Manager (or `~/.viviscape/mcp-credentials.json`
+on macOS/Linux). Every tool call then runs as *you*: your user id, account,
+role, and plan come from the session, so tools see exactly the data you can see
+in the app.
+
+```bash
+npx viviscape-mcp status    # who am I, which account, role, plan
+npx viviscape-mcp logout    # clear the stored session
+```
+
+If you already ran `vs auth login` with the [ViviScape CLI](https://viviscape.io),
+that session is picked up automatically. Inside an MCP client you can also call
+the `auth_login`, `auth_status`, and `auth_logout` tools. Sessions expire; when
+one does, tools report it and you re-run `login`.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VIVISCAPE_BASE_URL` | no | `https://work.viviscape.io` | ViviScape Work base URL |
+
+## Claude Desktop / Claude Code
+
+Add to your MCP client config (e.g. `claude_desktop_config.json` or `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "viviscape": {
+      "command": "npx",
+      "args": ["-y", "viviscape-mcp"]
+    }
+  }
+}
+```
+
+## OpenAI Codex CLI
+
+Codex accepts stdio MCP servers directly. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.viviscape]
+command = "npx"
+args = ["-y", "viviscape-mcp"]
+```
+
+## ChatGPT (Developer Mode / Apps SDK)
+
+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
+publicly (Cloudflare Tunnel, ngrok, or deploy to a host).
+
+Example with `supergateway`:
+
+```bash
+npx viviscape-mcp login   # once, on the host running the gateway
+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.
+
+Expose `http://localhost:8000/sse` publicly, then in ChatGPT:
+
+**Settings -> Connectors -> Create -> Custom MCP server**
+- **URL:** `https://your-public-host/sse`
+- **Auth:** none (or bearer, depending on your gateway)
+
+## Tools
+
+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`
+- **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`, `task_complete`
+- **Task tags** - `task_tags` (list/add/remove), `tasks_by_tag` (tasks carrying a label, or the account tag vocabulary), and a `tags` list on `task_add`
+- **Task references** - `task_references` (list/add/remove), `task_search` (find a task by keyword or id)
+- **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`, `task_log_time` (quick log against a task, or a note-only entry)
+- **Personal logs** - `personal_logs`, `personal_log_add`, `personal_log_remove` (service work that belongs to no task)
+- **Time clock** - `timeclock_punch` (in/out), `timeclock_history`
+- **Tickets** - `tickets_list` (the open, closed, or complete ticket queue; enterprise plan)
+- **Notes** - `note_add`, `note_get`, `note_update`, `note_remove`, `notes_mine`, `notes_query`, `notes_account`, `note_revisions`
+- **Second Brain** - `kb_search` (semantic search over tickets, plans, notes, products, resolutions and SOPs), `kb_sop` (list/get/save an SOP), `kb_status`, `kb_reindex`
+- **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, discussion, 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.
+
+### Task tags
+
+`task_tags` lists, adds, and removes the tags shown on the task board, and
+`task_add` takes a `tags` list so a generated task lands already categorised
+(handy for marking agent-written work).
+
+Verified behaviour, so callers do not have to discover it:
+
+- Labels are stored upper-case, and `add` is idempotent per label - re-adding
+  one returns the existing tag, not a duplicate.
+- `add` returns the persisted tag with its `tag_id`; `remove` takes that
+  `tag_id`, not the label, and answers `true` (unlike `note_tags`, whose remove
+  answers `false` even on success).
+- `color` is any hex string, defaulting to the board palette's first entry
+  (`#00325e`).
+- `task_tags` is per task, and list rows from `tasks_open` / `project_tasks`
+  carry `tags: null`, so read one task's tags with `task_tags` or `task_get`.
+- `tasks_by_tag` goes the other way, from a label to the tasks carrying it.
+  Labels match trimmed and case insensitively; `match: "any"` (default) returns
+  a task carrying at least one label, `match: "all"` only tasks carrying every
+  one. An optional `status` list narrows further. Hits are light rows that
+  carry the task's whole tag set, so the other labels arrive with the hit.
+  Called with no `tags`, it returns the account's tag vocabulary instead -
+  every distinct label with the number of tasks using it.
+- A tag failure inside `task_add` never fails the create: the task is returned
+  with the per-tag error recorded in its `tags` array.
+
+### Task references
+
+`task_references` links related tasks to each other - a duplicate, a blocker,
+the ticket a task came from - and `task_search` finds the id to link when only
+a keyword is known.
+
+Verified behaviour:
+
+- Links are **symmetric**. Adding A to B makes the pair visible from both
+  tasks, so link once; mirroring it by hand just returns the same row.
+- `list` rows describe the *other* task: `related_task_id` plus its title,
+  status, project and company, so a reference list needs no follow-up
+  `task_get`.
+- `add` is idempotent per pair (in either direction) and returns the persisted
+  link with its `reference_id`; `remove` takes that `reference_id`, not a task
+  id, and answers `true`.
+- Both tasks must belong to the signed-in account; a cross-account id comes
+  back as an empty link rather than an error.
+- `task_search` matches the task title, the description, and - for a numeric
+  query - the task id itself. It covers tickets too, so it is the one keyword
+  route that reaches ticket rows `tasks_open` never returns.
+
+### Task notes
+
+`task_update` takes a `notes` field: the free-form working notes on the task's
+Overview tab, stored as HTML by the rich-text editor. It **replaces** the field
+outright, so read the current value with `task_get` and send the merged text
+rather than only the new lines.
+
+### Task plans
+
+`task_add` and `task_update` take a `plan` field: the plan of action for the
+task or ticket -- the ordered steps an agent intends to take **before** it
+starts, so the work is inspectable and the next agent can pick it up. It shows
+up in the portal on the task's Plan tab, immediately left of Solution.
+
+Read it back with `task_get`, or across a set of tasks by asking a list tool
+for it (`fields: ["task_id", "task", "plan"]`) -- the default field set is
+light and leaves it out. Like `notes`, it **replaces** the field outright, so
+send the merged text rather than only the new steps. Omitting the argument
+leaves an existing plan untouched.
+
+The three long-text fields divide up as: `plan` = what will be done,
+`notes` = the extended instructions and scenario, `solution` = the outcome.
+
+### Second Brain
+
+`kb_search` reads the account knowledge base: the semantic index over tickets
+(description, plan, notes, solution), notes, products, distilled resolutions and
+SOPs. Consult it *before* planning work — it answers whether the thing has been
+solved here before.
+
+Two traps:
+
+- An empty result is **not** proof the knowledge is absent. Search answers with
+  no hits, not an error, when Second Brain is switched off for the account or
+  its AI token budget is inside the reserve. `kb_status` distinguishes the two.
+- A `kb_sop` save is *queued* for indexing, not indexed on the spot, so it does
+  not turn up in `kb_search` until the next ingest tick.
+
+Ticket and note knowledge is ingested automatically. An SOP is the only
+knowledge an agent authors directly, so `kb_sop` save is how a lesson from one
+ticket becomes reusable — search `source_types: ["sop"]` first and update the
+existing SOP rather than filing a near-duplicate.
+
+### 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`,
+`task_log_time`, `personal_log_add`, `timeclock_punch`, `task_complete`,
+`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)
+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
+
+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`,
+`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
+npm install
+npm run dev      # run with tsx, hot reload
+npm run build    # compile to dist/
+npm start        # run compiled
+```
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -153,6 +153,25 @@ export declare class ViviScapeClient {
     deleteTask(taskId: number): Promise<unknown>;
     /** Fold one task into another; the source task is consumed. */
     mergeTasks(fromTaskId: number, toTaskId: number): Promise<unknown>;
+    /**
+     * Close a task through the platform's completion route (what `vs tasks done`
+     * calls). This is not the same as posting status "completed": the route also
+     * stamps the completing user and runs the milestone/progress rollup the task
+     * board relies on.
+     */
+    completeTask(taskId: number, userId?: number): Promise<unknown>;
+    /**
+     * The ticket queue, filtered server-side by status set, company and team --
+     * the view behind `vs tickets list`. Closed tickets live on their own route.
+     * Tickets are Group_Tasks, so the rows are task rows and task_get reads one.
+     */
+    lookupTickets(opts?: {
+        status?: 'open' | 'closed' | 'all';
+        statuses?: string[];
+        query?: string;
+        company_id?: number;
+        team?: string;
+    }): Promise<unknown>;
     getTaskTags(taskId: number): Promise<unknown>;
     /**
      * Tag a task. The web app upper-cases the label and always sends a colour, so
@@ -209,6 +228,39 @@ export declare class ViviScapeClient {
     removeMilestone(milestoneId: number): Promise<unknown>;
     addTimeLog(data: Record<string, unknown>): Promise<unknown>;
     updateTimeLog(data: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Log time against a task the short way (`vs tasks log`). The quick route
+     * fills group_id and service_id from the task itself, so only the note, the
+     * duration and the date are needed. A zero duration posts a note-only entry:
+     * it lands on the task's time feed without adding hours.
+     */
+    quickLogTime(data: {
+        task_id: number;
+        note: string;
+        duration?: string;
+        log_date?: string;
+        billable?: boolean;
+    }): Promise<unknown>;
+    /** Personal (non-task) time logs for a user -- the `vs logs list` feed. */
+    getPersonalLogs(userId?: number): Promise<unknown>;
+    /**
+     * Add a personal time log: work that belongs to a service rather than to any
+     * task. start_date and end_date mirror log_date, which is what the web form
+     * posts for a single-day entry.
+     */
+    addPersonalLog(data: {
+        note: string;
+        duration?: string;
+        service_id?: number;
+        log_date?: string;
+    }): Promise<unknown>;
+    removePersonalLog(logId: number | string): Promise<unknown>;
+    /**
+     * Punch the time clock. type "in" opens a punch, "out" closes the open one;
+     * both go to the same route with clocked_in set accordingly.
+     */
+    addPunch(type: 'in' | 'out', note?: string): Promise<unknown>;
+    getPunchHistory(userId?: number): Promise<unknown>;
     getMyNotes(): Promise<unknown>;
     getNoteById(noteId: number | string): Promise<unknown>;
     addNote(data: Record<string, unknown>): Promise<unknown>;
@@ -295,6 +347,41 @@ export declare class ViviScapeClient {
             service_id?: number;
         }>;
     }): Promise<unknown>;
+    /**
+     * Semantic search over the account knowledge base -- tickets and their plans,
+     * notes, products, distilled resolutions, and SOPs.
+     *
+     * Answers an empty list, not an error, when Second Brain is disabled for the
+     * account or its AI token budget is inside the reserve, so "no hits" is NOT
+     * proof the knowledge is absent. Check kbStatus() before concluding that.
+     */
+    kbSearch(query: string, opts?: {
+        top_k?: number;
+        company_id?: number;
+        product_id?: string;
+        source_types?: string[];
+        visibility?: string[];
+    }): Promise<unknown>;
+    kbStatus(): Promise<unknown>;
+    kbFreshness(): Promise<unknown>;
+    listSops(opts?: {
+        product_id?: string;
+        status?: string;
+    }): Promise<unknown>;
+    getSop(sopId: string): Promise<unknown>;
+    /**
+     * Create or update an SOP -- the durable, deliberately authored half of the
+     * brain, and the way an agent contributes knowledge that outlives one ticket.
+     * The server stamps account and creator, then queues the SOP for indexing, so
+     * a save becomes searchable on the next ingest tick rather than immediately.
+     * Passing sop_id updates in place; omitting it creates.
+     */
+    saveSop(sop: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Queue one source for (re)indexing. The portal already enqueues on write,
+     * so this is for repairing a document that never made it into the brain.
+     */
+    kbEnqueue(sourceType: string, sourceKey: string, priority?: 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

@@ -50,6 +50,46 @@ function parseShorthandDuration(input) {
     const mm = String(minutes).padStart(2, '0');
     return { duration: `${hh}:${mm}:00`, log_time: raw };
 }
+/**
+ * Total minutes from shorthand ("1h30m", "45m", "2h", "90"). Used by the quick
+ * log and personal log routes, which want human text ("1h 30m") rather than the
+ * HH:MM:SS TimeSpan the full LOG_Time payload carries.
+ */
+function shorthandToMinutes(input) {
+    const raw = String(input ?? '').trim();
+    if (!raw)
+        return 0;
+    const clock = raw.match(/^(\d{1,2}):(\d{2})(?::\d{2})?$/);
+    if (clock)
+        return parseInt(clock[1], 10) * 60 + parseInt(clock[2], 10);
+    const hMatch = raw.match(/(\d+(?:\.\d+)?)\s*h/i);
+    const mMatch = raw.match(/(\d+)\s*m/i);
+    if (!hMatch && !mMatch) {
+        const bare = Number(raw);
+        return Number.isFinite(bare) ? Math.round(bare) : 0;
+    }
+    const hours = hMatch ? parseFloat(hMatch[1]) : 0;
+    const minutes = mMatch ? parseInt(mMatch[1], 10) : 0;
+    return Math.round(hours * 60) + minutes;
+}
+/** "1h 30m" / "45m" -- the log_time text the quick and personal log routes store. */
+function friendlyDuration(totalMinutes) {
+    if (totalMinutes <= 0)
+        return '';
+    if (totalMinutes < 60)
+        return `${totalMinutes}m`;
+    const h = Math.floor(totalMinutes / 60);
+    const m = totalMinutes % 60;
+    return m ? `${h}h ${m}m` : `${h}h`;
+}
+/** MM/DD/YYYY -- the date format both log routes expect. */
+function usDate(value) {
+    const d = value ? new Date(value) : new Date();
+    const use = Number.isNaN(d.getTime()) ? new Date() : d;
+    const mm = String(use.getMonth() + 1).padStart(2, '0');
+    const dd = String(use.getDate()).padStart(2, '0');
+    return `${mm}/${dd}/${use.getFullYear()}`;
+}
 /**
  * Build a full Group_Task payload from simplified MCP tool params.
  */
@@ -88,6 +128,8 @@ function buildTaskPayload(data, ctx) {
     };
     if (data.notes)
         payload.notes = data.notes;
+    if (data.plan)
+        payload.plan = data.plan;
     if (data.company_id)
         payload.company_id = data.company_id;
     if (data.assigned_to) {
@@ -108,6 +150,8 @@ function buildTaskUpdatePayload(data) {
         mapped.description = data.description;
     if (data.notes !== undefined)
         mapped.notes = data.notes;
+    if (data.plan !== undefined)
+        mapped.plan = data.plan;
     if (data.status !== undefined)
         mapped.status = data.status;
     if (data.priority !== undefined) {
@@ -633,6 +677,39 @@ export class ViviScapeClient {
     async mergeTasks(fromTaskId, toTaskId) {
         return this.post('tasks/merge', { task_from_id: fromTaskId, task_to_id: toTaskId });
     }
+    /**
+     * Close a task through the platform's completion route (what `vs tasks done`
+     * calls). This is not the same as posting status "completed": the route also
+     * stamps the completing user and runs the milestone/progress rollup the task
+     * board relies on.
+     */
+    async completeTask(taskId, userId) {
+        return this.get(`complete/task?task_id=${taskId}&user_id=${userId || this.userId}`);
+    }
+    // -- Tickets ------------------------------------------------
+    /**
+     * The ticket queue, filtered server-side by status set, company and team --
+     * the view behind `vs tickets list`. Closed tickets live on their own route.
+     * Tickets are Group_Tasks, so the rows are task rows and task_get reads one.
+     */
+    async lookupTickets(opts = {}) {
+        const state = opts.status ?? 'open';
+        const statuses = opts.statuses?.length
+            ? opts.statuses
+            : state === 'all'
+                ? []
+                : state === 'closed'
+                    ? ['completed', 'cancelled']
+                    : ['backlog', 'new', 'research', 'inprogress', 'testing', 'inreview', 'onhold'];
+        const path = state === 'closed' ? 'tickets/completed/lookup' : 'tickets/lookup';
+        return this.post(path, {
+            company_id: opts.company_id ?? 0,
+            status: '',
+            statuses,
+            query: opts.query ?? '',
+            teamfilter: opts.team ?? '',
+        });
+    }
     // -- Task tags ----------------------------------------------
     async getTaskTags(taskId) {
         return this.get(`grouptask/tags/${taskId}`);
@@ -777,6 +854,70 @@ export class ViviScapeClient {
     async updateTimeLog(data) {
         return this.post('logs/update', buildTimeLogPayload(data, this.ctx));
     }
+    /**
+     * Log time against a task the short way (`vs tasks log`). The quick route
+     * fills group_id and service_id from the task itself, so only the note, the
+     * duration and the date are needed. A zero duration posts a note-only entry:
+     * it lands on the task's time feed without adding hours.
+     */
+    async quickLogTime(data) {
+        const minutes = shorthandToMinutes(data.duration ?? '');
+        return this.post('quick/logs/add', {
+            account_id: this.accountId,
+            user_id: this.userId,
+            task_id: data.task_id,
+            note: data.note,
+            log_time: friendlyDuration(minutes),
+            log_date: usDate(data.log_date),
+            isnoteonly: minutes <= 0,
+            billable: data.billable ?? false,
+        });
+    }
+    // -- Personal logs -------------------------------------------
+    /** Personal (non-task) time logs for a user -- the `vs logs list` feed. */
+    async getPersonalLogs(userId) {
+        return this.get(`personal/logs/user/${userId || this.userId}`);
+    }
+    /**
+     * Add a personal time log: work that belongs to a service rather than to any
+     * task. start_date and end_date mirror log_date, which is what the web form
+     * posts for a single-day entry.
+     */
+    async addPersonalLog(data) {
+        const date = usDate(data.log_date);
+        return this.post('personal/log/add', {
+            account_id: this.accountId,
+            user_id: this.userId,
+            service_id: data.service_id ?? 0,
+            note: data.note,
+            log_time: friendlyDuration(shorthandToMinutes(data.duration ?? '')),
+            log_date: date,
+            start_date: date,
+            end_date: date,
+        });
+    }
+    async removePersonalLog(logId) {
+        return this.get(`personal/log/remove/${logId}`);
+    }
+    // -- Time clock ----------------------------------------------
+    /**
+     * Punch the time clock. type "in" opens a punch, "out" closes the open one;
+     * both go to the same route with clocked_in set accordingly.
+     */
+    async addPunch(type, note = '') {
+        return this.post('user/punch/add', {
+            type,
+            note,
+            user_id: this.userId,
+            account_id: this.accountId,
+            platform_account_id: this.accountId,
+            punch_time: nowIso(),
+            clocked_in: type === 'in',
+        });
+    }
+    async getPunchHistory(userId) {
+        return this.get(`user/punch/history?user_id=${userId || this.userId}&account_id=${this.accountId}`);
+    }
     // -- Notes --------------------------------------------------
     async getMyNotes() {
         return this.get('notes/me');
@@ -1061,6 +1202,64 @@ export class ViviScapeClient {
             })),
         });
     }
+    // -- Second Brain (knowledge base) ---------------------------
+    /**
+     * Semantic search over the account knowledge base -- tickets and their plans,
+     * notes, products, distilled resolutions, and SOPs.
+     *
+     * Answers an empty list, not an error, when Second Brain is disabled for the
+     * account or its AI token budget is inside the reserve, so "no hits" is NOT
+     * proof the knowledge is absent. Check kbStatus() before concluding that.
+     */
+    async kbSearch(query, opts = {}) {
+        return this.post('kb/search', {
+            query,
+            top_k: opts.top_k && opts.top_k > 0 ? opts.top_k : 8,
+            company_id: opts.company_id,
+            product_id: opts.product_id,
+            source_types: opts.source_types,
+            visibility: opts.visibility,
+        });
+    }
+    async kbStatus() {
+        return this.get('kb/account/status');
+    }
+    async kbFreshness() {
+        return this.get('kb/freshness');
+    }
+    async listSops(opts = {}) {
+        const qs = [
+            opts.product_id ? `product_id=${encodeURIComponent(opts.product_id)}` : '',
+            opts.status ? `status=${encodeURIComponent(opts.status)}` : '',
+        ].filter(Boolean).join('&');
+        return this.get(`kb/sop/list${qs ? '?' + qs : ''}`);
+    }
+    async getSop(sopId) {
+        return this.get(`kb/sop/${sopId}`);
+    }
+    /**
+     * Create or update an SOP -- the durable, deliberately authored half of the
+     * brain, and the way an agent contributes knowledge that outlives one ticket.
+     * The server stamps account and creator, then queues the SOP for indexing, so
+     * a save becomes searchable on the next ingest tick rather than immediately.
+     * Passing sop_id updates in place; omitting it creates.
+     */
+    async saveSop(sop) {
+        return this.post('kb/sop/save', sop);
+    }
+    /**
+     * Queue one source for (re)indexing. The portal already enqueues on write,
+     * so this is for repairing a document that never made it into the brain.
+     */
+    async kbEnqueue(sourceType, sourceKey, priority = 5) {
+        return this.post('kb/enqueue', {
+            account_id: this.accountId,
+            source_type: sourceType,
+            source_key: sourceKey,
+            operation: 'upsert',
+            priority,
+        });
+    }
     // -- Insights -----------------------------------------------
     async getHoursByPerson(data) {
         const userId = Number(data.user_id) || this.userId;

package/dist/auth/permissions.js

@@ -60,6 +60,16 @@ export function featureForPath(path) {
         return 'insights';
     if (p.startsWith('logs') || p.startsWith('timelog'))
         return 'logs';
+    // Quick task logging and personal logs are the same Pro-tier logging feature.
+    if (p.startsWith('quick/logs') || p.startsWith('personal/log'))
+        return 'logs';
+    if (p.startsWith('ticket'))
+        return 'tickets';
+    if (p.startsWith('user/punch'))
+        return 'time';
+    // Task completion route sits outside the tasks/* prefix.
+    if (p.startsWith('complete/task'))
+        return 'tasks';
     if (p.startsWith('prospect'))
         return 'crm';
     if (p.startsWith('task/comment'))

package/dist/index.js

@@ -35,7 +35,7 @@ function invalidateClient() {
 }
 const server = new McpServer({
     name: 'viviscape',
-    version: '2.0.0',
+    version: '2.9.0',
 });
 function json(data) {
     return JSON.stringify(data, null, 2);
@@ -57,7 +57,7 @@ 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.'),
+        .describe('Columns to return. Omit for a PM-relevant default; ["all"] for every column. The default set is light: ask for e.g. ["task_id","task","plan"] to read plans across a set of tasks.'),
     limit: z.number().optional().describe('Max rows to return (default 50)'),
     offset: z.number().optional().describe('Rows to skip, for paging (default 0)'),
 };
@@ -378,6 +378,7 @@ server.tool('task_add', 'Add a task to a project. The API requires a full Group_
     title: z.string().describe('Task title'),
     description: z.string().optional().describe('Task description'),
     notes: z.string().optional().describe('Task notes'),
+    plan: z.string().optional().describe('Plan of action for the new task -- the ordered steps to be taken before the work starts. Use notes for the extended instructions and scenario.'),
     assigned_to: z.number().optional().describe('User ID to assign the task to. The signed-in user is always recorded as creator.'),
     company_id: z.number().optional().describe('Company ID associated with the project'),
     service_id: z.number().optional().describe('Service ID classifying the work type'),
@@ -416,11 +417,12 @@ server.tool('task_add', 'Add a task to a project. The API requires a full Group_
     });
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('task_update', 'Update a task. Fetches existing task first and merges changes.', {
+server.tool('task_update', 'Update a task. Fetches existing task first and merges changes. This is where an agent records its plan -- see the plan argument.', {
     task_id: z.number().describe('Task ID to update'),
     title: z.string().optional().describe('Task title'),
     description: z.string().optional(),
     notes: z.string().optional().describe('Task notes -- the free-form working notes on the task Overview tab, held in HTML by the editor. Replaces the field outright, so read the current value with task_get and send the merged text rather than only the new lines.'),
+    plan: z.string().optional().describe('Plan of action for the task -- the ordered steps an agent intends to take BEFORE it starts, so the work is inspectable and the next agent can pick it up. Held in HTML by the Plan tab editor; plain text is accepted and stored as typed. Replaces the field outright, so read the current value with task_get and send the merged text rather than only the new steps. Use notes for the extended instructions and scenario, and solution for the outcome. Omit the argument to leave an existing plan untouched.'),
     assigned_to: z.number().optional().describe('User ID to assign to'),
     priority: z.enum(PRIORITIES).optional().describe('Priority (platform values)'),
     status: z.enum(TASK_STATUSES).optional().describe('Task status (platform values)'),
@@ -892,6 +894,35 @@ server.tool('task_merge', 'Merge one task into another. The source task is consu
     const result = await requireClient().mergeTasks(from_task_id, to_task_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
+server.tool('task_complete', 'Close a task through the platform completion route. Prefer this over task_update with status "completed": it also stamps who finished the work and runs the milestone/progress rollup the task board reads.', {
+    task_id: z.number().describe('Task ID to complete'),
+    user_id: z.number().optional().describe('User completing the task. Defaults to the signed-in user.'),
+    ...idempotencyArg,
+}, async ({ task_id, user_id, idempotency_key }) => {
+    const result = await once('task_complete', idempotency_key, () => requireClient().completeTask(task_id, user_id));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// TICKETS
+// ============================================================
+server.tool('tickets_list', 'The account ticket queue, filtered server-side by status set, company and team. status "open" (default) covers backlog, new, research, inprogress, testing, inreview and onhold; "closed" reads the completed/cancelled route; "all" drops the status filter. Tickets are tasks, so rows are task rows -- read one with task_get and search by keyword with task_search. Requires the enterprise plan.', {
+    status: z.enum(['open', 'closed', 'all']).optional().describe('Which ticket queue to read (default: open)'),
+    statuses: z.array(z.enum(TASK_STATUSES)).optional().describe('Exact status set, overriding the status shorthand'),
+    query: z.string().optional().describe('Search text matched server-side'),
+    company_id: z.number().optional().describe('Only tickets for this company'),
+    team: z.string().optional().describe('Team filter passed through to the API'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().lookupTickets({
+        status: params.status,
+        statuses: params.statuses,
+        query: params.query,
+        company_id: params.company_id,
+        team: params.team,
+    });
+    const rows = Array.isArray(result) ? annotateTasks(result) : result;
+    return { content: [{ type: 'text', text: json(shape(since(rows, params), TASK_FIELDS, paging(params))) }] };
+});
 // ============================================================
 // TASK COMMENTS
 // ============================================================
@@ -963,6 +994,56 @@ server.tool('timelog_update', 'Update an existing time log entry. Builds full LO
     const result = await requireClient().updateTimeLog(params);
     return { content: [{ type: 'text', text: json(result) }] };
 });
+server.tool('task_log_time', 'Log time against a task the short way: the quick route takes the project and service from the task itself, so only the note matters. Omit duration (or pass 0) to post a note-only entry -- it lands on the task time feed without adding hours. Use timelog_add when the entry needs an explicit project, service or user.', {
+    task_id: z.number().describe('Task ID to log against'),
+    note: z.string().describe('What was worked on'),
+    duration: z.string().optional().describe('Duration in shorthand (e.g., 1h30m, 45m, 2h). Omit for a note-only entry.'),
+    log_date: z.string().optional().describe('Date of the work (ISO 8601). Defaults to today.'),
+    billable: z.boolean().optional().describe('Whether this time is billable (default false)'),
+    ...idempotencyArg,
+}, async (params) => {
+    const result = await once('task_log_time', params.idempotency_key, () => requireClient().quickLogTime(params));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+// ============================================================
+// PERSONAL LOGS AND TIME CLOCK
+// ============================================================
+server.tool('personal_logs', 'Personal time logs for a user -- work booked against a service rather than any task.', {
+    user_id: z.number().optional().describe('User whose logs to read. Defaults to the signed-in user.'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getPersonalLogs(params.user_id);
+    return { content: [{ type: 'text', text: json(shape(since(result, params), [], paging(params))) }] };
+});
+server.tool('personal_log_add', 'Add a personal time log: work that belongs to a service rather than to a task. For task work use task_log_time or timelog_add.', {
+    note: z.string().describe('What was worked on'),
+    duration: z.string().optional().describe('Duration in shorthand (e.g., 1h30m, 45m, 2h)'),
+    service_id: z.number().optional().describe('Service ID classifying the work type'),
+    log_date: z.string().optional().describe('Date of the work (ISO 8601). Defaults to today.'),
+    ...idempotencyArg,
+}, async (params) => {
+    const result = await once('personal_log_add', params.idempotency_key, () => requireClient().addPersonalLog(params));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('personal_log_remove', 'Delete a personal time log by its log_id (from personal_logs).', { log_id: z.number().describe('Personal log ID to remove') }, async ({ log_id }) => {
+    const result = await requireClient().removePersonalLog(log_id);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('timeclock_punch', 'Punch the time clock for the signed-in user. type "in" opens a punch, "out" closes the open one. This is the attendance clock, separate from task time logs.', {
+    type: z.enum(['in', 'out']).describe('Punch direction'),
+    note: z.string().optional().describe('Optional punch note'),
+    ...idempotencyArg,
+}, async ({ type, note, idempotency_key }) => {
+    const result = await once('timeclock_punch', idempotency_key, () => requireClient().addPunch(type, note ?? ''));
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('timeclock_history', 'Time clock punch history for a user -- clock-in/clock-out pairs with their notes.', {
+    user_id: z.number().optional().describe('User whose punches to read. Defaults to the signed-in user.'),
+    ...pageArgs,
+}, async (params) => {
+    const result = await requireClient().getPunchHistory(params.user_id);
+    return { content: [{ type: 'text', text: json(shape(since(result, params), [], paging(params))) }] };
+});
 // ============================================================
 // NOTES
 // ============================================================
@@ -1100,6 +1181,74 @@ server.tool('insights_all_users_time', 'Get time totals for all users', {}, asyn
     const result = await requireClient().getAllUsersTime();
     return { content: [{ type: 'text', text: json(result) }] };
 });
+server.tool('kb_search', 'Search the account Second Brain -- the semantic index over tickets (their description, plan, notes and solution), notes, products, distilled resolutions and SOPs. This is the memory to consult BEFORE planning work: it answers "has this been solved here before, and how". Rows carry source_type + source_key, so a hit on a ticket names the task id to open with task_get, and a hit on an SOP names the sop_id to read with kb_sop. score is 1 - cosine distance, so higher is closer. IMPORTANT: an empty result is not proof the knowledge is absent -- the route answers with no hits when Second Brain is switched off for the account or its AI token budget is inside the reserve. Check kb_status when a search of an established account comes back empty.', {
+    query: z.string().describe('What to look for, in natural language -- this is embedded, so a question or a sentence retrieves better than a bare keyword'),
+    top_k: z.number().optional().describe('How many chunks to return (default 8)'),
+    company_id: z.number().optional().describe('Restrict to knowledge tied to one company'),
+    product_id: z.string().optional().describe('Restrict to knowledge tied to one product (GUID)'),
+    source_types: z.array(z.enum(['ticket', 'note', 'product', 'resolution', 'sop'])).optional()
+        .describe('Restrict to these kinds of source. Omit for all of them.'),
+    visibility: z.array(z.string()).optional()
+        .describe('Visibility bands to search; defaults to ["staff"]. Personal note knowledge is never reachable here.'),
+}, async ({ query, top_k, company_id, product_id, source_types, visibility }) => {
+    const result = await requireClient().kbSearch(query, { top_k, company_id, product_id, source_types, visibility });
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('kb_status', 'Report whether Second Brain is switched on for this account and how current its index is. Read this when kb_search comes back empty on an account that plainly has history: search answers with no hits (not an error) when the brain is disabled or the AI token budget is inside its reserve, and the freshness figures show what is still queued for ingest.', {}, async () => {
+    const c = requireClient();
+    const [status, freshness] = await Promise.all([c.kbStatus(), c.kbFreshness()]);
+    return { content: [{ type: 'text', text: json({ status, freshness }) }] };
+});
+server.tool('kb_sop', 'List, read, or write SOPs -- the durable, deliberately authored half of the Second Brain, and the way an agent contributes knowledge meant to outlive one ticket (a runbook, a recurring fix, a house convention). Ticket and note knowledge is ingested automatically; an SOP is the only knowledge an agent authors directly. save creates when sop_id is omitted and updates in place when it is given, and it returns the sop_id either way. A saved SOP is QUEUED for indexing rather than indexed on the spot, so kb_search will not surface it until the next ingest tick. Prefer updating the existing SOP over filing a near-duplicate: search first with kb_search source_types ["sop"]. New SOPs land as status "draft" so a person can approve them.', {
+    action: z.enum(['list', 'get', 'save']).describe('What to do'),
+    sop_id: z.string().optional().describe('SOP ID (get; and on save, to update that SOP in place instead of creating one)'),
+    title: z.string().optional().describe('SOP title (save, required)'),
+    body: z.string().optional().describe('The procedure itself (save). Plain text or light markdown; this is what gets embedded and retrieved.'),
+    triggers: z.string().optional().describe('When this SOP applies -- the symptoms, phrases or conditions that should pull it up (save)'),
+    product_id: z.string().optional().describe('Product this SOP belongs to (GUID), for both filtering a list and tagging a save'),
+    source_task_id: z.number().optional().describe('The task or ticket this SOP was written from (save) -- keeps the provenance of the procedure'),
+    status: z.enum(['draft', 'approved', 'archived']).optional()
+        .describe('On list, filter by status. On save, the status to store -- leave unset when creating so it lands as a draft for review.'),
+    visibility: z.enum(['staff', 'customer']).optional()
+        .describe('Who may retrieve this SOP (save). Defaults to staff; use customer only for text fit to leave the building.'),
+}, async ({ action, sop_id, title, body, triggers, product_id, source_task_id, status, visibility }) => {
+    const c = requireClient();
+    let result;
+    if (action === 'list') {
+        result = await c.listSops({ product_id, status });
+    }
+    else if (action === 'get') {
+        result = await c.getSop(need(action, 'sop_id', sop_id));
+    }
+    else {
+        // The server requires a title and fills account/creator itself. Only send
+        // what was supplied: an omitted field must not blank a stored one.
+        const sop = { title: need(action, 'title', title) };
+        if (sop_id !== undefined)
+            sop.sop_id = sop_id;
+        if (body !== undefined)
+            sop.body = body;
+        if (triggers !== undefined)
+            sop.triggers = triggers;
+        if (product_id !== undefined)
+            sop.product_id = product_id;
+        if (source_task_id !== undefined)
+            sop.source_task_id = source_task_id;
+        if (status !== undefined)
+            sop.status = status;
+        if (visibility !== undefined)
+            sop.visibility = visibility;
+        result = await c.saveSop(sop);
+    }
+    return { content: [{ type: 'text', text: json(result) }] };
+});
+server.tool('kb_reindex', 'Queue one source document for re-indexing into the Second Brain. The portal enqueues on every write already, so reach for this only to repair a document that never made it in -- a ticket whose plan or solution kb_search cannot find, say. source_key is the task id for a ticket, the note/product/SOP GUID otherwise.', {
+    source_type: z.enum(['ticket', 'note', 'product', 'resolution', 'sop']).describe('Kind of source to reindex'),
+    source_key: z.string().describe('Task id (ticket) or GUID (note, product, resolution, sop)'),
+}, async ({ source_type, source_key }) => {
+    const result = await requireClient().kbEnqueue(source_type, source_key);
+    return { content: [{ type: 'text', text: json(result) }] };
+});
 // ============================================================
 // START
 // ============================================================

package/dist/projection.js

@@ -90,7 +90,7 @@ export function filterTasks(rows, f) {
         if (f.assignee_id && !assigneeIds(row).includes(f.assignee_id))
             return false;
         if (f.search) {
-            const hay = `${lower(row.task)} ${lower(row.description)} ${lower(row.notes)}`;
+            const hay = `${lower(row.task)} ${lower(row.description)} ${lower(row.notes)} ${lower(row.plan)}`;
             if (!hay.includes(f.search.toLowerCase()))
                 return false;
         }

package/package.json

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