@atolis-hq/corum 0.1.36 → 0.1.38

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.
package/README.md CHANGED
@@ -301,10 +301,10 @@ Or if installed globally:
301
301
  | `list_nodes` | List graph nodes using a `filter` object with `templates`, `exclude_templates`, `component`, `state`, and `stability` |
302
302
  | `list_templates` | List loaded templates with summary metadata |
303
303
  | `get_template` | Return full details for a template |
304
- | `get_cluster` | Return a root node, its descendants, included external nodes, and edges |
304
+ | `get_cluster` | Return a node's structural contents. By default, schema and enum child nodes are collapsed into compact `schemas` and `enums` blocks on the root. Pass `collapse_schemas: false` to restore the full node-per-field representation |
305
305
  | `get_graph` | Return the semantic graph as `{ nodes, edges }`, excluding structural templates and structural edges by default |
306
306
  | `get_graph_metadata` | Return discoverable metadata: template names, node templates in use, edge types, and valid enum values |
307
- | `get_lineage` | Traverse lineage from one or more start nodes with depth, direction, and edge/node-type filters |
307
+ | `get_lineage` | Traverse lineage from one or more start nodes. Lean nodes and no `edges` by default; opt in to fuller payloads when needed |
308
308
  | `get_graph_summary` | Return high-level graph statistics: node count, component count, orphan breakdown, edge counts, diagnostics |
309
309
  | `search_nodes` | Fuzzy-search root-level nodes by ID, with optional template filters and property search |
310
310
  | `get_linked_fields` | Return `maps-to` edges touching fields owned by a root node |
@@ -313,12 +313,18 @@ Or if installed globally:
313
313
 
314
314
  All tools accept an optional `format` argument: `yaml` (default), `json`, or `toon`. All tools also accept `compact_keys: true` to shorten common keys before serialization, reducing token usage.
315
315
 
316
+ All node-returning MCP tools accept `include_provenance: true` to include `extractedFrom`, `lastModifiedAt`, `derivation`, and `derivedBy`. These fields are omitted by default. `schemaVersion` is never returned by MCP.
317
+
316
318
  Common notes:
317
319
  - `branch` is supported on graph-query tools when Corum is running against a source-backed graph.
318
320
  - `list_nodes` is a breaking-change surface from older builds: use `filter.templates` instead of top-level `template`.
319
321
  - `search_nodes` accepts `queries: string[]`.
320
- - `get_graph_metadata` is the quickest way to discover valid template names, edge types, lifecycle states, stabilities, lineage directions, and output formats before constructing other calls.
321
- - `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, and `reads_outbound_only`.
322
+ - `get_graph_metadata` should usually be your first call. Use `edge_types_in_use` to avoid traversing edge types that do not exist in the current graph.
323
+ - Prefer `search_nodes` over `list_nodes` for discovery. Use `list_nodes` when you need a full inventory under explicit filters.
324
+ - `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, `reads_outbound_only`, `lean`, and `include_edges`.
325
+ - `get_lineage` defaults to `lean: true` and `include_edges: false`. Lean lineage nodes contain only `id`, `origin_id`, `depth`, `via_edge_type`, and `via_node_id`.
326
+ - Pass multiple `node_ids` to `get_lineage` in one call instead of making separate traversal calls.
327
+ - Use `get_cluster` only when you need full structural contents for one node. By default it returns compact `schemas` and `enums` blocks on the root rather than individual field nodes, which keeps response size manageable for large aggregates. Use `get_lineage` for relationship traversal.
322
328
  - The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists; agents should treat naming and schema similarity as hypotheses and then verify via cluster inspection or source material.
323
329
 
324
330
  ## MCP Prompts
@@ -0,0 +1,169 @@
1
+ import { STRUCTURAL_EDGE_TYPES, STRUCTURAL_NODE_TEMPLATES } from './index.js';
2
+ const FIELD_EDGE_TYPES = new Set(['maps-to', 'derived-from']);
3
+ export function collapseClusterSchemas(graph, cluster) {
4
+ const rootId = cluster.root.id;
5
+ const rootPrefix = `${rootId}.`;
6
+ // Indexes keyed by local name or parent ID
7
+ const schemaChildIds = new Set();
8
+ const schemaNames = new Map(); // localName → exists
9
+ const enumNames = new Map(); // localName → exists
10
+ const fieldsByParentId = new Map(); // parentId → fieldName → Node
11
+ const valuesByEnumId = new Map(); // enumId → value names
12
+ const mappingsByParentId = new Map(); // parentSchemaId → mapName → Node
13
+ const semanticDescendants = [];
14
+ for (const n of cluster.descendants) {
15
+ if (!n.id.startsWith(rootPrefix)) {
16
+ semanticDescendants.push(n);
17
+ continue;
18
+ }
19
+ const suffix = n.id.slice(rootPrefix.length);
20
+ if (n.template === 'Schema') {
21
+ const m = /^schemas\.([^.]+)$/.exec(suffix);
22
+ if (m) {
23
+ schemaNames.set(m[1], true);
24
+ schemaChildIds.add(n.id);
25
+ continue;
26
+ }
27
+ }
28
+ if (n.template === 'EnumDefinition') {
29
+ const m = /^enums\.([^.]+)$/.exec(suffix);
30
+ if (m) {
31
+ enumNames.set(m[1], true);
32
+ schemaChildIds.add(n.id);
33
+ continue;
34
+ }
35
+ }
36
+ if (n.template === 'Field') {
37
+ const m = /^(.+)\.fields\.([^.]+)$/.exec(suffix);
38
+ if (m) {
39
+ const parentId = `${rootId}.${m[1]}`;
40
+ const existing = fieldsByParentId.get(parentId) ?? new Map();
41
+ existing.set(m[2], n);
42
+ fieldsByParentId.set(parentId, existing);
43
+ schemaChildIds.add(n.id);
44
+ continue;
45
+ }
46
+ }
47
+ if (n.template === 'EnumValue') {
48
+ const m = /^enums\.([^.]+)\.values\.([^.]+)$/.exec(suffix);
49
+ if (m) {
50
+ const enumId = `${rootId}.enums.${m[1]}`;
51
+ const values = valuesByEnumId.get(enumId) ?? [];
52
+ values.push(typeof n.properties.name === 'string' ? n.properties.name : m[2]);
53
+ valuesByEnumId.set(enumId, values);
54
+ schemaChildIds.add(n.id);
55
+ continue;
56
+ }
57
+ }
58
+ if (n.template === 'Mapping') {
59
+ const m = /^schemas\.([^.]+)\.mappings\.([^.]+)$/.exec(suffix);
60
+ if (m) {
61
+ const parentId = `${rootId}.schemas.${m[1]}`;
62
+ const existing = mappingsByParentId.get(parentId) ?? new Map();
63
+ existing.set(m[2], n);
64
+ mappingsByParentId.set(parentId, existing);
65
+ schemaChildIds.add(n.id);
66
+ continue;
67
+ }
68
+ }
69
+ semanticDescendants.push(n);
70
+ }
71
+ // Build schemas output
72
+ const schemas = {};
73
+ for (const localName of schemaNames.keys()) {
74
+ const schemaId = `${rootId}.schemas.${localName}`;
75
+ const fields = fieldsByParentId.get(schemaId) ?? new Map();
76
+ const mappings = mappingsByParentId.get(schemaId) ?? new Map();
77
+ const entry = {};
78
+ for (const [fieldName, fieldNode] of fields) {
79
+ entry[fieldName] = buildField(fieldNode, graph, rootId, mappings);
80
+ }
81
+ schemas[localName] = entry;
82
+ }
83
+ // Build enums output
84
+ const enums = {};
85
+ for (const localName of enumNames.keys()) {
86
+ const enumId = `${rootId}.enums.${localName}`;
87
+ enums[localName] = { values: valuesByEnumId.get(enumId) ?? [] };
88
+ }
89
+ // Filter edges: drop structural edge types and any edge originating from a schema child
90
+ const filteredEdges = cluster.edges.filter(e => !STRUCTURAL_EDGE_TYPES.has(e.type) && !schemaChildIds.has(e.from));
91
+ // Filter includedNodes: drop structural template nodes
92
+ const filteredIncludedNodes = cluster.includedNodes.filter(n => !STRUCTURAL_NODE_TEMPLATES.has(n.template));
93
+ return {
94
+ root: cluster.root,
95
+ schemas,
96
+ enums,
97
+ descendants: semanticDescendants,
98
+ edges: filteredEdges,
99
+ includedNodes: filteredIncludedNodes,
100
+ };
101
+ }
102
+ function buildField(fieldNode, graph, rootId, parentMappings) {
103
+ const props = fieldNode.properties;
104
+ const isArray = props.collection === 'array';
105
+ const isNullable = props.nullable === true;
106
+ let field = {};
107
+ const ref = typeof props.$ref === 'string' ? props.$ref : undefined;
108
+ if (ref?.startsWith('#/mappings/')) {
109
+ const mapName = ref.slice('#/mappings/'.length);
110
+ const mapNode = parentMappings.get(mapName);
111
+ if (mapNode) {
112
+ field = buildMappingField(mapNode, graph);
113
+ }
114
+ else {
115
+ field = { $ref: ref };
116
+ }
117
+ }
118
+ else if (ref) {
119
+ field = { $ref: ref };
120
+ if (isArray)
121
+ field.collection = 'array';
122
+ }
123
+ else if (typeof props.type === 'string') {
124
+ field = { type: props.type };
125
+ if (isArray)
126
+ field.collection = 'array';
127
+ }
128
+ if (isNullable)
129
+ field.nullable = true;
130
+ // Gather outbound field edges that cross the cluster boundary
131
+ const clusterPrefix = `${rootId}.`;
132
+ const fieldEdges = {};
133
+ for (const e of graph.edgesByFrom.get(fieldNode.id) ?? []) {
134
+ if (!FIELD_EDGE_TYPES.has(e.type))
135
+ continue;
136
+ if (e.to.startsWith(clusterPrefix))
137
+ continue;
138
+ const targets = fieldEdges[e.type] ?? [];
139
+ targets.push(e.to);
140
+ fieldEdges[e.type] = targets;
141
+ }
142
+ if (Object.keys(fieldEdges).length > 0)
143
+ field.edges = fieldEdges;
144
+ return field;
145
+ }
146
+ function buildMappingField(mapNode, graph) {
147
+ const props = mapNode.properties;
148
+ const key = typeof props['key-type'] === 'string' ? props['key-type'] : 'string';
149
+ const isArrayValue = props['value-collection'] === 'array';
150
+ let valueField = {};
151
+ if (typeof props.type === 'string') {
152
+ valueField = { type: props.type };
153
+ }
154
+ else if (typeof props.$ref === 'string') {
155
+ const ref = props.$ref;
156
+ const refNode = graph.nodesById.get(ref);
157
+ if (refNode?.template === 'Mapping') {
158
+ // Nested mapping — recurse once (no further recursion guard needed for realistic depths)
159
+ valueField = buildMappingField(refNode, graph);
160
+ }
161
+ else {
162
+ valueField = { $ref: ref };
163
+ }
164
+ }
165
+ const value = isArrayValue
166
+ ? { type: 'array', items: valueField }
167
+ : valueField;
168
+ return { type: 'map', key, value };
169
+ }
@@ -9,6 +9,7 @@ import { QueryError } from '../schema/index.js';
9
9
  import { createGraphRuntimeConfig } from '../source/config.js';
10
10
  import { startGraphFileWatcher, startWebServer } from '../web/server.js';
11
11
  import { USAGE_GUIDE_PROMPT } from './prompts/usage-guide.js';
12
+ import { collapseClusterSchemas } from '../graph/schema-collapse.js';
12
13
  import { compactKeys, getSerializer } from './serializers.js';
13
14
  const EDGE_TYPES = [
14
15
  'triggers',
@@ -56,19 +57,92 @@ function parseListNodesFilter(value) {
56
57
  : toStringArray(filterArg.stability),
57
58
  };
58
59
  }
60
+ function includesProvenance(args) {
61
+ return args.include_provenance === true || args.includeProvenance === true;
62
+ }
63
+ function summarizeNode(node, includeProvenance) {
64
+ return {
65
+ id: node.id,
66
+ template: node.template,
67
+ component: node.component,
68
+ state: node.state,
69
+ stability: node.stability,
70
+ ...(includeProvenance ? withProvenance(node) : {}),
71
+ };
72
+ }
73
+ function withProvenance(node) {
74
+ return {
75
+ ...(node.extractedFrom !== undefined ? { extractedFrom: node.extractedFrom } : {}),
76
+ ...(node.lastModifiedAt !== undefined ? { lastModifiedAt: node.lastModifiedAt } : {}),
77
+ ...(node.derivation !== undefined ? { derivation: node.derivation } : {}),
78
+ ...(node.derivedBy !== undefined ? { derivedBy: node.derivedBy } : {}),
79
+ };
80
+ }
81
+ function fullNode(node, includeProvenance) {
82
+ return {
83
+ id: node.id,
84
+ template: node.template,
85
+ component: node.component,
86
+ state: node.state,
87
+ stability: node.stability,
88
+ properties: node.properties,
89
+ ...(includeProvenance ? withProvenance(node) : {}),
90
+ };
91
+ }
92
+ function mapEdge(edge, includeProvenance) {
93
+ const out = {
94
+ id: edge.id,
95
+ from: edge.from,
96
+ to: edge.to,
97
+ type: edge.type,
98
+ state: edge.state,
99
+ stability: edge.stability,
100
+ };
101
+ if (edge.notes !== undefined)
102
+ out.notes = edge.notes;
103
+ if (includeProvenance) {
104
+ if (edge.derivation !== undefined)
105
+ out.derivation = edge.derivation;
106
+ if (edge.derivedBy !== undefined)
107
+ out.derivedBy = edge.derivedBy;
108
+ }
109
+ return out;
110
+ }
111
+ function mapLineageNode(node, includeProvenance, lean) {
112
+ const base = {
113
+ id: String(node.id),
114
+ origin_id: String(node.origin_id),
115
+ depth: Number(node.depth),
116
+ via_edge_type: String(node.via_edge_type),
117
+ via_node_id: String(node.via_node_id),
118
+ };
119
+ if (lean)
120
+ return base;
121
+ return {
122
+ ...base,
123
+ template: String(node.template),
124
+ component: String(node.component),
125
+ state: String(node.state),
126
+ stability: String(node.stability),
127
+ properties: (node.properties ?? {}),
128
+ ...(includeProvenance
129
+ ? {
130
+ ...(node.extractedFrom !== undefined ? { extractedFrom: node.extractedFrom } : {}),
131
+ ...(node.lastModifiedAt !== undefined ? { lastModifiedAt: node.lastModifiedAt } : {}),
132
+ ...(node.derivation !== undefined ? { derivation: node.derivation } : {}),
133
+ ...(node.derivedBy !== undefined ? { derivedBy: node.derivedBy } : {}),
134
+ }
135
+ : {}),
136
+ };
137
+ }
59
138
  export function createMcpHandlers(graph, source, cache) {
60
139
  const resolveMulti = (src) => cache ? cache.get() : loadMultiGraph({ source: src });
61
140
  return {
62
141
  list_nodes(args) {
63
142
  const run = (targetGraph) => {
64
143
  const filter = parseListNodesFilter(args.filter);
65
- const summaries = listNodes(targetGraph, filter).map(node => ({
66
- id: node.id,
67
- template: node.template,
68
- component: node.component,
69
- state: node.state,
70
- stability: node.stability,
71
- }));
144
+ const summaries = listNodes(targetGraph, filter)
145
+ .map(node => summarizeNode(node, includesProvenance(args)));
72
146
  return formatResult(summaries, args.format, getCompactKeys(args));
73
147
  };
74
148
  if (hasBranch(args)) {
@@ -107,7 +181,15 @@ export function createMcpHandlers(graph, source, cache) {
107
181
  offset: typeof args.offset === 'number' ? args.offset : 0,
108
182
  searchProperties: args.search_properties === true,
109
183
  };
110
- return formatResult(searchNodes(targetGraph, queries, options), args.format, getCompactKeys(args));
184
+ const wantFull = args.full_nodes === true;
185
+ const incProv = includesProvenance(args);
186
+ const results = searchNodes(targetGraph, queries, options).map(result => ({
187
+ score: result.score,
188
+ node: wantFull
189
+ ? fullNode(result.node, incProv)
190
+ : summarizeNode(result.node, incProv),
191
+ }));
192
+ return formatResult(results, args.format, getCompactKeys(args));
111
193
  };
112
194
  if (hasBranch(args) && source) {
113
195
  return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
@@ -164,12 +246,36 @@ export function createMcpHandlers(graph, source, cache) {
164
246
  const edgeTypes = parseEdgeTypes(args.edge_types)
165
247
  ?? [...SEMANTIC_EDGE_TYPES];
166
248
  const cluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
249
+ const includeProvenance = includesProvenance(args);
250
+ const collapseSchemas = args.collapse_schemas !== false;
251
+ let clusterPayload;
252
+ if (collapseSchemas) {
253
+ const collapsed = collapseClusterSchemas(targetGraph, cluster);
254
+ clusterPayload = {
255
+ root: {
256
+ ...fullNode(collapsed.root, includeProvenance),
257
+ ...(Object.keys(collapsed.schemas).length > 0 ? { schemas: collapsed.schemas } : {}),
258
+ ...(Object.keys(collapsed.enums).length > 0 ? { enums: collapsed.enums } : {}),
259
+ },
260
+ descendants: collapsed.descendants.map(node => fullNode(node, includeProvenance)),
261
+ includedNodes: collapsed.includedNodes.map(node => fullNode(node, includeProvenance)),
262
+ edges: collapsed.edges.map(e => mapEdge(e, includeProvenance)),
263
+ };
264
+ }
265
+ else {
266
+ clusterPayload = {
267
+ root: fullNode(cluster.root, includeProvenance),
268
+ descendants: cluster.descendants.map(node => fullNode(node, includeProvenance)),
269
+ includedNodes: cluster.includedNodes.map(node => fullNode(node, includeProvenance)),
270
+ edges: cluster.edges.map(e => mapEdge(e, includeProvenance)),
271
+ };
272
+ }
167
273
  if (overlayRefs.length === 0 || !source || !branchRef) {
168
- return formatResult(cluster, args.format, getCompactKeys(args));
274
+ return formatResult(clusterPayload, args.format, getCompactKeys(args));
169
275
  }
170
276
  const multi = await resolveMulti(source);
171
277
  const overlay = computeClusterOverlay(multi, branchRef, overlayRefs, String(args.node_id));
172
- return formatResult({ ...cluster, overlay }, args.format, getCompactKeys(args));
278
+ return formatResult({ ...clusterPayload, overlay }, args.format, getCompactKeys(args));
173
279
  };
174
280
  const branchRef = hasBranch(args) ? String(args.branch) : undefined;
175
281
  if (branchRef) {
@@ -184,23 +290,21 @@ export function createMcpHandlers(graph, source, cache) {
184
290
  ? { ...filter, excludeTemplates: [...STRUCTURAL_NODE_TEMPLATES] }
185
291
  : filter;
186
292
  const nodes = listNodes(targetGraph, effectiveFilter)
187
- .map(node => ({
188
- id: node.id,
189
- template: node.template,
190
- component: node.component,
191
- state: node.state,
192
- stability: node.stability,
193
- }));
194
- const nodeIds = new Set(nodes.map(node => node.id));
195
- const edges = [];
196
- for (const edgeList of targetGraph.edgesByFrom.values()) {
197
- for (const edge of edgeList) {
198
- if (!SEMANTIC_EDGE_TYPES.has(edge.type) || !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
199
- continue;
200
- edges.push({ id: edge.id, from: edge.from, to: edge.to, type: edge.type });
293
+ .map(node => summarizeNode(node, includesProvenance(args)));
294
+ const payload = { nodes };
295
+ if (args.include_edges === true) {
296
+ const nodeIds = new Set(nodes.map(node => node.id));
297
+ const edges = [];
298
+ for (const edgeList of targetGraph.edgesByFrom.values()) {
299
+ for (const edge of edgeList) {
300
+ if (!SEMANTIC_EDGE_TYPES.has(edge.type) || !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
301
+ continue;
302
+ edges.push({ id: edge.id, from: edge.from, to: edge.to, type: edge.type });
303
+ }
201
304
  }
305
+ payload.edges = edges;
202
306
  }
203
- return formatResult({ nodes, edges }, args.format, getCompactKeys(args));
307
+ return formatResult(payload, args.format, getCompactKeys(args));
204
308
  };
205
309
  if (hasBranch(args) && source) {
206
310
  return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
@@ -222,15 +326,18 @@ export function createMcpHandlers(graph, source, cache) {
222
326
  for (const edge of edgeList)
223
327
  edgeTypesInUse.add(edge.type);
224
328
  }
329
+ const includeStatic = args.include_static_enums === true;
225
330
  return formatResult({
226
331
  template_names: [...targetGraph.templates.keys()].sort(),
227
332
  node_templates_in_use: [...nodeTemplatesInUse].sort(),
228
333
  edge_types_in_use: [...edgeTypesInUse].sort(),
229
- valid_edge_types: [...EDGE_TYPES],
230
- states: [...STATE_VALUES],
231
- stabilities: [...STABILITY_VALUES],
232
- lineage_directions: [...LINEAGE_DIRECTIONS],
233
- output_formats: [...OUTPUT_FORMATS],
334
+ ...(includeStatic ? {
335
+ valid_edge_types: [...EDGE_TYPES],
336
+ states: [...STATE_VALUES],
337
+ stabilities: [...STABILITY_VALUES],
338
+ lineage_directions: [...LINEAGE_DIRECTIONS],
339
+ output_formats: [...OUTPUT_FORMATS],
340
+ } : {}),
234
341
  }, args.format, getCompactKeys(args));
235
342
  };
236
343
  if (hasBranch(args) && source) {
@@ -262,7 +369,18 @@ export function createMcpHandlers(graph, source, cache) {
262
369
  includeDanglingEdges: args.include_dangling_edges === true,
263
370
  readsOutboundOnly: args.reads_outbound_only !== false,
264
371
  };
265
- return formatResult(getLineage(targetGraph, nodeIds, options), args.format, getCompactKeys(args));
372
+ const lineage = getLineage(targetGraph, nodeIds, options);
373
+ const lean = args.lean !== false;
374
+ const includeEdges = args.include_edges === true;
375
+ const includeProvenance = includesProvenance(args);
376
+ const payload = {
377
+ nodes: lineage.nodes.map(node => mapLineageNode(node, includeProvenance, lean)),
378
+ };
379
+ if (includeEdges)
380
+ payload.edges = lineage.edges.map(e => mapEdge(e, includeProvenance));
381
+ if (args.include_dangling_edges === true && lineage.dangling_edges)
382
+ payload.dangling_edges = lineage.dangling_edges;
383
+ return formatResult(payload, args.format, getCompactKeys(args));
266
384
  };
267
385
  if (hasBranch(args) && source) {
268
386
  return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
@@ -275,7 +393,14 @@ export function createMcpHandlers(graph, source, cache) {
275
393
  }
276
394
  },
277
395
  get_linked_fields(args) {
278
- const run = (targetGraph) => formatResult(getLinkedFields(targetGraph, String(args.node_id)), args.format, getCompactKeys(args));
396
+ const run = (targetGraph) => {
397
+ const linked = getLinkedFields(targetGraph, String(args.node_id));
398
+ const incProv = includesProvenance(args);
399
+ return formatResult({
400
+ edges: linked.edges.map(e => mapEdge(e, incProv)),
401
+ nodes: linked.nodes.map(node => fullNode(node, incProv)),
402
+ }, args.format, getCompactKeys(args));
403
+ };
279
404
  if (hasBranch(args)) {
280
405
  return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
281
406
  }
@@ -347,6 +472,242 @@ function errorResult(err) {
347
472
  const message = err instanceof QueryError ? err.message : String(err);
348
473
  return { content: [{ type: 'text', text: message }], isError: true };
349
474
  }
475
+ export function getMcpToolDefinitions() {
476
+ return [
477
+ {
478
+ name: 'list_nodes',
479
+ description: 'List nodes in the graph. Returns id, template, component, state, stability for each matched node.',
480
+ inputSchema: {
481
+ type: 'object',
482
+ properties: {
483
+ filter: {
484
+ type: 'object',
485
+ description: 'Filter criteria',
486
+ properties: {
487
+ templates: {
488
+ type: 'array',
489
+ items: { type: 'string' },
490
+ description: 'Include only these template types (OR semantics)',
491
+ },
492
+ exclude_templates: {
493
+ type: 'array',
494
+ items: { type: 'string' },
495
+ description: 'Exclude these template types',
496
+ },
497
+ component: { type: 'string', description: 'Filter by component name' },
498
+ state: {
499
+ description: 'Filter by lifecycle state as a string or array',
500
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
501
+ },
502
+ stability: {
503
+ description: 'Filter by stability as a string or array',
504
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
505
+ },
506
+ },
507
+ },
508
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
509
+ branch: { type: 'string', description: 'Branch ref to load nodes from' },
510
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
511
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
512
+ },
513
+ },
514
+ },
515
+ {
516
+ name: 'list_templates',
517
+ description: 'List loaded graph templates. Returns name, version, core, abstract, extends, and description for each template.',
518
+ inputSchema: {
519
+ type: 'object',
520
+ properties: {
521
+ branch: { type: 'string', description: 'Branch ref to load templates from' },
522
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
523
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
524
+ },
525
+ },
526
+ },
527
+ {
528
+ name: 'get_template',
529
+ description: 'Get full details for a loaded graph template.',
530
+ inputSchema: {
531
+ type: 'object',
532
+ required: ['name'],
533
+ properties: {
534
+ name: { type: 'string', description: 'Template name' },
535
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
536
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
537
+ },
538
+ },
539
+ },
540
+ {
541
+ name: 'get_cluster',
542
+ description: 'Use when you need the full structural contents of a single node - its schema, fields, and owned children. Not suited for following relationships across the graph; use get_lineage for that. Note: large aggregates may exceed response size limits.',
543
+ inputSchema: {
544
+ type: 'object',
545
+ required: ['node_id'],
546
+ properties: {
547
+ node_id: { type: 'string', description: 'Fully qualified node ID' },
548
+ edge_types: {
549
+ type: 'array',
550
+ items: { type: 'string' },
551
+ description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
552
+ },
553
+ include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the cluster. Default false.' },
554
+ reads_outbound_only: { type: 'boolean', description: 'Restrict reads edges to outbound only. Default true.' },
555
+ collapse_schemas: { type: 'boolean', description: 'Collapse schema/enum child nodes into compact schemas and enums blocks on the root. Structural edges and schema child nodes are removed from descendants. Default true.' },
556
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
557
+ branch: { type: 'string', description: 'Branch ref to load the cluster from' },
558
+ overlay_refs: {
559
+ type: 'array',
560
+ items: { type: 'string' },
561
+ description: 'Branch refs to overlay. Returns ghost field data alongside the cluster.',
562
+ },
563
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
564
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
565
+ },
566
+ },
567
+ },
568
+ {
569
+ name: 'get_graph',
570
+ description: 'Return semantic nodes (and optionally edges) across the graph. Excludes structural templates and structural edge types by default. Pass include_edges: true to include the semantic edge list.',
571
+ inputSchema: {
572
+ type: 'object',
573
+ properties: {
574
+ filter: {
575
+ type: 'object',
576
+ properties: {
577
+ templates: { type: 'array', items: { type: 'string' } },
578
+ exclude_templates: { type: 'array', items: { type: 'string' } },
579
+ component: { type: 'string' },
580
+ state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
581
+ stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
582
+ },
583
+ },
584
+ include_edges: { type: 'boolean', description: 'Include the semantic edge list in the response. Default false.' },
585
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
586
+ branch: { type: 'string', description: 'Branch ref to load the graph from' },
587
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
588
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
589
+ },
590
+ },
591
+ },
592
+ {
593
+ name: 'get_graph_metadata',
594
+ description: 'Return discoverable graph metadata: template names, node templates in use, edge types in use. Call this first before making traversal queries. The edge_types_in_use field tells you which edge types are actually modelled in the current graph - there is no value traversing edge types that have no entries. Pass include_static_enums: true to also receive valid_edge_types, states, stabilities, lineage_directions, and output_formats.',
595
+ inputSchema: {
596
+ type: 'object',
597
+ properties: {
598
+ include_static_enums: { type: 'boolean', description: 'Include static enum reference fields (valid_edge_types, states, stabilities, lineage_directions, output_formats). Default false.' },
599
+ branch: { type: 'string', description: 'Branch ref to load metadata from' },
600
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
601
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
602
+ },
603
+ },
604
+ },
605
+ {
606
+ name: 'get_lineage',
607
+ description: 'Traverse the graph from one or more origin nodes via BFS and return annotated lineage results. Pass multiple node_ids to expand all origins in parallel in a single call rather than making separate calls - results are merged and deduplicated automatically.\n\nCommon patterns:\n- Event fan-out - direction: downstream, depth: 2 from an event node to see all triggered commands and the operations they invoke.\n- Find all writers to an aggregate - direction: upstream from a DomainModel node to see every command and operation that writes to it.\n- Full event chain - direction: downstream, depth: 3 or more to trace event -> command -> operation -> produced event chains.',
608
+ inputSchema: {
609
+ type: 'object',
610
+ required: ['node_ids'],
611
+ properties: {
612
+ node_ids: {
613
+ type: 'array',
614
+ items: { type: 'string' },
615
+ description: 'Fully-qualified IDs of origin nodes. All expand in parallel.',
616
+ },
617
+ depth: { type: 'number', description: 'Max hops. Default 2.' },
618
+ direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: 'Traversal direction. Default downstream.' },
619
+ edge_types: { type: 'array', items: { type: 'string' }, description: 'Edge types to traverse. Default: all non-structural.' },
620
+ node_types: { type: 'array', items: { type: 'string' }, description: 'Allowlist of node templates.' },
621
+ exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Denylist of node templates.' },
622
+ include_dangling_edges: { type: 'boolean', description: 'Include dangling edges in the response when present. Default false.' },
623
+ reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads edges in upstream traversal. Default true.' },
624
+ lean: { type: 'boolean', description: 'Return minimal lineage node shape. Default true.' },
625
+ include_edges: { type: 'boolean', description: 'Include the edges list in the response. Default false.' },
626
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
627
+ branch: { type: 'string', description: 'Branch ref to load the lineage from' },
628
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
629
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
630
+ },
631
+ },
632
+ },
633
+ {
634
+ name: 'get_linked_fields',
635
+ description: 'Get all maps-to edges touching fields owned by the given root node.',
636
+ inputSchema: {
637
+ type: 'object',
638
+ required: ['node_id'],
639
+ properties: {
640
+ node_id: { type: 'string', description: 'Fully qualified root node ID' },
641
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
642
+ branch: { type: 'string', description: 'Branch ref to load linked fields from' },
643
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
644
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
645
+ },
646
+ },
647
+ },
648
+ {
649
+ name: 'get_graph_summary',
650
+ description: 'Return high-level statistics: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
651
+ inputSchema: {
652
+ type: 'object',
653
+ properties: {
654
+ branch: { type: 'string', description: 'Branch ref to load the summary from' },
655
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
656
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
657
+ },
658
+ },
659
+ },
660
+ {
661
+ name: 'search_nodes',
662
+ description: 'Fuzzy search for root-level nodes by ID segments. Returns slim node summaries (id, template, component, state, stability) by default. Pass full_nodes: true to include properties. Prefer this over list_nodes when you have a domain term to search for - it returns ranked, targeted results without noise. Use list_nodes only when you need a complete inventory of nodes matching specific filter criteria.',
663
+ inputSchema: {
664
+ type: 'object',
665
+ required: ['queries'],
666
+ properties: {
667
+ queries: {
668
+ type: 'array',
669
+ items: { type: 'string' },
670
+ description: 'Search terms. OR semantics; any matching term qualifies the node.',
671
+ },
672
+ templates: { type: 'array', items: { type: 'string' }, description: 'Include only these template types.' },
673
+ exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these template types.' },
674
+ page_size: { type: 'number', description: 'Max results to return. Default 10.' },
675
+ offset: { type: 'number', description: 'Result offset for pagination. Default 0.' },
676
+ search_properties: { type: 'boolean', description: 'Also match name, description, and x-aka properties.' },
677
+ full_nodes: { type: 'boolean', description: 'Include properties on each result node. Default false.' },
678
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
679
+ branch: { type: 'string', description: 'Branch ref to search within' },
680
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
681
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
682
+ },
683
+ },
684
+ },
685
+ {
686
+ name: 'list_branches',
687
+ description: 'List branches available from the configured graph source and their load status.',
688
+ inputSchema: {
689
+ type: 'object',
690
+ properties: {
691
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
692
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
693
+ },
694
+ },
695
+ },
696
+ {
697
+ name: 'diff_branch',
698
+ description: 'Diff a branch against the default branch.',
699
+ inputSchema: {
700
+ type: 'object',
701
+ required: ['branch'],
702
+ properties: {
703
+ branch: { type: 'string', description: 'Branch ref to diff against the default branch' },
704
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
705
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
706
+ },
707
+ },
708
+ },
709
+ ];
710
+ }
350
711
  export async function startMcpServer(options = {}) {
351
712
  const { noWeb = false, watch = false } = options;
352
713
  const config = createGraphRuntimeConfig();
@@ -397,228 +758,7 @@ export async function startMcpServer(options = {}) {
397
758
  };
398
759
  });
399
760
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
400
- tools: [
401
- {
402
- name: 'list_nodes',
403
- description: 'List nodes in the graph. Returns id, template, component, state, stability for each matched node.',
404
- inputSchema: {
405
- type: 'object',
406
- properties: {
407
- filter: {
408
- type: 'object',
409
- description: 'Filter criteria',
410
- properties: {
411
- templates: {
412
- type: 'array',
413
- items: { type: 'string' },
414
- description: 'Include only these template types (OR semantics)',
415
- },
416
- exclude_templates: {
417
- type: 'array',
418
- items: { type: 'string' },
419
- description: 'Exclude these template types',
420
- },
421
- component: { type: 'string', description: 'Filter by component name' },
422
- state: {
423
- description: 'Filter by lifecycle state as a string or array',
424
- oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
425
- },
426
- stability: {
427
- description: 'Filter by stability as a string or array',
428
- oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
429
- },
430
- },
431
- },
432
- branch: { type: 'string', description: 'Branch ref to load nodes from' },
433
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
434
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
435
- },
436
- },
437
- },
438
- {
439
- name: 'list_templates',
440
- description: 'List loaded graph templates. Returns name, version, core, abstract, extends, and description for each template.',
441
- inputSchema: {
442
- type: 'object',
443
- properties: {
444
- branch: { type: 'string', description: 'Branch ref to load templates from' },
445
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
446
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
447
- },
448
- },
449
- },
450
- {
451
- name: 'get_template',
452
- description: 'Get full details for a loaded graph template.',
453
- inputSchema: {
454
- type: 'object',
455
- required: ['name'],
456
- properties: {
457
- name: { type: 'string', description: 'Template name' },
458
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
459
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
460
- },
461
- },
462
- },
463
- {
464
- name: 'get_cluster',
465
- description: 'Get the full cluster for a root node.',
466
- inputSchema: {
467
- type: 'object',
468
- required: ['node_id'],
469
- properties: {
470
- node_id: { type: 'string', description: 'Fully qualified node ID' },
471
- edge_types: {
472
- type: 'array',
473
- items: { type: 'string' },
474
- description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
475
- },
476
- include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the cluster. Default false.' },
477
- reads_outbound_only: { type: 'boolean', description: 'Restrict reads edges to outbound only. Default true.' },
478
- branch: { type: 'string', description: 'Branch ref to load the cluster from' },
479
- overlay_refs: {
480
- type: 'array',
481
- items: { type: 'string' },
482
- description: 'Branch refs to overlay. Returns ghost field data alongside the cluster.',
483
- },
484
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
485
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
486
- },
487
- },
488
- },
489
- {
490
- name: 'get_graph',
491
- description: 'Return all semantic nodes and edges. Excludes structural templates and structural edge types by default.',
492
- inputSchema: {
493
- type: 'object',
494
- properties: {
495
- filter: {
496
- type: 'object',
497
- properties: {
498
- templates: { type: 'array', items: { type: 'string' } },
499
- exclude_templates: { type: 'array', items: { type: 'string' } },
500
- component: { type: 'string' },
501
- state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
502
- stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
503
- },
504
- },
505
- branch: { type: 'string', description: 'Branch ref to load the graph from' },
506
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
507
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
508
- },
509
- },
510
- },
511
- {
512
- name: 'get_graph_metadata',
513
- description: 'Return discoverable graph metadata: template names, node templates in use, edge types, and valid enum values.',
514
- inputSchema: {
515
- type: 'object',
516
- properties: {
517
- branch: { type: 'string', description: 'Branch ref to load metadata from' },
518
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
519
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
520
- },
521
- },
522
- },
523
- {
524
- name: 'get_lineage',
525
- description: 'Traverse the graph from one or more origin nodes via BFS and return annotated lineage results.',
526
- inputSchema: {
527
- type: 'object',
528
- required: ['node_ids'],
529
- properties: {
530
- node_ids: {
531
- type: 'array',
532
- items: { type: 'string' },
533
- description: 'Fully-qualified IDs of origin nodes. All expand in parallel.',
534
- },
535
- depth: { type: 'number', description: 'Max hops. Default 2.' },
536
- direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: 'Traversal direction. Default downstream.' },
537
- edge_types: { type: 'array', items: { type: 'string' }, description: 'Edge types to traverse. Default: all non-structural.' },
538
- node_types: { type: 'array', items: { type: 'string' }, description: 'Allowlist of node templates.' },
539
- exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Denylist of node templates.' },
540
- include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the result set. Default false.' },
541
- reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads edges in upstream traversal. Default true.' },
542
- branch: { type: 'string', description: 'Branch ref to load the lineage from' },
543
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
544
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
545
- },
546
- },
547
- },
548
- {
549
- name: 'get_linked_fields',
550
- description: 'Get all maps-to edges touching fields owned by the given root node.',
551
- inputSchema: {
552
- type: 'object',
553
- required: ['node_id'],
554
- properties: {
555
- node_id: { type: 'string', description: 'Fully qualified root node ID' },
556
- branch: { type: 'string', description: 'Branch ref to load linked fields from' },
557
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
558
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
559
- },
560
- },
561
- },
562
- {
563
- name: 'get_graph_summary',
564
- description: 'Return high-level statistics: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
565
- inputSchema: {
566
- type: 'object',
567
- properties: {
568
- branch: { type: 'string', description: 'Branch ref to load the summary from' },
569
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
570
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
571
- },
572
- },
573
- },
574
- {
575
- name: 'search_nodes',
576
- description: 'Fuzzy search for root-level nodes by ID segments. Returns ranked results with score.',
577
- inputSchema: {
578
- type: 'object',
579
- required: ['queries'],
580
- properties: {
581
- queries: {
582
- type: 'array',
583
- items: { type: 'string' },
584
- description: 'Search terms. OR semantics; any matching term qualifies the node.',
585
- },
586
- templates: { type: 'array', items: { type: 'string' }, description: 'Include only these template types.' },
587
- exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these template types.' },
588
- page_size: { type: 'number', description: 'Max results to return. Default 10.' },
589
- offset: { type: 'number', description: 'Result offset for pagination. Default 0.' },
590
- search_properties: { type: 'boolean', description: 'Also match name, description, and x-aka properties.' },
591
- branch: { type: 'string', description: 'Branch ref to search within' },
592
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
593
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
594
- },
595
- },
596
- },
597
- {
598
- name: 'list_branches',
599
- description: 'List branches available from the configured graph source and their load status.',
600
- inputSchema: {
601
- type: 'object',
602
- properties: {
603
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
604
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
605
- },
606
- },
607
- },
608
- {
609
- name: 'diff_branch',
610
- description: 'Diff a branch against the default branch.',
611
- inputSchema: {
612
- type: 'object',
613
- required: ['branch'],
614
- properties: {
615
- branch: { type: 'string', description: 'Branch ref to diff against the default branch' },
616
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
617
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
618
- },
619
- },
620
- },
621
- ],
761
+ tools: getMcpToolDefinitions(),
622
762
  }));
623
763
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
624
764
  if (loadError) {
@@ -33,24 +33,38 @@ When likely relationships are absent, treat naming, shared component context, sc
33
33
 
34
34
  ## Recommended workflow
35
35
 
36
- 1. Orient - call get_graph_summary first. Returns node count, component count, orphan count, edge counts by type, and diagnostic count.
36
+ 1. Call get_graph_metadata first to discover which edge types are in use and what node templates exist.
37
37
 
38
- 2. Discover valid values - call get_graph_metadata when you need the available template names, edge types, or enum values for filters and traversal options.
38
+ 2. Use search_nodes with domain terms to find relevant starting nodes. Avoid list_nodes for discovery - it returns full inventories rather than ranked matches.
39
39
 
40
- 3. Find nodes - use search_nodes with one or more terms (OR semantics). It fuzzy-matches node IDs and, when search_properties is enabled, names, descriptions, and x-aka aliases. Pass templates to restrict to a type, for example ["DomainModel"].
40
+ 3. Call get_lineage with multiple node_ids batched together rather than separate calls per node.
41
41
 
42
- 4. Inspect a node - use get_cluster with a fully-qualified node ID. Returns the root, its owned descendants, and included semantic neighbors.
42
+ 4. Use direction "downstream" with depth 2 from events to trace event -> command -> operation chains.
43
43
 
44
- 5. Trace relationships - use get_lineage from one or more node IDs. Default: depth 2 downstream. Use direction "both" and a higher depth to see event flow around a node. Each result node carries origin_id, depth, via_edge_type, and via_node_id. When multiple origins reach the same node, origins lists all origin IDs.
44
+ 5. Use direction "upstream" from a DomainModel node to find all writers to that aggregate.
45
45
 
46
- 6. Broad scan - use get_graph or list_nodes with filters to fetch nodes across the graph. get_graph supports templates, exclude_templates, component, state, and stability filters.
46
+ 6. Avoid get_cluster for traversal questions - use it only when you need a node's full structural detail. Prefer get_lineage for following relationships.
47
47
 
48
- ## Output format tips
48
+ 7. Add include_provenance: true only when you need to bridge a finding to the source codebase.
49
49
 
50
- - Default format is YAML.
51
- - Use format "json" when you want conventional structured output for downstream parsing.
52
- - Use format "toon" when you want the most token-efficient machine-readable output, especially for large node or edge lists.
53
- - Add compact_keys true to shorten common keys (id->i, template->t, component->cp, state->s, stability->st).
50
+ ## Output format and token efficiency
51
+
52
+ Start with format "toon" and compact_keys true. TOON is the most token-efficient machine-readable format and compact_keys shortens common field names. Fall back to format "yaml" if a downstream consumer needs human-readable output, or format "json" if it needs conventional structured parsing.
53
+
54
+ When compact_keys is true the following field names are shortened in the response:
55
+
56
+ id → i template → t component → cp
57
+ state → s stability → st properties → p
58
+ nodes → n edges → e root → r
59
+ children → ch from → fr to → to
60
+ type → ty notes → nt version → v
61
+ core → c abstract → a extends → ex
62
+ origin_id → oi depth → d via_edge_type → vet
63
+ via_node_id → vni lastModifiedAt → lm extractedFrom → xf
64
+ derivation → dv derivedBy → db
65
+
66
+ - get_lineage is lean by default: it returns only id (i), origin_id (oi), depth (d), via_edge_type (vet), and via_node_id (vni) unless lean is set to false.
67
+ - get_lineage omits edges by default; add include_edges true when you need graph reconstruction or edge-level auditing.
54
68
 
55
69
  ## Common patterns
56
70
 
@@ -70,5 +84,10 @@ Field-level mappings between nodes:
70
84
  get_linked_fields - returns all maps-to edges touching fields owned by a root node
71
85
 
72
86
  Schema / field details:
73
- get_cluster - descendants include owned schemas, fields, and enum values
87
+ get_cluster - root includes compact schemas and enums blocks by default. Each schema entry
88
+ is a map of field name to { type?, $ref?, collection?, nullable?, edges? }. Local references
89
+ use $ref: '#/schemas/name' or $ref: '#/enums/name' pointing into the same blocks. Mapping
90
+ fields appear as { type: map, key: string, value: { ... } } inline on the field. Field-level
91
+ cross-cluster edges (maps-to, derived-from) appear as an edges block on the field. Pass
92
+ collapse_schemas: false to get the full structural node-per-field representation instead.
74
93
  `.trim();
@@ -41,6 +41,12 @@ const COMPACT_KEY_MAP = {
41
41
  lastModifiedAt: 'lm',
42
42
  extractedFrom: 'xf',
43
43
  properties: 'p',
44
+ origin_id: 'oi',
45
+ depth: 'd',
46
+ via_edge_type: 'vet',
47
+ via_node_id: 'vni',
48
+ derivation: 'dv',
49
+ derivedBy: 'db',
44
50
  root: 'r',
45
51
  children: 'ch',
46
52
  edges: 'e',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atolis-hq/corum",
3
- "version": "0.1.36",
3
+ "version": "0.1.38",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",