@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 +10 -4
- package/dist/src/graph/schema-collapse.js +169 -0
- package/dist/src/mcp/index.js +394 -254
- package/dist/src/mcp/prompts/usage-guide.js +31 -12
- package/dist/src/mcp/serializers.js +6 -0
- package/package.json +1 -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
|
|
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
|
|
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. 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
|
+
}
|
package/dist/src/mcp/index.js
CHANGED
|
@@ -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)
|
|
66
|
-
|
|
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
|
-
|
|
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(
|
|
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({ ...
|
|
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
|
-
|
|
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 });
|
|
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(
|
|
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
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
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
|
-
|
|
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) =>
|
|
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.
|
|
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. 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
|
|
|
@@ -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 -
|
|
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',
|