viviscape-mcp 2.6.0 → 2.8.0

package/README.md

@@ -1,247 +1,290 @@
-# 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), 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`).
-- Tags are per task. There is no tag-search route, and list rows from
-  `tasks_open` / `project_tasks` carry `tags: null`, so read a task's tags with
-  `task_tags` or `task_get`.
-- 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 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`
+- **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`,
+`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

@@ -162,6 +162,19 @@ export declare class ViviScapeClient {
     addTaskTag(taskId: number, tag: string, color?: string): Promise<unknown>;
     /** Takes the tag_id from getTaskTags, not the label. */
     removeTaskTag(tagId: string): Promise<unknown>;
+    /**
+     * Tasks carrying one or more tags. Labels are matched trimmed and case
+     * insensitively; match 'all' narrows to tasks carrying every label, 'any'
+     * (the default) returns tasks carrying at least one. Each hit carries its
+     * whole tag set, so a task's other labels come back with it.
+     */
+    searchTasksByTags(tags: string[], opts?: {
+        match?: 'any' | 'all';
+        status?: string[];
+        max?: number;
+    }): Promise<unknown>;
+    /** Every distinct task tag on the account, with the task count per label. */
+    getAccountTaskTags(): Promise<unknown>;
     /**
      * Cross references between tasks. The link is symmetric: adding A -> B makes
      * the pair visible from both tasks, and each row describes the OTHER task
@@ -282,6 +295,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

@@ -88,6 +88,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 +110,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) {
@@ -654,6 +658,25 @@ export class ViviScapeClient {
     async removeTaskTag(tagId) {
         return this.get(`grouptask/tag/remove/${tagId}`);
     }
+    /**
+     * Tasks carrying one or more tags. Labels are matched trimmed and case
+     * insensitively; match 'all' narrows to tasks carrying every label, 'any'
+     * (the default) returns tasks carrying at least one. Each hit carries its
+     * whole tag set, so a task's other labels come back with it.
+     */
+    async searchTasksByTags(tags, opts = {}) {
+        const params = new URLSearchParams({
+            tags: tags.map((t) => t.trim()).filter(Boolean).join(','),
+            match: opts.match ?? 'any',
+            status: (opts.status ?? []).map((s) => s.trim()).filter(Boolean).join(','),
+            max: String(opts.max ?? 25),
+        });
+        return this.get(`grouptask/tags/search?${params.toString()}`);
+    }
+    /** Every distinct task tag on the account, with the task count per label. */
+    async getAccountTaskTags() {
+        return this.get('grouptask/tags/all');
+    }
     // -- Task references ----------------------------------------
     /**
      * Cross references between tasks. The link is symmetric: adding A -> B makes
@@ -1042,6 +1065,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/index.js

@@ -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)'),
@@ -433,7 +435,7 @@ server.tool('task_get', 'Get a single task by ID', { task_id: z.number().describ
     const result = await requireClient().getTask(task_id);
     return { content: [{ type: 'text', text: json(result) }] };
 });
-server.tool('task_tags', 'List, add, or remove tags on a task -- the categorisation primitive of the task board, and the way to mark work an agent created or touched. Labels are stored upper-case, and add is idempotent per label: re-adding one returns the existing tag rather than a duplicate. add returns the persisted tag including its tag_id; remove takes that tag_id, not the label, and answers true. Tags are per task -- there is no tag search route, and list rows from tasks_open / project_tasks carry tags: null, so read a task tag set here or with task_get.', {
+server.tool('task_tags', 'List, add, or remove tags on a task -- the categorisation primitive of the task board, and the way to mark work an agent created or touched. Labels are stored upper-case, and add is idempotent per label: re-adding one returns the existing tag rather than a duplicate. add returns the persisted tag including its tag_id; remove takes that tag_id, not the label, and answers true. This tool is per task -- list rows from tasks_open / project_tasks carry tags: null, so read a task tag set here or with task_get. To go the other way, from a label to the tasks carrying it, use tasks_by_tag.', {
     action: z.enum(['list', 'add', 'remove']).describe('What to do'),
     task_id: z.number().optional().describe('Task ID (list, add)'),
     tag: z.string().optional().describe('Tag label (add). Stored upper-case.'),
@@ -467,6 +469,19 @@ server.tool('task_search', 'Keyword search over the account tasks and tickets --
     const result = await requireClient().searchTasks(query, { exclude_task_id, max });
     return { content: [{ type: 'text', text: json(result) }] };
 });
+server.tool('tasks_by_tag', 'Find the account tasks carrying given tags -- the reverse of task_tags, and the way a tag-driven queue is read (every task an agent marked, everything labelled RELEASE-BLOCKER, and so on). Labels match trimmed and case insensitively, so DEVOPS, devops and " DevOps " are the same tag. match "any" (default) returns a task carrying at least one label; match "all" narrows to tasks carrying every one. Rows are light (task_id, title, status, project, company) and carry the task whole tag set, so the other labels come back with the hit -- no follow-up task_tags call. Pass no tags to list instead the account tag vocabulary: every distinct label with the number of tasks using it, which is how to discover what is worth filtering on.', {
+    tags: z.array(z.string()).optional().describe('Tag labels to match. Omit or leave empty to list the account tag vocabulary instead.'),
+    match: z.enum(['any', 'all']).optional().describe('any = tasks carrying at least one of the tags (default); all = tasks carrying every one'),
+    status: z.array(z.enum(TASK_STATUSES)).optional().describe('Optional status filter, e.g. ["new","inprogress"]. Omit to include every status, completed and cancelled included.'),
+    max: z.number().optional().describe('Maximum rows to return (default 25, cap 100)'),
+}, async ({ tags, match, status, max }) => {
+    const c = requireClient();
+    const labels = (tags ?? []).map((t) => t.trim()).filter(Boolean);
+    const result = labels.length
+        ? await c.searchTasksByTags(labels, { match, status, max })
+        : await c.getAccountTaskTags();
+    return { content: [{ type: 'text', text: json(result) }] };
+});
 server.tool('tasks_pending', 'Get pending tasks for a user. Returns a page of trimmed rows; see fields/limit/offset.', {
     user_id: z.number().describe('User ID'),
     ...pageArgs,
@@ -1087,6 +1102,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.6.0",
+  "version": "2.8.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",