viviscape-mcp 2.7.0 → 2.8.0

package/README.md

@@ -116,6 +116,7 @@ The server exposes tools across these domains:
 - **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
@@ -194,6 +195,42 @@ 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

package/dist/api-client.d.ts

@@ -295,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) {
@@ -1061,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)'),
@@ -1100,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.7.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",