@naumu/mcp 0.11.0 → 0.12.0

package/dist/index.js

@@ -29,18 +29,71 @@ function safeErrorMessage(status, upstream) {
   return `Request failed with status ${status}.`;
 }
 
+// ../mcp-core/src/version.ts
+var NAUMU_MCP_VERSION = "0.12.0";
+
 // ../mcp-core/src/client.ts
+var HEADER_VALUE_MAX_LENGTH = 100;
+var sanitizeHeaderValue = (value) => {
+  const cleaned = value.replace(/[^\x20-\x7e]/g, "").trim();
+  return cleaned.length > 0 ? cleaned.slice(0, HEADER_VALUE_MAX_LENGTH) : void 0;
+};
 var NaumuClient = class {
   baseUrl;
   apiKey;
-  constructor(baseUrl, apiKey2) {
+  reportMcpClientHeaders;
+  mcpClientInfo;
+  pendingToolName;
+  constructor(baseUrl, apiKey2, options = {}) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     this.apiKey = apiKey2;
+    this.reportMcpClientHeaders = options.reportMcpClientHeaders === true;
+  }
+  /**
+   * Record the harness identity learned from the MCP initialize handshake
+   * (see `server.server.getClientVersion()` in the stdio entrypoint).
+   */
+  setMcpClientInfo(info) {
+    this.mcpClientInfo = info;
+  }
+  /**
+   * Mark which MCP tool is about to run. Set by the tool-attribution wrapper
+   * immediately before a handler executes.
+   */
+  setPendingToolName(toolName) {
+    this.pendingToolName = toolName;
+  }
+  /**
+   * Consume the pending tool name — FIRST request only.
+   *
+   * One MCP tool call can fan out into several REST calls (e.g. a schema fetch
+   * before the write). Consuming on the first request means the backend counts
+   * exactly one `mcp_tool_call` per tool invocation; the follow-up calls arrive
+   * without the tool header and are deliberately not tracked.
+   */
+  consumePendingToolName() {
+    const toolName = this.pendingToolName;
+    this.pendingToolName = void 0;
+    return toolName;
+  }
+  /** Opt-in usage-attribution headers. Empty unless `reportMcpClientHeaders` is on. */
+  mcpHeaders() {
+    if (!this.reportMcpClientHeaders) return {};
+    const headers = { "X-Naumu-Mcp-Version": NAUMU_MCP_VERSION };
+    const clientName = this.mcpClientInfo?.name ? sanitizeHeaderValue(this.mcpClientInfo.name) : void 0;
+    if (clientName) headers["X-Naumu-Mcp-Client"] = clientName;
+    const clientVersion = this.mcpClientInfo?.version ? sanitizeHeaderValue(this.mcpClientInfo.version) : void 0;
+    if (clientVersion) headers["X-Naumu-Mcp-Client-Version"] = clientVersion;
+    const pendingTool = this.consumePendingToolName();
+    const toolName = pendingTool ? sanitizeHeaderValue(pendingTool) : void 0;
+    if (toolName) headers["X-Naumu-Mcp-Tool"] = toolName;
+    return headers;
   }
   headers() {
     return {
       "Authorization": `Bearer ${this.apiKey}`,
-      "Content-Type": "application/json"
+      "Content-Type": "application/json",
+      ...this.mcpHeaders()
     };
   }
   async handleResponse(res) {
@@ -70,7 +123,7 @@ var NaumuClient = class {
   async getBinary(path) {
     const res = await fetch(`${this.baseUrl}${path}`, {
       method: "GET",
-      headers: { Authorization: `Bearer ${this.apiKey}` }
+      headers: { Authorization: `Bearer ${this.apiKey}`, ...this.mcpHeaders() }
     });
     if (!res.ok) {
       const upstream = await res.text().catch(() => "Unknown error");
@@ -89,6 +142,33 @@ var NaumuClient = class {
       contentType: res.headers.get("content-type") ?? "application/octet-stream"
     };
   }
+  /**
+   * Follow a redirect-issuing endpoint one hop and return the `Location` it
+   * points at, without fetching the target. Any non-3xx answer is a failure
+   * (403/404/…) and is mapped through the same safe-error path as the rest.
+   */
+  async getRedirectLocation(path) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: "GET",
+      redirect: "manual",
+      headers: { Authorization: `Bearer ${this.apiKey}`, ...this.mcpHeaders() }
+    });
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers.get("location");
+      if (location) return location;
+      console.error(`[mcp] upstream redirect ${res.status} without a Location header`);
+      throw new NaumuApiError(res.status, "Server error \u2014 try again shortly.");
+    }
+    const upstream = await res.text().catch(() => "Unknown error");
+    console.error(
+      `[mcp] upstream redirect ${res.status}: ${upstream.slice(0, 500)}`
+    );
+    throw new NaumuApiError(
+      res.status,
+      safeErrorMessage(res.status, upstream),
+      upstream
+    );
+  }
   async post(path, body) {
     const res = await fetch(`${this.baseUrl}${path}`, {
       method: "POST",
@@ -133,9 +213,6 @@ URL \u2192 tool mapping (the value after /spaces/ is the slug \u2014 resolve it
 
 Localhost URLs (http://localhost:3000/spaces/{slug}/...) follow the same shape \u2014 resolve the slug the same way. The MCP backend host is configured separately; the URL the user pastes is just for parsing structure.`;
 
-// ../mcp-core/src/version.ts
-var NAUMU_MCP_VERSION = "0.11.0";
-
 // ../mcp-core/src/tools/list-graphs.ts
 import { z } from "zod";
 function registerListGraphs(server2, client2) {
@@ -600,7 +677,7 @@ function registerGetNode(server2, client2) {
     {
       title: "Get Node",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
-      description: "Get a single node with all its properties and connections (incoming and outgoing edges).",
+      description: "Get a single node with all its properties, connections (incoming and outgoing edges with neighbor labels), and tied context: attached notes, conversations (threads), scheduled tasks, and the generated summary when one exists.",
       inputSchema: z11.object({
         graphId: z11.string().describe("The graph ID"),
         nodeId: z11.string().describe("The node ID")
@@ -1134,7 +1211,7 @@ function registerReadThread(server2, client2) {
     {
       title: "Read Thread",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
-      description: 'Read messages from a Naumu thread. Returns paginated history ordered newest-first; each message carries a `status` (`processing` while @Naumu is still composing, `complete` when done). Use this to pick up an answer after naumu_ask returns status "processing", or to read what naumu_delegate produced. Use `before` (timestamp ms) to page further back. Default page size 50, max 200.',
+      description: 'Read messages from a Naumu thread. Returns paginated history ordered newest-first; each message carries a `status` (`processing` while @Naumu is still composing, `complete` when done). Use this to pick up an answer after naumu_ask returns status "processing", or to read what naumu_delegate produced. Use `before` (timestamp ms) to page further back. Default page size 50, max 200. To read or download a message attachment, pass its `attachments[].id` to naumu_get_attachment.',
       inputSchema: z21.object({
         threadId: z21.string().describe("The thread ID to read from."),
         before: z21.number().optional().describe("Unix timestamp in milliseconds. Returns messages strictly older than this. Omit for the newest page."),
@@ -1206,15 +1283,31 @@ function registerListThreads(server2, client2) {
     {
       title: "List Threads",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
-      description: "List threads sorted by last activity (newest first), for self-discovery before deciding which to engage. With a user API key, pass `graphId` to list threads you can see in that space (resolve it via naumu_list_graphs). With a bot identity key, omit `graphId` to list threads in your own graph \u2014 each row carries an `isParticipant` flag (TRUE means you were explicitly invited and your replies fan out via webhook). Page back with `cursor` set to the oldest `lastActivityAt` from the previous page.",
+      description: "List threads sorted by last activity (newest first), for self-discovery before deciding which to engage. With a user API key, pass `graphId` to list threads you can see in that space (resolve it via naumu_list_graphs). Pass `nodeId` alongside `graphId` to list only the conversations tied to that node (attached, or that created/modified it). With a bot identity key, omit `graphId` to list threads in your own graph \u2014 each row carries an `isParticipant` flag (TRUE means you were explicitly invited and your replies fan out via webhook). Page back with `cursor` set to the oldest `lastActivityAt` from the previous page.",
       inputSchema: z23.object({
         graphId: z23.string().optional().describe("Graph (space) ID. Required for user API keys; omit for bot identity keys (defaults to your own graph)."),
+        nodeId: z23.string().optional().describe("Scope the listing to conversations tied to this node. Requires `graphId`."),
         cursor: z23.number().int().optional().describe("Unix timestamp ms \u2014 returns threads with `lastActivityAt` strictly older than this. Omit for the newest page."),
         limit: z23.number().int().min(1).max(200).optional().describe("Page size, default 50, max 200.")
       })
     },
-    async ({ graphId, cursor, limit }) => {
+    async ({ graphId, nodeId, cursor, limit }) => {
       try {
+        if (nodeId) {
+          if (!graphId) {
+            return {
+              content: [{ type: "text", text: "Error: `nodeId` requires `graphId`." }],
+              isError: true
+            };
+          }
+          const data2 = await client2.get(
+            `/api/threads?graphId=${encodeURIComponent(graphId)}&nodeId=${encodeURIComponent(nodeId)}`
+          );
+          const clean2 = Array.isArray(data2) ? data2.map(sanitizeThreadParticipants) : data2;
+          return {
+            content: [{ type: "text", text: JSON.stringify(clean2, null, 2) }]
+          };
+        }
         const params = new URLSearchParams();
         if (cursor !== void 0) params.set("cursor", String(cursor));
         if (limit !== void 0) params.set("limit", String(limit));
@@ -1580,8 +1673,80 @@ function registerPersistCanvasAttachment(server2, client2) {
   );
 }
 
-// ../mcp-core/src/tools/add-reaction.ts
+// ../mcp-core/src/tools/get-attachment.ts
 import { z as z30 } from "zod";
+var DOWNLOAD_URL_TTL_SECONDS = 900;
+var MAX_INLINE_PREVIEW_BYTES = 4 * 1024 * 1024;
+function normalizeAttachmentId(input) {
+  const trimmed = input.trim();
+  const withoutQuery = trimmed.split(/[?#]/)[0];
+  const segments = withoutQuery.split("/").filter((segment) => segment.length > 0);
+  const last = segments[segments.length - 1] ?? "";
+  try {
+    return decodeURIComponent(last);
+  } catch {
+    return last;
+  }
+}
+function registerGetAttachment(server2, client2) {
+  server2.registerTool(
+    "naumu_get_attachment",
+    {
+      title: "Get Attachment",
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+      description: "Read a chat attachment. Pass the `attachmentId` from a message's `attachments[].id` in naumu_read_thread (its `url` field works too - the id is extracted from it), and this resolves it into a short-lived download URL for the actual bytes.\n\nReturns a JSON text block with `{ attachmentId, downloadUrl, expiresInSeconds, note }`. Use `downloadUrl` EXACTLY as given:\n\u2022 GET it with no Authorization header - the URL itself is the auth, and adding one makes S3 answer 403.\n\u2022 It expires about 15 minutes after this call. Fetch it now; re-call this tool for a fresh URL rather than holding one.\n\u2022 Do not log it, quote it back to the user, or store it - it is a bearer capability for its whole lifetime.\n\nWhen the attachment is an image (or a video or PDF that has a generated poster), a downsized preview is also returned inline as an image block, so a visual attachment can often be understood without fetching anything. The preview is a thumbnail, not the original - fetch `downloadUrl` when you need full resolution or the exact file.\n\nAccess is checked the same way it is for a person: you only resolve attachments in threads you can already read.",
+      inputSchema: z30.object({
+        attachmentId: z30.string().min(1).describe("Attachment id, from `attachments[].id` on a message returned by naumu_read_thread. A full or relative download URL is also accepted - the id is extracted from its last path segment.")
+      })
+    },
+    async ({ attachmentId }) => {
+      try {
+        const id = normalizeAttachmentId(attachmentId);
+        const encoded = encodeURIComponent(id);
+        const downloadUrl = await client2.getRedirectLocation(
+          `/api/attachments/download/${encoded}`
+        );
+        const content = [];
+        try {
+          const preview = await client2.getBinary(
+            `/api/attachments/download/${encoded}?thumbnail=preview`
+          );
+          if (preview.contentType.startsWith("image/") && preview.buffer.length <= MAX_INLINE_PREVIEW_BYTES) {
+            content.push({
+              type: "image",
+              data: Buffer.from(preview.buffer).toString("base64"),
+              mimeType: preview.contentType
+            });
+          }
+        } catch {
+        }
+        content.push({
+          type: "text",
+          text: JSON.stringify(
+            {
+              attachmentId: id,
+              downloadUrl,
+              expiresInSeconds: DOWNLOAD_URL_TTL_SECONDS,
+              note: "downloadUrl is presigned - fetch it WITHOUT any Authorization header. It expires in about 15 minutes; do not log or store it."
+            },
+            null,
+            2
+          )
+        });
+        return { content };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
+// ../mcp-core/src/tools/add-reaction.ts
+import { z as z31 } from "zod";
 function registerAddReaction(server2, client2) {
   server2.registerTool(
     "naumu_add_reaction",
@@ -1589,10 +1754,10 @@ function registerAddReaction(server2, client2) {
       title: "Add Reaction",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: 'Add an emoji reaction to a message in a thread you are participating in; use for lightweight acknowledgement instead of posting a message. Idempotent - calling twice with the same emoji is a no-op (use `naumu_remove_reaction` to undo). Returns `{ ok, messageId, emoji, alreadyExisted, reactionCount, reactions }` so you can confirm the state without re-reading the thread; `alreadyExisted: true` means the reaction was already on the message and the call was a no-op.\n\nWhen to react vs. when to post a message:\n\u2022 React (no message) for lightweight acknowledgement (\u{1F440}, \u2705, \u{1F44D}), appreciation (\u2764\uFE0F, \u{1F64C}), laughter (\u{1F602}), or "I saw this".\n\u2022 Post a message for direct questions, clarification, important corrections, or final results - situations where words are required.\n\u2022 For long tasks: react \u{1F440} first to acknowledge, optionally post a short "On it - I\'ll report back" if the work will take >20s, do the work, then post the final result.\n\u2022 Ignore casual human banter, side-conversations someone else already answered, or anything where you would only say "ok"/"nice"/"lol".\n\nUse at most one reaction per message unless explicitly useful. Reactions are social backpressure relief, not a sparkle-confetti channel.',
-      inputSchema: z30.object({
-        threadId: z30.string().describe("Thread containing the message. You must be a participant."),
-        messageId: z30.string().describe("The message to react to."),
-        emoji: z30.string().min(1).describe('Emoji character (e.g. "\u{1F440}", "\u2705", "\u2764\uFE0F"). Custom-emoji shortcodes are NOT supported here - pass a real Unicode emoji.')
+      inputSchema: z31.object({
+        threadId: z31.string().describe("Thread containing the message. You must be a participant."),
+        messageId: z31.string().describe("The message to react to."),
+        emoji: z31.string().min(1).describe('Emoji character (e.g. "\u{1F440}", "\u2705", "\u2764\uFE0F"). Custom-emoji shortcodes are NOT supported here - pass a real Unicode emoji.')
       })
     },
     async ({ threadId, messageId, emoji }) => {
@@ -1616,7 +1781,7 @@ function registerAddReaction(server2, client2) {
 }
 
 // ../mcp-core/src/tools/remove-reaction.ts
-import { z as z31 } from "zod";
+import { z as z32 } from "zod";
 function registerRemoveReaction(server2, client2) {
   server2.registerTool(
     "naumu_remove_reaction",
@@ -1624,10 +1789,10 @@ function registerRemoveReaction(server2, client2) {
       title: "Remove Reaction",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: "Remove your own emoji reaction from a message; use to walk back an acknowledgement you previously added. Idempotent - calling on a reaction you never added is a no-op. Pair with `naumu_add_reaction` (e.g. you reacted \u{1F440} to start a task and want to clear it after a final result message lands). Returns `{ ok, messageId, emoji, alreadyExisted, reactionCount, reactions }` - `alreadyExisted: false` means there was nothing to remove and the call was a no-op.",
-      inputSchema: z31.object({
-        threadId: z31.string().describe("Thread containing the message. You must be a participant."),
-        messageId: z31.string().describe("The message to remove your reaction from."),
-        emoji: z31.string().min(1).describe("Emoji character to remove (must match what you originally reacted with).")
+      inputSchema: z32.object({
+        threadId: z32.string().describe("Thread containing the message. You must be a participant."),
+        messageId: z32.string().describe("The message to remove your reaction from."),
+        emoji: z32.string().min(1).describe("Emoji character to remove (must match what you originally reacted with).")
       })
     },
     async ({ threadId, messageId, emoji }) => {
@@ -1651,7 +1816,7 @@ function registerRemoveReaction(server2, client2) {
 }
 
 // ../mcp-core/src/tools/naumu-typing.ts
-import { z as z32 } from "zod";
+import { z as z33 } from "zod";
 function registerNaumuTyping(server2, client2) {
   server2.registerTool(
     "naumu_typing",
@@ -1662,9 +1827,9 @@ function registerNaumuTyping(server2, client2) {
       // repeating the same state is a no-op renew, so idempotent.
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: 'Show or hide your "is typing\u2026" pill in a thread; use to signal that you are composing a reply. Call with `state: "start"` the moment you decide to compose a reply (before any LLM call), and the server holds the pill alive - re-broadcasting on a short interval - until you stop, post a message, or the lease cap (~5 min) fires. You do NOT need to refresh on a timer; that\'s the lease\'s job.\n\nThe pill clears automatically when:\n\u2022 you call this tool with `state: "stop"`\n\u2022 you call `naumu_post_message` for the same thread (cleared on commit)\n\u2022 the lease cap expires\n\nUse `start` whenever you start work, even if you might end up not replying - call `stop` if you decide NOT to post. Calling `start` while a lease is already active renews it (resets the cap), so a long-running run can call `start` again as a heartbeat without breaking the indicator. You must be a participant of the thread.',
-      inputSchema: z32.object({
-        threadId: z32.string().describe("The thread ID to set typing in. You must be a participant."),
-        state: z32.enum(["start", "stop"]).describe('"start" acquires/renews the lease; "stop" ends it and clears the pill immediately.')
+      inputSchema: z33.object({
+        threadId: z33.string().describe("The thread ID to set typing in. You must be a participant."),
+        state: z33.enum(["start", "stop"]).describe('"start" acquires/renews the lease; "stop" ends it and clears the pill immediately.')
       })
     },
     async ({ threadId, state }) => {
@@ -1685,16 +1850,16 @@ function registerNaumuTyping(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-read.ts
-import { z as z33 } from "zod";
+import { z as z34 } from "zod";
 function registerNoteRead(server2, client2) {
   server2.registerTool(
     "naumu_note_read",
     {
       title: "Read Note",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
-      description: "Read the current contents of a note as markdown; use before editing so you know what you're working with. `naumu_note_find_replace` and the section-based tools (`naumu_note_insert`, `naumu_note_replace_section`, `naumu_note_delete_section`) anchor on text/headings present in the live doc.",
-      inputSchema: z33.object({
-        noteId: z33.string().describe("The note (Thought) ID")
+      description: "Read the current contents of a note as markdown, with its title and `connections` (the graph nodes the note is tied to); use before editing so you know what you're working with. `naumu_note_find_replace` and the section-based tools (`naumu_note_insert`, `naumu_note_replace_section`, `naumu_note_delete_section`) anchor on text/headings present in the live doc.",
+      inputSchema: z34.object({
+        noteId: z34.string().describe("The note (Thought) ID")
       })
     },
     async ({ noteId }) => {
@@ -1707,7 +1872,7 @@ function registerNoteRead(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-append.ts
-import { z as z34 } from "zod";
+import { z as z35 } from "zod";
 function registerNoteAppend(server2, client2) {
   server2.registerTool(
     "naumu_note_append",
@@ -1715,9 +1880,9 @@ function registerNoteAppend(server2, client2) {
       title: "Append to Note",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       description: "Append markdown blocks to the end of a note; use for additive note writing that never touches existing content. Other participants see your colored cursor while the write lands. Markdown supports headings (1-3), bold/italic/code, lists, blockquotes, code blocks, links, and tables. To embed media, write `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`. The one syntax covers images, video, audio, and other files, dispatched by the upload's MIME type into the note's canonical media node; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id. An id already embedded in the note can be repeated safely without re-uploading.",
-      inputSchema: z34.object({
-        noteId: z34.string().describe("The note (Thought) ID to append to"),
-        markdown: z34.string().min(1).describe("Markdown content to append at the end of the note")
+      inputSchema: z35.object({
+        noteId: z35.string().describe("The note (Thought) ID to append to"),
+        markdown: z35.string().min(1).describe("Markdown content to append at the end of the note")
       })
     },
     async ({ noteId, markdown }) => {
@@ -1730,7 +1895,7 @@ function registerNoteAppend(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-insert.ts
-import { z as z35 } from "zod";
+import { z as z36 } from "zod";
 function registerNoteInsert(server2, client2) {
   server2.registerTool(
     "naumu_note_insert",
@@ -1738,10 +1903,10 @@ function registerNoteInsert(server2, client2) {
       title: "Insert After Heading",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       description: "Insert markdown content into a note immediately after a named section; use to add content under a specific heading without rewriting it. The section ends at the next heading of equal-or-higher level (or end of doc). 404 if no heading matches `headingText` exactly - call `naumu_note_read` first to see the live structure. To embed media, write `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`. The one syntax covers images, video, audio, and other files, dispatched by the upload's MIME type; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id.",
-      inputSchema: z35.object({
-        noteId: z35.string().describe("The note (Thought) ID"),
-        headingText: z35.string().min(1).describe("Exact text of the heading whose section the new content follows"),
-        markdown: z35.string().min(1).describe("Markdown content to insert at the end of that section")
+      inputSchema: z36.object({
+        noteId: z36.string().describe("The note (Thought) ID"),
+        headingText: z36.string().min(1).describe("Exact text of the heading whose section the new content follows"),
+        markdown: z36.string().min(1).describe("Markdown content to insert at the end of that section")
       })
     },
     async ({ noteId, headingText, markdown }) => {
@@ -1757,7 +1922,7 @@ function registerNoteInsert(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-replace-section.ts
-import { z as z36 } from "zod";
+import { z as z37 } from "zod";
 function registerNoteReplaceSection(server2, client2) {
   server2.registerTool(
     "naumu_note_replace_section",
@@ -1765,11 +1930,11 @@ function registerNoteReplaceSection(server2, client2) {
       title: "Replace Section",
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
       description: "Replace the body under a named heading with new markdown; use to rewrite one section of a note while leaving the rest intact. By default the heading row itself is preserved (set `keepHeading: false` to drop it too). 404 if no heading matches. To embed media, write `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`. The one syntax covers images, video, audio, and other files, dispatched by the upload's MIME type; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id. An id already embedded elsewhere in the note can be repeated safely without re-uploading.",
-      inputSchema: z36.object({
-        noteId: z36.string().describe("The note (Thought) ID"),
-        headingText: z36.string().min(1).describe("Exact text of the heading anchoring the section"),
-        markdown: z36.string().describe("Replacement markdown for the section body"),
-        keepHeading: z36.boolean().optional().describe("Whether to keep the heading row itself. Default true.")
+      inputSchema: z37.object({
+        noteId: z37.string().describe("The note (Thought) ID"),
+        headingText: z37.string().min(1).describe("Exact text of the heading anchoring the section"),
+        markdown: z37.string().describe("Replacement markdown for the section body"),
+        keepHeading: z37.boolean().optional().describe("Whether to keep the heading row itself. Default true.")
       })
     },
     async ({ noteId, headingText, markdown, keepHeading }) => {
@@ -1786,7 +1951,7 @@ function registerNoteReplaceSection(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-delete-section.ts
-import { z as z37 } from "zod";
+import { z as z38 } from "zod";
 function registerNoteDeleteSection(server2, client2) {
   server2.registerTool(
     "naumu_note_delete_section",
@@ -1794,9 +1959,9 @@ function registerNoteDeleteSection(server2, client2) {
       title: "Delete Section",
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
       description: "\u26A0 DESTRUCTIVE: remove a heading row plus its body (down to the next heading of equal-or-higher level); ONLY use when the user explicitly asks to drop a section. Anything inside that section is gone - there is no per-call undo. If you're unsure which heading they meant, call `naumu_note_read` first to see the current structure. Returns 404 if `headingText` does not exactly match any live heading.",
-      inputSchema: z37.object({
-        noteId: z37.string().describe("The note (Thought) ID"),
-        headingText: z37.string().min(1).describe("Exact text of the heading whose section will be deleted")
+      inputSchema: z38.object({
+        noteId: z38.string().describe("The note (Thought) ID"),
+        headingText: z38.string().min(1).describe("Exact text of the heading whose section will be deleted")
       })
     },
     async ({ noteId, headingText }) => {
@@ -1811,7 +1976,7 @@ function registerNoteDeleteSection(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-replace.ts
-import { z as z38 } from "zod";
+import { z as z39 } from "zod";
 function registerNoteReplace(server2, client2) {
   server2.registerTool(
     "naumu_note_replace",
@@ -1819,9 +1984,9 @@ function registerNoteReplace(server2, client2) {
       title: "Replace Note",
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
       description: "\u26A0 DESTRUCTIVE: replace the entire note content with new markdown; ONLY use when the user explicitly asks to rewrite/replace the whole note. Any concurrent human edits made during the call are silently overwritten. For additive work prefer `naumu_note_append`. For section-level edits use `naumu_note_replace_section`. For inline tweaks use `naumu_note_find_replace`. Read with `naumu_note_read` first if you weren't the last writer. To embed media, write `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`. The one syntax covers images, video, audio, and other files, dispatched by the upload's MIME type; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id. Ids already embedded in the note (read them back via `naumu_note_read`) can be repeated safely without re-uploading.",
-      inputSchema: z38.object({
-        noteId: z38.string().describe("The note (Thought) ID"),
-        markdown: z38.string().describe("New markdown content for the entire note")
+      inputSchema: z39.object({
+        noteId: z39.string().describe("The note (Thought) ID"),
+        markdown: z39.string().describe("New markdown content for the entire note")
       })
     },
     async ({ noteId, markdown }) => {
@@ -1834,7 +1999,7 @@ function registerNoteReplace(server2, client2) {
 }
 
 // ../mcp-core/src/tools/note-find-replace.ts
-import { z as z39 } from "zod";
+import { z as z40 } from "zod";
 function registerNoteFindReplace(server2, client2) {
   server2.registerTool(
     "naumu_note_find_replace",
@@ -1842,11 +2007,11 @@ function registerNoteFindReplace(server2, client2) {
       title: "Find/Replace in Note",
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
       description: "Literal find/replace within a note's text content; use for mid-paragraph tweaks the section-based tools can't target. Marks (bold, italic, code, etc.) are preserved on the surrounding text. \u26A0 The match is literal-substring across every text leaf in the doc; an overly generic `find` (e.g. \" a \") can rewrite the doc unrecognizably. Pick a phrase distinctive enough to land where you mean. By default replaces every occurrence; set `all: false` for first-only. Returns `{ replacements }` so you can sanity-check the count. `replace` can embed media by containing `![alt](attachment://<attachmentId>)` as a sole-line image - the id must come from `naumu_request_attachment_upload` presigned with this same `noteId`; an unresolvable or wrong-note id fails the whole write with a 400 naming the bad id.",
-      inputSchema: z39.object({
-        noteId: z39.string().describe("The note (Thought) ID"),
-        find: z39.string().min(1).describe("Substring to search for. Literal - no regex."),
-        replace: z39.string().describe("Replacement string. May be empty to delete the match."),
-        all: z39.boolean().optional().describe("Replace all occurrences (default true). Pass false to replace only the first.")
+      inputSchema: z40.object({
+        noteId: z40.string().describe("The note (Thought) ID"),
+        find: z40.string().min(1).describe("Substring to search for. Literal - no regex."),
+        replace: z40.string().describe("Replacement string. May be empty to delete the match."),
+        all: z40.boolean().optional().describe("Replace all occurrences (default true). Pass false to replace only the first.")
       })
     },
     async ({ noteId, find, replace, all }) => {
@@ -1863,7 +2028,7 @@ function registerNoteFindReplace(server2, client2) {
 }
 
 // ../mcp-core/src/tools/create-note.ts
-import { z as z40 } from "zod";
+import { z as z41 } from "zod";
 function registerCreateNote(server2, client2) {
   server2.registerTool(
     "naumu_create_note",
@@ -1871,12 +2036,12 @@ function registerCreateNote(server2, client2) {
       title: "Create Note",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
       description: "Create a note in a graph, optionally with its full content already in place. Pass `markdown` to create the note and its body in a single call - the preferred path for imports and for any content you already hold. Returns the new note row including its `id`; use `naumu_note_append` / `naumu_note_replace` for LATER edits, not to fill in content you could have passed here. The returned row is the note as it stood BEFORE the body write landed, so its content may read as empty - the write still succeeded, do not retry the call or re-append the body. `attachment://` refs are not accepted in create-time `markdown`: upload the file after the note exists and embed it with a note write tool. Bots can only create notes in their own graph, and a bot-created note is private (participants only) unless `sharedWithSpace` is set true. Bots cannot file notes into topics - a bot passing `topicIds` is rejected (bots hold no topic membership); use `sharedWithSpace` instead.",
-      inputSchema: z40.object({
-        graphId: z40.string().describe("The graph ID to create the note in"),
-        title: z40.string().optional().describe("Optional title for the note"),
-        markdown: z40.string().optional().describe("Full initial note content as markdown. Provide it here to create the note with its content in a single call - preferred for imports; do not restate large content through extra edit calls."),
-        sharedWithSpace: z40.boolean().optional().describe("Share the note with everyone in the space. Omit (or false) to keep it private to its participants."),
-        topicIds: z40.array(z40.string()).max(8).optional().describe("File the note into these topics (get ids from naumu_list_topics), making it visible to those topics' members. Not available to bots.")
+      inputSchema: z41.object({
+        graphId: z41.string().describe("The graph ID to create the note in"),
+        title: z41.string().optional().describe("Optional title for the note"),
+        markdown: z41.string().optional().describe("Full initial note content as markdown. Provide it here to create the note with its content in a single call - preferred for imports; do not restate large content through extra edit calls."),
+        sharedWithSpace: z41.boolean().optional().describe("Share the note with everyone in the space. Omit (or false) to keep it private to its participants."),
+        topicIds: z41.array(z41.string()).max(8).optional().describe("File the note into these topics (get ids from naumu_list_topics), making it visible to those topics' members. Not available to bots.")
       })
     },
     async ({ graphId, title, markdown, sharedWithSpace, topicIds }) => {
@@ -1889,7 +2054,7 @@ function registerCreateNote(server2, client2) {
 }
 
 // ../mcp-core/src/tools/list-schema-violations.ts
-import { z as z41 } from "zod";
+import { z as z42 } from "zod";
 var DEFAULT_EXAMPLE_LIMIT = 5;
 var rowsForKind = (violations, kind) => {
   const rows = [];
@@ -1915,12 +2080,12 @@ function registerListSchemaViolations(server2, client2) {
       title: "List Schema Violations",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Audit a graph against its schema. By default returns a compact summary: total counts plus, for each violation kind, its count and up to 5 example nodes (id/label/type/message) \u2014 small enough not to flood the client. Violation kinds: parent_missing (schema expects a parent edge that does not exist), parent_multiple (more than one parent edge where one is expected), parent_mismatch (parent edge has wrong target type or relation label), parent_not_backbone (an edge uses a backbone/parent relation but is not stored as a backbone edge, so the subtree stays off the hierarchy), unknown_relation (edge uses a relation not in the schema), invalid_connection_target (edge connects to a type the schema does not allow for this source), unknown_type (node carries a type no longer in the schema), disconnected (node heads a group with no backbone path to the main tree). To see every node for one kind, pass `kind` to filter; `limit` caps how many rows are returned (examples in the default summary, or full rows when `kind` is set). Use for audits, import-verification, and CI-style checks after batch writes.",
-      inputSchema: z41.object({
-        graphId: z41.string().describe("The graph ID"),
-        kind: z41.string().optional().describe(
+      inputSchema: z42.object({
+        graphId: z42.string().describe("The graph ID"),
+        kind: z42.string().optional().describe(
           'Drill into one violation kind (e.g. "parent_not_backbone"). Returns the full list of nodes with that kind, up to `limit`, instead of the summary.'
         ),
-        limit: z41.number().int().min(1).optional().describe(
+        limit: z42.number().int().min(1).optional().describe(
           "Max rows to return. When `kind` is set, caps the full drill-down list (default: all). Otherwise caps example nodes per kind in the summary (default: 5)."
         )
       })
@@ -1972,7 +2137,7 @@ function registerListSchemaViolations(server2, client2) {
 }
 
 // ../mcp-core/src/tools/list-dense-nodes.ts
-import { z as z42 } from "zod";
+import { z as z43 } from "zod";
 function registerListDenseNodes(server2, client2) {
   server2.registerTool(
     "naumu_list_dense_nodes",
@@ -1980,10 +2145,10 @@ function registerListDenseNodes(server2, client2) {
       title: "List Dense Nodes",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: 'Return nodes whose child count (children via parent edges; mesh cross-links don\'t count) is \u2265 minConnections, grouped by type; use for /restructure hub detection. Each row includes `same_typed_child_count` - the number of children of the SAME type as the node (the Naumu hub-pattern signal) and `connection_count` - its total children. Sort the response by `same_typed_child_count` descending and route any node with \u226510 same-typed children through a mini-hub split. Pass `nodeTypes` (comma-separated) to restrict to a subset (e.g. ["Type A","Type B"]). Cheap to call - runs a single Cypher aggregation.',
-      inputSchema: z42.object({
-        graphId: z42.string().describe("The graph ID"),
-        minConnections: z42.number().int().min(1).describe("Minimum number of children (parent edges; mesh cross-links excluded). Typical: 10 for hub detection, 11 to count only hubs that exceed the round-4 \u226410 threshold."),
-        nodeTypes: z42.array(z42.string()).optional().describe("Optional list of node types to restrict the scan to.")
+      inputSchema: z43.object({
+        graphId: z43.string().describe("The graph ID"),
+        minConnections: z43.number().int().min(1).describe("Minimum number of children (parent edges; mesh cross-links excluded). Typical: 10 for hub detection, 11 to count only hubs that exceed the round-4 \u226410 threshold."),
+        nodeTypes: z43.array(z43.string()).optional().describe("Optional list of node types to restrict the scan to.")
       })
     },
     async ({ graphId, minConnections, nodeTypes }) => {
@@ -2001,7 +2166,7 @@ function registerListDenseNodes(server2, client2) {
 }
 
 // ../mcp-core/src/tools/list-node-connections.ts
-import { z as z43 } from "zod";
+import { z as z44 } from "zod";
 function registerListNodeConnections(server2, client2) {
   server2.registerTool(
     "naumu_list_node_connections",
@@ -2009,11 +2174,11 @@ function registerListNodeConnections(server2, client2) {
       title: "List Node Connections",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: 'Return a single node\'s edges (non-system) with the connected node on the other side; use during /restructure to confirm mini-hub candidates and verify reparenting outcomes. Filter with `edgeType` (relation label) and `direction` ("in" | "out" | "both", default both). Response: `{ node: {id,label,type}, edges: [{relation, direction, isParent, other: {id,label,type}}] }`.',
-      inputSchema: z43.object({
-        graphId: z43.string().describe("The graph ID"),
-        nodeId: z43.string().describe("The node ID to inspect"),
-        edgeType: z43.string().optional().describe('Restrict to a specific relation label (e.g. "ASSOCIATED_WITH"). Case-insensitive; non-alphanum chars are normalized.'),
-        direction: z43.enum(["in", "out", "both"]).optional().describe('Edge direction filter - "in" (incoming), "out" (outgoing), "both" (default).')
+      inputSchema: z44.object({
+        graphId: z44.string().describe("The graph ID"),
+        nodeId: z44.string().describe("The node ID to inspect"),
+        edgeType: z44.string().optional().describe('Restrict to a specific relation label (e.g. "ASSOCIATED_WITH"). Case-insensitive; non-alphanum chars are normalized.'),
+        direction: z44.enum(["in", "out", "both"]).optional().describe('Edge direction filter - "in" (incoming), "out" (outgoing), "both" (default).')
       })
     },
     async ({ graphId, nodeId, edgeType, direction }) => {
@@ -2031,7 +2196,7 @@ function registerListNodeConnections(server2, client2) {
 }
 
 // ../mcp-core/src/tools/reparent.ts
-import { z as z44 } from "zod";
+import { z as z45 } from "zod";
 function registerReparent(server2, client2) {
   server2.registerTool(
     "naumu_reparent",
@@ -2039,11 +2204,11 @@ function registerReparent(server2, client2) {
       title: "Reparent Node",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: 'Atomically swap a node\'s parent edge; use to move a child under a different parent (e.g. during /restructure to reparent children under newly-created mini-hubs). Deletes any existing `isParent: true` edges on the node and creates a new one to `newParentId` with relation `newRelation`. Preserves the node\'s id, content, attributes, and embedding - does NOT trigger embedding regeneration because only the parent edge changes. Idempotent: if the node already has the requested parent edge, response is `status: "skipped"`. Response shape: `{nodeId, oldParentId, newParentId, newRelation, status: "moved" | "skipped"}`.',
-      inputSchema: z44.object({
-        graphId: z44.string().describe("The graph ID"),
-        nodeId: z44.string().describe("The child node to reparent"),
-        newParentId: z44.string().describe("The new parent node id"),
-        newRelation: z44.string().describe('The new parent edge relation label (e.g. "PART_OF"). Must be valid per the schema for (child.type, relation, parent.type).')
+      inputSchema: z45.object({
+        graphId: z45.string().describe("The graph ID"),
+        nodeId: z45.string().describe("The child node to reparent"),
+        newParentId: z45.string().describe("The new parent node id"),
+        newRelation: z45.string().describe('The new parent edge relation label (e.g. "PART_OF"). Must be valid per the schema for (child.type, relation, parent.type).')
       })
     },
     async ({ graphId, nodeId, newParentId, newRelation }) => {
@@ -2059,7 +2224,7 @@ function registerReparent(server2, client2) {
 }
 
 // ../mcp-core/src/tools/batch-reparent.ts
-import { z as z45 } from "zod";
+import { z as z46 } from "zod";
 function registerBatchReparent(server2, client2) {
   server2.registerTool(
     "naumu_batch_reparent",
@@ -2067,11 +2232,11 @@ function registerBatchReparent(server2, client2) {
       title: "Batch Reparent Nodes",
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       description: 'Reparent 1-25 nodes onto a shared `newParentId` with the same `newRelation`; use to move a same-typed cluster under a freshly-created mini-hub in /restructure. Same semantics as `naumu_reparent` per-node: atomic swap of the isParent edge, preserves id/content/attributes/embedding, no re-embedding. Idempotent per node (already-parented nodes return `status: "skipped"`). Per-node response array: `[{nodeId, oldParentId, newParentId, status: "moved" | "skipped" | "error", error?}]`.',
-      inputSchema: z45.object({
-        graphId: z45.string().describe("The graph ID"),
-        newParentId: z45.string().describe("Parent node id every nodeId in the batch will be parented to"),
-        newRelation: z45.string().describe("Parent edge relation label (must be valid per schema for child.type \u2192 parent.type)"),
-        nodeIds: z45.array(z45.string()).min(1).max(25).describe("1\u201325 child node ids to reparent under `newParentId`")
+      inputSchema: z46.object({
+        graphId: z46.string().describe("The graph ID"),
+        newParentId: z46.string().describe("Parent node id every nodeId in the batch will be parented to"),
+        newRelation: z46.string().describe("Parent edge relation label (must be valid per schema for child.type \u2192 parent.type)"),
+        nodeIds: z46.array(z46.string()).min(1).max(25).describe("1\u201325 child node ids to reparent under `newParentId`")
       })
     },
     async ({ graphId, newParentId, newRelation, nodeIds }) => {
@@ -2088,7 +2253,7 @@ function registerBatchReparent(server2, client2) {
 }
 
 // ../mcp-core/src/tools/chatgpt-search.ts
-import { z as z46 } from "zod";
+import { z as z47 } from "zod";
 
 // ../mcp-core/src/public-origin.ts
 function publicOrigin() {
@@ -2142,8 +2307,8 @@ function registerChatgptSearch(server2, client2) {
       title: "Search",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Search across all of the knowledge graphs (spaces) you can access and return the most relevant nodes. Returns `{ results: [{ id, title, url }] }`. Pass each result `id` to the `fetch` tool to read the full node. (This is the cross-space entry point for ChatGPT/Deep Research; within a single space, `naumu_search` exposes more controls.)",
-      inputSchema: z46.object({
-        query: z46.string().describe(
+      inputSchema: z47.object({
+        query: z47.string().describe(
           "A short contiguous phrase \u2014 an entity name, label, or ID. The text half matches it verbatim as a case-insensitive substring; the semantic half matches meaning."
         )
       })
@@ -2177,7 +2342,7 @@ function registerChatgptSearch(server2, client2) {
 }
 
 // ../mcp-core/src/tools/chatgpt-fetch.ts
-import { z as z47 } from "zod";
+import { z as z48 } from "zod";
 var NON_ATTRIBUTE_PROPS = /* @__PURE__ */ new Set([
   "id",
   "label",
@@ -2196,7 +2361,8 @@ var NON_ATTRIBUTE_PROPS = /* @__PURE__ */ new Set([
   "updatedAt",
   "heatConvSignal",
   "heatConvComputedAt",
-  "heatComputedAt"
+  "heatComputedAt",
+  "context"
 ]);
 function parseResourceId(id) {
   const sep = id.indexOf(":");
@@ -2225,14 +2391,42 @@ ${attrLines.join("\n")}`);
   const edgeLines = [];
   for (const e of connections?.outgoing ?? []) {
     if (!e?.target) continue;
-    edgeLines.push(`- ${e.label ?? "related"} \u2192 ${e.target}${e.isParent ? " (parent)" : ""}`);
+    const target = e.targetLabel ? `${e.targetLabel} (${e.target})` : e.target;
+    edgeLines.push(`- ${e.label ?? "related"} \u2192 ${target}${e.isParent ? " (parent)" : ""}`);
   }
   for (const e of connections?.incoming ?? []) {
     if (!e?.source) continue;
-    edgeLines.push(`- ${e.source} \u2192 ${e.label ?? "related"} (incoming)`);
+    const source = e.sourceLabel ? `${e.sourceLabel} (${e.source})` : e.source;
+    edgeLines.push(`- ${source} \u2192 ${e.label ?? "related"} (incoming)`);
   }
   if (edgeLines.length) parts.push(`Connections:
 ${edgeLines.join("\n")}`);
+  const ctx = node.context ?? {};
+  if (ctx.notes?.length) {
+    const more = (ctx.notesTotal ?? ctx.notes.length) - ctx.notes.length;
+    const lines = ctx.notes.map((n) => `- ${n.title || "Untitled"} (${n.id})`);
+    if (more > 0) lines.push(`- \u2026and ${more} more`);
+    parts.push(`Notes:
+${lines.join("\n")}`);
+  }
+  if (ctx.threads?.length) {
+    const more = (ctx.threadsTotal ?? ctx.threads.length) - ctx.threads.length;
+    const lines = ctx.threads.map(
+      (t) => `- ${t.title || "Untitled"} (${t.id}${t.relations?.length ? ` \xB7 ${t.relations.join(", ")}` : ""})`
+    );
+    if (more > 0) lines.push(`- \u2026and ${more} more`);
+    parts.push(`Conversations:
+${lines.join("\n")}`);
+  }
+  if (ctx.scheduledTasks?.length) {
+    const lines = ctx.scheduledTasks.map(
+      (t) => `- ${t.title} (${t.id}${t.cron ? ` \xB7 cron ${t.cron}` : ""})`
+    );
+    parts.push(`Scheduled tasks:
+${lines.join("\n")}`);
+  }
+  if (ctx.summary?.content) parts.push(`Summary:
+${ctx.summary.content}`);
   return parts.join("\n\n");
 }
 function registerChatgptFetch(server2, client2) {
@@ -2242,8 +2436,8 @@ function registerChatgptFetch(server2, client2) {
       title: "Fetch",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Fetch the full contents of a node returned by the `search` tool. Pass the result `id` verbatim (format `<graphId>:<nodeId>`). Returns `{ id, title, text, url }` where `text` is the node content plus its type, attributes, and connections.",
-      inputSchema: z47.object({
-        id: z47.string().describe("A resource id from a previous `search` result, in the form `<graphId>:<nodeId>`.")
+      inputSchema: z48.object({
+        id: z48.string().describe("A resource id from a previous `search` result, in the form `<graphId>:<nodeId>`.")
       })
     },
     async ({ id }) => {
@@ -2286,7 +2480,7 @@ function registerChatgptFetch(server2, client2) {
 }
 
 // ../mcp-core/src/tools/admission-status.ts
-import { z as z48 } from "zod";
+import { z as z49 } from "zod";
 function registerAdmissionStatus(server2, client2) {
   server2.registerTool(
     "naumu_admission_status",
@@ -2294,8 +2488,8 @@ function registerAdmissionStatus(server2, client2) {
       title: "Admission Status",
       annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
       description: "Show who can auto-join a Naumu space (graph) and who is waiting for approval: the whitelisted emails (people who join the moment they sign in with that email), the auto-join domain wildcards, and the count of pending join requests. When there are pending requests, this also returns the full list (who requested, their email, git-email hint, and message) so you can act on them with naumu_resolve_join_request. Use it during repo init to review or seed access, or whenever the user asks who has access to a space or who is asking to join.",
-      inputSchema: z48.object({
-        graphId: z48.string().describe("The space (graph) ID to inspect admission for. You must be a member of this space.")
+      inputSchema: z49.object({
+        graphId: z49.string().describe("The space (graph) ID to inspect admission for. You must be a member of this space.")
       })
     },
     async ({ graphId }) => {
@@ -2325,7 +2519,7 @@ function registerAdmissionStatus(server2, client2) {
 }
 
 // ../mcp-core/src/tools/whitelist-members.ts
-import { z as z49 } from "zod";
+import { z as z50 } from "zod";
 function registerWhitelistMembers(server2, client2) {
   server2.registerTool(
     "naumu_whitelist_members",
@@ -2338,10 +2532,10 @@ function registerWhitelistMembers(server2, client2) {
         openWorldHint: false
       },
       description: "Whitelist emails so those people auto-join a Naumu space (graph) the moment they sign in with that email. Use this during repo init: after you scrub git history, present the curated list of collaborators to the user, and get their explicit confirmation, call this with the confirmed emails. It is silent - it sends no invite emails, it just pre-authorizes those addresses. Returns which entries were created and which were skipped (already whitelisted or already members). Set repoInit true when this call is part of the repo init flow.",
-      inputSchema: z49.object({
-        graphId: z49.string().describe("The space (graph) ID to whitelist emails for. You must be a member of this space."),
-        emails: z49.array(z49.string()).min(1).describe("The emails to whitelist. Each becomes an exact-match auto-join entry. Present these to the user and get confirmation before calling."),
-        repoInit: z49.boolean().optional().describe("Set true when this whitelist is being seeded as part of the repo init flow, so onboarding is tracked correctly.")
+      inputSchema: z50.object({
+        graphId: z50.string().describe("The space (graph) ID to whitelist emails for. You must be a member of this space."),
+        emails: z50.array(z50.string()).min(1).describe("The emails to whitelist. Each becomes an exact-match auto-join entry. Present these to the user and get confirmation before calling."),
+        repoInit: z50.boolean().optional().describe("Set true when this whitelist is being seeded as part of the repo init flow, so onboarding is tracked correctly.")
       })
     },
     async ({ graphId, emails, repoInit }) => {
@@ -2365,7 +2559,7 @@ function registerWhitelistMembers(server2, client2) {
 }
 
 // ../mcp-core/src/tools/resolve-admission.ts
-import { z as z50 } from "zod";
+import { z as z51 } from "zod";
 function registerResolveAdmission(server2, client2) {
   server2.registerTool(
     "naumu_resolve_admission",
@@ -2378,9 +2572,9 @@ function registerResolveAdmission(server2, client2) {
         openWorldHint: false
       },
       description: "The call a coding agent makes right after connecting when a repo's .naumu references a space the user is not yet a member of. It evaluates whether the user can join and does it: outcome is joined-whitelist or joined-wildcard (the user is now a member - proceed), already-member (nothing to do), request-created (a join request was just filed and is awaiting a member's approval), or request-pending (a request was already open). When the response also carries reason 'seat-limit' on a request-created/request-pending outcome, the user WOULD have auto-joined via a whitelist/domain match but the space is at its seat limit - so their access is pending an admin approving them or upgrading the plan; relay that specific reason honestly, do not just say 'no match'. Pass gitEmailHint from `git config user.email` so a matching whitelist or domain rule can admit them. Relay the outcome to the user honestly: say plainly whether they joined or are waiting for approval - never imply access that is still pending.",
-      inputSchema: z50.object({
-        graphId: z50.string().describe("The space (graph) ID referenced by the repo .naumu file that the user wants to join."),
-        gitEmailHint: z50.string().optional().describe("The email from `git config user.email`, used to match whitelist entries and auto-join domains.")
+      inputSchema: z51.object({
+        graphId: z51.string().describe("The space (graph) ID referenced by the repo .naumu file that the user wants to join."),
+        gitEmailHint: z51.string().optional().describe("The email from `git config user.email`, used to match whitelist entries and auto-join domains.")
       })
     },
     async ({ graphId, gitEmailHint }) => {
@@ -2404,7 +2598,7 @@ function registerResolveAdmission(server2, client2) {
 }
 
 // ../mcp-core/src/tools/resolve-join-request.ts
-import { z as z51 } from "zod";
+import { z as z52 } from "zod";
 function registerResolveJoinRequest(server2, client2) {
   server2.registerTool(
     "naumu_resolve_join_request",
@@ -2417,10 +2611,10 @@ function registerResolveJoinRequest(server2, client2) {
         openWorldHint: false
       },
       description: "For a member resolving a pending join request surfaced by naumu_admission_status. Approve to add the requester to the space as a member, or deny to reject the request. Get the requestId from naumu_admission_status's pending list, and confirm the decision with the user before calling since approving grants access.",
-      inputSchema: z51.object({
-        graphId: z51.string().describe("The space (graph) ID the request is for. You must be a member of this space."),
-        requestId: z51.string().describe("The pending join request ID, taken from naumu_admission_status."),
-        action: z51.enum(["approve", "deny"]).describe("approve adds the requester as a member; deny rejects the request.")
+      inputSchema: z52.object({
+        graphId: z52.string().describe("The space (graph) ID the request is for. You must be a member of this space."),
+        requestId: z52.string().describe("The pending join request ID, taken from naumu_admission_status."),
+        action: z52.enum(["approve", "deny"]).describe("approve adds the requester as a member; deny rejects the request.")
       })
     },
     async ({ graphId, requestId, action }) => {
@@ -2443,6 +2637,29 @@ function registerResolveJoinRequest(server2, client2) {
   );
 }
 
+// ../mcp-core/src/tools/tool-attribution.ts
+function withToolAttribution(server2, client2) {
+  return new Proxy(server2, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (prop !== "registerTool" || typeof value !== "function") return value;
+      return (...args) => {
+        const toolName = typeof args[0] === "string" ? args[0] : void 0;
+        const handlerIndex = args.length - 1;
+        const handler = args[handlerIndex];
+        if (toolName && typeof handler === "function") {
+          const original = handler;
+          args[handlerIndex] = (...handlerArgs) => {
+            client2.setPendingToolName(toolName);
+            return original(...handlerArgs);
+          };
+        }
+        return value.apply(target, args);
+      };
+    }
+  });
+}
+
 // ../mcp-core/src/tools/index.ts
 var TOOL_REGISTRARS = {
   naumu_list_graphs: registerListGraphs,
@@ -2470,16 +2687,18 @@ var TOOL_REGISTRARS = {
   naumu_whoami: registerWhoami,
   naumu_list_threads: registerListThreads,
   naumu_list_topics: registerListTopics,
-  // User-surface only. `POST /api/graphs/:id/topics` requires the ADMIN-only
-  // `space:manage-topics` permission, and bot identities always resolve to the
-  // editor role, so a bot calling this could only ever 403. It is therefore
-  // omitted from BOT_ONLY_TOOL_NAMES and has no entry in the backend
-  // PERMISSION_TO_MCP_TOOLS map (same treatment as the admission tools below).
+  // User-surface only. Omitted from BOT_ONLY_TOOL_NAMES and from the backend
+  // PERMISSION_TO_MCP_TOOLS map (same treatment as the admission tools
+  // below), so bot manifests never include it. Note the backend gate alone
+  // no longer keeps bots out: `space:manage-topics` is editor+ since
+  // 2026-08-11 and bot identities resolve to the editor role — the manifest
+  // omission is what keeps this tool off the bot surface.
   naumu_create_topic: registerCreateTopic,
   naumu_get_thread: registerGetThread,
   naumu_create_thread: registerCreateThread,
   naumu_request_attachment_upload: registerRequestAttachmentUpload,
   naumu_persist_canvas_attachment: registerPersistCanvasAttachment,
+  naumu_get_attachment: registerGetAttachment,
   naumu_add_reaction: registerAddReaction,
   naumu_remove_reaction: registerRemoveReaction,
   naumu_typing: registerNaumuTyping,
@@ -2515,18 +2734,20 @@ var ALL_TOOL_NAMES = Object.keys(TOOL_REGISTRARS).filter(
   (name) => !BOT_ONLY_TOOL_NAMES.has(name)
 );
 function registerAllTools(server2, client2) {
+  const attributed = withToolAttribution(server2, client2);
   for (const [name, registrar] of Object.entries(TOOL_REGISTRARS)) {
     if (BOT_ONLY_TOOL_NAMES.has(name)) continue;
-    registrar(server2, client2);
+    registrar(attributed, client2);
   }
 }
 function registerNamedTools(server2, client2, toolNames) {
+  const attributed = withToolAttribution(server2, client2);
   const registered = [];
   const skipped = [];
   for (const name of toolNames) {
     const registrar = TOOL_REGISTRARS[name];
     if (registrar) {
-      registrar(server2, client2);
+      registrar(attributed, client2);
       registered.push(name);
     } else {
       skipped.push(name);
@@ -2540,16 +2761,209 @@ function registerNamedTools(server2, client2, toolNames) {
   console.error(`[mcp] registered ${registered.length} tool(s) for bot key`);
 }
 
+// src/doctor.ts
+var MARKERS = {
+  pass: "[ok]  ",
+  fail: "[fail]",
+  warn: "[warn]"
+};
+var BOT_KEY_PREFIX = "nmu_bot_";
+var SETTINGS_URL = "https://naumu.ai/settings";
+var REGISTRY_LATEST_URL = "https://registry.npmjs.org/@naumu/mcp/latest";
+var API_TIMEOUT_MS = 1e4;
+var REGISTRY_TIMEOUT_MS = 4e3;
+var errorMessage = (err) => err instanceof Error ? err.message : String(err);
+var timeoutSignal = (ms) => typeof AbortSignal?.timeout === "function" ? AbortSignal.timeout(ms) : void 0;
+var formatDoctorCheck = (check) => `${MARKERS[check.status]} ${check.label}: ${check.detail}`;
+var checkApiKey = (apiKey2) => {
+  if (!apiKey2) {
+    return {
+      label: "API key",
+      status: "fail",
+      detail: "NAUMU_API_KEY is missing from the environment",
+      fix: `Set NAUMU_API_KEY - create a key at ${SETTINGS_URL} (Settings > Your agents > Create an API key)`
+    };
+  }
+  const kind = apiKey2.startsWith(BOT_KEY_PREFIX) ? "bot key" : "user key";
+  return {
+    label: "API key",
+    status: "pass",
+    detail: `NAUMU_API_KEY is set (${kind}; value not printed)`
+  };
+};
+var describeWhoami = (data) => {
+  const row = data ?? {};
+  if (row.kind === "user") {
+    const email = row.email ? ` <${row.email}>` : "";
+    return `authenticated as ${row.name ?? "unknown user"}${email}`;
+  }
+  if (row.id) {
+    return `authenticated as bot identity ${row.name ?? row.id} (graph ${row.graphId ?? "unknown"})`;
+  }
+  return "authenticated, but the identity payload was not recognized";
+};
+var checkApiReachability = async (options) => {
+  const label = "API";
+  const doFetch = options.fetchImpl ?? fetch;
+  const headers = { Accept: "application/json" };
+  if (options.apiKey) headers.Authorization = `Bearer ${options.apiKey}`;
+  let res;
+  try {
+    res = await doFetch(`${options.apiUrl}/api/identities/me/whoami`, {
+      headers,
+      signal: timeoutSignal(options.timeoutMs ?? API_TIMEOUT_MS)
+    });
+  } catch (err) {
+    return {
+      label,
+      status: "fail",
+      detail: `unreachable - no response from ${options.apiUrl} (${errorMessage(err)})`,
+      fix: `Check your network and NAUMU_API_URL - nothing answered at ${options.apiUrl}`
+    };
+  }
+  if (res.status === 401 || res.status === 403) {
+    if (!options.apiKey) {
+      return {
+        label,
+        status: "warn",
+        detail: `reachable (${options.apiUrl} answered HTTP ${res.status}), but there is no NAUMU_API_KEY to verify`
+      };
+    }
+    return {
+      label,
+      status: "fail",
+      detail: `reachable, but ${options.apiUrl} rejected the key (HTTP ${res.status})`,
+      fix: `NAUMU_API_KEY is invalid or revoked - create a new key at ${SETTINGS_URL} and update your MCP config`
+    };
+  }
+  if (!res.ok) {
+    return {
+      label,
+      status: "fail",
+      detail: `reachable, but ${options.apiUrl} answered HTTP ${res.status}`,
+      fix: "The Naumu API returned an unexpected status - retry shortly, or check NAUMU_API_URL points at the front-end origin"
+    };
+  }
+  try {
+    const data = await res.json();
+    return { label, status: "pass", detail: `reachable at ${options.apiUrl}; ${describeWhoami(data)}` };
+  } catch (err) {
+    return {
+      label,
+      status: "fail",
+      detail: `reachable, but the response from ${options.apiUrl} was not JSON (${errorMessage(err)})`,
+      fix: "NAUMU_API_URL does not look like a Naumu API - point it at https://naumu.ai"
+    };
+  }
+};
+var compareVersions = (a, b) => {
+  const parse = (value) => value.split(".").slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+  const left = parse(a);
+  const right = parse(b);
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (left[i] ?? 0) - (right[i] ?? 0);
+    if (diff !== 0) return diff < 0 ? -1 : 1;
+  }
+  return 0;
+};
+var checkVersionFreshness = async (options = {}) => {
+  const label = "Version";
+  const current = options.currentVersion ?? NAUMU_MCP_VERSION;
+  const doFetch = options.fetchImpl ?? fetch;
+  let latest;
+  try {
+    const res = await doFetch(REGISTRY_LATEST_URL, {
+      headers: { Accept: "application/json" },
+      signal: timeoutSignal(options.timeoutMs ?? REGISTRY_TIMEOUT_MS)
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const body = await res.json();
+    latest = body?.version;
+  } catch (err) {
+    return {
+      label,
+      status: "warn",
+      detail: `running ${current}; could not check the npm registry for the latest version (${errorMessage(err)})`
+    };
+  }
+  if (!latest) {
+    return {
+      label,
+      status: "warn",
+      detail: `running ${current}; could not check the npm registry for the latest version (no version field in the response)`
+    };
+  }
+  const comparison = compareVersions(current, latest);
+  if (comparison < 0) {
+    return {
+      label,
+      status: "fail",
+      detail: `running ${current}, but npm latest is ${latest}`,
+      fix: 'Update @naumu/mcp - run "npm cache clean --force" and reinstall (globally installed: "npm i -g @naumu/mcp@latest"; npx users: pin "@naumu/mcp@latest")'
+    };
+  }
+  if (comparison > 0) {
+    return { label, status: "pass", detail: `running ${current}, ahead of npm latest ${latest} (unpublished build)` };
+  }
+  return { label, status: "pass", detail: `running ${current} (npm latest)` };
+};
+var runDoctorChecks = async (options) => {
+  const checks = [];
+  checks.push(checkApiKey(options.apiKey));
+  checks.push(
+    await checkApiReachability({
+      apiUrl: options.apiUrl,
+      apiKey: options.apiKey,
+      fetchImpl: options.fetchImpl
+    })
+  );
+  checks.push(
+    await checkVersionFreshness({
+      currentVersion: options.currentVersion,
+      fetchImpl: options.fetchImpl
+    })
+  );
+  return checks;
+};
+var renderDoctorReport = (checks, context) => {
+  const version = context.version ?? NAUMU_MCP_VERSION;
+  const lines = [
+    `naumu-mcp doctor (v${version}, API ${context.apiUrl})`,
+    "",
+    ...checks.map(formatDoctorCheck),
+    ""
+  ];
+  const failures = checks.filter((check) => check.status === "fail");
+  if (failures.length === 0) {
+    lines.push("Verdict: all checks passed - the MCP server should start normally.");
+    return { text: lines.join("\n"), exitCode: 0 };
+  }
+  const plural = failures.length === 1 ? "check" : "checks";
+  lines.push(`Verdict: ${failures.length} ${plural} failed - the MCP server will not work until this is fixed.`);
+  const fix = failures.find((check) => check.fix)?.fix;
+  if (fix) lines.push(`Most likely fix: ${fix}`);
+  return { text: lines.join("\n"), exitCode: 1 };
+};
+var runDoctorCli = async (options) => {
+  const checks = await runDoctorChecks({ apiUrl: options.apiUrl, apiKey: options.apiKey });
+  const report = renderDoctorReport(checks, { apiUrl: options.apiUrl });
+  console.log(report.text);
+  return report.exitCode;
+};
+
 // src/index.ts
 var DEFAULT_API_URL = "https://naumu.ai";
-var BOT_KEY_PREFIX = "nmu_bot_";
+var BOT_KEY_PREFIX2 = "nmu_bot_";
 var apiUrl = (process.env.NAUMU_API_URL || DEFAULT_API_URL).replace(/\/api\/?$/, "");
 var apiKey = process.env.NAUMU_API_KEY;
+if (process.argv[2] === "doctor") {
+  process.exit(await runDoctorCli({ apiUrl, apiKey }));
+}
 if (!apiKey) {
   console.error("Missing required environment variable: NAUMU_API_KEY");
   process.exit(1);
 }
-var client = new NaumuClient(apiUrl, apiKey);
+var client = new NaumuClient(apiUrl, apiKey, { reportMcpClientHeaders: true });
 var server = new McpServer(
   {
     name: "naumu",
@@ -2559,7 +2973,7 @@ var server = new McpServer(
     instructions: NAUMU_INSTRUCTIONS
   }
 );
-var isBotKey = apiKey.startsWith(BOT_KEY_PREFIX);
+var isBotKey = apiKey.startsWith(BOT_KEY_PREFIX2);
 if (isBotKey) {
   try {
     const manifest = await client.get("/api/identities/me/mcp-tool-manifest");
@@ -2578,5 +2992,9 @@ if (isBotKey) {
     `[mcp] connected to ${apiUrl} as user key (${process.env.NAUMU_IDENTITY_ID ?? "no identity id set"})`
   );
 }
+server.server.oninitialized = () => {
+  const clientInfo = server.server.getClientVersion();
+  client.setMcpClientInfo(clientInfo ? { name: clientInfo.name, version: clientInfo.version } : void 0);
+};
 var transport = new StdioServerTransport();
 await server.connect(transport);