@naumu/mcp 0.14.2 → 0.16.0

package/dist/index.js

@@ -41,7 +41,7 @@ function parseRetryAfterSeconds(retryAfter) {
 }
 
 // ../mcp-core/src/version.ts
-var NAUMU_MCP_VERSION = "0.14.2";
+var NAUMU_MCP_VERSION = "0.16.0";
 
 // ../mcp-core/src/client.ts
 var HEADER_VALUE_MAX_LENGTH = 100;
@@ -385,6 +385,54 @@ function registerGetSchema(server2, client2) {
 
 // ../mcp-core/src/tools/update-schema.ts
 import { z as z5 } from "zod";
+
+// ../mcp-core/src/tools/reserved-names.ts
+var RESERVED_ATTRIBUTE_NAMES = /* @__PURE__ */ new Set([
+  // RESERVED_ATTRIBUTE_KEYS
+  "id",
+  "label",
+  "type",
+  "content",
+  "embedding",
+  "visibility",
+  "source",
+  "graphid",
+  // CASED_SYSTEM_NODE_KEYS (lowercased)
+  "sortkey",
+  "createdat",
+  "updatedat",
+  "createdby",
+  "createdbyuserid",
+  "editableby",
+  "lastmodifiedat",
+  "lastmodifiedby",
+  "lastactivityat",
+  "heatscore",
+  "heatobserved",
+  "heatexpected",
+  "heatsurprise",
+  "heatcomputedat",
+  "heatconvsignal",
+  "heatconvcomputedat",
+  "__indexcolor",
+  // Canvas / force-layout scratch props
+  "x",
+  "y",
+  "vx",
+  "vy",
+  "fx",
+  "fy",
+  "index"
+]);
+function isReservedAttributeName(name) {
+  return RESERVED_ATTRIBUTE_NAMES.has(name.toLowerCase());
+}
+function reservedAttributeNameError(name, where) {
+  const scope = where ? ` (type "${where}")` : "";
+  return `Attribute name "${name}" is reserved by Naumu (system property)${scope}. Choose a different name.`;
+}
+
+// ../mcp-core/src/tools/update-schema.ts
 var ConnectionSchema = z5.object({
   relation: z5.string().describe("UPPER_SNAKE_CASE relation name (e.g. WORKS_AT, BUILT_BY, BELONGS_TO)"),
   target_node: z5.string().optional().describe("Target type name. Omit when polymorphic=true."),
@@ -396,7 +444,12 @@ var AttributeValueSchema = z5.object({
   description: z5.string().optional().describe('Short note distinguishing this value from sibling values (e.g. "closed-won - signed and revenue committed"). Encouraged when the label alone is ambiguous.')
 });
 var AttributeSchema = z5.object({
-  name: z5.string().describe('Attribute key (e.g. "stage", "status", "category")'),
+  // Reserved system property names (`source`, `type`, `createdAt`, `x`, ...)
+  // are rejected here so the agent gets a field-level error instead of a
+  // blanket 400 from the backend. See ./reserved-names.ts.
+  name: z5.string().describe('Attribute key (e.g. "stage", "status", "category")').refine((n) => !isReservedAttributeName(n), {
+    error: (iss) => reservedAttributeNameError(String(iss.input))
+  }),
   type: z5.enum(["select", "multiselect", "string", "number", "date"]).describe('Attribute type (required). select/multiselect define a closed set of categories with values; string/number/date hold free-form per-node data with values []. Calendar dates use "date", not select values.'),
   values: z5.array(AttributeValueSchema).describe("Allowed enum values for select/multiselect; pass [] for string/number/date."),
   description: z5.string().optional().describe("Short note explaining what this attribute captures and how it differs from similarly-named attributes elsewhere in the schema. Strongly encouraged.")
@@ -416,7 +469,7 @@ var NodeTypeSchema = z5.object({
   description: z5.string().optional().describe('Short one-sentence description of what this type represents AND how it differs from semantically similar types (e.g. "Type A - distinct from Type B, which is broader"). Strongly encouraged on every type. Future agents rely on this when classifying a new node into one of several similar-sounding types.')
 });
 var SchemaDefinitionSchema = z5.object({
-  description: z5.string().optional().describe("Schema-level description / domain summary."),
+  description: z5.string().optional().describe("Schema-level description / domain summary. Omit to keep the current space-wide description; send an empty string to clear it. Max 4,000 chars."),
   nodes: z5.array(NodeTypeSchema).describe("All node types in the schema.")
 });
 function registerUpdateSchema(server2, client2) {
@@ -594,6 +647,12 @@ function registerAddAttribute(server2, client2) {
       })
     },
     async ({ graphId, node_type, name, type, values, description }) => {
+      if (isReservedAttributeName(name)) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: reservedAttributeNameError(name, node_type) }, null, 2) }],
+          isError: true
+        };
+      }
       const current = await client2.get(`/api/graphs/${graphId}/schema`);
       const schema = current.definition ? JSON.parse(current.definition) : { nodes: [] };
       const node = schema.nodes.find((n) => n.type === node_type);
@@ -631,6 +690,8 @@ function registerAddAttribute(server2, client2) {
 
 // ../mcp-core/src/tools/update-schema-description.ts
 import { z as z9 } from "zod";
+var SCHEMA_DESCRIPTION_MAX_LENGTH = 4e3;
+var TARGET_DESCRIPTION_MAX_LENGTH = 300;
 function errorResult(error) {
   return {
     content: [{ type: "text", text: JSON.stringify({ error }, null, 2) }]
@@ -648,7 +709,10 @@ function registerUpdateSchemaDescription(server2, client2) {
         nodeType: z9.string().optional().describe("Existing node type whose description (or whose attribute/value description) is being rewritten. Omit to rewrite the space-wide schema description instead."),
         attribute: z9.string().optional().describe("Attribute name on that type. Omit to target the node type itself. Required when `value` is set."),
         value: z9.string().optional().describe("Label of one value of `attribute`. When set, the description is written on that value instead of the attribute."),
-        description: z9.string().trim().min(1).max(300).describe("The new description (1-300 chars). One or two sentences, contrastive against sibling types/attributes/values so an agent can decide between them.")
+        description: z9.string().trim().min(1).max(SCHEMA_DESCRIPTION_MAX_LENGTH).describe("The new description. For a type, attribute, or value: 1-300 chars, one or two sentences, contrastive against sibling types/attributes/values so an agent can decide between them. For the space-wide schema description (nodeType omitted): up to 4,000 chars of guidance that holds across every type.")
+      }).refine((data) => data.nodeType === void 0 || data.description.length <= TARGET_DESCRIPTION_MAX_LENGTH, {
+        path: ["description"],
+        message: "per-type, attribute and value descriptions are limited to 300 characters; the space-wide description to 4,000"
       })
     },
     async ({ graphId, nodeType, attribute, value, description }) => {
@@ -950,7 +1014,7 @@ Use naumu_get_schema to check valid attributes and values for this node type.`
 }
 
 // ../mcp-core/src/tools/add-node.ts
-var RESERVED_KEYS = /* @__PURE__ */ new Set(["id", "label", "type", "content"]);
+var RESERVED_KEYS = /* @__PURE__ */ new Set(["id", "label", "type", "content", "source"]);
 function normalizeNodeAttributes(schema, nodeType, attributes) {
   const attrMap = /* @__PURE__ */ new Map();
   const nodeDef = schema.nodes.find((n) => n.type === nodeType);
@@ -1232,23 +1296,27 @@ function registerDelegate(server2, client2) {
         idempotentHint: false,
         openWorldHint: true
       },
-      description: 'Hand @Naumu a task to carry out asynchronously: add knowledge, make graph-aware changes, or record a status update (e.g. "mark task X done", "log this deployment"). Returns immediately with a threadId; @Naumu works in the background and may take seconds to minutes. For status reports you can fire and forget. To read what @Naumu did, poll naumu_read_thread with the returned threadId. When you instead need an answer synchronously, use naumu_ask. File the new thread into topics by passing `topicIds` (see naumu_list_topics): omitting them keeps the default private thread, providing them makes it visible to those topics\' members from birth. This always invokes @Naumu, even in threads where auto-response is paused, so the task text must never contain a literal "@Naumu" mention (plain text never renders or triggers a mention).',
+      description: 'Hand @Naumu a task to carry out asynchronously: add knowledge, make graph-aware changes, or record a status update (e.g. "mark task X done", "log this deployment"). Returns immediately with a threadId; @Naumu works in the background and may take seconds to minutes. For status reports you can fire and forget. To read what @Naumu did, poll naumu_read_thread with the returned threadId. When you instead need an answer synchronously, use naumu_ask. A new thread is visible to the whole space by default (it lands in the space\'s #misc feed), so delegated work reads as a shared work log. File it into specific topics instead by passing `topicIds` (see naumu_list_topics), or pass `private: true` to keep it between you and @Naumu. This always invokes @Naumu, even in threads where auto-response is paused, so the task text must never contain a literal "@Naumu" mention (plain text never renders or triggers a mention).',
       inputSchema: z20.object({
         graphId: z20.string().describe("The space (graph) id to act in."),
         task: z20.string().describe("What you want @Naumu to do, add, or record."),
         threadId: z20.string().optional().describe("Continue an existing conversation; omit to start a new one."),
         topicIds: z20.array(z20.string()).max(8).optional().describe(
-          "Topic ids (from naumu_list_topics) to file a NEW thread into, making it visible to those topics' members. Only used at creation; never adds topics to an existing thread, so it is ignored when threadId is provided. Omit to keep the default private thread."
+          "Topic ids (from naumu_list_topics) to file a NEW thread into, making it visible to those topics' members. Only used at creation; never adds topics to an existing thread, so it is ignored when threadId is provided. Omit to share the thread with the whole space instead."
+        ),
+        private: z20.boolean().optional().describe(
+          "Keep a NEW thread between you and @Naumu instead of sharing it with the space. Default false. Only used at creation; ignored when threadId or topicIds are provided."
         )
       })
     },
-    async ({ graphId, task, threadId, topicIds }) => {
+    async ({ graphId, task, threadId, topicIds, private: isPrivate }) => {
       try {
         let resolvedThreadId = threadId;
         if (!resolvedThreadId) {
+          const hasTopics = Boolean(topicIds && topicIds.length > 0);
           const thread = await client2.post("/api/threads", {
             graphId,
-            ...topicIds && topicIds.length > 0 ? { topicIds } : {}
+            ...hasTopics ? { topicIds } : { sharedWithSpace: !isPrivate }
           });
           resolvedThreadId = thread.id;
         }
@@ -1380,7 +1448,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, or oldest-first when you pass `after`; 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, or `after` (timestamp ms) to catch up on what arrived since you last looked. To wait for the next message instead of re-reading on a timer, use naumu_wait_for_activity. Default page size 50, max 200. Agent messages carry `memoryScope.line`, a one-line statement of which Memory scope the answer used; surface it under the answer. To read or download a message attachment, pass its `attachments[].id` to naumu_get_attachment.',
+      description: 'Read messages from a Naumu thread. Returns paginated history ordered newest-first, or oldest-first when you pass `after`; 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, or `after` (timestamp ms) to catch up on what arrived since you last looked. To wait for the next message instead of re-reading on a timer, use naumu_wait_for_activity. Default page size 50, max 200. Agent messages carry `memoryScope.line`, a one-line statement of which Memory scope the answer used; surface it under the answer. Audio attachments are transcribed by Naumu at post time: read `attachments[].transcription` (plus `transcriptionSummary` and `transcriptionStatus`) straight from the message instead of downloading and transcribing the file. To read or download any other attachment, pass its `attachments[].id` to naumu_get_attachment.',
       inputSchema: z23.object({
         threadId: z23.string().describe("The thread ID to read from."),
         before: z23.number().optional().describe("Unix timestamp in milliseconds. Returns messages strictly older than this. Omit for the newest page."),
@@ -1915,7 +1983,7 @@ function registerGetAttachment(server2, client2) {
     {
       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.",
+      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\nAudio attachments do not need this tool for their contents: Naumu transcribes them at post time and naumu_read_thread returns the text as `attachments[].transcription` on the message - use that instead of downloading and transcribing the file.\n\nAccess is checked the same way it is for a person: you only resolve attachments in threads you can already read.",
       inputSchema: z33.object({
         attachmentId: z33.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.")
       })

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@naumu/mcp",
-	"version": "0.14.2",
+	"version": "0.16.0",
 	"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>",

package/server.json

@@ -3,7 +3,7 @@
 	"name": "ai.naumu/mcp",
 	"title": "Naumu",
 	"description": "Search, extend, and act on your team's Naumu knowledge graph: notes, threads, and nodes.",
-	"version": "0.14.2",
+	"version": "0.16.0",
 	"websiteUrl": "https://naumu.ai",
 	"repository": {
 		"url": "https://github.com/naumu-ai/mcp",
@@ -27,7 +27,7 @@
 			"registryType": "npm",
 			"registryBaseUrl": "https://registry.npmjs.org",
 			"identifier": "@naumu/mcp",
-			"version": "0.14.2",
+			"version": "0.16.0",
 			"runtimeHint": "npx",
 			"transport": { "type": "stdio" },
 			"environmentVariables": [