viviscape-mcp 2.6.0 → 2.7.0

package/README.md

@@ -1,247 +1,253 @@
-# 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`
+- **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

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

package/dist/api-client.js

@@ -654,6 +654,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

package/dist/index.js

@@ -433,7 +433,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 +467,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,

package/package.json

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