@atolis-hq/corum 0.1.34 → 0.1.36
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 +35 -2
- package/dist/src/graph/index.js +306 -5
- package/dist/src/mcp/index.js +344 -14
- package/dist/src/mcp/prompts/usage-guide.js +74 -0
- package/dist/src/web/server.js +93 -33
- package/package.json +1 -1
- package/web/app.jsx +30 -16
- package/web/graph-utils.js +2 -61
- package/web/graph-utils.test.js +9 -84
- package/web/graph.jsx +39 -8
- package/web/search.jsx +18 -30
- package/web/style.css +13 -1
package/dist/src/mcp/index.js
CHANGED
|
@@ -1,25 +1,67 @@
|
|
|
1
1
|
import { printBanner } from '../banner.js';
|
|
2
2
|
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
|
3
3
|
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
4
|
-
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
|
|
4
|
+
import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
|
|
5
5
|
import { pathToFileURL } from 'node:url';
|
|
6
|
-
import { computeClusterOverlay,
|
|
6
|
+
import { computeClusterOverlay, getClusterView, getGraphSummary, getLineage, getLinkedFields, listNodes, SEMANTIC_EDGE_TYPES, searchNodes, STRUCTURAL_NODE_TEMPLATES, } from '../graph/index.js';
|
|
7
7
|
import { loadGraph, loadMultiGraph } from '../loader/index.js';
|
|
8
8
|
import { QueryError } from '../schema/index.js';
|
|
9
9
|
import { createGraphRuntimeConfig } from '../source/config.js';
|
|
10
10
|
import { startGraphFileWatcher, startWebServer } from '../web/server.js';
|
|
11
|
+
import { USAGE_GUIDE_PROMPT } from './prompts/usage-guide.js';
|
|
11
12
|
import { compactKeys, getSerializer } from './serializers.js';
|
|
13
|
+
const EDGE_TYPES = [
|
|
14
|
+
'triggers',
|
|
15
|
+
'produces',
|
|
16
|
+
'reads',
|
|
17
|
+
'calls',
|
|
18
|
+
'implements',
|
|
19
|
+
'maps-to',
|
|
20
|
+
'derived-from',
|
|
21
|
+
'renamed-from',
|
|
22
|
+
'has-field',
|
|
23
|
+
'has-value',
|
|
24
|
+
];
|
|
25
|
+
const EDGE_TYPE_SET = new Set(EDGE_TYPES);
|
|
26
|
+
const STATE_VALUES = ['draft', 'proposed', 'agreed', 'future', 'removed', 'implemented'];
|
|
27
|
+
const STABILITY_VALUES = ['unstable', 'stable', 'deprecated'];
|
|
28
|
+
const LINEAGE_DIRECTIONS = ['downstream', 'upstream', 'both'];
|
|
29
|
+
const OUTPUT_FORMATS = ['yaml', 'json', 'toon'];
|
|
30
|
+
function toStringArray(value) {
|
|
31
|
+
return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : undefined;
|
|
32
|
+
}
|
|
33
|
+
function parseEdgeTypes(value) {
|
|
34
|
+
const requested = toStringArray(value);
|
|
35
|
+
if (!requested)
|
|
36
|
+
return undefined;
|
|
37
|
+
const invalid = requested.filter(type => !EDGE_TYPE_SET.has(type));
|
|
38
|
+
if (invalid.length > 0) {
|
|
39
|
+
throw new QueryError(`Unknown edge type: ${invalid.join(', ')}`);
|
|
40
|
+
}
|
|
41
|
+
return requested;
|
|
42
|
+
}
|
|
43
|
+
function parseListNodesFilter(value) {
|
|
44
|
+
const filterArg = typeof value === 'object' && value !== null
|
|
45
|
+
? value
|
|
46
|
+
: {};
|
|
47
|
+
return {
|
|
48
|
+
templates: toStringArray(filterArg.templates),
|
|
49
|
+
excludeTemplates: toStringArray(filterArg.exclude_templates),
|
|
50
|
+
component: typeof filterArg.component === 'string' ? filterArg.component : undefined,
|
|
51
|
+
state: typeof filterArg.state === 'string'
|
|
52
|
+
? filterArg.state
|
|
53
|
+
: toStringArray(filterArg.state),
|
|
54
|
+
stability: typeof filterArg.stability === 'string'
|
|
55
|
+
? filterArg.stability
|
|
56
|
+
: toStringArray(filterArg.stability),
|
|
57
|
+
};
|
|
58
|
+
}
|
|
12
59
|
export function createMcpHandlers(graph, source, cache) {
|
|
13
60
|
const resolveMulti = (src) => cache ? cache.get() : loadMultiGraph({ source: src });
|
|
14
61
|
return {
|
|
15
62
|
list_nodes(args) {
|
|
16
63
|
const run = (targetGraph) => {
|
|
17
|
-
const filter =
|
|
18
|
-
template: typeof args.template === 'string' ? args.template : undefined,
|
|
19
|
-
component: typeof args.component === 'string' ? args.component : undefined,
|
|
20
|
-
state: typeof args.state === 'string' ? args.state : undefined,
|
|
21
|
-
stability: typeof args.stability === 'string' ? args.stability : undefined,
|
|
22
|
-
};
|
|
64
|
+
const filter = parseListNodesFilter(args.filter);
|
|
23
65
|
const summaries = listNodes(targetGraph, filter).map(node => ({
|
|
24
66
|
id: node.id,
|
|
25
67
|
template: node.template,
|
|
@@ -39,6 +81,44 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
39
81
|
return errorResult(err);
|
|
40
82
|
}
|
|
41
83
|
},
|
|
84
|
+
get_graph_summary(args) {
|
|
85
|
+
const run = (targetGraph) => formatResult(getGraphSummary(targetGraph), args.format, getCompactKeys(args));
|
|
86
|
+
if (hasBranch(args) && source) {
|
|
87
|
+
return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
|
|
88
|
+
}
|
|
89
|
+
try {
|
|
90
|
+
return run(graph);
|
|
91
|
+
}
|
|
92
|
+
catch (err) {
|
|
93
|
+
return errorResult(err);
|
|
94
|
+
}
|
|
95
|
+
},
|
|
96
|
+
search_nodes(args) {
|
|
97
|
+
const queries = Array.isArray(args.queries)
|
|
98
|
+
? args.queries.filter((query) => typeof query === 'string')
|
|
99
|
+
: [];
|
|
100
|
+
if (queries.length === 0)
|
|
101
|
+
return errorResult(new QueryError('queries is required'));
|
|
102
|
+
const run = (targetGraph) => {
|
|
103
|
+
const options = {
|
|
104
|
+
templates: toStringArray(args.templates),
|
|
105
|
+
excludeTemplates: toStringArray(args.exclude_templates),
|
|
106
|
+
limit: typeof args.page_size === 'number' ? args.page_size : 10,
|
|
107
|
+
offset: typeof args.offset === 'number' ? args.offset : 0,
|
|
108
|
+
searchProperties: args.search_properties === true,
|
|
109
|
+
};
|
|
110
|
+
return formatResult(searchNodes(targetGraph, queries, options), args.format, getCompactKeys(args));
|
|
111
|
+
};
|
|
112
|
+
if (hasBranch(args) && source) {
|
|
113
|
+
return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
|
|
114
|
+
}
|
|
115
|
+
try {
|
|
116
|
+
return run(graph);
|
|
117
|
+
}
|
|
118
|
+
catch (err) {
|
|
119
|
+
return errorResult(err);
|
|
120
|
+
}
|
|
121
|
+
},
|
|
42
122
|
list_templates(args) {
|
|
43
123
|
const run = (targetGraph) => {
|
|
44
124
|
const summaries = [...targetGraph.templates.values()]
|
|
@@ -81,7 +161,9 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
81
161
|
? args.overlay_refs.filter((ref) => typeof ref === 'string')
|
|
82
162
|
: [];
|
|
83
163
|
const run = async (targetGraph, branchRef) => {
|
|
84
|
-
const
|
|
164
|
+
const edgeTypes = parseEdgeTypes(args.edge_types)
|
|
165
|
+
?? [...SEMANTIC_EDGE_TYPES];
|
|
166
|
+
const cluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
|
|
85
167
|
if (overlayRefs.length === 0 || !source || !branchRef) {
|
|
86
168
|
return formatResult(cluster, args.format, getCompactKeys(args));
|
|
87
169
|
}
|
|
@@ -95,6 +177,103 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
95
177
|
}
|
|
96
178
|
return run(graph).catch(err => errorResult(err));
|
|
97
179
|
},
|
|
180
|
+
get_graph(args) {
|
|
181
|
+
const run = (targetGraph) => {
|
|
182
|
+
const filter = parseListNodesFilter(args.filter);
|
|
183
|
+
const effectiveFilter = (!filter.templates?.length && !filter.excludeTemplates?.length)
|
|
184
|
+
? { ...filter, excludeTemplates: [...STRUCTURAL_NODE_TEMPLATES] }
|
|
185
|
+
: filter;
|
|
186
|
+
const nodes = listNodes(targetGraph, effectiveFilter)
|
|
187
|
+
.map(node => ({
|
|
188
|
+
id: node.id,
|
|
189
|
+
template: node.template,
|
|
190
|
+
component: node.component,
|
|
191
|
+
state: node.state,
|
|
192
|
+
stability: node.stability,
|
|
193
|
+
}));
|
|
194
|
+
const nodeIds = new Set(nodes.map(node => node.id));
|
|
195
|
+
const edges = [];
|
|
196
|
+
for (const edgeList of targetGraph.edgesByFrom.values()) {
|
|
197
|
+
for (const edge of edgeList) {
|
|
198
|
+
if (!SEMANTIC_EDGE_TYPES.has(edge.type) || !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
|
|
199
|
+
continue;
|
|
200
|
+
edges.push({ id: edge.id, from: edge.from, to: edge.to, type: edge.type });
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
return formatResult({ nodes, edges }, args.format, getCompactKeys(args));
|
|
204
|
+
};
|
|
205
|
+
if (hasBranch(args) && source) {
|
|
206
|
+
return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
|
|
207
|
+
}
|
|
208
|
+
try {
|
|
209
|
+
return run(graph);
|
|
210
|
+
}
|
|
211
|
+
catch (err) {
|
|
212
|
+
return errorResult(err);
|
|
213
|
+
}
|
|
214
|
+
},
|
|
215
|
+
get_graph_metadata(args) {
|
|
216
|
+
const run = (targetGraph) => {
|
|
217
|
+
const nodeTemplatesInUse = new Set();
|
|
218
|
+
for (const node of targetGraph.nodesById.values())
|
|
219
|
+
nodeTemplatesInUse.add(node.template);
|
|
220
|
+
const edgeTypesInUse = new Set();
|
|
221
|
+
for (const edgeList of targetGraph.edgesByFrom.values()) {
|
|
222
|
+
for (const edge of edgeList)
|
|
223
|
+
edgeTypesInUse.add(edge.type);
|
|
224
|
+
}
|
|
225
|
+
return formatResult({
|
|
226
|
+
template_names: [...targetGraph.templates.keys()].sort(),
|
|
227
|
+
node_templates_in_use: [...nodeTemplatesInUse].sort(),
|
|
228
|
+
edge_types_in_use: [...edgeTypesInUse].sort(),
|
|
229
|
+
valid_edge_types: [...EDGE_TYPES],
|
|
230
|
+
states: [...STATE_VALUES],
|
|
231
|
+
stabilities: [...STABILITY_VALUES],
|
|
232
|
+
lineage_directions: [...LINEAGE_DIRECTIONS],
|
|
233
|
+
output_formats: [...OUTPUT_FORMATS],
|
|
234
|
+
}, args.format, getCompactKeys(args));
|
|
235
|
+
};
|
|
236
|
+
if (hasBranch(args) && source) {
|
|
237
|
+
return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
|
|
238
|
+
}
|
|
239
|
+
try {
|
|
240
|
+
return run(graph);
|
|
241
|
+
}
|
|
242
|
+
catch (err) {
|
|
243
|
+
return errorResult(err);
|
|
244
|
+
}
|
|
245
|
+
},
|
|
246
|
+
get_lineage(args) {
|
|
247
|
+
const nodeIds = Array.isArray(args.node_ids)
|
|
248
|
+
? args.node_ids.filter((id) => typeof id === 'string')
|
|
249
|
+
: [];
|
|
250
|
+
if (nodeIds.length === 0)
|
|
251
|
+
return errorResult(new QueryError('node_ids is required'));
|
|
252
|
+
const run = (targetGraph) => {
|
|
253
|
+
const direction = ['downstream', 'upstream', 'both'].includes(args.direction)
|
|
254
|
+
? args.direction
|
|
255
|
+
: 'downstream';
|
|
256
|
+
const options = {
|
|
257
|
+
depth: typeof args.depth === 'number' ? args.depth : 2,
|
|
258
|
+
direction,
|
|
259
|
+
edgeTypes: parseEdgeTypes(args.edge_types),
|
|
260
|
+
nodeTypes: toStringArray(args.node_types),
|
|
261
|
+
excludeNodeTypes: toStringArray(args.exclude_node_types),
|
|
262
|
+
includeDanglingEdges: args.include_dangling_edges === true,
|
|
263
|
+
readsOutboundOnly: args.reads_outbound_only !== false,
|
|
264
|
+
};
|
|
265
|
+
return formatResult(getLineage(targetGraph, nodeIds, options), args.format, getCompactKeys(args));
|
|
266
|
+
};
|
|
267
|
+
if (hasBranch(args) && source) {
|
|
268
|
+
return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
|
|
269
|
+
}
|
|
270
|
+
try {
|
|
271
|
+
return run(graph);
|
|
272
|
+
}
|
|
273
|
+
catch (err) {
|
|
274
|
+
return errorResult(err);
|
|
275
|
+
}
|
|
276
|
+
},
|
|
98
277
|
get_linked_fields(args) {
|
|
99
278
|
const run = (targetGraph) => formatResult(getLinkedFields(targetGraph, String(args.node_id)), args.format, getCompactKeys(args));
|
|
100
279
|
if (hasBranch(args)) {
|
|
@@ -197,7 +376,26 @@ export async function startMcpServer(options = {}) {
|
|
|
197
376
|
else if (watch && config.fileWatcherGraphPath) {
|
|
198
377
|
startGraphFileWatcher(graph, { graphPath: config.fileWatcherGraphPath });
|
|
199
378
|
}
|
|
200
|
-
const server = new Server({ name: 'corum', version: '0.1.0' }, { capabilities: { tools: {} } });
|
|
379
|
+
const server = new Server({ name: 'corum', version: '0.1.0' }, { capabilities: { tools: {}, prompts: {} } });
|
|
380
|
+
server.setRequestHandler(ListPromptsRequestSchema, async () => ({
|
|
381
|
+
prompts: [
|
|
382
|
+
{
|
|
383
|
+
name: 'usage-guide',
|
|
384
|
+
description: 'Orientation guide - recommended workflow, node ID format, edge types, output formats, and common query patterns.',
|
|
385
|
+
},
|
|
386
|
+
],
|
|
387
|
+
}));
|
|
388
|
+
server.setRequestHandler(GetPromptRequestSchema, async (request) => {
|
|
389
|
+
if (request.params.name !== 'usage-guide') {
|
|
390
|
+
throw new Error(`Unknown prompt: ${request.params.name}`);
|
|
391
|
+
}
|
|
392
|
+
return {
|
|
393
|
+
description: 'Corum graph query orientation guide',
|
|
394
|
+
messages: [
|
|
395
|
+
{ role: 'user', content: { type: 'text', text: USAGE_GUIDE_PROMPT } },
|
|
396
|
+
],
|
|
397
|
+
};
|
|
398
|
+
});
|
|
201
399
|
server.setRequestHandler(ListToolsRequestSchema, async () => ({
|
|
202
400
|
tools: [
|
|
203
401
|
{
|
|
@@ -206,10 +404,31 @@ export async function startMcpServer(options = {}) {
|
|
|
206
404
|
inputSchema: {
|
|
207
405
|
type: 'object',
|
|
208
406
|
properties: {
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
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
|
+
},
|
|
213
432
|
branch: { type: 'string', description: 'Branch ref to load nodes from' },
|
|
214
433
|
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
215
434
|
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
@@ -249,6 +468,13 @@ export async function startMcpServer(options = {}) {
|
|
|
249
468
|
required: ['node_id'],
|
|
250
469
|
properties: {
|
|
251
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.' },
|
|
252
478
|
branch: { type: 'string', description: 'Branch ref to load the cluster from' },
|
|
253
479
|
overlay_refs: {
|
|
254
480
|
type: 'array',
|
|
@@ -260,6 +486,65 @@ export async function startMcpServer(options = {}) {
|
|
|
260
486
|
},
|
|
261
487
|
},
|
|
262
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
|
+
},
|
|
263
548
|
{
|
|
264
549
|
name: 'get_linked_fields',
|
|
265
550
|
description: 'Get all maps-to edges touching fields owned by the given root node.',
|
|
@@ -274,6 +559,41 @@ export async function startMcpServer(options = {}) {
|
|
|
274
559
|
},
|
|
275
560
|
},
|
|
276
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
|
+
},
|
|
277
597
|
{
|
|
278
598
|
name: 'list_branches',
|
|
279
599
|
description: 'List branches available from the configured graph source and their load status.',
|
|
@@ -314,8 +634,18 @@ export async function startMcpServer(options = {}) {
|
|
|
314
634
|
return await handlers.get_template(args);
|
|
315
635
|
case 'get_cluster':
|
|
316
636
|
return await handlers.get_cluster(args);
|
|
637
|
+
case 'get_graph':
|
|
638
|
+
return await handlers.get_graph(args);
|
|
639
|
+
case 'get_graph_metadata':
|
|
640
|
+
return await handlers.get_graph_metadata(args);
|
|
641
|
+
case 'get_lineage':
|
|
642
|
+
return await handlers.get_lineage(args);
|
|
317
643
|
case 'get_linked_fields':
|
|
318
644
|
return await handlers.get_linked_fields(args);
|
|
645
|
+
case 'get_graph_summary':
|
|
646
|
+
return await handlers.get_graph_summary(args);
|
|
647
|
+
case 'search_nodes':
|
|
648
|
+
return await handlers.search_nodes(args);
|
|
319
649
|
case 'list_branches':
|
|
320
650
|
return await handlers.list_branches(args);
|
|
321
651
|
case 'diff_branch':
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
export const USAGE_GUIDE_PROMPT = `
|
|
2
|
+
# Corum graph - orientation guide
|
|
3
|
+
|
|
4
|
+
Corum models service architecture as a typed graph. Nodes are design artifacts; edges are typed relationships between them.
|
|
5
|
+
|
|
6
|
+
## Node IDs
|
|
7
|
+
|
|
8
|
+
IDs encode the ownership hierarchy as a dot-separated path:
|
|
9
|
+
|
|
10
|
+
{component}.{Template}.{name} - root node
|
|
11
|
+
{component}.{Template}.{name}.{section}.{child} - owned child (for example operations, schemas, fields)
|
|
12
|
+
|
|
13
|
+
Examples:
|
|
14
|
+
orders.DomainModel.order
|
|
15
|
+
orders.DomainModel.order.operations.place
|
|
16
|
+
orders.APIEndpoint.create-order
|
|
17
|
+
|
|
18
|
+
search_nodes and list_nodes only return root nodes.
|
|
19
|
+
|
|
20
|
+
## Edge types
|
|
21
|
+
|
|
22
|
+
Semantic (traversed by default in get_lineage / get_cluster):
|
|
23
|
+
triggers, produces, reads, calls, implements, maps-to, derived-from
|
|
24
|
+
|
|
25
|
+
Structural (excluded from traversal by default):
|
|
26
|
+
has-field, has-value, renamed-from
|
|
27
|
+
|
|
28
|
+
## Graph completeness
|
|
29
|
+
|
|
30
|
+
The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists.
|
|
31
|
+
|
|
32
|
+
When likely relationships are absent, treat naming, shared component context, schema similarity, and lineage adjacency as hypotheses. Then verify by inspecting the relevant nodes, clusters, and source material.
|
|
33
|
+
|
|
34
|
+
## Recommended workflow
|
|
35
|
+
|
|
36
|
+
1. Orient - call get_graph_summary first. Returns node count, component count, orphan count, edge counts by type, and diagnostic count.
|
|
37
|
+
|
|
38
|
+
2. Discover valid values - call get_graph_metadata when you need the available template names, edge types, or enum values for filters and traversal options.
|
|
39
|
+
|
|
40
|
+
3. Find nodes - use search_nodes with one or more terms (OR semantics). It fuzzy-matches node IDs and, when search_properties is enabled, names, descriptions, and x-aka aliases. Pass templates to restrict to a type, for example ["DomainModel"].
|
|
41
|
+
|
|
42
|
+
4. Inspect a node - use get_cluster with a fully-qualified node ID. Returns the root, its owned descendants, and included semantic neighbors.
|
|
43
|
+
|
|
44
|
+
5. Trace relationships - use get_lineage from one or more node IDs. Default: depth 2 downstream. Use direction "both" and a higher depth to see event flow around a node. Each result node carries origin_id, depth, via_edge_type, and via_node_id. When multiple origins reach the same node, origins lists all origin IDs.
|
|
45
|
+
|
|
46
|
+
6. Broad scan - use get_graph or list_nodes with filters to fetch nodes across the graph. get_graph supports templates, exclude_templates, component, state, and stability filters.
|
|
47
|
+
|
|
48
|
+
## Output format tips
|
|
49
|
+
|
|
50
|
+
- Default format is YAML.
|
|
51
|
+
- Use format "json" when you want conventional structured output for downstream parsing.
|
|
52
|
+
- Use format "toon" when you want the most token-efficient machine-readable output, especially for large node or edge lists.
|
|
53
|
+
- Add compact_keys true to shorten common keys (id->i, template->t, component->cp, state->s, stability->st).
|
|
54
|
+
|
|
55
|
+
## Common patterns
|
|
56
|
+
|
|
57
|
+
All events in a component:
|
|
58
|
+
list_nodes - filter { templates: ["DomainEvent", "IntegrationEvent"], component: "orders" }
|
|
59
|
+
|
|
60
|
+
What does an operation produce?
|
|
61
|
+
get_lineage - node_ids: ["orders.DomainModel.order.operations.place"], direction: "downstream"
|
|
62
|
+
|
|
63
|
+
What triggers an operation?
|
|
64
|
+
get_lineage - node_ids: ["orders.DomainModel.order.operations.complete"], direction: "upstream"
|
|
65
|
+
|
|
66
|
+
Full event flow around a node:
|
|
67
|
+
get_lineage - node_ids: ["orders.DomainEvent.order-placed"], direction: "both", depth: 3
|
|
68
|
+
|
|
69
|
+
Field-level mappings between nodes:
|
|
70
|
+
get_linked_fields - returns all maps-to edges touching fields owned by a root node
|
|
71
|
+
|
|
72
|
+
Schema / field details:
|
|
73
|
+
get_cluster - descendants include owned schemas, fields, and enum values
|
|
74
|
+
`.trim();
|