@naumu/mcp 0.11.1 → 0.12.1

package/README.md

@@ -1,14 +1,59 @@
 # @naumu/mcp
 
-MCP server for [Naumu](https://naumu.ai) — access your knowledge graph from Claude Code, Cursor, and other AI coding agents.
+MCP server for [Naumu](https://naumu.ai) - access your knowledge graph from Claude Code, Cursor, and other AI agents.
 
-## Setup
+Naumu speaks MCP over two transports:
+
+1. **Remote, over OAuth** at `https://naumu.ai/api/mcp` - the recommended path. You sign in through your browser, and there is no API key to create, paste, or keep in sync. This package is not involved.
+2. **Local stdio**, this package, launched on demand with `npx` and authenticated with an API key. Use it for clients that cannot do browser OAuth: CI jobs, bot and external-agent identities, and older stdio-only harnesses.
+
+## Recommended setup: remote MCP over OAuth
+
+Register the server once. The first time a session uses a Naumu tool, your browser opens to sign in and approve access. After that the tools are available in every session.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http --scope user naumu https://naumu.ai/api/mcp
+```
+
+`--scope user` registers the server for your whole machine rather than the current project, so you do not have to repeat it per repository.
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "naumu": {
+      "url": "https://naumu.ai/api/mcp"
+    }
+  }
+}
+```
+
+Leave any OAuth client ID and secret fields blank. Naumu registers the client for you automatically during sign-in, using Dynamic Client Registration (DCR).
+
+Other MCP-capable clients that support remote servers follow the same shape: point them at `https://naumu.ai/api/mcp` and let the browser handle sign-in. Use the front-end origin (`naumu.ai`), not a backend address - sign-in and consent rely on your Naumu session, which lives on the front-end origin.
+
+You can revoke a connected tool's access at any time in Naumu under **Settings > Your agents**, in the **Active access** list.
+
+See [Local MCP](https://naumu.ai/docs/local-mcp) for the full walkthrough.
+
+## Fallback setup: local stdio server with an API key
+
+Use this package when your client cannot do browser OAuth - CI, bots and external agent identities, or a harness that only speaks stdio.
 
 ### 1. Get an API key
 
-Generate an API key from your Naumu account settings.
+1. Open **Settings > Your agents** in Naumu.
+2. Select **Create an API key** and give it a recognizable name (such as the tool it is for).
+3. Copy the key right away. It is shown only once and cannot be retrieved later. Keys start with `nmu_`.
+
+Use a separate key per tool, so a leak only costs you that one key.
 
-### 2. Configure your IDE
+### 2. Configure your client
+
+You do not install this package globally; your client launches it on demand with `npx`.
 
 #### Claude Code
 
@@ -20,8 +65,6 @@ claude mcp add naumu -s user \
 
 #### Cursor
 
-Add to your Cursor MCP settings:
-
 ```json
 {
   "mcpServers": {
@@ -36,39 +79,138 @@ Add to your Cursor MCP settings:
 }
 ```
 
+### Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `NAUMU_API_KEY` | Yes | - | Your API key (starts with `nmu_`) |
+| `NAUMU_API_URL` | No | `https://naumu.ai` | Naumu API base URL. You do not need to set this |
+
 ## Available tools
 
+Both transports expose the same tool surface. Tools marked **bot** are only registered for bot identity keys (`nmu_bot_*`), which additionally receive a filtered subset based on the identity's permissions.
+
+### Spaces and members
+
 | Tool | Description |
 |------|-------------|
-| `naumu_list_graphs` | List all knowledge graphs you have access to |
-| `naumu_get_schema` | Get the schema (node types, relationships) for a graph |
-| `naumu_text_search` | Search nodes by exact text match on labels and content |
-| `naumu_semantic_search` | Search nodes by meaning using AI embeddings |
-| `naumu_filter` | Filter nodes by type and attributes with deterministic results |
-| `naumu_get_node` | Get a node with all its properties and connections |
-| `naumu_add_node` | Create a new node |
-| `naumu_update_node` | Update an existing node |
-| `naumu_add_edge` | Create a relationship between two nodes |
-| `naumu_remove_node` | Delete a node and its connections |
-| `naumu_remove_edge` | Delete a relationship |
-| `naumu_create_topic` | Create a topic (filing destination) in a space; admin-only, name must be a lowercase slug, returns an `id` for `topicIds` params |
-| `naumu_ask` | Ask @Naumu a question and get a synthesised answer back (answer + sources + confidence + threadId + status); leaves a visible thread in the space |
-| `naumu_delegate` | Hand @Naumu a task to carry out asynchronously (add knowledge, make changes); returns a `threadId` immediately, then poll with `naumu_read_thread` |
-| `naumu_read_thread` | Read a thread's messages; each message carries a `status` of `processing` or `complete` |
-| `naumu_whoami` | (Bot keys) Self-introspection — id, graphId, name, instructions, allowed tools |
-| `naumu_list_threads` | (Bot keys) List threads in your graph with `isParticipant` flag |
-| `naumu_get_thread` | (Bot keys) Fetch a thread plus its human + bot participant rosters |
-| `naumu_create_thread` | (Bot keys only) Start a new conversation, attach participants, post initial message, optionally file into topics via `topicIds` |
-| `naumu_request_attachment_upload` | (Bot keys) Get a presigned S3 URL to upload a file; pair with `naumu_post_message`'s `attachmentIds` |
-| `naumu_add_reaction` | (Bot keys) Add an emoji reaction to a message in a thread you participate in (idempotent) |
-| `naumu_remove_reaction` | (Bot keys) Remove your own reaction from a message |
-
-## Environment variables
+| `naumu_list_graphs` | List every space (graph) the key can access, with ids, names, and roles |
+| `naumu_create_graph` | Create a new, empty space owned by the authenticated user |
+| `naumu_list_members` | List a space's members with their roles |
+| `naumu_whoami` | Return who the calling key is (user, or bot identity with its graph and allowed tools) |
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `NAUMU_API_KEY` | Yes | — | Your API key (starts with `nmu_`) |
-| `NAUMU_API_URL` | No | `https://naumu.ai` | Naumu API base URL (only change for self-hosted) |
+### Schema
+
+| Tool | Description |
+|------|-------------|
+| `naumu_get_schema` | Get a space's schema (node types, attributes, connections) |
+| `naumu_update_schema` | Replace the schema with a full new definition |
+| `naumu_add_node_type` | Add one node type without resending the whole schema |
+| `naumu_add_connection` | Add one connection from an existing node type to another |
+| `naumu_add_attribute` | Add or extend an attribute on an existing node type |
+| `naumu_list_schema_violations` | Audit a space against its schema and report violations |
+
+### Reading the graph
+
+| Tool | Description |
+|------|-------------|
+| `naumu_search` | Hybrid (meaning plus text) search over graph nodes |
+| `naumu_filter` | Filter nodes by type and attributes, with deterministic and complete results |
+| `naumu_get_node` | Get one node with its properties, edges, notes, threads, and generated context |
+| `naumu_list_node_connections` | List a single node's connections |
+| `naumu_list_dense_nodes` | Find over-connected hub nodes by child count |
+| `naumu_ask` | Ask @Naumu a question and get a synthesised, node-grounded answer with sources and confidence |
+
+### Writing to the graph
+
+| Tool | Description |
+|------|-------------|
+| `naumu_add_node` | Create 1-25 nodes in one call |
+| `naumu_update_node` | Overwrite properties of an existing node |
+| `naumu_remove_node` | Delete a node and all of its connections (destructive) |
+| `naumu_add_edge` | Create 1-25 edges between existing nodes |
+| `naumu_remove_edge` | Delete one edge identified by (source, target, label) |
+| `naumu_remove_edges_bulk` | Delete 1-100 edges in one atomic call |
+| `naumu_reparent` | Atomically swap a node's parent edge |
+| `naumu_batch_reparent` | Reparent 1-25 nodes onto a shared new parent |
+| `naumu_delegate` | Hand @Naumu a task to carry out asynchronously; returns a `threadId` to poll |
+
+### Threads and topics
+
+| Tool | Description |
+|------|-------------|
+| `naumu_list_threads` | List threads by last activity, with an `isParticipant` flag |
+| `naumu_get_thread` | Fetch one thread plus its human and bot participant rosters |
+| `naumu_read_thread` | Read a thread's messages; each carries `processing` or `complete` status |
+| `naumu_post_message` | Post a markdown message in a thread you participate in |
+| `naumu_create_thread` | **bot** Start a new conversation, attach participants, post a first message, optionally file into topics |
+| `naumu_add_reaction` | Add an emoji reaction to a message (idempotent) |
+| `naumu_remove_reaction` | Remove your own reaction from a message |
+| `naumu_typing` | Show or hide your "is typing" indicator in a thread |
+| `naumu_list_topics` | List a space's topics (filing destinations) for use in `topicIds` |
+| `naumu_create_topic` | Create a topic; admin-only, name must be a lowercase slug |
+
+### Notes
+
+| Tool | Description |
+|------|-------------|
+| `naumu_create_note` | Create a note, optionally with its full markdown body in the same call |
+| `naumu_note_read` | Read a note's current markdown plus the nodes it is tied to |
+| `naumu_note_append` | Append markdown blocks to the end of a note |
+| `naumu_note_insert` | Insert markdown immediately after a named heading |
+| `naumu_note_replace_section` | Replace the body under a named heading |
+| `naumu_note_delete_section` | Delete a heading and its body (destructive) |
+| `naumu_note_replace` | Replace an entire note's content (destructive) |
+| `naumu_note_find_replace` | Literal find and replace within a note |
+
+### Attachments
+
+| Tool | Description |
+|------|-------------|
+| `naumu_request_attachment_upload` | Get a presigned S3 URL to upload a file, then reference it via `attachmentIds` |
+| `naumu_get_attachment` | Read a chat attachment by `attachmentId` |
+| `naumu_persist_canvas_attachment` | Promote a canvas-bound pending attachment to a persisted one |
+
+### Space admission
+
+| Tool | Description |
+|------|-------------|
+| `naumu_admission_status` | Show who can auto-join a space and who is waiting for approval |
+| `naumu_whitelist_members` | Whitelist emails so those people auto-join on sign-in |
+| `naumu_resolve_admission` | Join (or request to join) the space a repo's `.naumu` file references |
+| `naumu_resolve_join_request` | Approve or deny a pending join request |
+
+### ChatGPT compatibility
+
+The OpenAI MCP surface requires tools literally named `search` and `fetch`. These wrap cross-space search and node reads in the response shapes that client expects.
+
+| Tool | Description |
+|------|-------------|
+| `search` | Search across every accessible space; returns `{ results: [{ id, title, url }] }` |
+| `fetch` | Fetch a node returned by `search`; returns `{ id, title, text, url }` |
+
+## Troubleshooting
+
+When the stdio server is misconfigured it exits before the MCP handshake, and most clients simply show no server at all, with no error. Run the built-in self-check to find out why:
+
+```bash
+npx -y -p @naumu/mcp naumu-mcp doctor
+```
+
+It checks, in order, that `NAUMU_API_KEY` is set (the key itself is never printed), that the API is reachable and accepts the key, and that this build matches the latest published version. It prints one line per check plus a verdict, and exits non-zero if anything failed:
+
+```
+naumu-mcp doctor (v0.11.1, API https://naumu.ai)
+
+[fail] API key: NAUMU_API_KEY is missing from the environment
+[warn] API: reachable (https://naumu.ai answered HTTP 403), but there is no NAUMU_API_KEY to verify
+[ok]   Version: running 0.11.1 (npm latest)
+
+Verdict: 1 check failed - the MCP server will not work until this is fixed.
+Most likely fix: Set NAUMU_API_KEY - create a key at https://naumu.ai/settings (Settings > Your agents > Create an API key)
+```
+
+Run it with the same environment your MCP client uses, otherwise the key check reports on your shell rather than on the client's configuration.
 
 ## License
 

package/dist/index.js

@@ -30,7 +30,7 @@ function safeErrorMessage(status, upstream) {
 }
 
 // ../mcp-core/src/version.ts
-var NAUMU_MCP_VERSION = "0.11.1";
+var NAUMU_MCP_VERSION = "0.12.1";
 
 // ../mcp-core/src/client.ts
 var HEADER_VALUE_MAX_LENGTH = 100;
@@ -677,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")
@@ -1171,15 +1171,16 @@ function registerPostMessage(server2, client2) {
         idempotentHint: false,
         openWorldHint: false
       },
-      description: 'Post a message in a Naumu thread you participate in. Use it to reply to humans (or other bots) in a thread that pinged you. Write `content` in markdown (the default format): **bold**, *italic*, `inline code`, fenced code blocks, `- ` bullets, `1. ` ordered lists, and `> ` quotes all render natively; headings and tables are not supported and render as plain text. Mentions are inline pills: `@[Name](id)` mentions a person or bot and `#[label](topic-id)` tags a topic. For a human the mention id is their User id (from naumu_list_members or naumu_get_thread participantDetails) or their email - both work; for a bot/agent use its identity id; `@[Naumu](naumu-ai)` addresses the @Naumu agent (a bare `@naumu` in prose also summons it, so only type it when you mean to). @mentioning people loops them in (mention notifications, prompts) without invoking @Naumu. Set contentFormat to "tiptap" only when you need rich content beyond the markdown subset, passing a Tiptap JSON document with mention nodes (`{ type: "mention", attrs: { id, label } }`). To attach files call naumu_request_attachment_upload first, PUT the bytes to the returned uploadUrl, then pass the resulting attachmentIds here. The message needs either `content` or `attachmentIds`. Returns the created message JSON. To get a synthesised answer from @Naumu, use naumu_ask.',
+      description: 'Post a message in a Naumu thread you participate in. Use it to reply to humans (or other bots) in a thread that pinged you. Write `content` in markdown (the default format): **bold**, *italic*, `inline code`, fenced code blocks, `- ` bullets, `1. ` ordered lists, and `> ` quotes all render natively; headings and tables are not supported and render as plain text. Mentions are inline pills: `@[Name](id)` mentions a person or bot and `#[label](topic-id)` tags a topic. For a human the mention id is their User id (from naumu_list_members or naumu_get_thread participantDetails) or their email - both work; for a bot/agent use its identity id; `@[Naumu](naumu-ai)` addresses the @Naumu agent (a bare `@naumu` in prose also summons it, so only type it when you mean to). @mentioning people loops them in (mention notifications, prompts) without invoking @Naumu. Set contentFormat to "tiptap" only when you need rich content beyond the markdown subset, passing a Tiptap JSON document with mention nodes (`{ type: "mention", attrs: { id, label } }`). To attach files call naumu_request_attachment_upload first, PUT the bytes to the returned uploadUrl, then pass the resulting attachmentIds here. The message needs either `content` or `attachmentIds`. Returns the created message JSON. By default this only appends text: @Naumu is NOT summoned unless the thread auto-responds or you mention it, so nothing is committed to the graph. Pass `invokeAgent: true` when you need @Naumu to act on the message (record a work-log entry, file a status update); it summons @Naumu unconditionally, even in paused threads, and @Naumu works in the background - poll naumu_read_thread to see what it did. To get a synthesised answer from @Naumu, use naumu_ask.',
       inputSchema: z20.object({
         threadId: z20.string().describe("The thread ID to post into. You must be a participant in this thread."),
         content: z20.string().optional().describe('Message body. Markdown by default (see the tool description for the supported subset and the `@[Name](id)` mention pill syntax); a Tiptap JSON document when contentFormat is "tiptap". Optional when `attachmentIds` is provided.'),
         contentFormat: z20.enum(["tiptap", "markdown"]).optional().describe('Format of `content`. Defaults to "markdown" (rendered subset plus `@[Name](id)` / `#[label](topic-id)` mention pills). Use "tiptap" for full rich content, e.g. a doc containing `{ type: "mention", attrs: { id: userIdOrEmailOrIdentityId, label: displayName } }`.'),
-        attachmentIds: z20.array(z20.string().min(1)).max(25).optional().describe("Attachment IDs from prior `naumu_request_attachment_upload` calls. Each must be a successfully-uploaded pending attachment in this graph (1-hour TTL). Up to 25 per message.")
+        attachmentIds: z20.array(z20.string().min(1)).max(25).optional().describe("Attachment IDs from prior `naumu_request_attachment_upload` calls. Each must be a successfully-uploaded pending attachment in this graph (1-hour TTL). Up to 25 per message."),
+        invokeAgent: z20.boolean().optional().describe("Set true to summon @Naumu on this message unconditionally (mention-equivalent), even in threads where auto-response is paused. Required whenever the post must be committed to the graph (work-log entries, status updates). @Naumu processes in the background; poll naumu_read_thread. Defaults to false: plain append, no agent turn.")
       })
     },
-    async ({ threadId, content, contentFormat, attachmentIds }) => {
+    async ({ threadId, content, contentFormat, attachmentIds, invokeAgent }) => {
       try {
         const body = {
           // 'markdown' is the announced name for the API's 'text' mode;
@@ -1188,6 +1189,10 @@ function registerPostMessage(server2, client2) {
         };
         if (content !== void 0) body.content = content;
         if (attachmentIds && attachmentIds.length > 0) body.attachmentIds = attachmentIds;
+        if (invokeAgent === true) {
+          body.invokeAgent = true;
+          body.async = true;
+        }
         const data = await client2.post(`/api/threads/${threadId}/messages`, body);
         return {
           content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
@@ -1283,15 +1288,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));
@@ -1841,7 +1862,7 @@ function registerNoteRead(server2, client2) {
     {
       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.",
+      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")
       })
@@ -2345,7 +2366,8 @@ var NON_ATTRIBUTE_PROPS = /* @__PURE__ */ new Set([
   "updatedAt",
   "heatConvSignal",
   "heatConvComputedAt",
-  "heatComputedAt"
+  "heatComputedAt",
+  "context"
 ]);
 function parseResourceId(id) {
   const sep = id.indexOf(":");
@@ -2374,14 +2396,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) {
@@ -2642,11 +2692,12 @@ 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,
@@ -2715,11 +2766,204 @@ 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);
@@ -2734,7 +2978,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");

package/package.json

@@ -1,16 +1,16 @@
 {
 	"name": "@naumu/mcp",
-	"version": "0.11.1",
-	"description": "MCP server for Naumu – access your knowledge graph from Claude Code, Cursor, and other AI coding agents",
+	"version": "0.12.1",
+	"description": "MCP server for Naumu - access your knowledge graph from Claude Code, Cursor, and other AI coding agents",
 	"license": "MIT",
 	"author": "Naumu <hello@naumu.ai>",
+	"mcpName": "ai.naumu/mcp",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/naumu-app/naumu",
-		"directory": "packages/mcp"
+		"url": "https://github.com/naumu-ai/mcp"
 	},
 	"homepage": "https://naumu.ai",
-	"bugs": "https://github.com/naumu-app/naumu/issues",
+	"bugs": "https://github.com/naumu-ai/mcp/issues",
 	"keywords": [
 		"mcp",
 		"model-context-protocol",
@@ -28,7 +28,8 @@
 	"type": "module",
 	"files": [
 		"dist",
-		"README.md"
+		"README.md",
+		"server.json"
 	],
 	"engines": {
 		"node": ">=18"

package/server.json

@@ -0,0 +1,58 @@
+{
+	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+	"name": "ai.naumu/mcp",
+	"title": "Naumu",
+	"description": "Search, extend, and act on your team's Naumu knowledge graph: notes, threads, and nodes.",
+	"version": "0.12.1",
+	"websiteUrl": "https://naumu.ai",
+	"repository": {
+		"url": "https://github.com/naumu-ai/mcp",
+		"source": "github"
+	},
+	"icons": [
+		{
+			"src": "https://cdn.naumu.ai/brand/icon-256.png",
+			"mimeType": "image/png",
+			"sizes": ["256x256"]
+		}
+	],
+	"remotes": [
+		{
+			"type": "streamable-http",
+			"url": "https://naumu.ai/api/mcp"
+		}
+	],
+	"packages": [
+		{
+			"registryType": "npm",
+			"registryBaseUrl": "https://registry.npmjs.org",
+			"identifier": "@naumu/mcp",
+			"version": "0.12.1",
+			"runtimeHint": "npx",
+			"transport": { "type": "stdio" },
+			"environmentVariables": [
+				{
+					"name": "NAUMU_API_KEY",
+					"description": "Naumu API key (starts with nmu_), created in Naumu under Settings > Your agents.",
+					"isRequired": true,
+					"isSecret": true,
+					"format": "string"
+				},
+				{
+					"name": "NAUMU_API_URL",
+					"description": "Override the Naumu API base URL. Defaults to https://naumu.ai.",
+					"isRequired": false,
+					"isSecret": false,
+					"format": "string"
+				},
+				{
+					"name": "NAUMU_IDENTITY_ID",
+					"description": "Optional bot identity id to act as when the key covers several identities.",
+					"isRequired": false,
+					"isSecret": false,
+					"format": "string"
+				}
+			]
+		}
+	]
+}