botnote 0.1.30 → 0.1.33

package/dist/mcp/server.js

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { serializeEntity } from "./http-client.js";
+import { BotnoteHttpError, serializeEntity } from "./http-client.js";
 import { VERSION } from "../version.js";
 // Inline kind constants so the MCP package can be packaged without pulling
 // drizzle / the db schema module at runtime.
@@ -18,12 +18,28 @@ const RECURRENCE_PRESETS = ["hourly", "daily", "weekly", "monthly", "yearly"];
 const RECURRENCE_ANCHORS = ["scheduled", "completion"];
 const WEEKDAYS = ["MO", "TU", "WE", "TH", "FR", "SA", "SU"];
 const PROJECT_STATUSES = ["planned", "active", "watching", "paused", "archived"];
-const EntityIdRef = z
+/** Accepts a full UUID, a unique UUID prefix (≥8 hex chars), or a human-readable KEY-SEQ such as BOT-55. */
+const EntityRef = z
     .string()
-    .min(8)
-    .max(36)
-    .regex(/^[0-9a-fA-F-]+$/)
-    .describe("Full entity UUID or a unique UUID prefix such as the first 8 hex characters.");
+    .min(1)
+    .max(40)
+    .describe("UUID, unique UUID prefix, or human-readable KEY-SEQ such as BOT-55.");
+/**
+ * Resolve an entity reference to a UUID (or pass through for the backend to handle).
+ * If `ref` matches the KEY-SEQ pattern (e.g. BOT-55), it calls getEntityByKey and
+ * returns the resolved UUID. Otherwise it passes `ref` through unchanged so the
+ * backend can resolve UUID / prefix as before.
+ */
+async function resolveEntityRef(c, ref) {
+    const keySeqMatch = /^([A-Z][A-Z0-9_]*)-(\d+)$/.exec(ref);
+    if (keySeqMatch) {
+        const projectKey = keySeqMatch[1];
+        const sequenceId = parseInt(keySeqMatch[2], 10);
+        const entity = await c.getEntityByKey(projectKey, sequenceId);
+        return entity.id;
+    }
+    return ref;
+}
 function displayTitle(e) {
     if (e.title && e.title.trim())
         return e.title;
@@ -32,9 +48,57 @@ function displayTitle(e) {
         return firstLine.length > 60 ? `${firstLine.slice(0, 60)}…` : firstLine;
     return "(untitled)";
 }
-function summarizeEntity(e) {
+/**
+ * Human-readable reference for an entity: KEY-SEQ (e.g. BOT-55) when the
+ * project key is known, otherwise kind/uuid-prefix. Both forms are accepted
+ * back as EntityRef inputs, so tool output never needs the full UUID.
+ */
+function entityRefLabel(e, projectKey) {
+    if (projectKey && e.sequenceId != null)
+        return `${projectKey}-${e.sequenceId}`;
+    return `${e.kind}/${e.id.slice(0, 8)}`;
+}
+function summarizeEntity(e, projectKey) {
     const tagPart = e.tags.length ? ` [${e.tags.join(", ")}]` : "";
-    return `${e.kind}/${e.id} · id: ${e.id} · ${displayTitle(e)}${tagPart}`;
+    const base = `${entityRefLabel(e, projectKey)} · ${displayTitle(e)}${tagPart}`;
+    if (e.kind !== "task")
+        return `${base} (note)`;
+    // Compact task suffix: status, optional priority, and due/completedAt date.
+    const parts = [e.status];
+    if (e.priority && e.priority !== "none")
+        parts.push(e.priority);
+    if (e.status === "done" && e.completedAt) {
+        parts.push(`done ${e.completedAt.slice(0, 10)}`);
+    }
+    else if (e.dueAt) {
+        parts.push(`due ${e.dueAt.slice(0, 10)}`);
+    }
+    return `${base} (${parts.join(", ")})`;
+}
+/**
+ * Format a caught error from a write-tool handler into a structured isError
+ * response. For BotnoteHttpError produces a human-readable hint keyed to the
+ * status code; for everything else falls back to the error message.
+ */
+function formatToolError(err) {
+    let text;
+    if (err instanceof BotnoteHttpError) {
+        const body = err.body?.trim() || err.statusText;
+        if (err.status === 404) {
+            text = `not found: ${body}`;
+        }
+        else if (err.status === 400 || err.status === 422) {
+            text = `invalid request: ${body}`;
+        }
+        else {
+            text = `HTTP ${err.status} ${err.statusText}: ${body}`;
+        }
+    }
+    else {
+        const e = err;
+        text = String(e?.message ?? err);
+    }
+    return { isError: true, content: [{ type: "text", text }] };
 }
 const ProjectKey = z
     .string()
@@ -43,12 +107,50 @@ const ProjectKey = z
     .regex(/^[A-Z][A-Z0-9_]*$/);
 const HexColor = z.string().regex(/^#[0-9a-fA-F]{6}$/);
 const IconName = z.string().min(1).max(40).regex(/^[a-z0-9_-]+$/);
+/**
+ * Server-level behavioral guidance, surfaced to MCP clients at initialize time
+ * (Claude Code injects it into the agent's context). Keep it short — this is
+ * always-on context for every session that connects to botnote.
+ */
+const SERVER_INSTRUCTIONS = `botnote is the user's task + memory system. Rules for agents:
+
+Proactive task capture (propose, don't silently create):
+- When a discussion turns into a decision to build/fix/do something, propose recording it as a task before starting the work.
+- When new work emerges mid-task that is outside the current task's scope, propose capturing it as a new task (link it via parentId or a reference) instead of silently doing it or letting it drop.
+- Confirm with the user before creating. Batch proposals at natural checkpoints rather than interrupting for every item.
+
+Task scope:
+- Keep tasks small: one focused session (roughly ≤1 hour). Propose splitting bigger work into a parent milestone task plus small subtasks via parentId.
+
+References:
+- Refer to tasks and notes by their KEY-SEQ identifier (e.g. BOT-55) when talking to the user, never by UUID.
+
+Session start: call opening_brief first to load project context.`;
 export function buildMcpServer(ctx) {
     const server = new McpServer({
         name: "botnote",
         version: ctx.version ?? VERSION
-    });
+    }, { instructions: SERVER_INSTRUCTIONS });
     const c = ctx.client;
+    // projectId → key cache used to render human-readable KEY-SEQ refs (BOT-55)
+    // in tool output. Loaded lazily; refreshed whenever an unknown projectId
+    // shows up (e.g. a project created after the cache was filled).
+    let projectKeyCache = null;
+    async function projectKeysFor(rows) {
+        const cache = projectKeyCache;
+        if (!cache || rows.some((e) => e.projectId && !cache.has(e.projectId))) {
+            const projects = await c.listProjects({ includeArchived: true });
+            projectKeyCache = new Map(projects.map((p) => [p.id, p.key]));
+        }
+        return projectKeyCache;
+    }
+    async function summarizeAll(rows) {
+        const keys = await projectKeysFor(rows);
+        return rows.map((e) => summarizeEntity(e, e.projectId ? (keys.get(e.projectId) ?? null) : null));
+    }
+    async function summarize(e) {
+        return (await summarizeAll([e]))[0];
+    }
     // ----- 1. opening_brief -----
     server.registerTool("opening_brief", {
         title: "Opening Brief",
@@ -93,7 +195,8 @@ export function buildMcpServer(ctx) {
             kind,
             limit
         });
-        const lines = hits.map((h) => `${h.score.toFixed(4)} ${summarizeEntity(h.entity)}\n    ${h.entity.body.slice(0, 200).replace(/\n/g, " ")}`);
+        const summaries = await summarizeAll(hits.map((h) => h.entity));
+        const lines = hits.map((h, i) => `${h.score.toFixed(4)} ${summaries[i]}\n    ${h.entity.body.slice(0, 200).replace(/\n/g, " ")}`);
         return {
             content: [
                 {
@@ -128,13 +231,14 @@ export function buildMcpServer(ctx) {
             kinds,
             limit
         });
+        const summaries = await summarizeAll(rows);
         return {
             content: [
                 {
                     type: "text",
                     text: rows.length
                         ? rows
-                            .map((r) => `${r.createdAt.slice(0, 16).replace("T", " ")} · ${summarizeEntity(r)}`)
+                            .map((r, i) => `${r.createdAt.slice(0, 16).replace("T", " ")} · ${summaries[i]}`)
                             .join("\n")
                         : "no recent entities"
                 }
@@ -262,17 +366,18 @@ export function buildMcpServer(ctx) {
     // ----- 8. get_entity -----
     server.registerTool("get_entity", {
         title: "Get Entity",
-        description: "Fetch a single task or note by its UUID or unique UUID prefix.",
+        description: "Fetch a single task or note by its UUID, unique UUID prefix, or human-readable KEY-SEQ (e.g. BOT-55).",
         annotations: {
             readOnlyHint: true,
             destructiveHint: false,
             idempotentHint: true,
             openWorldHint: false
         },
-        inputSchema: { id: EntityIdRef }
+        inputSchema: { id: EntityRef }
     }, async ({ id }) => {
         try {
-            const entity = await c.getEntity(id);
+            const resolvedId = await resolveEntityRef(c, id);
+            const entity = await c.getEntity(resolvedId);
             return { content: [{ type: "text", text: JSON.stringify(serializeEntity(entity), null, 2) }] };
         }
         catch {
@@ -317,7 +422,14 @@ export function buildMcpServer(ctx) {
             "- `status`: defaults to 'open'. Use 'in_progress' only if work has actually started in this turn.\n" +
             "- `dueAt`: include when the user mentions a date. Use an ISO datetime in UTC.\n" +
             "- `tags`: 2-4 short lowercase kebab-case tokens. Re-use existing tags when possible — search first if unsure.\n" +
-            "- `parentId`: include when this task is a follow-up under another task or note.",
+            "- `parentId`: include when this task is a follow-up under another task or note.\n" +
+            "\n" +
+            "Scope — keep tasks small:\n" +
+            "- One task = one focused work session (roughly ≤1 hour). If the work spans multiple hours, days, or deliverables, propose a split into smaller executable tasks and get the user's agreement before creating anything.\n" +
+            "- For a large goal, create a parent milestone task (no dueAt needed), then attach small executable subtasks via `parentId`.\n" +
+            "- Heuristic: if the title needs 'and' to chain multiple verbs, it should be several tasks.\n" +
+            "\n" +
+            "When reporting a created task to the user, refer to it by its KEY-SEQ identifier (e.g. BOT-55), never the UUID.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -330,26 +442,34 @@ export function buildMcpServer(ctx) {
             body: z.string().default(""),
             tags: z.array(z.string()).default([]),
             status: z.enum(TASK_STATUSES).default("open"),
-            parentId: z.string().uuid().optional().describe("Link this task under another entity."),
+            parentId: EntityRef.optional().describe("Link this task under another entity. Accepts UUID, UUID prefix, or KEY-SEQ such as BOT-55."),
             actorKind: z.enum(ACTOR_KINDS).default("agent"),
             dueAt: z.string().datetime().optional().describe("ISO datetime."),
             priority: z.enum(PRIORITIES).default("none"),
             idempotencyKey: z.string().min(1).max(200).optional()
         }
     }, async (input) => {
-        const entity = await c.createTask({
-            projectId: input.projectId ?? null,
-            title: input.title,
-            body: input.body,
-            tags: input.tags,
-            status: input.status,
-            parentId: input.parentId ?? null,
-            actorKind: input.actorKind,
-            dueAt: input.dueAt ?? null,
-            priority: input.priority,
-            idempotencyKey: input.idempotencyKey
-        });
-        return { content: [{ type: "text", text: `created task ${summarizeEntity(entity)}\nid: ${entity.id}` }] };
+        try {
+            const resolvedParentId = input.parentId
+                ? await resolveEntityRef(c, input.parentId)
+                : null;
+            const entity = await c.createTask({
+                projectId: input.projectId ?? null,
+                title: input.title,
+                body: input.body,
+                tags: input.tags,
+                status: input.status,
+                parentId: resolvedParentId,
+                actorKind: input.actorKind,
+                dueAt: input.dueAt ?? null,
+                priority: input.priority,
+                idempotencyKey: input.idempotencyKey
+            });
+            return { content: [{ type: "text", text: `created task ${await summarize(entity)}\nid: ${entity.id}` }] };
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
     });
     // ----- 11. remember (= create_note) -----
     server.registerTool("remember", {
@@ -374,23 +494,31 @@ export function buildMcpServer(ctx) {
             title: z.string().max(500).optional().describe("Optional; first body line is used as fallback."),
             body: z.string().default(""),
             tags: z.array(z.string()).default([]),
-            parentId: z.string().uuid().optional().describe("Link this note under a task or other entity."),
+            parentId: EntityRef.optional().describe("Link this note under a task or other entity. Accepts UUID, UUID prefix, or KEY-SEQ such as BOT-55."),
             actorKind: z.enum(ACTOR_KINDS).default("agent"),
             pinned: z.boolean().default(false).describe("Pin to project opening brief (must-read context)."),
             idempotencyKey: z.string().min(1).max(200).optional()
         }
     }, async (input) => {
-        const entity = await c.remember({
-            projectId: input.projectId ?? null,
-            title: input.title ?? null,
-            body: input.body,
-            tags: input.tags,
-            parentId: input.parentId ?? null,
-            actorKind: input.actorKind,
-            pinned: input.pinned,
-            idempotencyKey: input.idempotencyKey
-        });
-        return { content: [{ type: "text", text: `remembered ${summarizeEntity(entity)}\nid: ${entity.id}` }] };
+        try {
+            const resolvedParentId = input.parentId
+                ? await resolveEntityRef(c, input.parentId)
+                : null;
+            const entity = await c.remember({
+                projectId: input.projectId ?? null,
+                title: input.title ?? null,
+                body: input.body,
+                tags: input.tags,
+                parentId: resolvedParentId,
+                actorKind: input.actorKind,
+                pinned: input.pinned,
+                idempotencyKey: input.idempotencyKey
+            });
+            return { content: [{ type: "text", text: `remembered ${await summarize(entity)}\nid: ${entity.id}` }] };
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
     });
     // ----- 12. update_entity -----
     server.registerTool("update_entity", {
@@ -401,6 +529,7 @@ export function buildMcpServer(ctx) {
             "- task completion: `status='done'`. Optionally `remember` a closing note with `parentId` set to this task.\n" +
             "- task cancellation / give up: `status='rejected'`.\n" +
             "- start work: `status='in_progress'` ONLY when work actually begins in this turn (not just on every mention).\n" +
+            "- move between projects: pass `projectId` (or `null` to move to workspace scope).\n" +
             "- re-parent: pass `parentId` (or `null` to detach).\n" +
             "- pin/unpin: `pinned: true/false`. Pinned notes drive opening_brief — use sparingly.\n" +
             "- title=null clears the title (notes only).",
@@ -411,17 +540,27 @@ export function buildMcpServer(ctx) {
             openWorldHint: false
         },
         inputSchema: {
-            id: EntityIdRef,
+            id: EntityRef,
+            projectId: z
+                .string()
+                .uuid()
+                .nullable()
+                .optional()
+                .describe("Move to a project UUID, or pass null for workspace scope."),
             title: z
                 .string()
                 .max(500)
                 .nullable()
                 .optional()
                 .describe("Pass null to clear the title (notes only)."),
-            body: z.string().optional(),
+            body: z.string().optional().describe("Replace the entire body. Mutually exclusive with bodyAppend."),
+            bodyAppend: z
+                .string()
+                .optional()
+                .describe("Atomically append text to the existing body, separated by a blank line when the current body is non-empty. Mutually exclusive with body."),
             tags: z.array(z.string()).optional(),
             status: z.enum(TASK_STATUSES).optional(),
-            parentId: z.string().uuid().nullable().optional().describe("Re-link or unlink (null) parent."),
+            parentId: EntityRef.nullable().optional().describe("Re-link or unlink (null) parent. Accepts UUID, UUID prefix, or KEY-SEQ such as BOT-55."),
             dueAt: z.string().datetime().nullable().optional().describe("ISO datetime or null to clear."),
             priority: z.enum(PRIORITIES).optional(),
             pinned: z.boolean().optional().describe("Pin or unpin from project opening brief."),
@@ -430,10 +569,19 @@ export function buildMcpServer(ctx) {
                 .optional()
                 .describe("For recurring task occurrences: 'this' applies the edit to this occurrence only (does not propagate to future); 'future' (default) propagates the edit to future occurrences.")
         }
-    }, async ({ id, ...fields }) => {
-        const defined = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
-        const updated = await c.updateEntity(id, defined);
-        return { content: [{ type: "text", text: `updated ${summarizeEntity(updated)}` }] };
+    }, async ({ id, parentId, ...fields }) => {
+        try {
+            const resolvedId = await resolveEntityRef(c, id);
+            const resolvedParentId = parentId === null ? null : parentId !== undefined ? await resolveEntityRef(c, parentId) : undefined;
+            const defined = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+            if (resolvedParentId !== undefined)
+                defined.parentId = resolvedParentId;
+            const updated = await c.updateEntity(resolvedId, defined);
+            return { content: [{ type: "text", text: `updated ${await summarize(updated)}` }] };
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
     });
     // ----- 13. recurrence -----
     server.registerTool("configure_recurrence", {
@@ -446,7 +594,7 @@ export function buildMcpServer(ctx) {
             openWorldHint: false
         },
         inputSchema: {
-            taskId: z.string().uuid(),
+            taskId: EntityRef.describe("Task UUID, unique UUID prefix, or KEY-SEQ such as BOT-55."),
             rrule: z.string().min(1).max(1000).optional().describe("Raw RRULE such as FREQ=WEEKLY;BYDAY=MO."),
             preset: z.enum(RECURRENCE_PRESETS).optional(),
             interval: z.number().int().min(1).max(999).optional(),
@@ -462,16 +610,22 @@ export function buildMcpServer(ctx) {
             anchor: z.enum(RECURRENCE_ANCHORS).optional()
         }
     }, async ({ taskId, ...fields }) => {
-        const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
-        const rule = await c.configureRecurrence(taskId, body);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `configured recurrence ${rule.id}\nrrule: ${rule.rrule}\nanchor: ${rule.anchor}\nnext: ${rule.nextOccurrenceAt ?? "-"}`
-                }
-            ]
-        };
+        try {
+            const resolvedTaskId = await resolveEntityRef(c, taskId);
+            const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+            const rule = await c.configureRecurrence(resolvedTaskId, body);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `configured recurrence ${rule.id}\nrrule: ${rule.rrule}\nanchor: ${rule.anchor}\nnext: ${rule.nextOccurrenceAt ?? "-"}`
+                    }
+                ]
+            };
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
     });
     server.registerTool("get_recurrence", {
         title: "Get Recurrence",
@@ -482,9 +636,10 @@ export function buildMcpServer(ctx) {
             idempotentHint: true,
             openWorldHint: false
         },
-        inputSchema: { taskId: z.string().uuid() }
+        inputSchema: { taskId: EntityRef.describe("Task UUID, unique UUID prefix, or KEY-SEQ such as BOT-55.") }
     }, async ({ taskId }) => {
-        const details = await c.getRecurrence(taskId);
+        const resolvedTaskId = await resolveEntityRef(c, taskId);
+        const details = await c.getRecurrence(resolvedTaskId);
         const serialized = {
             ...details,
             currentOccurrence: details.currentOccurrence
@@ -503,19 +658,25 @@ export function buildMcpServer(ctx) {
             openWorldHint: false
         },
         inputSchema: {
-            taskId: z.string().uuid(),
+            taskId: EntityRef.describe("Task UUID, unique UUID prefix, or KEY-SEQ such as BOT-55."),
             reason: z.string().max(500).optional()
         }
     }, async ({ taskId, reason }) => {
-        const result = await c.skipOccurrence(taskId, { reason, actorKind: "agent" });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `skipped ${summarizeEntity(result.skipped)}\nnext: ${result.next ? summarizeEntity(result.next) : "-"}`
-                }
-            ]
-        };
+        try {
+            const resolvedTaskId = await resolveEntityRef(c, taskId);
+            const result = await c.skipOccurrence(resolvedTaskId, { reason, actorKind: "agent" });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `skipped ${await summarize(result.skipped)}\nnext: ${result.next ? await summarize(result.next) : "-"}`
+                    }
+                ]
+            };
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
     });
     server.registerTool("stop_recurrence", {
         title: "Stop Recurrence",
@@ -531,8 +692,13 @@ export function buildMcpServer(ctx) {
             reason: z.string().max(500).optional()
         }
     }, async ({ ruleId, reason }) => {
-        const rule = await c.stopRecurrence(ruleId, { reason });
-        return { content: [{ type: "text", text: `stopped recurrence ${rule.id}` }] };
+        try {
+            const rule = await c.stopRecurrence(ruleId, { reason });
+            return { content: [{ type: "text", text: `stopped recurrence ${rule.id}` }] };
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
     });
     server.registerTool("split_recurrence", {
         title: "Split Recurrence",
@@ -559,16 +725,21 @@ export function buildMcpServer(ctx) {
             anchor: z.enum(RECURRENCE_ANCHORS).optional()
         }
     }, async ({ ruleId, ...fields }) => {
-        const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
-        const rule = await c.splitRecurrence(ruleId, body);
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `split into recurrence ${rule.id}\nrrule: ${rule.rrule}\nanchor: ${rule.anchor}\nnext: ${rule.nextOccurrenceAt ?? "-"}`
-                }
-            ]
-        };
+        try {
+            const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+            const rule = await c.splitRecurrence(ruleId, body);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `split into recurrence ${rule.id}\nrrule: ${rule.rrule}\nanchor: ${rule.anchor}\nnext: ${rule.nextOccurrenceAt ?? "-"}`
+                    }
+                ]
+            };
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
     });
     // ----- 14. related -----
     server.registerTool("related", {
@@ -580,15 +751,17 @@ export function buildMcpServer(ctx) {
             idempotentHint: true,
             openWorldHint: false
         },
-        inputSchema: { id: EntityIdRef }
+        inputSchema: { id: EntityRef }
     }, async ({ id }) => {
-        const rows = await c.listRelated(id);
+        const resolvedId = await resolveEntityRef(c, id);
+        const rows = await c.listRelated(resolvedId);
+        const summaries = await summarizeAll(rows);
         return {
             content: [
                 {
                     type: "text",
                     text: rows.length
-                        ? rows.map((r) => `- ${summarizeEntity(r)}`).join("\n")
+                        ? summaries.map((s) => `- ${s}`).join("\n")
                         : "no related entities"
                 }
             ]
@@ -605,22 +778,222 @@ export function buildMcpServer(ctx) {
             openWorldHint: false
         },
         inputSchema: {
-            fromId: z.string().uuid(),
-            toId: z.string().uuid(),
+            fromId: EntityRef.describe("Source entity: UUID, UUID prefix, or KEY-SEQ such as BOT-55."),
+            toId: EntityRef.describe("Target entity: UUID, UUID prefix, or KEY-SEQ such as BOT-55."),
             kind: z.enum(EDGE_KINDS)
         }
     }, async ({ fromId, toId, kind }) => {
-        const result = await c.link(fromId, { toId, kind: kind });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: result.created
-                        ? `linked ${fromId} -[${kind}]-> ${toId}`
-                        : `link already exists`
+        try {
+            const resolvedFromId = await resolveEntityRef(c, fromId);
+            const resolvedToId = await resolveEntityRef(c, toId);
+            const result = await c.link(resolvedFromId, { toId: resolvedToId, kind: kind });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: result.created
+                            ? `linked ${fromId} -[${kind}]-> ${toId}`
+                            : `link already exists`
+                    }
+                ]
+            };
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
+    });
+    // ----- 16. list_tasks -----
+    server.registerTool("list_tasks", {
+        title: "List Tasks",
+        description: "Return tasks split into Overdue / Scheduled / Backlog buckets for a given date range. Scheduled includes tasks whose display date falls in [from, to). Overdue is unfinished work before the range start (or before now when from is omitted). Backlog is undated tasks (when includeBacklog is true).",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        },
+        inputSchema: {
+            projectId: z.string().uuid().optional().describe("Scope to a single project UUID."),
+            projectIds: z.array(z.string().uuid()).optional().describe("Scope to multiple project UUIDs."),
+            from: z.string().datetime().optional().describe("Range start (ISO datetime, inclusive)."),
+            to: z.string().datetime().optional().describe("Range end (ISO datetime, exclusive)."),
+            includeBacklog: z.boolean().default(true).describe("Include undated tasks."),
+            includeDone: z.boolean().default(false).describe("Include completed tasks."),
+            includeVirtualRecurrences: z.boolean().default(false).describe("Include ephemeral future ghost occurrences for recurring tasks.")
+        }
+    }, async ({ projectId, projectIds, from, to, includeBacklog, includeDone, includeVirtualRecurrences }) => {
+        // Merge projectId into projectIds for the REST call
+        const ids = [];
+        if (projectId)
+            ids.push(projectId);
+        if (projectIds)
+            ids.push(...projectIds);
+        const result = await c.tasksRange({
+            from: from ?? null,
+            to: to ?? null,
+            projectIds: ids.length ? ids : null,
+            includeBacklog,
+            includeDone,
+            includeVirtualRecurrences
+        });
+        const lines = [];
+        const buckets = [
+            ["## Overdue", result.overdue.map(serializeEntity)],
+            ["## Scheduled", result.scheduled.map(serializeEntity)],
+            ["## Backlog", result.backlog.map(serializeEntity)]
+        ];
+        for (const [header, rows] of buckets) {
+            if (!rows.length)
+                continue;
+            lines.push(header);
+            for (const s of await summarizeAll(rows))
+                lines.push(`- ${s}`);
+        }
+        if (result.virtualOccurrences.length) {
+            lines.push("## Virtual Occurrences (upcoming, not yet materialized)");
+            for (const v of result.virtualOccurrences) {
+                lines.push(`- ${v.title ?? "(untitled)"} · ${v.dueAt.slice(0, 10)} [virtual]`);
+            }
+        }
+        const text = lines.length
+            ? lines.join("\n")
+            : "no tasks";
+        return { content: [{ type: "text", text }] };
+    });
+    // ----- 17. list_tags -----
+    server.registerTool("list_tags", {
+        title: "List Tags",
+        description: "Return distinct tags across all entities, ordered by usage count (most-used first). Optionally scope to a single project. Useful for discovering existing tag vocabulary before creating tasks or notes.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        },
+        inputSchema: {
+            projectId: z.string().uuid().optional().describe("Scope to a single project UUID.")
+        }
+    }, async ({ projectId }) => {
+        const tags = await c.listTags(projectId ?? null);
+        const text = tags.length
+            ? tags.map((t) => `${t.tag} (${t.count})`).join("\n")
+            : "no tags";
+        return { content: [{ type: "text", text }] };
+    });
+    // ----- 18. get_links -----
+    server.registerTool("get_links", {
+        title: "Get Links",
+        description: "Read typed graph edges for an entity. direction='outgoing' returns edges where the entity is the source; direction='incoming' returns edges where the entity is the target; direction='both' (default) returns all. Filter by kind when you only need a specific edge type (blocks, references, or parent_of).",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        },
+        inputSchema: {
+            id: EntityRef,
+            kind: z.enum(EDGE_KINDS).optional().describe("Edge type filter: blocks, references, or parent_of."),
+            direction: z.enum(["outgoing", "incoming", "both"]).default("both").describe("Edge direction relative to the given entity.")
+        }
+    }, async ({ id, kind, direction }) => {
+        const resolvedId = await resolveEntityRef(c, id);
+        const links = await c.getLinks(resolvedId, { kind: kind ?? null, direction });
+        const summaries = await summarizeAll(links.map((l) => serializeEntity(l.entity)));
+        const text = links.length
+            ? links
+                .map((l, i) => `- [${l.kind} ▸ ${l.direction}] ${summaries[i]}`)
+                .join("\n")
+            : "no links";
+        return { content: [{ type: "text", text }] };
+    });
+    // ----- 19. update_entities (batch) -----
+    const UpdateEntityItem = z.object({
+        id: EntityRef,
+        projectId: z
+            .string()
+            .uuid()
+            .nullable()
+            .optional()
+            .describe("Move to a project UUID, or pass null for workspace scope."),
+        title: z.string().max(500).nullable().optional().describe("Pass null to clear the title (notes only)."),
+        body: z.string().optional().describe("Replace the entire body. Mutually exclusive with bodyAppend."),
+        bodyAppend: z.string().optional().describe("Atomically append text to the body. Mutually exclusive with body."),
+        tags: z.array(z.string()).optional(),
+        status: z.enum(TASK_STATUSES).optional(),
+        parentId: EntityRef.nullable().optional().describe("Re-link or unlink (null) parent."),
+        dueAt: z.string().datetime().nullable().optional().describe("ISO datetime or null to clear."),
+        priority: z.enum(PRIORITIES).optional(),
+        pinned: z.boolean().optional(),
+        recurrenceScope: z.enum(["this", "future"]).optional()
+    });
+    server.registerTool("update_entities", {
+        title: "Batch Update Entities",
+        description: "Apply per-item patches to multiple tasks or notes in a single call. Each item specifies an entity ref (UUID, UUID prefix, or KEY-SEQ like BOT-55) and the fields to change — same as update_entity. A per-item failure does NOT abort the rest; partial success is reported. Returns one line per item plus a final tally.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false
+        },
+        inputSchema: {
+            items: z
+                .array(UpdateEntityItem)
+                .min(1)
+                .max(50)
+                .describe("List of entities to update (1–50 items).")
+        }
+    }, async ({ items }) => {
+        try {
+            const lines = [];
+            let okCount = 0;
+            let failCount = 0;
+            for (const item of items) {
+                const { id, parentId, ...fields } = item;
+                try {
+                    const resolvedId = await resolveEntityRef(c, id);
+                    const resolvedParentId = parentId === null ? null : parentId !== undefined ? await resolveEntityRef(c, parentId) : undefined;
+                    const defined = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+                    if (resolvedParentId !== undefined)
+                        defined.parentId = resolvedParentId;
+                    const updated = await c.updateEntity(resolvedId, defined);
+                    lines.push(`✓ ${await summarize(updated)}`);
+                    okCount++;
                 }
-            ]
-        };
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    lines.push(`✗ ${id}: ${msg}`);
+                    failCount++;
+                }
+            }
+            lines.push(`\n${okCount} ok, ${failCount} failed`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        catch (err) {
+            return formatToolError(err);
+        }
+    });
+    // ----- 20. context -----
+    server.registerTool("context", {
+        title: "Server Context",
+        description: "Return the current server time, workspace timezone, botnote version, and project list. Call this tool first to resolve relative dates ('tomorrow', 'next Monday') and to pick the correct project UUID before creating tasks.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false
+        },
+        inputSchema: {}
+    }, async () => {
+        const ctx = await c.getContext();
+        const projectLines = ctx.projects.map((p) => `  ${p.key} — ${p.name} [${p.status}]`);
+        const text = [
+            `now: ${ctx.now}`,
+            `timezone: ${ctx.timezone}`,
+            `version: ${ctx.version}`,
+            `projects:`,
+            ...projectLines
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
     });
     // ----- bonus resource: workspace overview -----
     server.registerResource("workspace_overview", "botnote://workspace", {
@@ -642,8 +1015,9 @@ export function buildMcpServer(ctx) {
         }
         lines.push("");
         lines.push("## Recent (workspace-wide)");
-        for (const r of recentRows) {
-            lines.push(`- ${r.createdAt.slice(0, 16).replace("T", " ")} · ${r.kind}/${r.id} · ${displayTitle(r)}`);
+        const summaries = await summarizeAll(recentRows);
+        for (let i = 0; i < recentRows.length; i++) {
+            lines.push(`- ${recentRows[i].createdAt.slice(0, 16).replace("T", " ")} · ${summaries[i]}`);
         }
         return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: lines.join("\n") }] };
     });