@naumu/mcp 0.6.3 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +3 -2
  2. package/dist/index.js +418 -673
  3. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -118,6 +118,8 @@ var NaumuClient = class {
118
118
  // ../mcp-core/src/instructions.ts
119
119
  var NAUMU_INSTRUCTIONS = `The Naumu MCP server gives structured access to Naumu knowledge graphs (also called spaces). Prefer these tools over WebFetch whenever the user mentions a naumu.ai URL \u2014 Naumu pages are client-rendered React, so WebFetch returns an empty shell with no data.
120
120
 
121
+ Getting information about a space: use naumu_ask. It puts your question to the @Naumu agent (which has full read access and inspects the graph for you) and returns a synthesised, node-grounded answer with the exact source node ids and a confidence hint, in a single call. It is the authoritative answer for what is in a space, what is new or recently changed, how something works, or any summary - present it and its sources directly. Do NOT then re-read the graph yourself with naumu_get_schema, naumu_filter, naumu_get_node or fetch to verify or sanity-check the answer: that repeats work naumu_ask already did and is dramatically slower (it can turn a 40-second answer into minutes). Trust the answer and its cited sources. Reach for a granular read only to fetch one specific node the answer pointed to, or for a need naumu_ask genuinely cannot serve (naumu_search to locate nodes by meaning, naumu_list_threads + naumu_read_thread for conversation history). Recording the question and answer as a visible conversation in the space is expected and useful, so do not avoid naumu_ask to prevent creating a thread. To hand @Naumu work to carry out in the background (add knowledge, make changes, record a status update), use naumu_delegate.
122
+
121
123
  IMPORTANT: graphId is a UUID (e.g. "0464cbfa-60ca-41b3-ac8f-bbeb8243a193"). The value in the URL right after /spaces/ is a slug (e.g. "naumu-0464cbfa"), NOT the graphId. You must resolve the slug to a graphId first.
122
124
 
123
125
  How to resolve a slug \u2192 graphId:
@@ -125,20 +127,9 @@ Call naumu_list_graphs and find the graph whose 'slug' field matches the URL seg
125
127
 
126
128
  URL \u2192 tool mapping (the value after /spaces/ is the slug \u2014 resolve it first):
127
129
  - naumu.ai/spaces/{slug} \u2192 naumu_list_graphs (resolve), then naumu_get_schema for an overview
128
- - naumu.ai/spaces/{slug}/views/{viewId} \u2192 naumu_list_graphs (resolve), then naumu_get_view, then naumu_list_view_nodes
129
130
  - naumu.ai/spaces/{slug}/nodes/{nodeId} \u2192 naumu_list_graphs (resolve), then naumu_get_node
130
- - naumu.ai/spaces/{slug}/chat/{threadId} \u2192 naumu_list_graphs (resolve), then naumu_get_ai_thread
131
- - Other panel URLs (notes, canvases, conversations, members, settings, schema, heat, health, changelog) have no dedicated tool \u2014 fall back to naumu_get_node with the relevant id, or naumu_get_schema for the space-level question.
132
-
133
- Recommended workflow when a user pastes a view URL:
134
- 1. naumu_list_graphs \u2014 find the graph whose slug matches the URL. Note its 'id' (the UUID) as graphId.
135
- 2. naumu_get_view {graphId, viewId} \u2014 read the returned 'summary' and 'filters' to understand what the view returns. This is cheap.
136
- 3. naumu_list_view_nodes {graphId, viewId} \u2014 page through results.
137
- - fields:"summary" (default) for {id, label, type} per node \u2014 best for browsing.
138
- - fields:"id" for {id} only \u2014 best when you just need to count or iterate.
139
- - fields:"full" for the complete node payload \u2014 only when you need every attribute.
140
- - The response always includes totalCount, so you don't need to page through everything to get a count.
141
- 4. naumu_get_node {graphId, nodeId} for per-node detail when needed.
131
+ - naumu.ai/spaces/{slug}/chat/{threadId} \u2192 naumu_list_graphs (resolve), then naumu_read_thread
132
+ - Other panel URLs (notes, canvases, views, conversations, members, settings, schema, heat, health, changelog) have no dedicated tool \u2014 fall back to naumu_get_node with the relevant id, or naumu_get_schema for the space-level question.
142
133
 
143
134
  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.`;
144
135
 
@@ -149,7 +140,7 @@ function registerListGraphs(server2, client2) {
149
140
  "naumu_list_graphs",
150
141
  {
151
142
  title: "List Graphs",
152
- annotations: { readOnlyHint: true },
143
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
153
144
  description: "List all knowledge graphs (spaces) the authenticated user has access to. Returns graph IDs, names, and roles.",
154
145
  inputSchema: z.object({})
155
146
  },
@@ -169,8 +160,8 @@ function registerCreateGraph(server2, client2) {
169
160
  "naumu_create_graph",
170
161
  {
171
162
  title: "Create Graph",
172
- annotations: { destructiveHint: true },
173
- description: "Create a new knowledge graph (space) owned by the authenticated user. Returns `{id, name, slug, role, memberRole, createdAt, onboardingThreadId}` \u2014 use the returned `id` as `graphId` for subsequent tool calls. The space starts empty (no schema, no nodes); follow up with `naumu_update_schema` to register types before any `naumu_add_node` calls.",
163
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
164
+ description: "Create a new, empty knowledge graph (space) owned by the authenticated user; use when you need a fresh space to populate. Returns `{id, name, slug, role, memberRole, createdAt, onboardingThreadId}` - use the returned `id` as `graphId` for subsequent tool calls. The space starts empty (no schema, no nodes); follow up with `naumu_update_schema` to register types before any `naumu_add_node` calls.",
174
165
  inputSchema: z2.object({
175
166
  name: z2.string().min(1).describe("Display name for the new space. A URL slug is generated from this name.")
176
167
  })
@@ -186,36 +177,41 @@ function registerCreateGraph(server2, client2) {
186
177
 
187
178
  // ../mcp-core/src/tools/get-schema.ts
188
179
  import { z as z3 } from "zod";
180
+ function formatConnection(c) {
181
+ const out = { relation: c.relation };
182
+ if (c.polymorphic) {
183
+ out.polymorphic = true;
184
+ } else if (c.target_node) {
185
+ out.target_node = c.target_node;
186
+ }
187
+ return out;
188
+ }
189
189
  function formatSchema(schema) {
190
190
  return {
191
191
  description: schema.description ?? null,
192
192
  types: schema.nodes.map((node) => {
193
193
  const result = { type: node.type };
194
194
  if (node.description) result.description = node.description;
195
+ const connections = {
196
+ required: (node.connections.required ?? []).map(formatConnection),
197
+ suggested: (node.connections.suggested ?? []).map(formatConnection)
198
+ };
195
199
  if (node.connections.parent) {
196
- result.parent = `${node.connections.parent.relation} \u2192 ${node.connections.parent.target_node}`;
200
+ connections.parent = formatConnection(node.connections.parent);
197
201
  }
198
- const connections = [
199
- ...node.connections.required.map((c) => `${c.relation} \u2192 ${c.target_node} (required)`),
200
- ...node.connections.suggested.map((c) => `${c.relation} \u2192 ${c.target_node}`)
201
- ];
202
- if (connections.length > 0) result.connections = connections;
202
+ result.connections = connections;
203
203
  if (node.attributes && node.attributes.length > 0) {
204
- result.attributes = Object.fromEntries(
205
- node.attributes.map((a) => {
206
- const values = (a.values ?? []).map(
207
- (v) => v.description ? { label: v.label, description: v.description } : v.label
208
- );
209
- const attrDetail = { values };
210
- if (a.description) attrDetail.description = a.description;
211
- const hasDesc = !!a.description;
212
- const hasValueDescs = values.some((v) => typeof v !== "string");
213
- if (!hasDesc && !hasValueDescs) {
214
- return [a.name, (a.values ?? []).map((v) => v.label)];
215
- }
216
- return [a.name, attrDetail];
217
- })
218
- );
204
+ result.attributes = node.attributes.map((a) => {
205
+ const values = (a.values ?? []).map((v) => {
206
+ const value = { label: v.label };
207
+ if (v.color) value.color = v.color;
208
+ if (v.description) value.description = v.description;
209
+ return value;
210
+ });
211
+ const attr = { name: a.name, type: a.type ?? "select", values };
212
+ if (a.description) attr.description = a.description;
213
+ return attr;
214
+ });
219
215
  }
220
216
  return result;
221
217
  })
@@ -226,8 +222,8 @@ function registerGetSchema(server2, client2) {
226
222
  "naumu_get_schema",
227
223
  {
228
224
  title: "Get Graph Schema",
229
- annotations: { readOnlyHint: true },
230
- description: "Get the schema definition for a knowledge graph. Returns node types, their allowed attributes (with valid values), allowed relationships, and any descriptions authored on types/attributes/values. Call this before classifying a new node into a type, before picking an attribute value, or before extending the schema \u2014 descriptions are short, contrastive notes from the schema author explaining what each type/attribute/value is for and how it differs from similar-sounding ones.",
225
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
226
+ description: "Get the schema definition for a knowledge graph; call this before classifying a new node into a type, before picking an attribute value, or before extending the schema. Returns a ROUND-TRIPPABLE structural schema: each `types[]` entry has the SAME shape `naumu_update_schema` ingests (type, description, structured `connections: { parent?, required, suggested }` with parent NESTED - not a string, and structured attributes), so you can copy a type straight back into naumu_update_schema without losing data (notably the parent relation). Descriptions are short, contrastive notes from the schema author explaining what each type/attribute/value is for and how it differs from similar-sounding ones.",
231
227
  inputSchema: z3.object({
232
228
  graphId: z3.string().describe("The graph ID")
233
229
  })
@@ -260,16 +256,16 @@ var ConnectionSchema = z4.object({
260
256
  var AttributeValueSchema = z4.object({
261
257
  label: z4.string().describe("Display label for this enum value"),
262
258
  color: z4.string().optional().describe('Optional hex color (e.g. "#ff5722")'),
263
- description: z4.string().optional().describe('Short note distinguishing this value from sibling values (e.g. "closed-won \u2014 deal signed and revenue committed"). Encouraged when the label alone is ambiguous.')
259
+ description: z4.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.')
264
260
  });
265
261
  var AttributeSchema = z4.object({
266
262
  name: z4.string().describe('Attribute key (e.g. "stage", "status", "category")'),
267
- type: z4.enum(["select", "multiselect", "string", "number", "date"]).optional().describe("Attribute type. Defaults to select if omitted."),
263
+ type: z4.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.'),
268
264
  values: z4.array(AttributeValueSchema).describe("Allowed enum values for select/multiselect; pass [] for string/number/date."),
269
265
  description: z4.string().optional().describe("Short note explaining what this attribute captures and how it differs from similarly-named attributes elsewhere in the schema. Strongly encouraged.")
270
266
  });
271
267
  var NodeTypeSchema = z4.object({
272
- type: z4.string().describe("Type name in PascalCase (e.g. Company, Person, Feature, Document)"),
268
+ type: z4.string().describe("Type name in PascalCase (e.g. TypeA, TypeB)"),
273
269
  connections: z4.object({
274
270
  parent: ConnectionSchema.optional().describe("Optional parent relation (this type nests under another via this connection)."),
275
271
  required: z4.array(ConnectionSchema).default([]).describe("Required outgoing connections to other types."),
@@ -277,10 +273,10 @@ var NodeTypeSchema = z4.object({
277
273
  }),
278
274
  attributes: z4.array(AttributeSchema).optional().describe("Type-level attributes for instances of this type."),
279
275
  defaultVisibility: z4.enum(["restricted", "internal", "open"]).optional().describe(
280
- 'Default visibility for NEW nodes of this type when no explicit visibility is passed on creation. Does NOT retroactively change visibility on existing nodes. "open" = visible to anyone with the space link (including non-members), "internal" = visible to all space members, "restricted" = only members explicitly granted access. Omit to leave the type unset \u2014 it then falls back to the space-level defaultVisibility.'
276
+ 'Default visibility for NEW nodes of this type when no explicit visibility is passed on creation. Does NOT retroactively change visibility on existing nodes. "open" = visible to anyone with the space link (including non-members), "internal" = visible to all space members, "restricted" = only members explicitly granted access. Omit to leave the type unset - it then falls back to the space-level defaultVisibility.'
281
277
  ),
282
278
  color: z4.string().optional().describe("Optional hex color for instances of this type."),
283
- description: z4.string().optional().describe('Short one-sentence description of what this type represents AND how it differs from semantically similar types (e.g. "External entity delivering services on contract \u2014 distinct from Organization which is any legal entity"). Strongly encouraged on every type. Future agents rely on this when classifying a new node into one of several similar-sounding types.')
279
+ description: z4.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.')
284
280
  });
285
281
  var SchemaDefinitionSchema = z4.object({
286
282
  description: z4.string().optional().describe("Schema-level description / domain summary."),
@@ -291,8 +287,8 @@ function registerUpdateSchema(server2, client2) {
291
287
  "naumu_update_schema",
292
288
  {
293
289
  title: "Update Graph Schema",
294
- annotations: { destructiveHint: true },
295
- description: "Replace the graph schema with a new full definition. STRUCTURAL RULES (load-bearing): (1) HIERARCHICAL with a single root \u2014 exactly ONE type has no parent; every other type MUST declare a parent. (2) Each parent / required / suggested connection is XOR: ONE concrete target_node OR polymorphic=true \u2014 never both, never a list of multiple targets. (3) DEFAULT TO CONCRETE target_node. Polymorphic is the ESCAPE HATCH \u2014 reserve for genuinely cross-cutting concepts like Comment or Tag (entities that validly attach to many distinct types). If you find yourself making most parents polymorphic, you are avoiding the design work \u2014 pick concrete relationships instead. If you can't pick a concrete parent, you may be missing a type \u2014 add the missing type first. (4) Same-type nesting is implicit: a node can be placed under another of its same type using the existing parent relation \u2014 never add a self-relation just to enable nesting. (5) Always provide `description` on every node type, attribute, and select value \u2014 one short, contrastive sentence (what it IS and what it is NOT vs sibling types/attrs/values). This is the single strongest disambiguation signal for future agents classifying nodes. Use to bootstrap an empty graph (cold-start) or fully replace mid-build (call naumu_get_schema first, send the FULL new schema \u2014 anything you omit is removed). Conventions: type names PascalCase (Company, Person, Feature), relation names UPPER_SNAKE_CASE (WORKS_AT, BELONGS_TO). Bias toward general types \u2014 refine via attributes or nested children, not type proliferation.",
290
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
291
+ description: "Replace the graph schema with a new full definition; use to bootstrap an empty graph (cold-start) or fully replace mid-build. STRUCTURAL RULES (load-bearing): (1) HIERARCHICAL with a single root - exactly ONE type has no parent; every other type MUST declare a parent. (2) Each parent / required / suggested connection is XOR: ONE concrete target_node OR polymorphic=true - never both, never a list of multiple targets. (3) DEFAULT TO CONCRETE target_node. Polymorphic is the ESCAPE HATCH - reserve for genuinely cross-cutting concepts like Comment or Tag (entities that validly attach to many distinct types). If you find yourself making most parents polymorphic, you are avoiding the design work - pick concrete relationships instead. If you can't pick a concrete parent, you may be missing a type - add the missing type first. (4) Same-type nesting is implicit: a node can be placed under another of its same type using the existing parent relation - never add a self-relation just to enable nesting. (5) Always provide `description` on every node type, attribute, and select value - one short, contrastive sentence (what it IS and what it is NOT vs sibling types/attrs/values). This is the single strongest disambiguation signal for future agents classifying nodes. When replacing mid-build, call naumu_get_schema first (it returns a round-trippable structural schema you can copy back) and send the FULL new schema; anything you omit is removed. PARENT PRESERVATION: omitting a type's `connections.parent` PRESERVES its existing parent (so a round-trip never silently orphans a type). To intentionally remove a parent and make a type a root, send `parent: null` explicitly. (A parent whose target type you delete is dropped automatically.) Conventions: type names PascalCase, relation names UPPER_SNAKE_CASE. Bias toward general types - refine via attributes or nested children, not type proliferation.",
296
292
  inputSchema: z4.object({
297
293
  graphId: z4.string().describe("The graph ID"),
298
294
  schema: SchemaDefinitionSchema
@@ -319,28 +315,28 @@ var ConnectionSchema2 = z5.object({
319
315
  var AttributeValueSchema2 = z5.object({
320
316
  label: z5.string(),
321
317
  color: z5.string().optional(),
322
- description: z5.string().optional().describe('Short note distinguishing this value from sibling values (e.g. for status="closed-won", "Deal signed and revenue committed"). Encouraged when the label alone is ambiguous.')
318
+ description: z5.string().optional().describe('Short note distinguishing this value from sibling values (e.g. for status="closed-won", "signed and revenue committed"). Encouraged when the label alone is ambiguous.')
323
319
  });
324
320
  var AttributeSchema2 = z5.object({
325
321
  name: z5.string(),
326
- type: z5.enum(["select", "multiselect", "string", "number", "date"]).optional(),
322
+ 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.'),
327
323
  values: z5.array(AttributeValueSchema2).default([]),
328
- description: z5.string().optional().describe('Short note explaining what this attribute captures and how it differs from similarly-named attributes on other types (e.g. "stage on Feature" vs "stage on Deal"). Strongly encouraged.')
324
+ description: z5.string().optional().describe('Short note explaining what this attribute captures and how it differs from similarly-named attributes on other types (e.g. "stage on Type A" vs "stage on Type B"). Strongly encouraged.')
329
325
  });
330
326
  function registerAddNodeType(server2, client2) {
331
327
  server2.registerTool(
332
328
  "naumu_add_node_type",
333
329
  {
334
330
  title: "Add Node Type to Schema",
335
- annotations: { destructiveHint: true },
336
- description: 'Add one new node type to the schema. Cheaper than naumu_update_schema. STRUCTURAL RULES: (1) Schemas are hierarchical with a single root. If schema is empty, the first type IS the root \u2014 omit `parent`. Every subsequent type MUST set `parent`. (2) DEFAULT TO CONCRETE \u2014 pass {relation, target_node: <existing type>}. Polymorphic is the ESCAPE HATCH \u2014 use {relation, polymorphic: true} ONLY for genuinely cross-cutting concepts like Comment or Tag (types that validly attach to many distinct parents). If you can\'t pick a concrete parent, you may be missing a type \u2014 add the missing type first instead of falling back to polymorphic. (3) Required/suggested connections also each take ONE concrete target_node OR polymorphic \u2014 never a list. Default concrete there too. (4) Type name PascalCase (Company, Person, Feature). Relation names UPPER_SNAKE_CASE (BELONGS_TO, WORKS_AT). (5) ALWAYS provide `description` \u2014 one short sentence that says what this type is AND what it is NOT relative to semantically close types (e.g. "External entity that delivers services on contract; distinct from Organization which is any legal entity"). This is the single strongest signal future agents have when classifying a node into one of several similar-sounding types. Returns an error if the type already exists \u2014 use naumu_add_attribute / naumu_add_connection to extend it.',
331
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
332
+ description: 'Add one new node type to the schema; use to extend an existing schema without resending the whole thing (cheaper than naumu_update_schema). STRUCTURAL RULES: (1) Schemas are hierarchical with a single root. If schema is empty, the first type IS the root - omit `parent`. Every subsequent type MUST set `parent`. (2) DEFAULT TO CONCRETE - pass {relation, target_node: <existing type>}. Polymorphic is the ESCAPE HATCH - use {relation, polymorphic: true} ONLY for genuinely cross-cutting concepts like Comment or Tag (types that validly attach to many distinct parents). If you can\'t pick a concrete parent, you may be missing a type - add the missing type first instead of falling back to polymorphic. (3) Required/suggested connections also each take ONE concrete target_node OR polymorphic - never a list. Default concrete there too. (4) Type name PascalCase. Relation names UPPER_SNAKE_CASE. (5) ALWAYS provide `description` - one short sentence that says what this type is AND what it is NOT relative to semantically close types (e.g. "Type A \u2014 distinct from Type B, which is broader"). This is the single strongest signal future agents have when classifying a node into one of several similar-sounding types. Returns an error if the type already exists - use naumu_add_attribute / naumu_add_connection to extend it.',
337
333
  inputSchema: z5.object({
338
334
  graphId: z5.string(),
339
335
  type: z5.string().describe("PascalCase type name"),
340
336
  description: z5.string().optional().describe(
341
- "Short one-sentence description of what this type represents and how it differs from sibling types. Contrastive (say what it IS and what it is NOT) is most useful. Strongly encouraged on every new type \u2014 agents reading the schema later rely on this to classify nodes."
337
+ "Short one-sentence description of what this type represents and how it differs from sibling types. Contrastive (say what it IS and what it is NOT) is most useful. Strongly encouraged on every new type - agents reading the schema later rely on this to classify nodes."
342
338
  ),
343
- parent: ConnectionSchema2.optional().describe("Optional parent connection \u2014 sets this type as a child of another type."),
339
+ parent: ConnectionSchema2.optional().describe("Optional parent connection - sets this type as a child of another type."),
344
340
  required: z5.array(ConnectionSchema2).optional(),
345
341
  suggested: z5.array(ConnectionSchema2).optional(),
346
342
  attributes: z5.array(AttributeSchema2).optional(),
@@ -386,8 +382,8 @@ function registerAddConnection(server2, client2) {
386
382
  "naumu_add_connection",
387
383
  {
388
384
  title: "Add Connection to Node Type",
389
- annotations: { destructiveHint: true },
390
- description: 'Add one connection from an existing node type to another. `kind`: "parent" (sets/replaces \u2014 every non-root type needs exactly one parent; only ONE type in the whole schema has no parent), "required" (must exist on instances), "suggested" (optional). Each connection is XOR: ONE concrete target_node OR polymorphic=true \u2014 never both. DEFAULT TO CONCRETE target_node. Polymorphic is the ESCAPE HATCH \u2014 reserve for genuinely cross-cutting relations (e.g. a Tag-style relation that validly applies to many distinct types). If you can\'t pick a concrete target, you may be missing a type \u2014 add it first instead of falling back to polymorphic. Same-type nesting (e.g. Topic under Topic) does NOT need a new connection \u2014 use the existing parent relation. Relation name UPPER_SNAKE_CASE.',
385
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
386
+ description: 'Add one connection from an existing node type to another; use to extend a type\'s relations without resending the whole schema. `kind`: "parent" (sets/replaces - every non-root type needs exactly one parent; only ONE type in the whole schema has no parent), "required" (must exist on instances), "suggested" (optional). Each connection is XOR: ONE concrete target_node OR polymorphic=true - never both. DEFAULT TO CONCRETE target_node. Polymorphic is the ESCAPE HATCH - reserve for genuinely cross-cutting relations (e.g. a Tag-style relation that validly applies to many distinct types). If you can\'t pick a concrete target, you may be missing a type - add it first instead of falling back to polymorphic. Same-type nesting (e.g. Type A under Type A) does NOT need a new connection - use the existing parent relation. Relation name UPPER_SNAKE_CASE.',
391
387
  inputSchema: z6.object({
392
388
  graphId: z6.string(),
393
389
  source_type: z6.string().describe("Existing node type to add the connection to."),
@@ -436,18 +432,18 @@ function registerAddAttribute(server2, client2) {
436
432
  "naumu_add_attribute",
437
433
  {
438
434
  title: "Add Attribute to Node Type",
439
- annotations: { destructiveHint: true },
440
- description: 'Add or extend an attribute on an existing node type. If the attribute name doesn\'t exist, it is created. If it exists and is a select/multiselect, new values are merged in (existing values kept). Use type "select"/"multiselect" with values; "string"/"number"/"date" for free-form fields (pass values: [] \u2014 string/number/date have no enum values). Example date attribute: { name: "due_date", type: "date", values: [], description: "Target completion date (single day or range)" }. Date values on nodes are written via naumu_update_node as either an ISO date string "YYYY-MM-DD" (single day) or an object { start, end? } with ISO date strings (inclusive range). Strongly encouraged to provide `description` on the attribute and on each value \u2014 short, contrastive notes (e.g. attribute "stage \u2014 sales funnel position; distinct from status which captures health/blockers", value "closed-won \u2014 deal signed and revenue committed"). Descriptions are the single strongest signal future agents use when picking which attribute/value to set.',
435
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
436
+ description: 'Add or extend an attribute on an existing node type; use to add a field or merge new enum values into an existing one. If the attribute name doesn\'t exist, it is created. If it exists and is a select/multiselect, new values are merged in (existing values kept). Date values on nodes are written via naumu_update_node as either an ISO date string "YYYY-MM-DD" (single day) or an object { start, end? } with ISO date strings (inclusive range). Strongly encouraged to provide `description` on the attribute and on each value - short, contrastive notes (e.g. attribute "stage - sales funnel position; distinct from status which captures health/blockers", value "closed-won - deal signed and revenue committed"). Descriptions are the single strongest signal future agents use when picking which attribute/value to set.',
441
437
  inputSchema: z7.object({
442
438
  graphId: z7.string(),
443
439
  node_type: z7.string().describe("Existing node type to add the attribute to."),
444
440
  name: z7.string().describe('Attribute key (e.g. "stage", "status").'),
445
- type: z7.enum(["select", "multiselect", "string", "number", "date"]).default("select"),
441
+ type: z7.enum(["select", "multiselect", "string", "number", "date"]).describe('Attribute type (required). select/multiselect define a closed set of categories - provide their values. string/number/date hold free-form per-node data - pass values: []. A specific calendar date is per-node data, so use type "date" and write the date on the node, rather than adding the date as a select value.'),
446
442
  values: z7.array(
447
443
  z7.object({
448
444
  label: z7.string(),
449
445
  color: z7.string().optional(),
450
- description: z7.string().optional().describe('Short note distinguishing this value from sibling values (e.g. "closed-won \u2014 deal signed and revenue committed"). Encouraged when the label alone is ambiguous.')
446
+ description: z7.string().optional().describe('Short note distinguishing this value from sibling values (e.g. "closed-won - deal signed and revenue committed"). Encouraged when the label alone is ambiguous.')
451
447
  })
452
448
  ).default([]),
453
449
  description: z7.string().optional().describe('Short note explaining what this attribute captures and how it differs from similarly-named attributes elsewhere in the schema (e.g. "Sales funnel position; differs from `status` which captures health/blockers"). Strongly encouraged.')
@@ -490,15 +486,15 @@ function registerSearch(server2, client2) {
490
486
  "naumu_search",
491
487
  {
492
488
  title: "Search Graph",
493
- annotations: { readOnlyHint: true },
494
- description: 'Hybrid search over graph nodes. Combines exact-token text matching (good for UUIDs, proper nouns, specific labels) with semantic similarity (good for paraphrase and meaning), then fuses both rankings with Reciprocal Rank Fusion. Returns the top matches with a `matchedVia` tag \u2014 `both` is the highest-confidence signal, then `semantic`, then `text`. Use `naumu_filter` for structured queries by type and attributes (e.g. "all in-progress Tasks"). Tip: include both synonyms ("authentication login SSO") and exact tokens you remember in the same query \u2014 the fusion handles both.',
489
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
490
+ description: 'Hybrid search over graph nodes; use for meaning-based lookup when you don\'t know the exact label. Combines exact-token text matching (good for UUIDs, proper nouns, specific labels) with semantic similarity (good for paraphrase and meaning), then fuses both rankings with Reciprocal Rank Fusion. Returns the top matches with a `matchedVia` tag - `both` is the highest-confidence signal, then `semantic`, then `text`. Use `naumu_filter` for structured queries by type and attributes (e.g. "all in-progress Tasks"). Tip: include both synonyms ("authentication login SSO") and exact tokens you remember in the same query - the fusion handles both.',
495
491
  inputSchema: z8.object({
496
492
  graphId: z8.string().describe("The graph ID"),
497
493
  query: z8.string().describe(
498
494
  'Search query text. Mix synonyms and exact tokens freely (e.g. "auth login SSO 2fa Twitter handle").'
499
495
  ),
500
496
  limit: z8.number().optional().default(20).describe("Max results to return (default 20, max 200). Adaptive cutoff may return fewer when the top match is weak."),
501
- nodeTypes: z8.array(z8.string()).optional().describe('Filter to specific node types (e.g. ["Feature", "Pain"])')
497
+ nodeTypes: z8.array(z8.string()).optional().describe('Filter to specific node types (e.g. ["Type A", "Type B"])')
502
498
  })
503
499
  },
504
500
  async ({ graphId, query, limit, nodeTypes }) => {
@@ -521,15 +517,15 @@ function registerFilter(server2, client2) {
521
517
  "naumu_filter",
522
518
  {
523
519
  title: "Filter Graph Nodes",
524
- annotations: { readOnlyHint: true },
525
- description: 'Filter nodes by type and attributes with deterministic, complete results. Use this for structured queries like "all in-progress Tasks" or "Bugs not yet resolved." Unlike search tools, this returns every matching node (up to the limit) \u2014 no semantic ranking, no missed results. Results are sorted by sortKey or recency.',
520
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
521
+ description: 'Filter nodes by type and attributes with deterministic, complete results; use for structured queries like "all in-progress Tasks" or "Bugs not yet resolved." Unlike search tools, this returns every matching node (up to the limit) - no semantic ranking, no missed results. Results are sorted by sortKey or recency.',
526
522
  inputSchema: z9.object({
527
523
  graphId: z9.string().describe("The graph ID"),
528
- nodeTypes: z9.array(z9.string()).optional().describe('Filter to specific node types (e.g. ["Task", "Bug"])'),
529
- includeAttributes: z9.record(z9.array(z9.string())).optional().describe(
524
+ nodeTypes: z9.array(z9.string()).optional().describe('Filter to specific node types (e.g. ["Type A", "Type B"])'),
525
+ includeAttributes: z9.record(z9.string(), z9.array(z9.string())).optional().describe(
530
526
  'Only include nodes where attribute matches one of the values. Example: {"Status": ["Todo", "In Progress"]}'
531
527
  ),
532
- excludeAttributes: z9.record(z9.array(z9.string())).optional().describe(
528
+ excludeAttributes: z9.record(z9.string(), z9.array(z9.string())).optional().describe(
533
529
  'Exclude nodes where attribute matches any of the values. Example: {"Status": ["Done", "Wont do"]}'
534
530
  ),
535
531
  sortBy: z9.enum(["sortKey", "updatedAt", "label"]).optional().default("sortKey").describe('Sort order: "sortKey" (default), "updatedAt" (most recent first), or "label" (alphabetical)'),
@@ -564,7 +560,7 @@ function registerGetNode(server2, client2) {
564
560
  "naumu_get_node",
565
561
  {
566
562
  title: "Get Node",
567
- annotations: { readOnlyHint: true },
563
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
568
564
  description: "Get a single node with all its properties and connections (incoming and outgoing edges).",
569
565
  inputSchema: z10.object({
570
566
  graphId: z10.string().describe("The graph ID"),
@@ -584,8 +580,8 @@ function registerGetNode(server2, client2) {
584
580
  import { z as z11 } from "zod";
585
581
  var NodeInput = z11.object({
586
582
  label: z11.string().describe("Display name of the node"),
587
- type: z11.string().describe("Node type from the graph schema (e.g. Feature, Pain, Metric)"),
588
- content: z11.string().min(1).describe("Rich text content / description. REQUIRED \u2014 every node must explain what it is."),
583
+ type: z11.string().describe("Node type from the graph schema"),
584
+ content: z11.string().min(1).describe("Rich text content / description. REQUIRED - every node must explain what it is."),
589
585
  attributes: z11.record(z11.string(), z11.unknown()).optional().describe("Additional key-value attributes")
590
586
  });
591
587
  function registerAddNode(server2, client2) {
@@ -593,8 +589,8 @@ function registerAddNode(server2, client2) {
593
589
  "naumu_add_node",
594
590
  {
595
591
  title: "Add Nodes (bulk)",
596
- annotations: { destructiveHint: true },
597
- description: 'Create 1\u201325 nodes in the knowledge graph in a single call. Keep batches small and atomic (5\u201325 nodes) so failures stay contained. Each node MUST include a non-empty `content` describing what it is. Returns one entry per input node with `{id, label, type, status: "created"}` \u2014 there is NO server-side dedup, every input becomes a node. Dedup is the caller\'s responsibility: BEFORE calling this tool, run `naumu_semantic_search` on each candidate label and skip/route to update if a result has high similarity (\u22650.78) and matching type. Warning: nodes are isolated until you connect them with `naumu_add_edge`. **Prefer `naumu_ask`** for general knowledge intake \u2014 it discovers and creates connections for you. Use this when you have a vetted, dedup-checked batch ready to insert.',
592
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
593
+ description: 'Create 1-25 nodes in the knowledge graph in a single call; use when you have a vetted, dedup-checked batch ready to insert. Keep batches small and atomic (5-25 nodes) so failures stay contained. Each node MUST include a non-empty `content` describing what it is. Returns one entry per input node with `{id, label, type, status: "created"}` - there is NO server-side dedup, every input becomes a node. Dedup is the caller\'s responsibility: BEFORE calling this tool, run `naumu_search` on each candidate label and skip/route to update if a result has high similarity (\u22650.78) and matching type. Warning: nodes are isolated until you connect them with `naumu_add_edge`. Prefer `naumu_delegate` for general knowledge intake - it discovers and creates connections for you.',
598
594
  inputSchema: z11.object({
599
595
  graphId: z11.string().describe("The graph ID"),
600
596
  nodes: z11.array(NodeInput).min(1).max(25).describe("Batch of 1\u201325 nodes to create. Keep batches small for atomicity.")
@@ -670,8 +666,8 @@ function registerUpdateNode(server2, client2) {
670
666
  "naumu_update_node",
671
667
  {
672
668
  title: "Update Node",
673
- annotations: { destructiveHint: true },
674
- description: 'Update properties of an existing node. Only the provided fields will be changed. Good for simple attribute changes like setting a status, priority, or due date. For content or structural changes, consider `naumu_ask` instead \u2014 it understands the full graph context and can propagate updates to related nodes. Attribute keys AND values must match the schema for the node type. Use naumu_get_schema to check valid attribute names, types, and values before updating. Date attributes accept either null (to clear), an ISO date string "YYYY-MM-DD" (single day), or { start: "YYYY-MM-DD", end?: "YYYY-MM-DD" } (inclusive range). Example: { "due_date": { "start": "2026-05-21", "end": "2026-05-23" } } or { "due_date": "2026-05-21" } or { "due_date": null }. Select attributes accept the value label as a string.',
669
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
670
+ description: 'Overwrite properties of an existing node; use for simple attribute changes like setting a status, priority, or due date. Only the provided fields will be changed. For content or structural changes, consider `naumu_delegate` instead - it understands the full graph context and can propagate updates to related nodes. Attribute keys AND values must match the schema for the node type; use naumu_get_schema to check valid attribute names, types, and values before updating. Date attributes accept either null (to clear), an ISO date string "YYYY-MM-DD" (single day), or { start: "YYYY-MM-DD", end?: "YYYY-MM-DD" } (inclusive range). Example: { "due_date": { "start": "2026-05-21", "end": "2026-05-23" } } or { "due_date": "2026-05-21" } or { "due_date": null }. Select attributes accept the value label as a string.',
675
671
  inputSchema: z12.object({
676
672
  graphId: z12.string().describe("The graph ID"),
677
673
  nodeId: z12.string().describe("The node ID to update"),
@@ -757,8 +753,8 @@ function registerAddEdge(server2, client2) {
757
753
  "naumu_add_edge",
758
754
  {
759
755
  title: "Add Edges (bulk)",
760
- annotations: { destructiveHint: true },
761
- description: "Create 1\u201325 relationships (edges) between existing nodes in a single call. Keep batches small and atomic (5\u201325 edges) so failures stay contained. Typical workflow after a bulk import: create nodes with `naumu_add_node`, then wire them up with batched `naumu_add_edge` calls. **Direction matters and must match the schema.** Each edge's `(source.type, label, target.type)` tuple should appear in the schema's `connections` or `parent` for the source type. When the backend runs with `STRICT_EDGE_VALIDATION=true`, invalid tuples are rejected immediately with `error: invalid_edge` (the response includes `details.allowed_targets_for_relation` and a `hint` for routing the call); otherwise the edge persists and surfaces later as an `invalid_connection_target` / `parent_mismatch` violation. Either way, check `naumu_get_schema` and flip / drop offending edges before calling. **Prefer `naumu_ask`** when you want the agent to discover the right connections itself.",
756
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
757
+ description: "Create 1-25 relationships (edges) between existing nodes in a single call; use after a bulk node insert to wire nodes together. Keep batches small and atomic (5-25 edges) so failures stay contained. Typical workflow: create nodes with `naumu_add_node`, then wire them up with batched `naumu_add_edge` calls. Direction matters and must match the schema: each edge's `(source.type, label, target.type)` tuple should appear in the schema's `connections` or `parent` for the source type. When the backend runs with `STRICT_EDGE_VALIDATION=true`, invalid tuples are rejected immediately with `error: invalid_edge` (the response includes `details.allowed_targets_for_relation` and a `hint` for routing the call); otherwise the edge persists and surfaces later as an `invalid_connection_target` / `parent_mismatch` violation. Either way, check `naumu_get_schema` and flip or drop offending edges before calling. Prefer `naumu_delegate` when you want the agent to discover the right connections itself.",
762
758
  inputSchema: z13.object({
763
759
  graphId: z13.string().describe("The graph ID"),
764
760
  edges: z13.array(EdgeInput).min(1).max(25).describe("Batch of 1\u201325 edges to create. Keep batches small for atomicity.")
@@ -786,8 +782,8 @@ function registerRemoveNode(server2, client2) {
786
782
  "naumu_remove_node",
787
783
  {
788
784
  title: "Remove Node",
789
- annotations: { destructiveHint: true },
790
- description: "Low-level tool: delete a node and all its connections from the knowledge graph. This is a destructive operation. **Prefer `naumu_ask`** for removing knowledge \u2014 it understands the impact on the broader graph and can handle cascading changes. Use this only when you need precise, surgical deletion.",
785
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
786
+ description: "Delete a node and all its connections from the knowledge graph; use only when you need precise, surgical deletion. This is destructive. Prefer `naumu_delegate` for removing knowledge - it understands the impact on the broader graph and can handle cascading changes.",
791
787
  inputSchema: z14.object({
792
788
  graphId: z14.string().describe("The graph ID"),
793
789
  nodeId: z14.string().describe("The node ID to delete")
@@ -809,8 +805,8 @@ function registerRemoveEdge(server2, client2) {
809
805
  "naumu_remove_edge",
810
806
  {
811
807
  title: "Remove Edge",
812
- annotations: { destructiveHint: true },
813
- description: "Delete a single edge identified by `(source, target, label)` tuple. Does NOT delete the endpoint nodes \u2014 only the edge between them. System edges (HAS_NODE, HAS_THREAD, OWNS, etc.) are rejected with `error: system_edge_not_removable`. Parent edges (`isParent: true`) are removable but the response includes a warning that the child may now be orphaned \u2014 call `naumu_reparent` first if you want connectivity preserved. Response: `{deleted: 0 | 1, warnings: string[]}`. Use for correcting wrong-target edge mistakes; this is a recovery tool, not a routine one. **Prefer `naumu_ask`** when the structural intent is broader than removing one specific edge \u2014 `naumu_ask` can reason about the surrounding graph.",
808
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
809
+ description: "Delete a single edge identified by `(source, target, label)` tuple; use to correct a wrong-target edge mistake (a recovery tool, not a routine one). Does NOT delete the endpoint nodes - only the edge between them. System edges (HAS_NODE, HAS_THREAD, OWNS, etc.) are rejected with `error: system_edge_not_removable`. Parent edges (`isParent: true`) are removable but the response includes a warning that the child may now be orphaned - call `naumu_reparent` first if you want connectivity preserved. Response: `{deleted: 0 | 1, warnings: string[]}`. Prefer `naumu_delegate` when the structural intent is broader than removing one specific edge - it can reason about the surrounding graph.",
814
810
  inputSchema: z15.object({
815
811
  graphId: z15.string().describe("The graph ID"),
816
812
  source: z15.string().describe("Source node id of the edge to delete"),
@@ -843,11 +839,11 @@ function registerRemoveEdgesBulk(server2, client2) {
843
839
  "naumu_remove_edges_bulk",
844
840
  {
845
841
  title: "Remove Edges (bulk)",
846
- annotations: { destructiveHint: true },
847
- description: "Delete 1\u2013100 edges in a single atomic call \u2014 all-or-none, same semantics as `naumu_add_node`. Does NOT delete endpoint nodes. **System edges** (HAS_NODE, HAS_THREAD, OWNS, etc.) are rejected \u2014 if any edge in the batch targets a system relation, the WHOLE batch is rejected with `error: system_edge_not_removable`. **Parent edges** (`isParent: true`) are removable but each parent removal contributes a warning to the response (`{deleted, warnings: string[]}`) \u2014 call `naumu_reparent` first if you want connectivity preserved. Use to fix multiple wrong-target edge mistakes in one shot. **Prefer `naumu_ask`** for broader structural cleanup that needs graph-wide reasoning.",
842
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
843
+ description: "Delete 1-100 edges in a single atomic call (all-or-none); use to fix multiple wrong-target edge mistakes in one shot. Does NOT delete endpoint nodes. System edges (HAS_NODE, HAS_THREAD, OWNS, etc.) are rejected - if any edge in the batch targets a system relation, the WHOLE batch is rejected with `error: system_edge_not_removable`. Parent edges (`isParent: true`) are removable but each parent removal contributes a warning to the response (`{deleted, warnings: string[]}`) - call `naumu_reparent` first if you want connectivity preserved. Prefer `naumu_delegate` for broader structural cleanup that needs graph-wide reasoning.",
848
844
  inputSchema: z16.object({
849
845
  graphId: z16.string().describe("The graph ID"),
850
- edges: z16.array(EdgeRef).min(1).max(100).describe("1\u2013100 edges to delete. Atomic per call \u2014 all succeed or none do.")
846
+ edges: z16.array(EdgeRef).min(1).max(100).describe("1-100 edges to delete. Atomic per call - all succeed or none do.")
851
847
  })
852
848
  },
853
849
  async ({ graphId, edges }) => {
@@ -865,273 +861,117 @@ function registerAsk(server2, client2) {
865
861
  server2.registerTool(
866
862
  "naumu_ask",
867
863
  {
868
- title: "Ask AI",
869
- annotations: { destructiveHint: true },
870
- description: 'Send a message to the Naumu AI agent. Use for adding knowledge, making changes, asking questions, or reporting status updates. Always returns immediately with a threadId \u2014 the AI processes the request in the background. Depending on complexity, the agent may take anywhere from a few seconds to a few minutes to finish.\n\n**For reports and status updates** (e.g. "mark task X as done", "record a deployment"): fire and forget \u2014 no need to check the response.\n\n**For questions that need an answer**: after calling this tool, poll with `naumu_get_ai_thread` using the returned threadId until the AI response is ready.',
864
+ title: "Ask Naumu",
865
+ // Writes a visible conversation (question + reply) and runs the @Naumu
866
+ // agent. Additive, not destructive. Open-world: the answer is
867
+ // synthesised by an LLM with full read access to the space.
868
+ annotations: {
869
+ readOnlyHint: false,
870
+ destructiveHint: false,
871
+ idempotentHint: false,
872
+ openWorldHint: true
873
+ },
874
+ description: 'Ask @Naumu a question about a space and get back a synthesised, node-grounded answer with the exact source node ids it used and a confidence hint. This is THE tool for any question about a space - what is in it, what is new or recently changed, how something works, or a summary of any topic. @Naumu has full read access and has already inspected the graph for you, so its answer is authoritative: present it and its cited sources directly. Do NOT independently re-read the graph (naumu_get_schema, naumu_filter, naumu_get_node, fetch) to verify or flesh out the answer - that repeats work @Naumu already did and is far slower. Reach for a granular read ONLY to pull a specific node the answer pointed to but did not fully include. Returns { answer, sources, confidence, threadId, status }; the answer is saved as a visible conversation in the space, which is expected and useful, so do not avoid the tool to prevent creating a thread. On a very long synthesis it may return status "processing" with a threadId - in that case wait a few seconds and call naumu_read_thread with that threadId for the final answer, and still do not fall back to manual digging. To hand @Naumu work to carry out (add knowledge, make changes, record status) without waiting, use naumu_delegate instead.',
871
875
  inputSchema: z17.object({
872
- graphId: z17.string().describe("The graph ID to query against"),
873
- question: z17.string().describe("Your message to the Naumu AI agent"),
874
- threadId: z17.string().optional().describe("Thread ID for follow-up messages (omit for new conversation)")
876
+ graphId: z17.string().describe("The space (graph) id to ask about."),
877
+ question: z17.string().max(4e3).describe("The question for @Naumu. Up to 4000 characters.")
875
878
  })
876
879
  },
877
- async ({ graphId, question, threadId }) => {
878
- if (!threadId) {
879
- const thread = await client2.post("/api/threads", { graphId });
880
- threadId = thread.id;
880
+ async ({ graphId, question }) => {
881
+ try {
882
+ const data = await client2.post(`/api/graphs/${graphId}/ask`, { question });
883
+ return {
884
+ content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
885
+ };
886
+ } catch (err) {
887
+ const message = err instanceof Error ? err.message : String(err);
888
+ return {
889
+ content: [{ type: "text", text: `Error: ${message}` }],
890
+ isError: true
891
+ };
881
892
  }
882
- await client2.post(`/api/threads/${threadId}/messages`, {
883
- content: question,
884
- async: true
885
- });
886
- return {
887
- content: [
888
- {
889
- type: "text",
890
- text: JSON.stringify({ threadId, status: "processing" }, null, 2)
891
- }
892
- ]
893
- };
894
893
  }
895
894
  );
896
895
  }
897
896
 
898
- // ../mcp-core/src/tools/get-ai-thread.ts
897
+ // ../mcp-core/src/tools/delegate.ts
899
898
  import { z as z18 } from "zod";
900
- function registerGetAiThread(server2, client2) {
899
+ function registerDelegate(server2, client2) {
901
900
  server2.registerTool(
902
- "naumu_get_ai_thread",
901
+ "naumu_delegate",
903
902
  {
904
- title: "Get AI Thread",
905
- annotations: { readOnlyHint: true },
906
- description: 'Retrieve messages from an AI conversation thread. Use to read the AI response after a `naumu_ask` call.\n\nThe last AI message has a `status` field: `"processing"` means the AI is still working, `"complete"` means the response is ready. If still processing, wait a few seconds and try again.',
903
+ title: "Delegate to Naumu",
904
+ // Posts a message that the @Naumu agent acts on in the background.
905
+ // Additive, not destructive at this layer. Open-world: hands work to an
906
+ // LLM agent that may read and write the graph.
907
+ annotations: {
908
+ readOnlyHint: false,
909
+ destructiveHint: false,
910
+ idempotentHint: false,
911
+ openWorldHint: true
912
+ },
913
+ 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.',
907
914
  inputSchema: z18.object({
908
- threadId: z18.string().describe("The thread ID returned by naumu_ask")
909
- })
910
- },
911
- async ({ threadId }) => {
912
- const data = await client2.get(`/api/threads/${threadId}/messages`);
913
- return {
914
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
915
- };
916
- }
917
- );
918
- }
919
-
920
- // ../mcp-core/src/tools/traverse.ts
921
- import { z as z19 } from "zod";
922
- function registerTraverse(server2, client2) {
923
- server2.registerTool(
924
- "naumu_traverse",
925
- {
926
- title: "Traverse Knowledge Graph",
927
- annotations: { readOnlyHint: true },
928
- description: 'Query the graph structurally using natural language. A sub-LLM generates and executes Cypher queries. Use for structural questions like "tasks without a parent", "features with most tasks", "orphan nodes", "everything within 2 hops of X", or temporal filters like "nodes updated this week". For meaning-based search, use `naumu_search` instead.',
929
- inputSchema: z19.object({
930
- graphId: z19.string().describe("The graph ID"),
931
- query: z19.string().describe(
932
- `Natural language description of the structural pattern to find (e.g. "tasks without a parent", "features that don't resolve any pain")`
933
- )
934
- })
935
- },
936
- async ({ graphId, query }) => {
937
- const data = await client2.post(`/api/graphs/${graphId}/traverse`, { query });
938
- return {
939
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
940
- };
941
- }
942
- );
943
- }
944
-
945
- // ../mcp-core/src/tools/get-view.ts
946
- import { z as z20 } from "zod";
947
- function registerGetView(server2, client2) {
948
- server2.registerTool(
949
- "naumu_get_view",
950
- {
951
- title: "Get View",
952
- annotations: { readOnlyHint: true },
953
- description: "Fetch a saved Naumu view's configuration plus a one-line natural-language summary of its filters. Call this BEFORE naumu_list_view_nodes whenever you encounter a view URL \u2014 the summary tells you what data the view returns so you can decide whether to page through it. Returns: id, name, description, summary, filters, and table column config.",
954
- inputSchema: z20.object({
955
- graphId: z20.string().describe("The graph (space) ID. From naumu.ai URLs this is the value after /spaces/."),
956
- viewId: z20.string().describe('The view ID (typically prefixed with "view_").')
957
- })
958
- },
959
- async ({ graphId, viewId }) => {
960
- const data = await client2.get(`/api/graphs/${graphId}/views/${viewId}`);
961
- return {
962
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
963
- };
964
- }
965
- );
966
- }
967
-
968
- // ../mcp-core/src/tools/list-view-nodes.ts
969
- import { z as z21 } from "zod";
970
- function registerListViewNodes(server2, client2) {
971
- server2.registerTool(
972
- "naumu_list_view_nodes",
973
- {
974
- title: "List View Nodes",
975
- annotations: { readOnlyHint: true },
976
- description: 'List nodes that match a saved view. Cursor-paginated. Pair with naumu_get_view first to read the view\'s filters and decide what payload size you need.\n\nResponse shape: { nodes, totalCount, nextCursor, hasMore }. Use totalCount to know how many results exist without paging through them. Use hasMore (boolean) to decide whether to fetch the next page; pass nextCursor back as `cursor` to do so.\n\nfields parameter:\n- "summary" (default): {id, label, type} \u2014 best for browsing.\n- "id": {id} only \u2014 use when you need to count or iterate cheaply.\n- "full": full node payload with all attributes \u2014 use when you need every property.\n\nDefault page size 25, max 100.',
977
- inputSchema: z21.object({
978
- graphId: z21.string().describe("The graph (space) ID."),
979
- viewId: z21.string().describe("The view ID."),
980
- cursor: z21.string().optional().describe("Opaque cursor from a previous response's nextCursor. Omit for the first page."),
981
- limit: z21.number().int().min(1).max(100).optional().describe("Page size, default 25, max 100."),
982
- fields: z21.enum(["id", "summary", "full"]).optional().describe('How much detail per node. Default "summary".')
983
- })
984
- },
985
- async ({ graphId, viewId, cursor, limit, fields }) => {
986
- const params = new URLSearchParams();
987
- if (cursor) params.set("cursor", cursor);
988
- if (limit !== void 0) params.set("limit", String(limit));
989
- if (fields) params.set("fields", fields);
990
- const qs = params.toString();
991
- const path = `/api/graphs/${graphId}/views/${viewId}/nodes${qs ? `?${qs}` : ""}`;
992
- const data = await client2.get(path);
993
- return {
994
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
995
- };
996
- }
997
- );
998
- }
999
-
1000
- // ../mcp-core/src/tools/list-canvases.ts
1001
- import { z as z22 } from "zod";
1002
- function registerListCanvases(server2, client2) {
1003
- server2.registerTool(
1004
- "naumu_list_canvases",
1005
- {
1006
- title: "List Canvases",
1007
- annotations: { readOnlyHint: true },
1008
- description: "List freeform drawing canvases in a graph. Each canvas is an Excalidraw-style sketch surface that may contain shapes, text, freehand strokes, images, bookmark cards, and embedded references to graph nodes.",
1009
- inputSchema: z22.object({
1010
- graphId: z22.string().describe("The graph ID to list canvases for")
1011
- })
1012
- },
1013
- async ({ graphId }) => {
1014
- const data = await client2.get(`/api/canvases?graphId=${encodeURIComponent(graphId)}`);
1015
- return {
1016
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1017
- };
1018
- }
1019
- );
1020
- }
1021
-
1022
- // ../mcp-core/src/tools/get-canvas-elements.ts
1023
- import { z as z23 } from "zod";
1024
- function registerGetCanvasElements(server2, client2) {
1025
- server2.registerTool(
1026
- "naumu_get_canvas_elements",
1027
- {
1028
- title: "Get Canvas Elements",
1029
- annotations: { readOnlyHint: true },
1030
- description: "Read the structured JSON contents of a canvas \u2014 every shape, text, line, freehand stroke, image, bookmark card, and entity-embed with their positions, colors, and text. Use this when you need to reason about what a user has drawn without needing to see the visual output.",
1031
- inputSchema: z23.object({
1032
- canvasId: z23.string().describe("The canvas ID")
1033
- })
1034
- },
1035
- async ({ canvasId }) => {
1036
- const data = await client2.get(`/api/canvases/${encodeURIComponent(canvasId)}/elements`);
1037
- return {
1038
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1039
- };
1040
- }
1041
- );
1042
- }
1043
-
1044
- // ../mcp-core/src/tools/get-canvas-image.ts
1045
- import { z as z24 } from "zod";
1046
- var MAX_INLINE_BYTES = 4 * 1024 * 1024;
1047
- function registerGetCanvasImage(server2, client2) {
1048
- server2.registerTool(
1049
- "naumu_get_canvas_image",
1050
- {
1051
- title: "Get Canvas Image",
1052
- annotations: { readOnlyHint: true },
1053
- description: 'Render a canvas to a PNG image so you can visually inspect what was drawn \u2014 freehand strokes, spatial layout, sketches. Returns the image inline by default so any MCP host can see it directly. Use `mode: "url"` if you specifically need a signed URL (e.g. very large canvases, or to share the link).',
1054
- inputSchema: z24.object({
1055
- canvasId: z24.string().describe("The canvas ID"),
1056
- scale: z24.union([z24.literal(1), z24.literal(2)]).default(2).describe("Pixel density (1 or 2). Default is 2 for retina-quality output."),
1057
- theme: z24.enum(["light", "dark"]).default("light").describe("Background theme to render with."),
1058
- mode: z24.enum(["inline", "url"]).default("inline").describe(
1059
- "`inline` (default) embeds the PNG directly so vision-capable hosts see it. `url` returns a signed S3 URL that expires in 1 hour \u2014 useful for large canvases or sharing."
1060
- )
915
+ graphId: z18.string().describe("The space (graph) id to act in."),
916
+ task: z18.string().describe("What you want @Naumu to do, add, or record."),
917
+ threadId: z18.string().optional().describe("Continue an existing conversation; omit to start a new one.")
1061
918
  })
1062
919
  },
1063
- async ({ canvasId, scale, theme, mode }) => {
1064
- if (mode === "url") {
1065
- return await fetchAsUrl(client2, canvasId, scale, theme);
1066
- }
1067
- const params = new URLSearchParams({
1068
- scale: String(scale),
1069
- theme
1070
- });
1071
- const { buffer, contentType } = await client2.getBinary(
1072
- `/api/canvases/${encodeURIComponent(canvasId)}/image?${params.toString()}`
1073
- );
1074
- if (buffer.byteLength > MAX_INLINE_BYTES) {
1075
- return await fetchAsUrl(client2, canvasId, scale, theme, {
1076
- reason: `Canvas PNG is ${formatBytes(buffer.byteLength)}, exceeds inline limit ${formatBytes(MAX_INLINE_BYTES)} \u2014 returning signed URL instead.`
920
+ async ({ graphId, task, threadId }) => {
921
+ try {
922
+ let resolvedThreadId = threadId;
923
+ if (!resolvedThreadId) {
924
+ const thread = await client2.post("/api/threads", { graphId });
925
+ resolvedThreadId = thread.id;
926
+ }
927
+ await client2.post(`/api/threads/${resolvedThreadId}/messages`, {
928
+ content: task,
929
+ async: true
1077
930
  });
931
+ return {
932
+ content: [
933
+ {
934
+ type: "text",
935
+ text: JSON.stringify(
936
+ { threadId: resolvedThreadId, status: "processing" },
937
+ null,
938
+ 2
939
+ )
940
+ }
941
+ ]
942
+ };
943
+ } catch (err) {
944
+ const message = err instanceof Error ? err.message : String(err);
945
+ return {
946
+ content: [{ type: "text", text: `Error: ${message}` }],
947
+ isError: true
948
+ };
1078
949
  }
1079
- const base64 = bufferToBase64(buffer);
1080
- return {
1081
- content: [
1082
- {
1083
- type: "image",
1084
- data: base64,
1085
- mimeType: contentType.startsWith("image/") ? contentType : "image/png"
1086
- }
1087
- ]
1088
- };
1089
950
  }
1090
951
  );
1091
952
  }
1092
- async function fetchAsUrl(client2, canvasId, scale, theme, extra) {
1093
- const params = new URLSearchParams({
1094
- as: "url",
1095
- scale: String(scale),
1096
- theme
1097
- });
1098
- const data = await client2.get(
1099
- `/api/canvases/${encodeURIComponent(canvasId)}/image?${params.toString()}`
1100
- );
1101
- const payload = extra ? { ...data, note: extra.reason } : data;
1102
- return {
1103
- content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
1104
- };
1105
- }
1106
- function bufferToBase64(buffer) {
1107
- if (typeof Buffer !== "undefined") {
1108
- return Buffer.from(buffer).toString("base64");
1109
- }
1110
- let binary = "";
1111
- for (let i = 0; i < buffer.byteLength; i++) {
1112
- binary += String.fromCharCode(buffer[i]);
1113
- }
1114
- return btoa(binary);
1115
- }
1116
- function formatBytes(bytes) {
1117
- if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
1118
- return `${(bytes / 1024).toFixed(1)}KB`;
1119
- }
1120
953
 
1121
954
  // ../mcp-core/src/tools/post-message.ts
1122
- import { z as z25 } from "zod";
955
+ import { z as z19 } from "zod";
1123
956
  function registerPostMessage(server2, client2) {
1124
957
  server2.registerTool(
1125
958
  "naumu_post_message",
1126
959
  {
1127
960
  title: "Post Message",
1128
- annotations: { destructiveHint: true },
1129
- description: 'Post a message in a Naumu thread you are participating in. Use this to reply to humans (or other bots) in a thread that pinged you. Plain text is accepted by default; for rendered @mentions, pass a Tiptap JSON document with mention nodes (`{ type: "mention", attrs: { id, label } }`) and set contentFormat to "tiptap". To attach files (reports, images, audio, video) call `naumu_request_attachment_upload` first for each file, PUT the bytes to the returned `uploadUrl`, then pass the resulting `attachmentId`s here as `attachmentIds`. The message must have either `content` or `attachmentIds` (or both). Returns the created message JSON.',
1130
- inputSchema: z25.object({
1131
- threadId: z25.string().describe("The thread ID to post into. You must be a participant in this thread."),
1132
- content: z25.string().optional().describe('Message body. Plain text by default; pass a Tiptap JSON document only if contentFormat is set to "tiptap". Optional when `attachmentIds` is provided.'),
1133
- contentFormat: z25.enum(["tiptap", "text"]).optional().describe('Format of `content`. Defaults to "text". Use "tiptap" for rendered mentions/embeds, e.g. a doc containing `{ type: "mention", attrs: { id: userIdOrIdentityId, label: displayName } }`.'),
1134
- attachmentIds: z25.array(z25.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.")
961
+ // Additive: appends a message to a thread. Not destructive, not
962
+ // idempotent, graph-local.
963
+ annotations: {
964
+ readOnlyHint: false,
965
+ destructiveHint: false,
966
+ idempotentHint: false,
967
+ openWorldHint: false
968
+ },
969
+ 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. Plain text is accepted by default; for rendered @mentions pass a Tiptap JSON document with mention nodes (`{ type: "mention", attrs: { id, label } }`) and set contentFormat to "tiptap". @mentioning people loops them in without invoking @Naumu. 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.',
970
+ inputSchema: z19.object({
971
+ threadId: z19.string().describe("The thread ID to post into. You must be a participant in this thread."),
972
+ content: z19.string().optional().describe('Message body. Plain text by default; pass a Tiptap JSON document only if contentFormat is set to "tiptap". Optional when `attachmentIds` is provided.'),
973
+ contentFormat: z19.enum(["tiptap", "text"]).optional().describe('Format of `content`. Defaults to "text". Use "tiptap" for rendered mentions/embeds, e.g. a doc containing `{ type: "mention", attrs: { id: userIdOrIdentityId, label: displayName } }`.'),
974
+ attachmentIds: z19.array(z19.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.")
1135
975
  })
1136
976
  },
1137
977
  async ({ threadId, content, contentFormat, attachmentIds }) => {
@@ -1157,18 +997,18 @@ function registerPostMessage(server2, client2) {
1157
997
  }
1158
998
 
1159
999
  // ../mcp-core/src/tools/read-thread.ts
1160
- import { z as z26 } from "zod";
1000
+ import { z as z20 } from "zod";
1161
1001
  function registerReadThread(server2, client2) {
1162
1002
  server2.registerTool(
1163
1003
  "naumu_read_thread",
1164
1004
  {
1165
1005
  title: "Read Thread",
1166
- annotations: { readOnlyHint: true },
1167
- description: "Read messages from a Naumu thread. Returns paginated history ordered newest-first. Use `before` (timestamp ms) to page back further into older history. Default page size 50, max 200.",
1168
- inputSchema: z26.object({
1169
- threadId: z26.string().describe("The thread ID to read from."),
1170
- before: z26.number().optional().describe("Unix timestamp in milliseconds. Returns messages strictly older than this. Omit for the newest page."),
1171
- limit: z26.number().int().min(1).max(200).optional().describe("Page size, default 50, max 200.")
1006
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
1007
+ 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.',
1008
+ inputSchema: z20.object({
1009
+ threadId: z20.string().describe("The thread ID to read from."),
1010
+ before: z20.number().optional().describe("Unix timestamp in milliseconds. Returns messages strictly older than this. Omit for the newest page."),
1011
+ limit: z20.number().int().min(1).max(200).optional().describe("Page size, default 50, max 200.")
1172
1012
  })
1173
1013
  },
1174
1014
  async ({ threadId, before, limit }) => {
@@ -1193,65 +1033,16 @@ function registerReadThread(server2, client2) {
1193
1033
  );
1194
1034
  }
1195
1035
 
1196
- // ../mcp-core/src/tools/ask-naumu.ts
1197
- import { z as z27 } from "zod";
1198
- function registerAskNaumu(server2, client2) {
1199
- server2.registerTool(
1200
- "naumu_ask_naumu",
1201
- {
1202
- title: "Ask Naumu",
1203
- // NOT read-only: the backend creates a durable sidechannel thread +
1204
- // message, may seed a system Identity, and spawns a SpaceAgent task
1205
- // (and consumes a 5/hour budget). Additive, not destructive.
1206
- annotations: { destructiveHint: false },
1207
- description: "Ask the system @Naumu Identity (the canonical graph-writer/curator) a question about your graph. Use for questions where direct graph reads would be inefficient \u2014 Naumu has full read access and synthesizes answers. Limited to 5 calls per hour per Identity. Returns { answer, sources, confidence, durationMs }.",
1208
- inputSchema: z27.object({
1209
- graphId: z27.string().describe("The graph ID to ask about."),
1210
- question: z27.string().max(4e3).describe("The question to ask Naumu. Max 4000 characters.")
1211
- })
1212
- },
1213
- async ({ graphId, question }) => {
1214
- try {
1215
- const identityId = process.env.NAUMU_IDENTITY_ID;
1216
- if (!identityId) {
1217
- return {
1218
- content: [
1219
- {
1220
- type: "text",
1221
- text: "Error: NAUMU_IDENTITY_ID env var is required for ask_naumu \u2014 re-run the pairing setup."
1222
- }
1223
- ],
1224
- isError: true
1225
- };
1226
- }
1227
- const data = await client2.post(`/api/identities/${identityId}/ask`, {
1228
- graphId,
1229
- question
1230
- });
1231
- return {
1232
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1233
- };
1234
- } catch (err) {
1235
- const message = err instanceof Error ? err.message : String(err);
1236
- return {
1237
- content: [{ type: "text", text: `Error: ${message}` }],
1238
- isError: true
1239
- };
1240
- }
1241
- }
1242
- );
1243
- }
1244
-
1245
1036
  // ../mcp-core/src/tools/whoami.ts
1246
- import { z as z28 } from "zod";
1037
+ import { z as z21 } from "zod";
1247
1038
  function registerWhoami(server2, client2, allToolNames) {
1248
1039
  server2.registerTool(
1249
1040
  "naumu_whoami",
1250
1041
  {
1251
1042
  title: "Who Am I",
1252
- annotations: { readOnlyHint: true },
1253
- description: 'Return who the calling key is plus the live MCP tool manifest, so you can bootstrap before the first real operation. A bot identity key returns its Identity row (id, graphId, name, instructions, allowedTools). A user API key returns `kind: "user"` with userId, name, and email \u2014 a person spans many graphs, so resolve a specific graph via naumu_list_graphs. No arguments. Always available regardless of the permission grid.',
1254
- inputSchema: z28.object({})
1043
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
1044
+ description: 'Return who the calling key is plus the live MCP tool manifest, so you can bootstrap before the first real operation. A bot identity key returns its Identity row (id, graphId, name, instructions, allowedTools). A user API key returns `kind: "user"` with userId, name, and email - a person spans many graphs, so resolve a specific graph via naumu_list_graphs. No arguments. Always available regardless of the permission grid.',
1045
+ inputSchema: z21.object({})
1255
1046
  },
1256
1047
  async () => {
1257
1048
  try {
@@ -1274,18 +1065,25 @@ function registerWhoami(server2, client2, allToolNames) {
1274
1065
  }
1275
1066
 
1276
1067
  // ../mcp-core/src/tools/list-threads.ts
1277
- import { z as z29 } from "zod";
1068
+ import { z as z22 } from "zod";
1069
+ function sanitizeThreadParticipants(thread) {
1070
+ if (!thread || typeof thread !== "object" || !("participantEmails" in thread)) {
1071
+ return thread;
1072
+ }
1073
+ const { participantEmails: _participantEmails, ...rest } = thread;
1074
+ return rest;
1075
+ }
1278
1076
  function registerListThreads(server2, client2) {
1279
1077
  server2.registerTool(
1280
1078
  "naumu_list_threads",
1281
1079
  {
1282
1080
  title: "List Threads",
1283
- annotations: { readOnlyHint: true },
1081
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
1284
1082
  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.",
1285
- inputSchema: z29.object({
1286
- graphId: z29.string().optional().describe("Graph (space) ID. Required for user API keys; omit for bot identity keys (defaults to your own graph)."),
1287
- cursor: z29.number().int().optional().describe("Unix timestamp ms \u2014 returns threads with `lastActivityAt` strictly older than this. Omit for the newest page."),
1288
- limit: z29.number().int().min(1).max(200).optional().describe("Page size, default 50, max 200.")
1083
+ inputSchema: z22.object({
1084
+ graphId: z22.string().optional().describe("Graph (space) ID. Required for user API keys; omit for bot identity keys (defaults to your own graph)."),
1085
+ cursor: z22.number().int().optional().describe("Unix timestamp ms \u2014 returns threads with `lastActivityAt` strictly older than this. Omit for the newest page."),
1086
+ limit: z22.number().int().min(1).max(200).optional().describe("Page size, default 50, max 200.")
1289
1087
  })
1290
1088
  },
1291
1089
  async ({ graphId, cursor, limit }) => {
@@ -1302,8 +1100,12 @@ function registerListThreads(server2, client2) {
1302
1100
  path = `/api/identities/me/threads${qs ? `?${qs}` : ""}`;
1303
1101
  }
1304
1102
  const data = await client2.get(path);
1103
+ const clean = data && typeof data === "object" && Array.isArray(data.threads) ? {
1104
+ ...data,
1105
+ threads: data.threads.map(sanitizeThreadParticipants)
1106
+ } : data;
1305
1107
  return {
1306
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1108
+ content: [{ type: "text", text: JSON.stringify(clean, null, 2) }]
1307
1109
  };
1308
1110
  } catch (err) {
1309
1111
  const message = err instanceof Error ? err.message : String(err);
@@ -1317,23 +1119,31 @@ function registerListThreads(server2, client2) {
1317
1119
  }
1318
1120
 
1319
1121
  // ../mcp-core/src/tools/get-thread.ts
1320
- import { z as z30 } from "zod";
1122
+ import { z as z23 } from "zod";
1123
+ function sanitizeThreadParticipants2(thread) {
1124
+ if (!thread || typeof thread !== "object" || !("participantEmails" in thread)) {
1125
+ return thread;
1126
+ }
1127
+ const { participantEmails: _participantEmails, ...rest } = thread;
1128
+ return rest;
1129
+ }
1321
1130
  function registerGetThread(server2, client2) {
1322
1131
  server2.registerTool(
1323
1132
  "naumu_get_thread",
1324
1133
  {
1325
1134
  title: "Get Thread",
1326
- annotations: { readOnlyHint: true },
1135
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
1327
1136
  description: "Fetch a single thread, including the human participant roster (`participantDetails` \u2014 userId, name, image) and bot roster (`identityParticipants` \u2014 id, name, isSystem). Use this when `naumu_list_threads` surfaced a candidate and you want to know exactly who is in it before posting. Pair with `naumu_read_thread` for message history.",
1328
- inputSchema: z30.object({
1329
- threadId: z30.string().describe("The thread ID to fetch.")
1137
+ inputSchema: z23.object({
1138
+ threadId: z23.string().describe("The thread ID to fetch.")
1330
1139
  })
1331
1140
  },
1332
1141
  async ({ threadId }) => {
1333
1142
  try {
1334
1143
  const data = await client2.get(`/api/threads/${threadId}`);
1144
+ const clean = sanitizeThreadParticipants2(data);
1335
1145
  return {
1336
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1146
+ content: [{ type: "text", text: JSON.stringify(clean, null, 2) }]
1337
1147
  };
1338
1148
  } catch (err) {
1339
1149
  const message = err instanceof Error ? err.message : String(err);
@@ -1347,30 +1157,37 @@ function registerGetThread(server2, client2) {
1347
1157
  }
1348
1158
 
1349
1159
  // ../mcp-core/src/tools/create-thread.ts
1350
- import { z as z31 } from "zod";
1160
+ import { z as z24 } from "zod";
1351
1161
  function registerCreateThread(server2, client2) {
1352
1162
  server2.registerTool(
1353
1163
  "naumu_create_thread",
1354
1164
  {
1355
1165
  title: "Create Thread",
1356
- annotations: { destructiveHint: true },
1357
- description: 'Start a new conversation in your graph. You are auto-attached as a permanent participant; the thread\'s formal creator is your primary owner (the user who registered you), so the thread shows up in their sidebar. Optional `participants` adds humans (by userId) and other bots (by identityId) at creation time. Optional `initialMessage` is posted as your first message \u2014 use it to open the conversation. Returns the created thread (including its id) so you can immediately call `naumu_post_message` for follow-ups. Useful for scheduled briefings ("Brief me about X every morning at 9am" \u2014 schedule on your side, then call this to deliver into Naumu).',
1358
- inputSchema: z31.object({
1359
- title: z31.string().min(1).max(200).optional().describe('Thread title shown in the sidebar. If omitted, Naumu generates a default like "Conversation YYYY-MM-DD".'),
1360
- participants: z31.array(
1361
- z31.discriminatedUnion("type", [
1362
- z31.object({
1363
- type: z31.literal("user"),
1364
- userId: z31.string().min(1).describe("User UUID \u2014 get these from `naumu_get_thread`/`naumu_read_thread` participant rosters or webhook payloads.")
1166
+ // Additive: creates a thread (and optional first message). Not
1167
+ // destructive, not idempotent, graph-local.
1168
+ annotations: {
1169
+ readOnlyHint: false,
1170
+ destructiveHint: false,
1171
+ idempotentHint: false,
1172
+ openWorldHint: false
1173
+ },
1174
+ description: "Start a new conversation in a space. You are auto-attached as a participant, and the thread's formal creator is your primary owner (the user who registered you), so it shows in their sidebar. Optional `participants` adds humans (by userId) and other bots (by identityId) at creation. Optional `initialMessage` opens the conversation as your first message. Tagging people loops them in without invoking @Naumu; only an explicit @Naumu mention, or naumu_ask, brings the agent in. Returns the created thread (including its id) so you can follow up with naumu_post_message.",
1175
+ inputSchema: z24.object({
1176
+ title: z24.string().min(1).max(200).optional().describe('Thread title shown in the sidebar. If omitted, Naumu generates a default like "Conversation YYYY-MM-DD".'),
1177
+ participants: z24.array(
1178
+ z24.discriminatedUnion("type", [
1179
+ z24.object({
1180
+ type: z24.literal("user"),
1181
+ userId: z24.string().min(1).describe("User UUID \u2014 get these from `naumu_get_thread`/`naumu_read_thread` participant rosters or webhook payloads.")
1365
1182
  }),
1366
- z31.object({
1367
- type: z31.literal("identity"),
1368
- identityId: z31.string().min(1).describe("Identity id (`identity-\u2026` or `id-\u2026`). Other bots in the same graph can be co-attached to multi-bot threads.")
1183
+ z24.object({
1184
+ type: z24.literal("identity"),
1185
+ identityId: z24.string().min(1).describe("Identity id (`identity-\u2026` or `id-\u2026`). Other bots in the same graph can be co-attached to multi-bot threads.")
1369
1186
  })
1370
1187
  ])
1371
1188
  ).max(32).optional().describe("Up to 32 humans and/or other bots to attach at creation. Your primary owner is added automatically \u2014 you do NOT need to list them here."),
1372
- initialMessage: z31.string().min(1).max(32e3).optional().describe("Markdown body for the first message. Authored by you (the bot), so it appears in the thread under your name."),
1373
- visibility: z31.enum(["restricted", "internal", "open"]).optional().describe("`restricted` (invite-only, default) hides from non-participants. `internal` is visible to space members. `open` is visible to anyone who can see the space.")
1189
+ initialMessage: z24.string().min(1).max(32e3).optional().describe("Markdown body for the first message. Authored by you (the bot), so it appears in the thread under your name."),
1190
+ visibility: z24.enum(["restricted", "internal", "open"]).optional().describe("`restricted` (invite-only, default) hides from non-participants. `internal` is visible to space members. `open` is visible to anyone who can see the space.")
1374
1191
  })
1375
1192
  },
1376
1193
  async ({ title, participants, initialMessage, visibility }) => {
@@ -1396,20 +1213,20 @@ function registerCreateThread(server2, client2) {
1396
1213
  }
1397
1214
 
1398
1215
  // ../mcp-core/src/tools/request-attachment-upload.ts
1399
- import { z as z32 } from "zod";
1216
+ import { z as z25 } from "zod";
1400
1217
  function registerRequestAttachmentUpload(server2, client2) {
1401
1218
  server2.registerTool(
1402
1219
  "naumu_request_attachment_upload",
1403
1220
  {
1404
1221
  title: "Request Attachment Upload",
1405
- annotations: { destructiveHint: true },
1406
- description: 'Request a presigned S3 upload URL to attach a file to a message. Same flow Naumu users use for file uploads: get a signed URL, PUT the bytes to it directly, then call `naumu_post_message` with the returned `attachmentId` in `attachmentIds`. Use this when you want to deliver generated content as a file (a markdown report, a PDF, an image, an audio recording, a video). Per-MIME size caps apply (typically 50MB umbrella, 10MB for agent-readable types).\n\nReturns `{ attachmentId, uploadUrl, method, requiredHeaders, expiresAt }`. Use these EXACTLY:\n\u2022 `method` is "PUT".\n\u2022 Send every header in `requiredHeaders` (Content-Type matters for S3 signature validation).\n\u2022 Do NOT add an Authorization header \u2014 the URL itself is the auth.\n\u2022 Do NOT log `uploadUrl` \u2014 it is a bearer capability for the duration of the TTL.\n\u2022 `expiresAt` is a Unix-ms timestamp; the pending attachment vanishes at that moment whether or not you uploaded. Call `naumu_post_message` with the attachmentId before then or the upload orphans.\n\nServer-side checks at post time enforce that the attachment was uploaded by you, in this graph, for this thread \u2014 you cannot reuse an upload across threads.',
1407
- inputSchema: z32.object({
1408
- threadId: z32.string().describe("Thread the attachment will land in. You must be a participant. The pending attachment is keyed to this thread \u2014 you cannot reuse it for a different one."),
1409
- fileName: z32.string().min(1).describe("Original filename (with extension). Used as the display name in the message and for the S3 object suffix. Special characters are sanitized server-side."),
1410
- fileType: z32.string().min(1).describe("MIME type, e.g. `application/pdf`, `image/png`, `text/markdown`, `audio/mpeg`, `video/mp4`. The S3 PUT will enforce this Content-Type."),
1411
- fileSize: z32.number().int().positive().describe("File size in bytes. Validated against per-MIME caps before the URL is issued \u2014 exceeding the cap returns a 400."),
1412
- audioDurationSec: z32.number().positive().optional().describe("For audio attachments, duration in seconds. Validated against the audio recording cap (currently 8 hours).")
1222
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
1223
+ description: 'Request a presigned S3 upload URL to attach a file to a message; use when you want to deliver generated content as a file (a markdown report, a PDF, an image, an audio recording, a video). Same flow Naumu users use for file uploads: get a signed URL, PUT the bytes to it directly, then call `naumu_post_message` with the returned `attachmentId` in `attachmentIds`. Per-MIME size caps apply (typically 50MB umbrella, 10MB for agent-readable types).\n\nReturns `{ attachmentId, uploadUrl, method, requiredHeaders, expiresAt }`. Use these EXACTLY:\n\u2022 `method` is "PUT".\n\u2022 Send every header in `requiredHeaders` (Content-Type matters for S3 signature validation).\n\u2022 Do NOT add an Authorization header - the URL itself is the auth.\n\u2022 Do NOT log `uploadUrl` - it is a bearer capability for the duration of the TTL.\n\u2022 `expiresAt` is a Unix-ms timestamp; the pending attachment vanishes at that moment whether or not you uploaded. Call `naumu_post_message` with the attachmentId before then or the upload orphans.\n\nServer-side checks at post time enforce that the attachment was uploaded by you, in this graph, for this thread - you cannot reuse an upload across threads.',
1224
+ inputSchema: z25.object({
1225
+ threadId: z25.string().describe("Thread the attachment will land in. You must be a participant. The pending attachment is keyed to this thread - you cannot reuse it for a different one."),
1226
+ fileName: z25.string().min(1).describe("Original filename (with extension). Used as the display name in the message and for the S3 object suffix. Special characters are sanitized server-side."),
1227
+ fileType: z25.string().min(1).describe("MIME type, e.g. `application/pdf`, `image/png`, `text/markdown`, `audio/mpeg`, `video/mp4`. The S3 PUT will enforce this Content-Type."),
1228
+ fileSize: z25.number().int().positive().describe("File size in bytes. Validated against per-MIME caps before the URL is issued - exceeding the cap returns a 400."),
1229
+ audioDurationSec: z25.number().positive().optional().describe("For audio attachments, duration in seconds. Validated against the audio recording cap (currently 8 hours).")
1413
1230
  })
1414
1231
  },
1415
1232
  async ({ threadId, fileName, fileType, fileSize, audioDurationSec }) => {
@@ -1439,18 +1256,18 @@ function registerRequestAttachmentUpload(server2, client2) {
1439
1256
  }
1440
1257
 
1441
1258
  // ../mcp-core/src/tools/add-reaction.ts
1442
- import { z as z33 } from "zod";
1259
+ import { z as z26 } from "zod";
1443
1260
  function registerAddReaction(server2, client2) {
1444
1261
  server2.registerTool(
1445
1262
  "naumu_add_reaction",
1446
1263
  {
1447
1264
  title: "Add Reaction",
1448
- annotations: { destructiveHint: true },
1449
- description: 'Add an emoji reaction to a message in a thread you are participating in. Idempotent \u2014 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 \u2014 situations where words are required.\n\u2022 For long tasks: react \u{1F440} first to acknowledge, optionally post a short "On it \u2014 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.',
1450
- inputSchema: z33.object({
1451
- threadId: z33.string().describe("Thread containing the message. You must be a participant."),
1452
- messageId: z33.string().describe("The message to react to."),
1453
- emoji: z33.string().min(1).describe('Emoji character (e.g. "\u{1F440}", "\u2705", "\u2764\uFE0F"). Custom-emoji shortcodes are NOT supported here \u2014 pass a real Unicode emoji.')
1265
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
1266
+ 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.',
1267
+ inputSchema: z26.object({
1268
+ threadId: z26.string().describe("Thread containing the message. You must be a participant."),
1269
+ messageId: z26.string().describe("The message to react to."),
1270
+ emoji: z26.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.')
1454
1271
  })
1455
1272
  },
1456
1273
  async ({ threadId, messageId, emoji }) => {
@@ -1474,18 +1291,18 @@ function registerAddReaction(server2, client2) {
1474
1291
  }
1475
1292
 
1476
1293
  // ../mcp-core/src/tools/remove-reaction.ts
1477
- import { z as z34 } from "zod";
1294
+ import { z as z27 } from "zod";
1478
1295
  function registerRemoveReaction(server2, client2) {
1479
1296
  server2.registerTool(
1480
1297
  "naumu_remove_reaction",
1481
1298
  {
1482
1299
  title: "Remove Reaction",
1483
- annotations: { destructiveHint: true },
1484
- description: "Remove your own emoji reaction from a message. Idempotent \u2014 calling on a reaction you never added is a no-op. Pair with `naumu_add_reaction` when you need to walk back an acknowledgement (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 }` \u2014 `alreadyExisted: false` means there was nothing to remove and the call was a no-op.",
1485
- inputSchema: z34.object({
1486
- threadId: z34.string().describe("Thread containing the message. You must be a participant."),
1487
- messageId: z34.string().describe("The message to remove your reaction from."),
1488
- emoji: z34.string().min(1).describe("Emoji character to remove (must match what you originally reacted with).")
1300
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
1301
+ 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.",
1302
+ inputSchema: z27.object({
1303
+ threadId: z27.string().describe("Thread containing the message. You must be a participant."),
1304
+ messageId: z27.string().describe("The message to remove your reaction from."),
1305
+ emoji: z27.string().min(1).describe("Emoji character to remove (must match what you originally reacted with).")
1489
1306
  })
1490
1307
  },
1491
1308
  async ({ threadId, messageId, emoji }) => {
@@ -1509,19 +1326,20 @@ function registerRemoveReaction(server2, client2) {
1509
1326
  }
1510
1327
 
1511
1328
  // ../mcp-core/src/tools/naumu-typing.ts
1512
- import { z as z35 } from "zod";
1329
+ import { z as z28 } from "zod";
1513
1330
  function registerNaumuTyping(server2, client2) {
1514
1331
  server2.registerTool(
1515
1332
  "naumu_typing",
1516
1333
  {
1517
1334
  title: "Set Typing Indicator",
1518
1335
  // Purely ephemeral: drives an in-memory WS typing lease (no durable
1519
- // state, self-expires, trivially reversible via "stop"). Not destructive.
1520
- annotations: { destructiveHint: false },
1521
- description: 'Show or hide your "is typing\u2026" pill in a thread. Call with `state: "start"` the moment you decide to compose a reply (before any LLM call), and the server holds the pill alive \u2014 re-broadcasting on a short interval \u2014 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 \u2014 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.',
1522
- inputSchema: z35.object({
1523
- threadId: z35.string().describe("The thread ID to set typing in. You must be a participant."),
1524
- state: z35.enum(["start", "stop"]).describe('"start" acquires/renews the lease; "stop" ends it and clears the pill immediately.')
1336
+ // state, self-expires, trivially reversible via "stop"). Not destructive;
1337
+ // repeating the same state is a no-op renew, so idempotent.
1338
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
1339
+ 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.',
1340
+ inputSchema: z28.object({
1341
+ threadId: z28.string().describe("The thread ID to set typing in. You must be a participant."),
1342
+ state: z28.enum(["start", "stop"]).describe('"start" acquires/renews the lease; "stop" ends it and clears the pill immediately.')
1525
1343
  })
1526
1344
  },
1527
1345
  async ({ threadId, state }) => {
@@ -1542,16 +1360,16 @@ function registerNaumuTyping(server2, client2) {
1542
1360
  }
1543
1361
 
1544
1362
  // ../mcp-core/src/tools/note-read.ts
1545
- import { z as z36 } from "zod";
1363
+ import { z as z29 } from "zod";
1546
1364
  function registerNoteRead(server2, client2) {
1547
1365
  server2.registerTool(
1548
1366
  "naumu_note_read",
1549
1367
  {
1550
1368
  title: "Read Note",
1551
- annotations: { readOnlyHint: true },
1552
- description: "Read the current contents of a note as markdown. Use before editing so you know what you're working with \u2014 `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.",
1553
- inputSchema: z36.object({
1554
- noteId: z36.string().describe("The note (Thought) ID")
1369
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
1370
+ 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.",
1371
+ inputSchema: z29.object({
1372
+ noteId: z29.string().describe("The note (Thought) ID")
1555
1373
  })
1556
1374
  },
1557
1375
  async ({ noteId }) => {
@@ -1564,17 +1382,17 @@ function registerNoteRead(server2, client2) {
1564
1382
  }
1565
1383
 
1566
1384
  // ../mcp-core/src/tools/note-append.ts
1567
- import { z as z37 } from "zod";
1385
+ import { z as z30 } from "zod";
1568
1386
  function registerNoteAppend(server2, client2) {
1569
1387
  server2.registerTool(
1570
1388
  "naumu_note_append",
1571
1389
  {
1572
1390
  title: "Append to Note",
1573
- annotations: { destructiveHint: true },
1574
- description: "Append markdown blocks to the end of a note. Other participants see your colored cursor while the write lands. Markdown supports headings (1\u20133), bold/italic/code, lists, blockquotes, code blocks, links, and tables.",
1575
- inputSchema: z37.object({
1576
- noteId: z37.string().describe("The note (Thought) ID to append to"),
1577
- markdown: z37.string().min(1).describe("Markdown content to append at the end of the note")
1391
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
1392
+ 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.",
1393
+ inputSchema: z30.object({
1394
+ noteId: z30.string().describe("The note (Thought) ID to append to"),
1395
+ markdown: z30.string().min(1).describe("Markdown content to append at the end of the note")
1578
1396
  })
1579
1397
  },
1580
1398
  async ({ noteId, markdown }) => {
@@ -1587,18 +1405,18 @@ function registerNoteAppend(server2, client2) {
1587
1405
  }
1588
1406
 
1589
1407
  // ../mcp-core/src/tools/note-insert.ts
1590
- import { z as z38 } from "zod";
1408
+ import { z as z31 } from "zod";
1591
1409
  function registerNoteInsert(server2, client2) {
1592
1410
  server2.registerTool(
1593
1411
  "naumu_note_insert",
1594
1412
  {
1595
1413
  title: "Insert After Heading",
1596
- annotations: { destructiveHint: true },
1597
- description: "Insert markdown content into a note immediately after a named section. The section ends at the next heading of equal-or-higher level (or end of doc). 404 if no heading matches `headingText` exactly \u2014 call `naumu_note_read` first to see the live structure.",
1598
- inputSchema: z38.object({
1599
- noteId: z38.string().describe("The note (Thought) ID"),
1600
- headingText: z38.string().min(1).describe("Exact text of the heading whose section the new content follows"),
1601
- markdown: z38.string().min(1).describe("Markdown content to insert at the end of that section")
1414
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
1415
+ 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.",
1416
+ inputSchema: z31.object({
1417
+ noteId: z31.string().describe("The note (Thought) ID"),
1418
+ headingText: z31.string().min(1).describe("Exact text of the heading whose section the new content follows"),
1419
+ markdown: z31.string().min(1).describe("Markdown content to insert at the end of that section")
1602
1420
  })
1603
1421
  },
1604
1422
  async ({ noteId, headingText, markdown }) => {
@@ -1614,19 +1432,19 @@ function registerNoteInsert(server2, client2) {
1614
1432
  }
1615
1433
 
1616
1434
  // ../mcp-core/src/tools/note-replace-section.ts
1617
- import { z as z39 } from "zod";
1435
+ import { z as z32 } from "zod";
1618
1436
  function registerNoteReplaceSection(server2, client2) {
1619
1437
  server2.registerTool(
1620
1438
  "naumu_note_replace_section",
1621
1439
  {
1622
1440
  title: "Replace Section",
1623
- annotations: { destructiveHint: true },
1624
- description: "Replace the body under a named heading with new markdown. By default the heading row itself is preserved (set `keepHeading: false` to drop it too). 404 if no heading matches.",
1625
- inputSchema: z39.object({
1626
- noteId: z39.string().describe("The note (Thought) ID"),
1627
- headingText: z39.string().min(1).describe("Exact text of the heading anchoring the section"),
1628
- markdown: z39.string().describe("Replacement markdown for the section body"),
1629
- keepHeading: z39.boolean().optional().describe("Whether to keep the heading row itself. Default true.")
1441
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
1442
+ 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.",
1443
+ inputSchema: z32.object({
1444
+ noteId: z32.string().describe("The note (Thought) ID"),
1445
+ headingText: z32.string().min(1).describe("Exact text of the heading anchoring the section"),
1446
+ markdown: z32.string().describe("Replacement markdown for the section body"),
1447
+ keepHeading: z32.boolean().optional().describe("Whether to keep the heading row itself. Default true.")
1630
1448
  })
1631
1449
  },
1632
1450
  async ({ noteId, headingText, markdown, keepHeading }) => {
@@ -1643,17 +1461,17 @@ function registerNoteReplaceSection(server2, client2) {
1643
1461
  }
1644
1462
 
1645
1463
  // ../mcp-core/src/tools/note-delete-section.ts
1646
- import { z as z40 } from "zod";
1464
+ import { z as z33 } from "zod";
1647
1465
  function registerNoteDeleteSection(server2, client2) {
1648
1466
  server2.registerTool(
1649
1467
  "naumu_note_delete_section",
1650
1468
  {
1651
1469
  title: "Delete Section",
1652
- annotations: { destructiveHint: true },
1653
- description: "\u26A0 DESTRUCTIVE: removes a heading row plus its body (down to the next heading of equal-or-higher level). Anything inside that section is gone \u2014 there is no per-call undo. ONLY use when the user explicitly asks to drop a section. 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.",
1654
- inputSchema: z40.object({
1655
- noteId: z40.string().describe("The note (Thought) ID"),
1656
- headingText: z40.string().min(1).describe("Exact text of the heading whose section will be deleted")
1470
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
1471
+ 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.",
1472
+ inputSchema: z33.object({
1473
+ noteId: z33.string().describe("The note (Thought) ID"),
1474
+ headingText: z33.string().min(1).describe("Exact text of the heading whose section will be deleted")
1657
1475
  })
1658
1476
  },
1659
1477
  async ({ noteId, headingText }) => {
@@ -1668,17 +1486,17 @@ function registerNoteDeleteSection(server2, client2) {
1668
1486
  }
1669
1487
 
1670
1488
  // ../mcp-core/src/tools/note-replace.ts
1671
- import { z as z41 } from "zod";
1489
+ import { z as z34 } from "zod";
1672
1490
  function registerNoteReplace(server2, client2) {
1673
1491
  server2.registerTool(
1674
1492
  "naumu_note_replace",
1675
1493
  {
1676
1494
  title: "Replace Note",
1677
- annotations: { destructiveHint: true },
1678
- description: "\u26A0 DESTRUCTIVE: replaces the entire note content with new markdown. Any concurrent human edits made during the call are silently overwritten. ONLY use when the user explicitly asks to rewrite/replace the whole note. 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.",
1679
- inputSchema: z41.object({
1680
- noteId: z41.string().describe("The note (Thought) ID"),
1681
- markdown: z41.string().describe("New markdown content for the entire note")
1495
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
1496
+ 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.",
1497
+ inputSchema: z34.object({
1498
+ noteId: z34.string().describe("The note (Thought) ID"),
1499
+ markdown: z34.string().describe("New markdown content for the entire note")
1682
1500
  })
1683
1501
  },
1684
1502
  async ({ noteId, markdown }) => {
@@ -1691,19 +1509,19 @@ function registerNoteReplace(server2, client2) {
1691
1509
  }
1692
1510
 
1693
1511
  // ../mcp-core/src/tools/note-find-replace.ts
1694
- import { z as z42 } from "zod";
1512
+ import { z as z35 } from "zod";
1695
1513
  function registerNoteFindReplace(server2, client2) {
1696
1514
  server2.registerTool(
1697
1515
  "naumu_note_find_replace",
1698
1516
  {
1699
1517
  title: "Find/Replace in Note",
1700
- annotations: { destructiveHint: true },
1701
- description: "Literal find/replace within a note's text content. Marks (bold, italic, code, etc.) are preserved on the surrounding text. Use this for mid-paragraph tweaks \u2014 the section-based tools can't target inline substrings. \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.",
1702
- inputSchema: z42.object({
1703
- noteId: z42.string().describe("The note (Thought) ID"),
1704
- find: z42.string().min(1).describe("Substring to search for. Literal \u2014 no regex."),
1705
- replace: z42.string().describe("Replacement string. May be empty to delete the match."),
1706
- all: z42.boolean().optional().describe("Replace all occurrences (default true). Pass false to replace only the first.")
1518
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
1519
+ 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.",
1520
+ inputSchema: z35.object({
1521
+ noteId: z35.string().describe("The note (Thought) ID"),
1522
+ find: z35.string().min(1).describe("Substring to search for. Literal - no regex."),
1523
+ replace: z35.string().describe("Replacement string. May be empty to delete the match."),
1524
+ all: z35.boolean().optional().describe("Replace all occurrences (default true). Pass false to replace only the first.")
1707
1525
  })
1708
1526
  },
1709
1527
  async ({ noteId, find, replace, all }) => {
@@ -1719,117 +1537,18 @@ function registerNoteFindReplace(server2, client2) {
1719
1537
  );
1720
1538
  }
1721
1539
 
1722
- // ../mcp-core/src/tools/canvas-add-element.ts
1723
- import { z as z43 } from "zod";
1724
- var ELEMENT_TYPES = [
1725
- "rectangle",
1726
- "ellipse",
1727
- "diamond",
1728
- "text",
1729
- "line",
1730
- "arrow",
1731
- "freehand",
1732
- "image",
1733
- "bookmark-card",
1734
- "entity-embed"
1735
- ];
1736
- function registerCanvasAddElement(server2, client2) {
1737
- server2.registerTool(
1738
- "naumu_canvas_add_element",
1739
- {
1740
- title: "Add Canvas Element",
1741
- annotations: { destructiveHint: true },
1742
- description: "Add a new element to a canvas. Other participants see your colored cursor at the element's center while it lands. The server fills in `id`, `version`, `fractionalIndex`, and `seed` automatically \u2014 pass only `type`, position (`x`, `y`), and size (`width`, `height`); other fields are optional and have sensible defaults (stroke #1e1e1e, no fill, opacity 1, etc.). For text elements, set `label` and `fontSize`. Coordinates are canvas-space (the same units the live editor uses).",
1743
- inputSchema: z43.object({
1744
- canvasId: z43.string().describe("The canvas ID"),
1745
- element: z43.object({
1746
- type: z43.enum(ELEMENT_TYPES).describe("Element shape"),
1747
- x: z43.number().describe("Top-left x coordinate in canvas space"),
1748
- y: z43.number().describe("Top-left y coordinate in canvas space"),
1749
- width: z43.number().describe("Width in canvas units"),
1750
- height: z43.number().describe("Height in canvas units"),
1751
- strokeColor: z43.string().optional().describe("Stroke color (hex). Default #1e1e1e."),
1752
- fillColor: z43.string().optional().describe('Fill color (hex) or "transparent". Default transparent.'),
1753
- strokeWidth: z43.number().optional().describe("Stroke width. Default 2."),
1754
- opacity: z43.number().min(0).max(1).optional().describe("0..1, default 1"),
1755
- roughness: z43.number().min(0).max(2).optional().describe("Hand-drawn roughness 0..2. Default 1."),
1756
- label: z43.string().optional().describe("Optional label/text content"),
1757
- labelFontSize: z43.number().optional().describe("Label font size"),
1758
- angle: z43.number().optional().describe("Rotation in radians. Default 0.")
1759
- }).passthrough().describe("Element fields. Pass only what you set \u2014 defaults fill the rest.")
1760
- })
1761
- },
1762
- async ({ canvasId, element }) => {
1763
- const data = await client2.post(`/api/canvases/${canvasId}/elements`, { element });
1764
- return {
1765
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1766
- };
1767
- }
1768
- );
1769
- }
1770
-
1771
- // ../mcp-core/src/tools/canvas-update-element.ts
1772
- import { z as z44 } from "zod";
1773
- function registerCanvasUpdateElement(server2, client2) {
1774
- server2.registerTool(
1775
- "naumu_canvas_update_element",
1776
- {
1777
- title: "Update Canvas Element",
1778
- annotations: { destructiveHint: true },
1779
- description: "Patch an existing canvas element. Only the fields you pass in `changes` are updated \u2014 `id`, `version`, `createdBy`, and `isDeleted` are server-managed and ignored if present. Useful for moving (`x`, `y`), resizing (`width`, `height`), recoloring (`strokeColor`, `fillColor`), or relabeling (`label`).",
1780
- inputSchema: z44.object({
1781
- canvasId: z44.string().describe("The canvas ID"),
1782
- elementId: z44.string().describe("The element ID returned by `naumu_canvas_add_element` or `naumu_get_canvas_elements`"),
1783
- changes: z44.record(z44.string(), z44.unknown()).describe("Partial element fields to merge in. Server bumps `version` automatically.")
1784
- })
1785
- },
1786
- async ({ canvasId, elementId, changes }) => {
1787
- const data = await client2.patch(
1788
- `/api/canvases/${canvasId}/elements/${elementId}`,
1789
- { changes }
1790
- );
1791
- return {
1792
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1793
- };
1794
- }
1795
- );
1796
- }
1797
-
1798
- // ../mcp-core/src/tools/canvas-remove-element.ts
1799
- import { z as z45 } from "zod";
1800
- function registerCanvasRemoveElement(server2, client2) {
1801
- server2.registerTool(
1802
- "naumu_canvas_remove_element",
1803
- {
1804
- title: "Remove Canvas Element",
1805
- annotations: { destructiveHint: true },
1806
- description: "Soft-delete a canvas element. The element is tombstoned (isDeleted=true) so concurrent edits don't resurrect it. 404 if the element id is not present on this canvas.",
1807
- inputSchema: z45.object({
1808
- canvasId: z45.string().describe("The canvas ID"),
1809
- elementId: z45.string().describe("The element ID to delete")
1810
- })
1811
- },
1812
- async ({ canvasId, elementId }) => {
1813
- const data = await client2.del(`/api/canvases/${canvasId}/elements/${elementId}`);
1814
- return {
1815
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1816
- };
1817
- }
1818
- );
1819
- }
1820
-
1821
1540
  // ../mcp-core/src/tools/create-note.ts
1822
- import { z as z46 } from "zod";
1541
+ import { z as z36 } from "zod";
1823
1542
  function registerCreateNote(server2, client2) {
1824
1543
  server2.registerTool(
1825
1544
  "naumu_create_note",
1826
1545
  {
1827
1546
  title: "Create Note",
1828
- annotations: { destructiveHint: true },
1829
- description: "Create a new empty note in a graph. Returns the new note row including its `id` \u2014 pass that id to `naumu_note_append` / `naumu_note_replace` to fill in the content. Bots can only create notes in their own graph.",
1830
- inputSchema: z46.object({
1831
- graphId: z46.string().describe("The graph ID to create the note in"),
1832
- title: z46.string().optional().describe("Optional title for the note")
1547
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
1548
+ description: "Create a new empty note in a graph; use when you need a fresh note to write into. Returns the new note row including its `id` - pass that id to `naumu_note_append` / `naumu_note_replace` to fill in the content. Bots can only create notes in their own graph.",
1549
+ inputSchema: z36.object({
1550
+ graphId: z36.string().describe("The graph ID to create the note in"),
1551
+ title: z36.string().optional().describe("Optional title for the note")
1833
1552
  })
1834
1553
  },
1835
1554
  async ({ graphId, title }) => {
@@ -1841,66 +1560,102 @@ function registerCreateNote(server2, client2) {
1841
1560
  );
1842
1561
  }
1843
1562
 
1844
- // ../mcp-core/src/tools/create-canvas.ts
1845
- import { z as z47 } from "zod";
1846
- function registerCreateCanvas(server2, client2) {
1847
- server2.registerTool(
1848
- "naumu_create_canvas",
1849
- {
1850
- title: "Create Canvas",
1851
- annotations: { destructiveHint: true },
1852
- description: "Create a new empty canvas in a graph. Returns the new canvas row including its `id` \u2014 pass that id to `naumu_canvas_add_element` to start drawing. Bots can only create canvases in their own graph.",
1853
- inputSchema: z47.object({
1854
- graphId: z47.string().describe("The graph ID to create the canvas in"),
1855
- title: z47.string().optional().describe("Optional title for the canvas")
1856
- })
1857
- },
1858
- async ({ graphId, title }) => {
1859
- const data = await client2.post("/api/canvases", { graphId, title });
1860
- return {
1861
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1862
- };
1863
- }
1864
- );
1865
- }
1866
-
1867
1563
  // ../mcp-core/src/tools/list-schema-violations.ts
1868
- import { z as z48 } from "zod";
1564
+ import { z as z37 } from "zod";
1565
+ var DEFAULT_EXAMPLE_LIMIT = 5;
1566
+ var rowsForKind = (violations, kind) => {
1567
+ const rows = [];
1568
+ for (const v of violations) {
1569
+ for (const issue of v.issues) {
1570
+ if (issue.kind !== kind) continue;
1571
+ rows.push({ nodeId: v.nodeId, label: v.label, type: v.type, message: issue.message });
1572
+ }
1573
+ }
1574
+ return rows;
1575
+ };
1576
+ var allKinds = (violations) => {
1577
+ const seen = /* @__PURE__ */ new Set();
1578
+ for (const v of violations) {
1579
+ for (const issue of v.issues) seen.add(issue.kind);
1580
+ }
1581
+ return [...seen];
1582
+ };
1869
1583
  function registerListSchemaViolations(server2, client2) {
1870
1584
  server2.registerTool(
1871
1585
  "naumu_list_schema_violations",
1872
1586
  {
1873
1587
  title: "List Schema Violations",
1874
- annotations: { readOnlyHint: true },
1875
- description: "List every schema-validation issue in a graph. Returns each node with issues and a summary by violation kind: parent_missing (schema expects a parent edge that does not exist), parent_multiple (more than one parent edge on a node that should have one), parent_mismatch (parent edge has wrong target type or relation label), unknown_relation (edge uses a relation label not defined in the schema), invalid_connection_target (edge connects to a type the schema does not allow for this source). Use for audits, import-verification, and CI-style checks after batch writes.",
1876
- inputSchema: z48.object({
1877
- graphId: z48.string().describe("The graph ID")
1588
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
1589
+ 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.",
1590
+ inputSchema: z37.object({
1591
+ graphId: z37.string().describe("The graph ID"),
1592
+ kind: z37.string().optional().describe(
1593
+ '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.'
1594
+ ),
1595
+ limit: z37.number().int().min(1).optional().describe(
1596
+ "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)."
1597
+ )
1878
1598
  })
1879
1599
  },
1880
- async ({ graphId }) => {
1600
+ async ({ graphId, kind, limit }) => {
1881
1601
  const data = await client2.get(
1882
1602
  `/api/graphs/${graphId}/schema/validation`
1883
1603
  );
1604
+ const { violations, summary } = data;
1605
+ if (kind) {
1606
+ const rows = rowsForKind(violations, kind);
1607
+ const capped = limit !== void 0 ? rows.slice(0, limit) : rows;
1608
+ const payload2 = {
1609
+ graphId,
1610
+ kind,
1611
+ nodeCount: summary.nodeCount,
1612
+ totalForKind: rows.length,
1613
+ returned: capped.length,
1614
+ truncated: capped.length < rows.length,
1615
+ rows: capped
1616
+ };
1617
+ return {
1618
+ content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }]
1619
+ };
1620
+ }
1621
+ const exampleLimit = limit ?? DEFAULT_EXAMPLE_LIMIT;
1622
+ const byKind = allKinds(violations).map((k) => {
1623
+ const rows = rowsForKind(violations, k);
1624
+ return {
1625
+ kind: k,
1626
+ count: summary.byKind[k] ?? rows.length,
1627
+ examples: rows.slice(0, exampleLimit)
1628
+ };
1629
+ }).sort((a, b) => b.count - a.count);
1630
+ const payload = {
1631
+ graphId,
1632
+ nodeCount: summary.nodeCount,
1633
+ nodesWithIssues: summary.nodesWithIssues,
1634
+ totalIssues: summary.totalIssues,
1635
+ exampleLimit,
1636
+ byKind,
1637
+ hint: summary.totalIssues === 0 ? "No violations \u2014 the graph conforms to its schema." : "Pass `kind` to list every node for one violation kind (use `limit` to cap rows)."
1638
+ };
1884
1639
  return {
1885
- content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
1640
+ content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
1886
1641
  };
1887
1642
  }
1888
1643
  );
1889
1644
  }
1890
1645
 
1891
1646
  // ../mcp-core/src/tools/list-dense-nodes.ts
1892
- import { z as z49 } from "zod";
1647
+ import { z as z38 } from "zod";
1893
1648
  function registerListDenseNodes(server2, client2) {
1894
1649
  server2.registerTool(
1895
1650
  "naumu_list_dense_nodes",
1896
1651
  {
1897
1652
  title: "List Dense Nodes",
1898
- annotations: { readOnlyHint: true },
1899
- description: 'Return nodes whose total edge count (in+out, non-system) is \u2265 minConnections, grouped by type. Built for /restructure hub detection: each row includes `same_typed_child_count` \u2014 the number of children of the SAME type as the node (the Naumu hub-pattern signal). 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. ["Feature","Company"]). Cheap to call \u2014 runs a single Cypher aggregation.',
1900
- inputSchema: z49.object({
1901
- graphId: z49.string().describe("The graph ID"),
1902
- minConnections: z49.number().int().min(1).describe("Minimum total edge count (in + out, excluding system relations). Typical: 10 for hub detection, 11 to count only hubs that exceed the round-4 \u226410 threshold."),
1903
- nodeTypes: z49.array(z49.string()).optional().describe("Optional list of node types to restrict the scan to.")
1653
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
1654
+ 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.',
1655
+ inputSchema: z38.object({
1656
+ graphId: z38.string().describe("The graph ID"),
1657
+ minConnections: z38.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."),
1658
+ nodeTypes: z38.array(z38.string()).optional().describe("Optional list of node types to restrict the scan to.")
1904
1659
  })
1905
1660
  },
1906
1661
  async ({ graphId, minConnections, nodeTypes }) => {
@@ -1918,19 +1673,19 @@ function registerListDenseNodes(server2, client2) {
1918
1673
  }
1919
1674
 
1920
1675
  // ../mcp-core/src/tools/list-node-connections.ts
1921
- import { z as z50 } from "zod";
1676
+ import { z as z39 } from "zod";
1922
1677
  function registerListNodeConnections(server2, client2) {
1923
1678
  server2.registerTool(
1924
1679
  "naumu_list_node_connections",
1925
1680
  {
1926
1681
  title: "List Node Connections",
1927
- annotations: { readOnlyHint: true },
1928
- description: 'Return a single node\'s edges (non-system) with the connected node on the other side. Used 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}}] }`.',
1929
- inputSchema: z50.object({
1930
- graphId: z50.string().describe("The graph ID"),
1931
- nodeId: z50.string().describe("The node ID to inspect"),
1932
- edgeType: z50.string().optional().describe('Restrict to a specific relation label (e.g. "ASSOCIATED_WITH"). Case-insensitive; non-alphanum chars are normalized.'),
1933
- direction: z50.enum(["in", "out", "both"]).optional().describe('Edge direction filter \u2014 "in" (incoming), "out" (outgoing), "both" (default).')
1682
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
1683
+ 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}}] }`.',
1684
+ inputSchema: z39.object({
1685
+ graphId: z39.string().describe("The graph ID"),
1686
+ nodeId: z39.string().describe("The node ID to inspect"),
1687
+ edgeType: z39.string().optional().describe('Restrict to a specific relation label (e.g. "ASSOCIATED_WITH"). Case-insensitive; non-alphanum chars are normalized.'),
1688
+ direction: z39.enum(["in", "out", "both"]).optional().describe('Edge direction filter - "in" (incoming), "out" (outgoing), "both" (default).')
1934
1689
  })
1935
1690
  },
1936
1691
  async ({ graphId, nodeId, edgeType, direction }) => {
@@ -1948,19 +1703,19 @@ function registerListNodeConnections(server2, client2) {
1948
1703
  }
1949
1704
 
1950
1705
  // ../mcp-core/src/tools/reparent.ts
1951
- import { z as z51 } from "zod";
1706
+ import { z as z40 } from "zod";
1952
1707
  function registerReparent(server2, client2) {
1953
1708
  server2.registerTool(
1954
1709
  "naumu_reparent",
1955
1710
  {
1956
1711
  title: "Reparent Node",
1957
- annotations: { destructiveHint: true },
1958
- description: 'Atomically swap a node\'s parent edge. 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** \u2014 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"}`. Use during /restructure to reparent children under newly-created mini-hubs.',
1959
- inputSchema: z51.object({
1960
- graphId: z51.string().describe("The graph ID"),
1961
- nodeId: z51.string().describe("The child node to reparent"),
1962
- newParentId: z51.string().describe("The new parent node id"),
1963
- newRelation: z51.string().describe('The new parent edge relation label (e.g. "PART_OF"). Must be valid per the schema for (child.type, relation, parent.type).')
1712
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
1713
+ 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"}`.',
1714
+ inputSchema: z40.object({
1715
+ graphId: z40.string().describe("The graph ID"),
1716
+ nodeId: z40.string().describe("The child node to reparent"),
1717
+ newParentId: z40.string().describe("The new parent node id"),
1718
+ newRelation: z40.string().describe('The new parent edge relation label (e.g. "PART_OF"). Must be valid per the schema for (child.type, relation, parent.type).')
1964
1719
  })
1965
1720
  },
1966
1721
  async ({ graphId, nodeId, newParentId, newRelation }) => {
@@ -1976,19 +1731,19 @@ function registerReparent(server2, client2) {
1976
1731
  }
1977
1732
 
1978
1733
  // ../mcp-core/src/tools/batch-reparent.ts
1979
- import { z as z52 } from "zod";
1734
+ import { z as z41 } from "zod";
1980
1735
  function registerBatchReparent(server2, client2) {
1981
1736
  server2.registerTool(
1982
1737
  "naumu_batch_reparent",
1983
1738
  {
1984
1739
  title: "Batch Reparent Nodes",
1985
- annotations: { destructiveHint: true },
1986
- description: 'Reparent 1\u201325 nodes onto a shared `newParentId` with the same `newRelation`. 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?}]`. Used to move a same-typed cluster under a freshly-created mini-hub in /restructure.',
1987
- inputSchema: z52.object({
1988
- graphId: z52.string().describe("The graph ID"),
1989
- newParentId: z52.string().describe("Parent node id every nodeId in the batch will be parented to"),
1990
- newRelation: z52.string().describe("Parent edge relation label (must be valid per schema for child.type \u2192 parent.type)"),
1991
- nodeIds: z52.array(z52.string()).min(1).max(25).describe("1\u201325 child node ids to reparent under `newParentId`")
1740
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
1741
+ 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?}]`.',
1742
+ inputSchema: z41.object({
1743
+ graphId: z41.string().describe("The graph ID"),
1744
+ newParentId: z41.string().describe("Parent node id every nodeId in the batch will be parented to"),
1745
+ newRelation: z41.string().describe("Parent edge relation label (must be valid per schema for child.type \u2192 parent.type)"),
1746
+ nodeIds: z41.array(z41.string()).min(1).max(25).describe("1\u201325 child node ids to reparent under `newParentId`")
1992
1747
  })
1993
1748
  },
1994
1749
  async ({ graphId, newParentId, newRelation, nodeIds }) => {
@@ -2005,7 +1760,7 @@ function registerBatchReparent(server2, client2) {
2005
1760
  }
2006
1761
 
2007
1762
  // ../mcp-core/src/tools/chatgpt-search.ts
2008
- import { z as z53 } from "zod";
1763
+ import { z as z42 } from "zod";
2009
1764
 
2010
1765
  // ../mcp-core/src/public-origin.ts
2011
1766
  function publicOrigin() {
@@ -2057,10 +1812,10 @@ function registerChatgptSearch(server2, client2) {
2057
1812
  "search",
2058
1813
  {
2059
1814
  title: "Search",
2060
- annotations: { readOnlyHint: true },
1815
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
2061
1816
  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.)",
2062
- inputSchema: z53.object({
2063
- query: z53.string().describe('Search query text. Mix synonyms and exact tokens freely (e.g. "auth login SSO 2fa").')
1817
+ inputSchema: z42.object({
1818
+ query: z42.string().describe('Search query text. Mix synonyms and exact tokens freely (e.g. "auth login SSO 2fa").')
2064
1819
  })
2065
1820
  },
2066
1821
  async ({ query }) => {
@@ -2092,7 +1847,7 @@ function registerChatgptSearch(server2, client2) {
2092
1847
  }
2093
1848
 
2094
1849
  // ../mcp-core/src/tools/chatgpt-fetch.ts
2095
- import { z as z54 } from "zod";
1850
+ import { z as z43 } from "zod";
2096
1851
  var NON_ATTRIBUTE_PROPS = /* @__PURE__ */ new Set([
2097
1852
  "id",
2098
1853
  "label",
@@ -2155,10 +1910,10 @@ function registerChatgptFetch(server2, client2) {
2155
1910
  "fetch",
2156
1911
  {
2157
1912
  title: "Fetch",
2158
- annotations: { readOnlyHint: true },
1913
+ annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
2159
1914
  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.",
2160
- inputSchema: z54.object({
2161
- id: z54.string().describe("A resource id from a previous `search` result, in the form `<graphId>:<nodeId>`.")
1915
+ inputSchema: z43.object({
1916
+ id: z43.string().describe("A resource id from a previous `search` result, in the form `<graphId>:<nodeId>`.")
2162
1917
  })
2163
1918
  },
2164
1919
  async ({ id }) => {
@@ -2212,8 +1967,6 @@ var TOOL_REGISTRARS = {
2212
1967
  naumu_search: registerSearch,
2213
1968
  naumu_filter: registerFilter,
2214
1969
  naumu_get_node: registerGetNode,
2215
- naumu_get_view: registerGetView,
2216
- naumu_list_view_nodes: registerListViewNodes,
2217
1970
  naumu_add_node: registerAddNode,
2218
1971
  naumu_update_node: registerUpdateNode,
2219
1972
  naumu_add_edge: registerAddEdge,
@@ -2221,14 +1974,10 @@ var TOOL_REGISTRARS = {
2221
1974
  naumu_remove_edge: registerRemoveEdge,
2222
1975
  naumu_remove_edges_bulk: registerRemoveEdgesBulk,
2223
1976
  naumu_ask: registerAsk,
2224
- naumu_get_ai_thread: registerGetAiThread,
2225
- naumu_traverse: registerTraverse,
2226
- naumu_list_canvases: registerListCanvases,
2227
- naumu_get_canvas_elements: registerGetCanvasElements,
2228
- naumu_get_canvas_image: registerGetCanvasImage,
1977
+ naumu_delegate: registerDelegate,
1978
+ // naumu_traverse omitted on purpose — backend stub returns 503 (see import note).
2229
1979
  naumu_post_message: registerPostMessage,
2230
1980
  naumu_read_thread: registerReadThread,
2231
- naumu_ask_naumu: registerAskNaumu,
2232
1981
  naumu_whoami: registerWhoami,
2233
1982
  naumu_list_threads: registerListThreads,
2234
1983
  naumu_get_thread: registerGetThread,
@@ -2244,11 +1993,7 @@ var TOOL_REGISTRARS = {
2244
1993
  naumu_note_delete_section: registerNoteDeleteSection,
2245
1994
  naumu_note_replace: registerNoteReplace,
2246
1995
  naumu_note_find_replace: registerNoteFindReplace,
2247
- naumu_canvas_add_element: registerCanvasAddElement,
2248
- naumu_canvas_update_element: registerCanvasUpdateElement,
2249
- naumu_canvas_remove_element: registerCanvasRemoveElement,
2250
1996
  naumu_create_note: registerCreateNote,
2251
- naumu_create_canvas: registerCreateCanvas,
2252
1997
  naumu_list_schema_violations: registerListSchemaViolations,
2253
1998
  naumu_list_dense_nodes: registerListDenseNodes,
2254
1999
  naumu_list_node_connections: registerListNodeConnections,