@atolis-hq/corum 0.1.37 → 0.1.38
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -301,7 +301,7 @@ 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
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 |
|
|
@@ -324,7 +324,7 @@ Common notes:
|
|
|
324
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
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
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
|
|
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.
|
|
328
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.
|
|
329
329
|
|
|
330
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',
|
|
@@ -246,12 +247,29 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
246
247
|
?? [...SEMANTIC_EDGE_TYPES];
|
|
247
248
|
const cluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
|
|
248
249
|
const includeProvenance = includesProvenance(args);
|
|
249
|
-
const
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
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
|
+
}
|
|
255
273
|
if (overlayRefs.length === 0 || !source || !branchRef) {
|
|
256
274
|
return formatResult(clusterPayload, args.format, getCompactKeys(args));
|
|
257
275
|
}
|
|
@@ -534,6 +552,7 @@ export function getMcpToolDefinitions() {
|
|
|
534
552
|
},
|
|
535
553
|
include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the cluster. Default false.' },
|
|
536
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.' },
|
|
537
556
|
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
538
557
|
branch: { type: 'string', description: 'Branch ref to load the cluster from' },
|
|
539
558
|
overlay_refs: {
|
|
@@ -43,7 +43,7 @@ When likely relationships are absent, treat naming, shared component context, sc
|
|
|
43
43
|
|
|
44
44
|
5. Use direction "upstream" from a DomainModel node to find all writers to that aggregate.
|
|
45
45
|
|
|
46
|
-
6. Avoid get_cluster for traversal questions - use it only when you need a node's full structural detail
|
|
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
|
|
|
@@ -84,5 +84,10 @@ Field-level mappings between nodes:
|
|
|
84
84
|
get_linked_fields - returns all maps-to edges touching fields owned by a root node
|
|
85
85
|
|
|
86
86
|
Schema / field details:
|
|
87
|
-
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.
|
|
88
93
|
`.trim();
|