@atolis-hq/corum 0.1.35 → 0.1.37
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 +10 -4
- package/dist/src/graph/index.js +14 -1
- package/dist/src/mcp/index.js +375 -254
- package/dist/src/mcp/prompts/usage-guide.js +25 -11
- package/dist/src/mcp/serializers.js +6 -0
- package/package.json +1 -1
- package/web/app.jsx +30 -16
- package/web/style.css +13 -1
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 root node, its descendants, included external nodes, and edges for one node's full structural detail |
|
|
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
|
|
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`
|
|
321
|
-
- `
|
|
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 such as schemas and fields. 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
|
package/dist/src/graph/index.js
CHANGED
|
@@ -181,9 +181,18 @@ export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRoo
|
|
|
181
181
|
}
|
|
182
182
|
export function getGraphSummary(graph) {
|
|
183
183
|
const components = new Set();
|
|
184
|
+
const nodesByComponent = {};
|
|
185
|
+
const nodesByTemplate = {};
|
|
186
|
+
const nodesByState = {};
|
|
187
|
+
const nodesByStability = {};
|
|
184
188
|
for (const node of graph.nodesById.values()) {
|
|
185
|
-
if (node.component)
|
|
189
|
+
if (node.component) {
|
|
186
190
|
components.add(node.component);
|
|
191
|
+
nodesByComponent[node.component] = (nodesByComponent[node.component] ?? 0) + 1;
|
|
192
|
+
}
|
|
193
|
+
nodesByTemplate[node.template] = (nodesByTemplate[node.template] ?? 0) + 1;
|
|
194
|
+
nodesByState[node.state] = (nodesByState[node.state] ?? 0) + 1;
|
|
195
|
+
nodesByStability[node.stability] = (nodesByStability[node.stability] ?? 0) + 1;
|
|
187
196
|
}
|
|
188
197
|
const nodesWithEdges = new Set();
|
|
189
198
|
const edgesByType = {};
|
|
@@ -207,6 +216,10 @@ export function getGraphSummary(graph) {
|
|
|
207
216
|
return {
|
|
208
217
|
nodeCount: graph.nodesById.size,
|
|
209
218
|
componentCount: components.size,
|
|
219
|
+
nodesByComponent,
|
|
220
|
+
nodesByTemplate,
|
|
221
|
+
nodesByState,
|
|
222
|
+
nodesByStability,
|
|
210
223
|
orphanNodeCount: Object.values(orphansByTemplate).reduce((sum, count) => sum + count, 0),
|
|
211
224
|
orphansByTemplate,
|
|
212
225
|
edgesByType,
|
package/dist/src/mcp/index.js
CHANGED
|
@@ -56,19 +56,92 @@ function parseListNodesFilter(value) {
|
|
|
56
56
|
: toStringArray(filterArg.stability),
|
|
57
57
|
};
|
|
58
58
|
}
|
|
59
|
+
function includesProvenance(args) {
|
|
60
|
+
return args.include_provenance === true || args.includeProvenance === true;
|
|
61
|
+
}
|
|
62
|
+
function summarizeNode(node, includeProvenance) {
|
|
63
|
+
return {
|
|
64
|
+
id: node.id,
|
|
65
|
+
template: node.template,
|
|
66
|
+
component: node.component,
|
|
67
|
+
state: node.state,
|
|
68
|
+
stability: node.stability,
|
|
69
|
+
...(includeProvenance ? withProvenance(node) : {}),
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
function withProvenance(node) {
|
|
73
|
+
return {
|
|
74
|
+
...(node.extractedFrom !== undefined ? { extractedFrom: node.extractedFrom } : {}),
|
|
75
|
+
...(node.lastModifiedAt !== undefined ? { lastModifiedAt: node.lastModifiedAt } : {}),
|
|
76
|
+
...(node.derivation !== undefined ? { derivation: node.derivation } : {}),
|
|
77
|
+
...(node.derivedBy !== undefined ? { derivedBy: node.derivedBy } : {}),
|
|
78
|
+
};
|
|
79
|
+
}
|
|
80
|
+
function fullNode(node, includeProvenance) {
|
|
81
|
+
return {
|
|
82
|
+
id: node.id,
|
|
83
|
+
template: node.template,
|
|
84
|
+
component: node.component,
|
|
85
|
+
state: node.state,
|
|
86
|
+
stability: node.stability,
|
|
87
|
+
properties: node.properties,
|
|
88
|
+
...(includeProvenance ? withProvenance(node) : {}),
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
function mapEdge(edge, includeProvenance) {
|
|
92
|
+
const out = {
|
|
93
|
+
id: edge.id,
|
|
94
|
+
from: edge.from,
|
|
95
|
+
to: edge.to,
|
|
96
|
+
type: edge.type,
|
|
97
|
+
state: edge.state,
|
|
98
|
+
stability: edge.stability,
|
|
99
|
+
};
|
|
100
|
+
if (edge.notes !== undefined)
|
|
101
|
+
out.notes = edge.notes;
|
|
102
|
+
if (includeProvenance) {
|
|
103
|
+
if (edge.derivation !== undefined)
|
|
104
|
+
out.derivation = edge.derivation;
|
|
105
|
+
if (edge.derivedBy !== undefined)
|
|
106
|
+
out.derivedBy = edge.derivedBy;
|
|
107
|
+
}
|
|
108
|
+
return out;
|
|
109
|
+
}
|
|
110
|
+
function mapLineageNode(node, includeProvenance, lean) {
|
|
111
|
+
const base = {
|
|
112
|
+
id: String(node.id),
|
|
113
|
+
origin_id: String(node.origin_id),
|
|
114
|
+
depth: Number(node.depth),
|
|
115
|
+
via_edge_type: String(node.via_edge_type),
|
|
116
|
+
via_node_id: String(node.via_node_id),
|
|
117
|
+
};
|
|
118
|
+
if (lean)
|
|
119
|
+
return base;
|
|
120
|
+
return {
|
|
121
|
+
...base,
|
|
122
|
+
template: String(node.template),
|
|
123
|
+
component: String(node.component),
|
|
124
|
+
state: String(node.state),
|
|
125
|
+
stability: String(node.stability),
|
|
126
|
+
properties: (node.properties ?? {}),
|
|
127
|
+
...(includeProvenance
|
|
128
|
+
? {
|
|
129
|
+
...(node.extractedFrom !== undefined ? { extractedFrom: node.extractedFrom } : {}),
|
|
130
|
+
...(node.lastModifiedAt !== undefined ? { lastModifiedAt: node.lastModifiedAt } : {}),
|
|
131
|
+
...(node.derivation !== undefined ? { derivation: node.derivation } : {}),
|
|
132
|
+
...(node.derivedBy !== undefined ? { derivedBy: node.derivedBy } : {}),
|
|
133
|
+
}
|
|
134
|
+
: {}),
|
|
135
|
+
};
|
|
136
|
+
}
|
|
59
137
|
export function createMcpHandlers(graph, source, cache) {
|
|
60
138
|
const resolveMulti = (src) => cache ? cache.get() : loadMultiGraph({ source: src });
|
|
61
139
|
return {
|
|
62
140
|
list_nodes(args) {
|
|
63
141
|
const run = (targetGraph) => {
|
|
64
142
|
const filter = parseListNodesFilter(args.filter);
|
|
65
|
-
const summaries = listNodes(targetGraph, filter)
|
|
66
|
-
|
|
67
|
-
template: node.template,
|
|
68
|
-
component: node.component,
|
|
69
|
-
state: node.state,
|
|
70
|
-
stability: node.stability,
|
|
71
|
-
}));
|
|
143
|
+
const summaries = listNodes(targetGraph, filter)
|
|
144
|
+
.map(node => summarizeNode(node, includesProvenance(args)));
|
|
72
145
|
return formatResult(summaries, args.format, getCompactKeys(args));
|
|
73
146
|
};
|
|
74
147
|
if (hasBranch(args)) {
|
|
@@ -107,7 +180,15 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
107
180
|
offset: typeof args.offset === 'number' ? args.offset : 0,
|
|
108
181
|
searchProperties: args.search_properties === true,
|
|
109
182
|
};
|
|
110
|
-
|
|
183
|
+
const wantFull = args.full_nodes === true;
|
|
184
|
+
const incProv = includesProvenance(args);
|
|
185
|
+
const results = searchNodes(targetGraph, queries, options).map(result => ({
|
|
186
|
+
score: result.score,
|
|
187
|
+
node: wantFull
|
|
188
|
+
? fullNode(result.node, incProv)
|
|
189
|
+
: summarizeNode(result.node, incProv),
|
|
190
|
+
}));
|
|
191
|
+
return formatResult(results, args.format, getCompactKeys(args));
|
|
111
192
|
};
|
|
112
193
|
if (hasBranch(args) && source) {
|
|
113
194
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
|
|
@@ -164,12 +245,19 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
164
245
|
const edgeTypes = parseEdgeTypes(args.edge_types)
|
|
165
246
|
?? [...SEMANTIC_EDGE_TYPES];
|
|
166
247
|
const cluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
|
|
248
|
+
const includeProvenance = includesProvenance(args);
|
|
249
|
+
const clusterPayload = {
|
|
250
|
+
root: fullNode(cluster.root, includeProvenance),
|
|
251
|
+
descendants: cluster.descendants.map(node => fullNode(node, includeProvenance)),
|
|
252
|
+
includedNodes: cluster.includedNodes.map(node => fullNode(node, includeProvenance)),
|
|
253
|
+
edges: cluster.edges.map(e => mapEdge(e, includeProvenance)),
|
|
254
|
+
};
|
|
167
255
|
if (overlayRefs.length === 0 || !source || !branchRef) {
|
|
168
|
-
return formatResult(
|
|
256
|
+
return formatResult(clusterPayload, args.format, getCompactKeys(args));
|
|
169
257
|
}
|
|
170
258
|
const multi = await resolveMulti(source);
|
|
171
259
|
const overlay = computeClusterOverlay(multi, branchRef, overlayRefs, String(args.node_id));
|
|
172
|
-
return formatResult({ ...
|
|
260
|
+
return formatResult({ ...clusterPayload, overlay }, args.format, getCompactKeys(args));
|
|
173
261
|
};
|
|
174
262
|
const branchRef = hasBranch(args) ? String(args.branch) : undefined;
|
|
175
263
|
if (branchRef) {
|
|
@@ -184,23 +272,21 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
184
272
|
? { ...filter, excludeTemplates: [...STRUCTURAL_NODE_TEMPLATES] }
|
|
185
273
|
: filter;
|
|
186
274
|
const nodes = listNodes(targetGraph, effectiveFilter)
|
|
187
|
-
.map(node => (
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
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 });
|
|
275
|
+
.map(node => summarizeNode(node, includesProvenance(args)));
|
|
276
|
+
const payload = { nodes };
|
|
277
|
+
if (args.include_edges === true) {
|
|
278
|
+
const nodeIds = new Set(nodes.map(node => node.id));
|
|
279
|
+
const edges = [];
|
|
280
|
+
for (const edgeList of targetGraph.edgesByFrom.values()) {
|
|
281
|
+
for (const edge of edgeList) {
|
|
282
|
+
if (!SEMANTIC_EDGE_TYPES.has(edge.type) || !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
|
|
283
|
+
continue;
|
|
284
|
+
edges.push({ id: edge.id, from: edge.from, to: edge.to, type: edge.type });
|
|
285
|
+
}
|
|
201
286
|
}
|
|
287
|
+
payload.edges = edges;
|
|
202
288
|
}
|
|
203
|
-
return formatResult(
|
|
289
|
+
return formatResult(payload, args.format, getCompactKeys(args));
|
|
204
290
|
};
|
|
205
291
|
if (hasBranch(args) && source) {
|
|
206
292
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
|
|
@@ -222,15 +308,18 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
222
308
|
for (const edge of edgeList)
|
|
223
309
|
edgeTypesInUse.add(edge.type);
|
|
224
310
|
}
|
|
311
|
+
const includeStatic = args.include_static_enums === true;
|
|
225
312
|
return formatResult({
|
|
226
313
|
template_names: [...targetGraph.templates.keys()].sort(),
|
|
227
314
|
node_templates_in_use: [...nodeTemplatesInUse].sort(),
|
|
228
315
|
edge_types_in_use: [...edgeTypesInUse].sort(),
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
316
|
+
...(includeStatic ? {
|
|
317
|
+
valid_edge_types: [...EDGE_TYPES],
|
|
318
|
+
states: [...STATE_VALUES],
|
|
319
|
+
stabilities: [...STABILITY_VALUES],
|
|
320
|
+
lineage_directions: [...LINEAGE_DIRECTIONS],
|
|
321
|
+
output_formats: [...OUTPUT_FORMATS],
|
|
322
|
+
} : {}),
|
|
234
323
|
}, args.format, getCompactKeys(args));
|
|
235
324
|
};
|
|
236
325
|
if (hasBranch(args) && source) {
|
|
@@ -262,7 +351,18 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
262
351
|
includeDanglingEdges: args.include_dangling_edges === true,
|
|
263
352
|
readsOutboundOnly: args.reads_outbound_only !== false,
|
|
264
353
|
};
|
|
265
|
-
|
|
354
|
+
const lineage = getLineage(targetGraph, nodeIds, options);
|
|
355
|
+
const lean = args.lean !== false;
|
|
356
|
+
const includeEdges = args.include_edges === true;
|
|
357
|
+
const includeProvenance = includesProvenance(args);
|
|
358
|
+
const payload = {
|
|
359
|
+
nodes: lineage.nodes.map(node => mapLineageNode(node, includeProvenance, lean)),
|
|
360
|
+
};
|
|
361
|
+
if (includeEdges)
|
|
362
|
+
payload.edges = lineage.edges.map(e => mapEdge(e, includeProvenance));
|
|
363
|
+
if (args.include_dangling_edges === true && lineage.dangling_edges)
|
|
364
|
+
payload.dangling_edges = lineage.dangling_edges;
|
|
365
|
+
return formatResult(payload, args.format, getCompactKeys(args));
|
|
266
366
|
};
|
|
267
367
|
if (hasBranch(args) && source) {
|
|
268
368
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
|
|
@@ -275,7 +375,14 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
275
375
|
}
|
|
276
376
|
},
|
|
277
377
|
get_linked_fields(args) {
|
|
278
|
-
const run = (targetGraph) =>
|
|
378
|
+
const run = (targetGraph) => {
|
|
379
|
+
const linked = getLinkedFields(targetGraph, String(args.node_id));
|
|
380
|
+
const incProv = includesProvenance(args);
|
|
381
|
+
return formatResult({
|
|
382
|
+
edges: linked.edges.map(e => mapEdge(e, incProv)),
|
|
383
|
+
nodes: linked.nodes.map(node => fullNode(node, incProv)),
|
|
384
|
+
}, args.format, getCompactKeys(args));
|
|
385
|
+
};
|
|
279
386
|
if (hasBranch(args)) {
|
|
280
387
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
|
|
281
388
|
}
|
|
@@ -347,6 +454,241 @@ function errorResult(err) {
|
|
|
347
454
|
const message = err instanceof QueryError ? err.message : String(err);
|
|
348
455
|
return { content: [{ type: 'text', text: message }], isError: true };
|
|
349
456
|
}
|
|
457
|
+
export function getMcpToolDefinitions() {
|
|
458
|
+
return [
|
|
459
|
+
{
|
|
460
|
+
name: 'list_nodes',
|
|
461
|
+
description: 'List nodes in the graph. Returns id, template, component, state, stability for each matched node.',
|
|
462
|
+
inputSchema: {
|
|
463
|
+
type: 'object',
|
|
464
|
+
properties: {
|
|
465
|
+
filter: {
|
|
466
|
+
type: 'object',
|
|
467
|
+
description: 'Filter criteria',
|
|
468
|
+
properties: {
|
|
469
|
+
templates: {
|
|
470
|
+
type: 'array',
|
|
471
|
+
items: { type: 'string' },
|
|
472
|
+
description: 'Include only these template types (OR semantics)',
|
|
473
|
+
},
|
|
474
|
+
exclude_templates: {
|
|
475
|
+
type: 'array',
|
|
476
|
+
items: { type: 'string' },
|
|
477
|
+
description: 'Exclude these template types',
|
|
478
|
+
},
|
|
479
|
+
component: { type: 'string', description: 'Filter by component name' },
|
|
480
|
+
state: {
|
|
481
|
+
description: 'Filter by lifecycle state as a string or array',
|
|
482
|
+
oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
|
|
483
|
+
},
|
|
484
|
+
stability: {
|
|
485
|
+
description: 'Filter by stability as a string or array',
|
|
486
|
+
oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
|
|
487
|
+
},
|
|
488
|
+
},
|
|
489
|
+
},
|
|
490
|
+
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
491
|
+
branch: { type: 'string', description: 'Branch ref to load nodes from' },
|
|
492
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
493
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
494
|
+
},
|
|
495
|
+
},
|
|
496
|
+
},
|
|
497
|
+
{
|
|
498
|
+
name: 'list_templates',
|
|
499
|
+
description: 'List loaded graph templates. Returns name, version, core, abstract, extends, and description for each template.',
|
|
500
|
+
inputSchema: {
|
|
501
|
+
type: 'object',
|
|
502
|
+
properties: {
|
|
503
|
+
branch: { type: 'string', description: 'Branch ref to load templates from' },
|
|
504
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
505
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
506
|
+
},
|
|
507
|
+
},
|
|
508
|
+
},
|
|
509
|
+
{
|
|
510
|
+
name: 'get_template',
|
|
511
|
+
description: 'Get full details for a loaded graph template.',
|
|
512
|
+
inputSchema: {
|
|
513
|
+
type: 'object',
|
|
514
|
+
required: ['name'],
|
|
515
|
+
properties: {
|
|
516
|
+
name: { type: 'string', description: 'Template name' },
|
|
517
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
518
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
519
|
+
},
|
|
520
|
+
},
|
|
521
|
+
},
|
|
522
|
+
{
|
|
523
|
+
name: 'get_cluster',
|
|
524
|
+
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.',
|
|
525
|
+
inputSchema: {
|
|
526
|
+
type: 'object',
|
|
527
|
+
required: ['node_id'],
|
|
528
|
+
properties: {
|
|
529
|
+
node_id: { type: 'string', description: 'Fully qualified node ID' },
|
|
530
|
+
edge_types: {
|
|
531
|
+
type: 'array',
|
|
532
|
+
items: { type: 'string' },
|
|
533
|
+
description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
|
|
534
|
+
},
|
|
535
|
+
include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the cluster. Default false.' },
|
|
536
|
+
reads_outbound_only: { type: 'boolean', description: 'Restrict reads edges to outbound only. Default true.' },
|
|
537
|
+
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
538
|
+
branch: { type: 'string', description: 'Branch ref to load the cluster from' },
|
|
539
|
+
overlay_refs: {
|
|
540
|
+
type: 'array',
|
|
541
|
+
items: { type: 'string' },
|
|
542
|
+
description: 'Branch refs to overlay. Returns ghost field data alongside the cluster.',
|
|
543
|
+
},
|
|
544
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
545
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
546
|
+
},
|
|
547
|
+
},
|
|
548
|
+
},
|
|
549
|
+
{
|
|
550
|
+
name: 'get_graph',
|
|
551
|
+
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.',
|
|
552
|
+
inputSchema: {
|
|
553
|
+
type: 'object',
|
|
554
|
+
properties: {
|
|
555
|
+
filter: {
|
|
556
|
+
type: 'object',
|
|
557
|
+
properties: {
|
|
558
|
+
templates: { type: 'array', items: { type: 'string' } },
|
|
559
|
+
exclude_templates: { type: 'array', items: { type: 'string' } },
|
|
560
|
+
component: { type: 'string' },
|
|
561
|
+
state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
|
|
562
|
+
stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
|
|
563
|
+
},
|
|
564
|
+
},
|
|
565
|
+
include_edges: { type: 'boolean', description: 'Include the semantic edge list in the response. Default false.' },
|
|
566
|
+
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
567
|
+
branch: { type: 'string', description: 'Branch ref to load the graph from' },
|
|
568
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
569
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
570
|
+
},
|
|
571
|
+
},
|
|
572
|
+
},
|
|
573
|
+
{
|
|
574
|
+
name: 'get_graph_metadata',
|
|
575
|
+
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.',
|
|
576
|
+
inputSchema: {
|
|
577
|
+
type: 'object',
|
|
578
|
+
properties: {
|
|
579
|
+
include_static_enums: { type: 'boolean', description: 'Include static enum reference fields (valid_edge_types, states, stabilities, lineage_directions, output_formats). Default false.' },
|
|
580
|
+
branch: { type: 'string', description: 'Branch ref to load metadata from' },
|
|
581
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
582
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
583
|
+
},
|
|
584
|
+
},
|
|
585
|
+
},
|
|
586
|
+
{
|
|
587
|
+
name: 'get_lineage',
|
|
588
|
+
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.',
|
|
589
|
+
inputSchema: {
|
|
590
|
+
type: 'object',
|
|
591
|
+
required: ['node_ids'],
|
|
592
|
+
properties: {
|
|
593
|
+
node_ids: {
|
|
594
|
+
type: 'array',
|
|
595
|
+
items: { type: 'string' },
|
|
596
|
+
description: 'Fully-qualified IDs of origin nodes. All expand in parallel.',
|
|
597
|
+
},
|
|
598
|
+
depth: { type: 'number', description: 'Max hops. Default 2.' },
|
|
599
|
+
direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: 'Traversal direction. Default downstream.' },
|
|
600
|
+
edge_types: { type: 'array', items: { type: 'string' }, description: 'Edge types to traverse. Default: all non-structural.' },
|
|
601
|
+
node_types: { type: 'array', items: { type: 'string' }, description: 'Allowlist of node templates.' },
|
|
602
|
+
exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Denylist of node templates.' },
|
|
603
|
+
include_dangling_edges: { type: 'boolean', description: 'Include dangling edges in the response when present. Default false.' },
|
|
604
|
+
reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads edges in upstream traversal. Default true.' },
|
|
605
|
+
lean: { type: 'boolean', description: 'Return minimal lineage node shape. Default true.' },
|
|
606
|
+
include_edges: { type: 'boolean', description: 'Include the edges list in the response. Default false.' },
|
|
607
|
+
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
608
|
+
branch: { type: 'string', description: 'Branch ref to load the lineage from' },
|
|
609
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
610
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
611
|
+
},
|
|
612
|
+
},
|
|
613
|
+
},
|
|
614
|
+
{
|
|
615
|
+
name: 'get_linked_fields',
|
|
616
|
+
description: 'Get all maps-to edges touching fields owned by the given root node.',
|
|
617
|
+
inputSchema: {
|
|
618
|
+
type: 'object',
|
|
619
|
+
required: ['node_id'],
|
|
620
|
+
properties: {
|
|
621
|
+
node_id: { type: 'string', description: 'Fully qualified root node ID' },
|
|
622
|
+
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
623
|
+
branch: { type: 'string', description: 'Branch ref to load linked fields from' },
|
|
624
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
625
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
626
|
+
},
|
|
627
|
+
},
|
|
628
|
+
},
|
|
629
|
+
{
|
|
630
|
+
name: 'get_graph_summary',
|
|
631
|
+
description: 'Return high-level statistics: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
|
|
632
|
+
inputSchema: {
|
|
633
|
+
type: 'object',
|
|
634
|
+
properties: {
|
|
635
|
+
branch: { type: 'string', description: 'Branch ref to load the summary from' },
|
|
636
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
637
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
638
|
+
},
|
|
639
|
+
},
|
|
640
|
+
},
|
|
641
|
+
{
|
|
642
|
+
name: 'search_nodes',
|
|
643
|
+
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.',
|
|
644
|
+
inputSchema: {
|
|
645
|
+
type: 'object',
|
|
646
|
+
required: ['queries'],
|
|
647
|
+
properties: {
|
|
648
|
+
queries: {
|
|
649
|
+
type: 'array',
|
|
650
|
+
items: { type: 'string' },
|
|
651
|
+
description: 'Search terms. OR semantics; any matching term qualifies the node.',
|
|
652
|
+
},
|
|
653
|
+
templates: { type: 'array', items: { type: 'string' }, description: 'Include only these template types.' },
|
|
654
|
+
exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these template types.' },
|
|
655
|
+
page_size: { type: 'number', description: 'Max results to return. Default 10.' },
|
|
656
|
+
offset: { type: 'number', description: 'Result offset for pagination. Default 0.' },
|
|
657
|
+
search_properties: { type: 'boolean', description: 'Also match name, description, and x-aka properties.' },
|
|
658
|
+
full_nodes: { type: 'boolean', description: 'Include properties on each result node. Default false.' },
|
|
659
|
+
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
660
|
+
branch: { type: 'string', description: 'Branch ref to search within' },
|
|
661
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
662
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
663
|
+
},
|
|
664
|
+
},
|
|
665
|
+
},
|
|
666
|
+
{
|
|
667
|
+
name: 'list_branches',
|
|
668
|
+
description: 'List branches available from the configured graph source and their load status.',
|
|
669
|
+
inputSchema: {
|
|
670
|
+
type: 'object',
|
|
671
|
+
properties: {
|
|
672
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
673
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
674
|
+
},
|
|
675
|
+
},
|
|
676
|
+
},
|
|
677
|
+
{
|
|
678
|
+
name: 'diff_branch',
|
|
679
|
+
description: 'Diff a branch against the default branch.',
|
|
680
|
+
inputSchema: {
|
|
681
|
+
type: 'object',
|
|
682
|
+
required: ['branch'],
|
|
683
|
+
properties: {
|
|
684
|
+
branch: { type: 'string', description: 'Branch ref to diff against the default branch' },
|
|
685
|
+
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
686
|
+
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
687
|
+
},
|
|
688
|
+
},
|
|
689
|
+
},
|
|
690
|
+
];
|
|
691
|
+
}
|
|
350
692
|
export async function startMcpServer(options = {}) {
|
|
351
693
|
const { noWeb = false, watch = false } = options;
|
|
352
694
|
const config = createGraphRuntimeConfig();
|
|
@@ -397,228 +739,7 @@ export async function startMcpServer(options = {}) {
|
|
|
397
739
|
};
|
|
398
740
|
});
|
|
399
741
|
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
|
-
],
|
|
742
|
+
tools: getMcpToolDefinitions(),
|
|
622
743
|
}));
|
|
623
744
|
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
624
745
|
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.
|
|
36
|
+
1. Call get_graph_metadata first to discover which edge types are in use and what node templates exist.
|
|
37
37
|
|
|
38
|
-
2.
|
|
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.
|
|
40
|
+
3. Call get_lineage with multiple node_ids batched together rather than separate calls per node.
|
|
41
41
|
|
|
42
|
-
4.
|
|
42
|
+
4. Use direction "downstream" with depth 2 from events to trace event -> command -> operation chains.
|
|
43
43
|
|
|
44
|
-
5.
|
|
44
|
+
5. Use direction "upstream" from a DomainModel node to find all writers to that aggregate.
|
|
45
45
|
|
|
46
|
-
6.
|
|
46
|
+
6. Avoid get_cluster for traversal questions - use it only when you need a node's full structural detail (schema, fields). Prefer get_lineage for following relationships.
|
|
47
47
|
|
|
48
|
-
|
|
48
|
+
7. Add include_provenance: true only when you need to bridge a finding to the source codebase.
|
|
49
49
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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
|
|
|
@@ -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
package/web/app.jsx
CHANGED
|
@@ -530,26 +530,25 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
|
|
|
530
530
|
.catch(() => setBranchDiff(null));
|
|
531
531
|
}, [isOnNonDefaultBranch, viewingRef, defaultBranchRef]);
|
|
532
532
|
|
|
533
|
-
const componentCount = new Set(nodes.map(n => n.component).filter(Boolean)).size;
|
|
534
|
-
const nodeCount = nodes.length;
|
|
535
533
|
const totalEdges = stats ? Object.values(stats.edgesByType).reduce((a, b) => a + b, 0) : '…';
|
|
536
534
|
|
|
537
535
|
const templateMap = new Map(templates.map(t => [t.name, t]));
|
|
538
536
|
|
|
539
|
-
const nodesByTemplate =
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
537
|
+
const nodesByTemplate = stats
|
|
538
|
+
? Object.entries(stats.nodesByTemplate).sort((a, b) => b[1] - a[1])
|
|
539
|
+
: [];
|
|
540
|
+
|
|
541
|
+
const nodesByComponent = stats
|
|
542
|
+
? Object.entries(stats.nodesByComponent).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
|
|
543
|
+
: [];
|
|
543
544
|
|
|
544
|
-
const nodesByState =
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
}, new Map()).entries()].sort((a, b) => b[1] - a[1]);
|
|
545
|
+
const nodesByState = stats
|
|
546
|
+
? Object.entries(stats.nodesByState).sort((a, b) => b[1] - a[1])
|
|
547
|
+
: [];
|
|
548
548
|
|
|
549
|
-
const nodesByStability =
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
}, new Map()).entries()].sort((a, b) => b[1] - a[1]);
|
|
549
|
+
const nodesByStability = stats
|
|
550
|
+
? Object.entries(stats.nodesByStability).sort((a, b) => b[1] - a[1])
|
|
551
|
+
: [];
|
|
553
552
|
|
|
554
553
|
const edgeRows = stats
|
|
555
554
|
? Object.entries(stats.edgesByType).filter(([, count]) => count > 0).sort((a, b) => b[1] - a[1])
|
|
@@ -562,8 +561,8 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
|
|
|
562
561
|
return (
|
|
563
562
|
<div className="content">
|
|
564
563
|
<div className="dashboard-hero">
|
|
565
|
-
<HeroCard value={componentCount} label="Components" />
|
|
566
|
-
<HeroCard value={nodeCount} label="Nodes" />
|
|
564
|
+
<HeroCard value={stats ? stats.componentCount : '…'} label="Components" />
|
|
565
|
+
<HeroCard value={stats ? stats.nodeCount : '…'} label="Nodes" />
|
|
567
566
|
<HeroCard value={totalEdges} label="Edges" />
|
|
568
567
|
<HeroCard value={stats ? stats.orphanNodeCount : '…'} label="Orphan Nodes" />
|
|
569
568
|
</div>
|
|
@@ -584,6 +583,7 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
|
|
|
584
583
|
<div className="dashboard-panel">
|
|
585
584
|
<div className="card-head">Nodes by Type</div>
|
|
586
585
|
<div className="card-body" style={{ padding: '12px 16px' }}>
|
|
586
|
+
{stats === null && <div className="label-sm">Loading…</div>}
|
|
587
587
|
{nodesByTemplate.map(([name, count]) => {
|
|
588
588
|
const tmpl = templateMap.get(name);
|
|
589
589
|
const colour = tmpl?.ui?.colour ?? 'var(--ink-4)';
|
|
@@ -600,6 +600,19 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
|
|
|
600
600
|
</div>
|
|
601
601
|
</div>
|
|
602
602
|
|
|
603
|
+
<div className="dashboard-panel">
|
|
604
|
+
<div className="card-head">Nodes by Component</div>
|
|
605
|
+
<div className="card-body" style={{ padding: '12px 16px' }}>
|
|
606
|
+
{stats === null && <div className="label-sm">Loading…</div>}
|
|
607
|
+
{nodesByComponent.map(([name, count]) => (
|
|
608
|
+
<div key={name} className="stat-row">
|
|
609
|
+
<span className="stat-row-label">{name}</span>
|
|
610
|
+
<span className="stat-row-value">{count}</span>
|
|
611
|
+
</div>
|
|
612
|
+
))}
|
|
613
|
+
</div>
|
|
614
|
+
</div>
|
|
615
|
+
|
|
603
616
|
<div className="dashboard-panel">
|
|
604
617
|
<div className="card-head">Orphan Nodes by Type</div>
|
|
605
618
|
<div className="card-body" style={{ padding: '12px 16px' }}>
|
|
@@ -640,6 +653,7 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
|
|
|
640
653
|
<div className="dashboard-panel">
|
|
641
654
|
<div className="card-head">State & Stability</div>
|
|
642
655
|
<div className="card-body" style={{ padding: '12px 16px' }}>
|
|
656
|
+
{stats === null && <div className="label-sm">Loading…</div>}
|
|
643
657
|
{nodesByState.map(([state, count]) => (
|
|
644
658
|
<div key={state} className="stat-row">
|
|
645
659
|
<span className="stat-row-label"><StateTag state={state} /></span>
|
package/web/style.css
CHANGED
|
@@ -1526,10 +1526,22 @@ button {
|
|
|
1526
1526
|
|
|
1527
1527
|
.dashboard-grid {
|
|
1528
1528
|
display: grid;
|
|
1529
|
-
grid-template-columns:
|
|
1529
|
+
grid-template-columns: repeat(3, minmax(260px, 1fr));
|
|
1530
1530
|
gap: 16px;
|
|
1531
1531
|
}
|
|
1532
1532
|
|
|
1533
|
+
@media (max-width: 960px) {
|
|
1534
|
+
.dashboard-grid {
|
|
1535
|
+
grid-template-columns: repeat(2, minmax(260px, 1fr));
|
|
1536
|
+
}
|
|
1537
|
+
}
|
|
1538
|
+
|
|
1539
|
+
@media (max-width: 640px) {
|
|
1540
|
+
.dashboard-grid {
|
|
1541
|
+
grid-template-columns: 1fr;
|
|
1542
|
+
}
|
|
1543
|
+
}
|
|
1544
|
+
|
|
1533
1545
|
.dashboard-panel {
|
|
1534
1546
|
overflow: hidden;
|
|
1535
1547
|
border: 1px solid var(--rule-2);
|