@atolis-hq/corum 0.1.44 → 0.1.46
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 +111 -9
- package/dist/src/graph/index.js +69 -37
- package/dist/src/graph/overlay.js +106 -36
- package/dist/src/import/runner.js +17 -3
- package/dist/src/linter/index.js +242 -106
- package/dist/src/loader/cluster-loader.js +36 -3
- package/dist/src/loader/edge-loader.js +8 -2
- package/dist/src/mcp/index.js +633 -142
- package/dist/src/mcp/prompts/usage-guide.js +73 -65
- package/dist/src/mutate/alias.js +68 -0
- package/dist/src/mutate/apply-cluster.js +255 -0
- package/dist/src/mutate/delete.js +47 -0
- package/dist/src/mutate/errors.js +14 -0
- package/dist/src/mutate/index.js +11 -0
- package/dist/src/mutate/rename.js +135 -0
- package/dist/src/mutate/session.js +551 -0
- package/dist/src/mutate/util.js +62 -0
- package/dist/src/reconcile/index.js +126 -3
- package/dist/src/source/file-source.js +64 -15
- package/dist/src/source/git-source.js +121 -31
- package/dist/src/writer/graph-writer.js +64 -10
- package/package.json +2 -1
package/dist/src/mcp/index.js
CHANGED
|
@@ -6,9 +6,10 @@ import { pathToFileURL } from 'node:url';
|
|
|
6
6
|
import { computeClusterOverlay, expandExternalNodes, getClusterView, getGraphSummary, getLineage, getLinkedFields, getStructuralNodeTemplates, getVisibleEdgeTypes, isVisibleEdgeType, listNodes, searchNodes, } from '../graph/index.js';
|
|
7
7
|
import { loadGraph, loadMultiGraph } from '../loader/index.js';
|
|
8
8
|
import { QueryError } from '../schema/index.js';
|
|
9
|
+
import { MutationError, getActiveSession, startSession } from '../mutate/index.js';
|
|
9
10
|
import { createGraphRuntimeConfig } from '../source/config.js';
|
|
10
11
|
import { createMultiGraphCache, replaceGraph, startGraphFileWatcher, startWebServer } from '../web/server.js';
|
|
11
|
-
import {
|
|
12
|
+
import { buildUsageGuidePrompt } from './prompts/usage-guide.js';
|
|
12
13
|
import { collapseClusterSchemas } from '../graph/schema-collapse.js';
|
|
13
14
|
import { compactKeys, getSerializer } from './serializers.js';
|
|
14
15
|
const STATE_VALUES = ['draft', 'proposed', 'agreed', 'future', 'removed', 'implemented'];
|
|
@@ -75,6 +76,7 @@ function fullNode(node, includeProvenance) {
|
|
|
75
76
|
component: node.component,
|
|
76
77
|
state: node.state,
|
|
77
78
|
stability: node.stability,
|
|
79
|
+
...(node.corum !== undefined ? { corum: node.corum } : {}),
|
|
78
80
|
properties: node.properties,
|
|
79
81
|
...(includeProvenance ? withProvenance(node) : {}),
|
|
80
82
|
};
|
|
@@ -131,6 +133,21 @@ function mapLineageNode(node, includeProvenance, lean) {
|
|
|
131
133
|
}
|
|
132
134
|
export function createMcpHandlers(graph, source, cache) {
|
|
133
135
|
const resolveMulti = (src) => cache ? cache.get() : loadMultiGraph({ source: src });
|
|
136
|
+
// Reads reflect the working session while one is open (design §7/§8):
|
|
137
|
+
// un-branched reads serve the session's working graph; branch-scoped reads
|
|
138
|
+
// for the session's own branch do too (see withBranchGraph). Behaviour with
|
|
139
|
+
// no open session is unchanged.
|
|
140
|
+
const readGraph = () => {
|
|
141
|
+
const session = getActiveSession();
|
|
142
|
+
return session && !session.isClosed() ? session.graph : graph;
|
|
143
|
+
};
|
|
144
|
+
const requireSession = () => {
|
|
145
|
+
const session = getActiveSession();
|
|
146
|
+
if (!session || session.isClosed()) {
|
|
147
|
+
throw new QueryError('no working session is open — call start_changes first');
|
|
148
|
+
}
|
|
149
|
+
return session;
|
|
150
|
+
};
|
|
134
151
|
return {
|
|
135
152
|
list_nodes(args) {
|
|
136
153
|
const run = (targetGraph) => {
|
|
@@ -143,7 +160,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
143
160
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
|
|
144
161
|
}
|
|
145
162
|
try {
|
|
146
|
-
return run(
|
|
163
|
+
return run(readGraph());
|
|
147
164
|
}
|
|
148
165
|
catch (err) {
|
|
149
166
|
return errorResult(err);
|
|
@@ -155,7 +172,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
155
172
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
|
|
156
173
|
}
|
|
157
174
|
try {
|
|
158
|
-
return run(
|
|
175
|
+
return run(readGraph());
|
|
159
176
|
}
|
|
160
177
|
catch (err) {
|
|
161
178
|
return errorResult(err);
|
|
@@ -177,19 +194,16 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
177
194
|
};
|
|
178
195
|
const wantFull = args.full_nodes === true;
|
|
179
196
|
const incProv = includesProvenance(args);
|
|
180
|
-
const results = searchNodes(targetGraph, queries, options).map(result =>
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
? fullNode(result.node, incProv)
|
|
184
|
-
: summarizeNode(result.node, incProv),
|
|
185
|
-
}));
|
|
197
|
+
const results = searchNodes(targetGraph, queries, options).map(result => wantFull
|
|
198
|
+
? fullNode(result.node, incProv)
|
|
199
|
+
: summarizeNode(result.node, incProv));
|
|
186
200
|
return formatResult(results, args.format, getCompactKeys(args));
|
|
187
201
|
};
|
|
188
202
|
if (hasBranch(args) && source) {
|
|
189
203
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
|
|
190
204
|
}
|
|
191
205
|
try {
|
|
192
|
-
return run(
|
|
206
|
+
return run(readGraph());
|
|
193
207
|
}
|
|
194
208
|
catch (err) {
|
|
195
209
|
return errorResult(err);
|
|
@@ -213,7 +227,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
213
227
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
|
|
214
228
|
}
|
|
215
229
|
try {
|
|
216
|
-
return run(
|
|
230
|
+
return run(readGraph());
|
|
217
231
|
}
|
|
218
232
|
catch (err) {
|
|
219
233
|
return errorResult(err);
|
|
@@ -222,7 +236,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
222
236
|
get_template(args) {
|
|
223
237
|
try {
|
|
224
238
|
const name = String(args.name);
|
|
225
|
-
const template =
|
|
239
|
+
const template = readGraph().templates.get(name);
|
|
226
240
|
if (!template) {
|
|
227
241
|
throw new QueryError(`Template not found: ${name}`);
|
|
228
242
|
}
|
|
@@ -252,7 +266,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
252
266
|
const includeProvenance = includesProvenance(args);
|
|
253
267
|
const collapseSchemas = args.collapse_schemas !== false;
|
|
254
268
|
const includeEdges = args.include_edges === true;
|
|
255
|
-
const includeDescendants = args.include_descendants
|
|
269
|
+
const includeDescendants = args.include_descendants === true;
|
|
256
270
|
const nodeTypes = toStringArray(args.node_types);
|
|
257
271
|
const edgeOptions = getEdgeOutputOptions(args);
|
|
258
272
|
let clusterPayload;
|
|
@@ -315,7 +329,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
315
329
|
if (branchRef) {
|
|
316
330
|
return withBranchGraph(source, branchRef, branch => run(branch.graph, branchRef), cache);
|
|
317
331
|
}
|
|
318
|
-
return run(
|
|
332
|
+
return run(readGraph()).catch(err => errorResult(err));
|
|
319
333
|
},
|
|
320
334
|
get_graph(args) {
|
|
321
335
|
const run = (targetGraph) => {
|
|
@@ -344,7 +358,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
344
358
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
|
|
345
359
|
}
|
|
346
360
|
try {
|
|
347
|
-
return run(
|
|
361
|
+
return run(readGraph());
|
|
348
362
|
}
|
|
349
363
|
catch (err) {
|
|
350
364
|
return errorResult(err);
|
|
@@ -378,7 +392,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
378
392
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
|
|
379
393
|
}
|
|
380
394
|
try {
|
|
381
|
-
return run(
|
|
395
|
+
return run(readGraph());
|
|
382
396
|
}
|
|
383
397
|
catch (err) {
|
|
384
398
|
return errorResult(err);
|
|
@@ -421,7 +435,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
421
435
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
|
|
422
436
|
}
|
|
423
437
|
try {
|
|
424
|
-
return run(
|
|
438
|
+
return run(readGraph());
|
|
425
439
|
}
|
|
426
440
|
catch (err) {
|
|
427
441
|
return errorResult(err);
|
|
@@ -441,7 +455,7 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
441
455
|
return withBranchGraph(source, String(args.branch), branch => run(branch.graph), cache);
|
|
442
456
|
}
|
|
443
457
|
try {
|
|
444
|
-
return run(
|
|
458
|
+
return run(readGraph());
|
|
445
459
|
}
|
|
446
460
|
catch (err) {
|
|
447
461
|
return errorResult(err);
|
|
@@ -478,10 +492,276 @@ export function createMcpHandlers(graph, source, cache) {
|
|
|
478
492
|
return errorResult(err);
|
|
479
493
|
}
|
|
480
494
|
},
|
|
495
|
+
// -- write tools (design §8): thin wrappers over the working session ------
|
|
496
|
+
async start_changes(args) {
|
|
497
|
+
try {
|
|
498
|
+
if (!source)
|
|
499
|
+
throw new QueryError('GraphSource is required for start_changes');
|
|
500
|
+
const session = await startSession(source, {
|
|
501
|
+
branch: typeof args.branch === 'string' ? args.branch : undefined,
|
|
502
|
+
create: args.create === true,
|
|
503
|
+
...(typeof args.autosave === 'boolean' ? { autosave: args.autosave } : {}),
|
|
504
|
+
});
|
|
505
|
+
return formatResult({
|
|
506
|
+
branch: session.branch,
|
|
507
|
+
default_branch: session.defaultBranch,
|
|
508
|
+
base_sha: session.baseSha,
|
|
509
|
+
autosave: session.autosave,
|
|
510
|
+
}, args.format, getCompactKeys(args));
|
|
511
|
+
}
|
|
512
|
+
catch (err) {
|
|
513
|
+
return errorResult(err, args.format);
|
|
514
|
+
}
|
|
515
|
+
},
|
|
516
|
+
async apply_cluster(args) {
|
|
517
|
+
try {
|
|
518
|
+
const session = requireSession();
|
|
519
|
+
if (args.mode !== 'merge' && args.mode !== 'replace') {
|
|
520
|
+
throw new QueryError("mode must be 'merge' or 'replace'");
|
|
521
|
+
}
|
|
522
|
+
if (!isPlainObject(args.document)) {
|
|
523
|
+
throw new QueryError('document must be an object (cluster-style document)');
|
|
524
|
+
}
|
|
525
|
+
const result = await session.applyCluster(args.document, args.mode);
|
|
526
|
+
return formatResult(result, args.format, getCompactKeys(args));
|
|
527
|
+
}
|
|
528
|
+
catch (err) {
|
|
529
|
+
return errorResult(err, args.format);
|
|
530
|
+
}
|
|
531
|
+
},
|
|
532
|
+
async create_node(args) {
|
|
533
|
+
try {
|
|
534
|
+
const session = requireSession();
|
|
535
|
+
if (!isPlainObject(args.document)) {
|
|
536
|
+
throw new QueryError('document is required and must be an object');
|
|
537
|
+
}
|
|
538
|
+
const result = await session.createNode({
|
|
539
|
+
document: args.document,
|
|
540
|
+
parentId: typeof args.parent_id === 'string' ? args.parent_id : undefined,
|
|
541
|
+
section: typeof args.section === 'string' ? args.section : undefined,
|
|
542
|
+
name: typeof args.name === 'string' ? args.name : undefined,
|
|
543
|
+
});
|
|
544
|
+
return formatResult(result, args.format, getCompactKeys(args));
|
|
545
|
+
}
|
|
546
|
+
catch (err) {
|
|
547
|
+
return errorResult(err, args.format);
|
|
548
|
+
}
|
|
549
|
+
},
|
|
550
|
+
async update_node(args) {
|
|
551
|
+
try {
|
|
552
|
+
const session = requireSession();
|
|
553
|
+
const result = await session.updateNode(requireString(args.id, 'id'), {
|
|
554
|
+
properties: isPlainObject(args.properties) ? args.properties : undefined,
|
|
555
|
+
state: args.state,
|
|
556
|
+
stability: args.stability,
|
|
557
|
+
});
|
|
558
|
+
return formatResult(result, args.format, getCompactKeys(args));
|
|
559
|
+
}
|
|
560
|
+
catch (err) {
|
|
561
|
+
return errorResult(err, args.format);
|
|
562
|
+
}
|
|
563
|
+
},
|
|
564
|
+
async rename_node(args) {
|
|
565
|
+
try {
|
|
566
|
+
const session = requireSession();
|
|
567
|
+
const result = await session.renameNode(requireString(args.id, 'id'), requireString(args.new_name, 'new_name'), typeof args.record_trail === 'boolean' ? args.record_trail : undefined);
|
|
568
|
+
return formatResult(result, args.format, getCompactKeys(args));
|
|
569
|
+
}
|
|
570
|
+
catch (err) {
|
|
571
|
+
return errorResult(err, args.format);
|
|
572
|
+
}
|
|
573
|
+
},
|
|
574
|
+
async delete_node(args) {
|
|
575
|
+
try {
|
|
576
|
+
const session = requireSession();
|
|
577
|
+
const result = await session.deleteNode(requireString(args.id, 'id'), {
|
|
578
|
+
purge: args.purge === true,
|
|
579
|
+
recordTrail: typeof args.record_trail === 'boolean' ? args.record_trail : undefined,
|
|
580
|
+
});
|
|
581
|
+
return formatResult(result, args.format, getCompactKeys(args));
|
|
582
|
+
}
|
|
583
|
+
catch (err) {
|
|
584
|
+
return errorResult(err, args.format);
|
|
585
|
+
}
|
|
586
|
+
},
|
|
587
|
+
async create_fields(args) {
|
|
588
|
+
try {
|
|
589
|
+
const session = requireSession();
|
|
590
|
+
if (!Array.isArray(args.fields)) {
|
|
591
|
+
throw new QueryError('fields is required and must be an array');
|
|
592
|
+
}
|
|
593
|
+
// Group by parent so fields sharing a root/schema become one merged
|
|
594
|
+
// document: one applyCluster call per parent (atomic per parent),
|
|
595
|
+
// instead of one call per field.
|
|
596
|
+
const documentsByParent = new Map();
|
|
597
|
+
const order = [];
|
|
598
|
+
const fieldPaths = [];
|
|
599
|
+
args.fields.forEach((field, index) => {
|
|
600
|
+
if (!isPlainObject(field)) {
|
|
601
|
+
throw new QueryError(`fields[${index}] must be an object`);
|
|
602
|
+
}
|
|
603
|
+
const parentId = requireString(pickDefined(field.parent_id, field.parentId), `fields[${index}].parent_id`);
|
|
604
|
+
const schemaName = requireString(pickDefined(field.schema_name, field.schemaName), `fields[${index}].schema_name`);
|
|
605
|
+
const fieldName = requireString(field.name, `fields[${index}].name`);
|
|
606
|
+
const fieldDef = {
|
|
607
|
+
type: requireString(field.type, `fields[${index}].type`),
|
|
608
|
+
};
|
|
609
|
+
if (field.nullable !== undefined) {
|
|
610
|
+
if (typeof field.nullable !== 'boolean') {
|
|
611
|
+
throw new QueryError(`fields[${index}].nullable must be a boolean`);
|
|
612
|
+
}
|
|
613
|
+
fieldDef.nullable = field.nullable;
|
|
614
|
+
}
|
|
615
|
+
if (typeof field.description === 'string') {
|
|
616
|
+
fieldDef.description = field.description;
|
|
617
|
+
}
|
|
618
|
+
if (field.state !== undefined)
|
|
619
|
+
fieldDef.state = field.state;
|
|
620
|
+
if (field.stability !== undefined)
|
|
621
|
+
fieldDef.stability = field.stability;
|
|
622
|
+
let document = documentsByParent.get(parentId);
|
|
623
|
+
if (!document) {
|
|
624
|
+
document = { id: parentId, schemas: {} };
|
|
625
|
+
documentsByParent.set(parentId, document);
|
|
626
|
+
order.push(parentId);
|
|
627
|
+
}
|
|
628
|
+
const schemas = document.schemas;
|
|
629
|
+
const schema = (schemas[schemaName] ??= { fields: {} });
|
|
630
|
+
const fields = schema.fields;
|
|
631
|
+
fields[fieldName] = fieldDef;
|
|
632
|
+
fieldPaths.push({ parentId, schemaName, fieldName });
|
|
633
|
+
});
|
|
634
|
+
const results = [];
|
|
635
|
+
for (const parentId of order) {
|
|
636
|
+
const result = await session.applyCluster(documentsByParent.get(parentId), 'merge');
|
|
637
|
+
results.push({ parentId, summary: result.summary, createdIds: result.createdIds, warnings: result.warnings });
|
|
638
|
+
}
|
|
639
|
+
return formatResult({ created: fieldPaths.length, fields: fieldPaths, applied: results }, args.format, getCompactKeys(args));
|
|
640
|
+
}
|
|
641
|
+
catch (err) {
|
|
642
|
+
return errorResult(err, args.format);
|
|
643
|
+
}
|
|
644
|
+
},
|
|
645
|
+
async create_edges(args) {
|
|
646
|
+
try {
|
|
647
|
+
const session = requireSession();
|
|
648
|
+
if (!Array.isArray(args.edges)) {
|
|
649
|
+
throw new QueryError('edges is required and must be an array');
|
|
650
|
+
}
|
|
651
|
+
const inputs = args.edges.map((edge, index) => {
|
|
652
|
+
if (!isPlainObject(edge)) {
|
|
653
|
+
throw new QueryError(`edges[${index}] must be an object`);
|
|
654
|
+
}
|
|
655
|
+
return {
|
|
656
|
+
from: requireString(edge.from, `edges[${index}].from`),
|
|
657
|
+
to: requireString(edge.to, `edges[${index}].to`),
|
|
658
|
+
type: requireString(edge.type, `edges[${index}].type`),
|
|
659
|
+
state: edge.state,
|
|
660
|
+
stability: edge.stability,
|
|
661
|
+
notes: typeof edge.notes === 'string' ? edge.notes : undefined,
|
|
662
|
+
properties: isPlainObject(edge.properties) ? edge.properties : undefined,
|
|
663
|
+
};
|
|
664
|
+
});
|
|
665
|
+
// Validated and applied as a single atomic batch (session.createEdges):
|
|
666
|
+
// any invalid edge aborts the whole call before any edge is created.
|
|
667
|
+
const result = await session.createEdges(inputs);
|
|
668
|
+
const edges = result.edges.map(edge => ({ edge }));
|
|
669
|
+
return formatResult({ created: edges.length, edges, summary: result.summary, warnings: result.warnings }, args.format, getCompactKeys(args));
|
|
670
|
+
}
|
|
671
|
+
catch (err) {
|
|
672
|
+
return errorResult(err, args.format);
|
|
673
|
+
}
|
|
674
|
+
},
|
|
675
|
+
async update_edge(args) {
|
|
676
|
+
try {
|
|
677
|
+
const session = requireSession();
|
|
678
|
+
const result = await session.updateEdge(requireString(args.id, 'id'), {
|
|
679
|
+
state: args.state,
|
|
680
|
+
stability: args.stability,
|
|
681
|
+
notes: args.notes === null ? null : typeof args.notes === 'string' ? args.notes : undefined,
|
|
682
|
+
properties: isPlainObject(args.properties) ? args.properties : undefined,
|
|
683
|
+
});
|
|
684
|
+
return formatResult(result, args.format, getCompactKeys(args));
|
|
685
|
+
}
|
|
686
|
+
catch (err) {
|
|
687
|
+
return errorResult(err, args.format);
|
|
688
|
+
}
|
|
689
|
+
},
|
|
690
|
+
async delete_edge(args) {
|
|
691
|
+
try {
|
|
692
|
+
const session = requireSession();
|
|
693
|
+
const result = await session.deleteEdge(requireString(args.id, 'id'));
|
|
694
|
+
return formatResult(result, args.format, getCompactKeys(args));
|
|
695
|
+
}
|
|
696
|
+
catch (err) {
|
|
697
|
+
return errorResult(err, args.format);
|
|
698
|
+
}
|
|
699
|
+
},
|
|
700
|
+
pending_changes(args) {
|
|
701
|
+
try {
|
|
702
|
+
const session = requireSession();
|
|
703
|
+
return formatResult(session.pendingChanges(), args.format, getCompactKeys(args));
|
|
704
|
+
}
|
|
705
|
+
catch (err) {
|
|
706
|
+
return errorResult(err, args.format);
|
|
707
|
+
}
|
|
708
|
+
},
|
|
709
|
+
async discard_changes(args) {
|
|
710
|
+
try {
|
|
711
|
+
const session = requireSession();
|
|
712
|
+
const branch = session.branch;
|
|
713
|
+
session.discard();
|
|
714
|
+
if (session.autosave && session.branch === session.defaultBranch && source) {
|
|
715
|
+
const fresh = await loadGraph({ source, ref: session.defaultBranch, strict: false });
|
|
716
|
+
cache?.invalidate();
|
|
717
|
+
replaceGraph(graph, fresh);
|
|
718
|
+
}
|
|
719
|
+
return formatResult({ discarded: true, branch }, args.format, getCompactKeys(args));
|
|
720
|
+
}
|
|
721
|
+
catch (err) {
|
|
722
|
+
return errorResult(err, args.format);
|
|
723
|
+
}
|
|
724
|
+
},
|
|
725
|
+
async commit_changes(args) {
|
|
726
|
+
try {
|
|
727
|
+
const session = requireSession();
|
|
728
|
+
const result = await session.commitChanges(typeof args.message === 'string' ? args.message : undefined);
|
|
729
|
+
// Committed content invalidates branch-scoped caches; when the session
|
|
730
|
+
// was on the default branch, refresh the base graph in place so
|
|
731
|
+
// post-session reads see the committed state.
|
|
732
|
+
cache?.invalidate();
|
|
733
|
+
if (result.committed && session.branch === session.defaultBranch) {
|
|
734
|
+
replaceGraph(graph, session.graph);
|
|
735
|
+
}
|
|
736
|
+
return formatResult(result, args.format, getCompactKeys(args));
|
|
737
|
+
}
|
|
738
|
+
catch (err) {
|
|
739
|
+
return errorResult(err, args.format);
|
|
740
|
+
}
|
|
741
|
+
},
|
|
481
742
|
};
|
|
482
743
|
}
|
|
744
|
+
/** Prefers `primary` over `secondary`, falling back only when `primary` is absent (not merely falsy/empty). */
|
|
745
|
+
function pickDefined(primary, secondary) {
|
|
746
|
+
return primary !== undefined ? primary : secondary;
|
|
747
|
+
}
|
|
748
|
+
function requireString(value, name) {
|
|
749
|
+
if (typeof value !== 'string' || value.length === 0) {
|
|
750
|
+
throw new QueryError(`${name} is required`);
|
|
751
|
+
}
|
|
752
|
+
return value;
|
|
753
|
+
}
|
|
754
|
+
function isPlainObject(value) {
|
|
755
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
756
|
+
}
|
|
483
757
|
async function withBranchGraph(source, branchRef, fn, cache) {
|
|
484
758
|
try {
|
|
759
|
+
// While a working session is open, branch-scoped reads of the session's
|
|
760
|
+
// branch serve the working graph (design §7: reads see the working state).
|
|
761
|
+
const session = getActiveSession();
|
|
762
|
+
if (session && !session.isClosed() && session.branch === branchRef) {
|
|
763
|
+
return await fn({ ref: branchRef, isDefault: branchRef === session.defaultBranch, graph: session.graph });
|
|
764
|
+
}
|
|
485
765
|
if (!source)
|
|
486
766
|
throw new QueryError('GraphSource is required when branch is provided');
|
|
487
767
|
const multi = cache ? await cache.get() : await loadMultiGraph({ source });
|
|
@@ -519,117 +799,118 @@ export async function ensureGraphLoaded(graph, loadError, loader, onReload) {
|
|
|
519
799
|
}
|
|
520
800
|
function formatResult(value, format, compact = false) {
|
|
521
801
|
const payload = compact === true ? compactKeys(value) : value;
|
|
522
|
-
return { content: [{ type: 'text', text: getSerializer(format).serialize(payload) }] };
|
|
802
|
+
return { content: [{ type: 'text', text: getSerializer(format ?? 'toon').serialize(payload) }] };
|
|
523
803
|
}
|
|
524
804
|
function getCompactKeys(args) {
|
|
525
805
|
return args.compact_keys === true || args.compactKeys === true;
|
|
526
806
|
}
|
|
527
|
-
function errorResult(err) {
|
|
807
|
+
function errorResult(err, format) {
|
|
808
|
+
// Validation failures return the linter's diagnostic format (severity,
|
|
809
|
+
// message, nodeId) so agents can self-correct (design §8).
|
|
810
|
+
if (err instanceof MutationError) {
|
|
811
|
+
const payload = {
|
|
812
|
+
error: err.message,
|
|
813
|
+
diagnostics: err.diagnostics.map(d => ({
|
|
814
|
+
severity: d.severity,
|
|
815
|
+
message: d.message,
|
|
816
|
+
...(d.nodeId !== undefined ? { nodeId: d.nodeId } : {}),
|
|
817
|
+
})),
|
|
818
|
+
};
|
|
819
|
+
let text;
|
|
820
|
+
try {
|
|
821
|
+
text = getSerializer(format ?? 'toon').serialize(payload);
|
|
822
|
+
}
|
|
823
|
+
catch {
|
|
824
|
+
text = getSerializer(undefined).serialize(payload);
|
|
825
|
+
}
|
|
826
|
+
return { content: [{ type: 'text', text }], isError: true };
|
|
827
|
+
}
|
|
528
828
|
const message = err instanceof QueryError ? err.message : String(err);
|
|
529
829
|
return { content: [{ type: 'text', text: message }], isError: true };
|
|
530
830
|
}
|
|
831
|
+
// Shared parameter schemas — these appear on nearly every tool, so factoring
|
|
832
|
+
// them out keeps the always-loaded tool definitions lean and consistent. Deep
|
|
833
|
+
// guidance (compact_keys mapping, toon rationale, workflows) lives in the
|
|
834
|
+
// on-demand usage-guide prompt, not here.
|
|
835
|
+
const FORMAT_PARAM = { type: 'string', enum: [...OUTPUT_FORMATS], description: 'Default toon (lean, self-describing). yaml for humans, json for conventional parsing.' };
|
|
836
|
+
const COMPACT_KEYS_PARAM = { type: 'boolean', description: 'Abbreviate field-name keys to save tokens (see usage-guide). Default false.' };
|
|
837
|
+
const BRANCH_READ_PARAM = { type: 'string', description: 'Branch ref to read from. Default: open session or source default.' };
|
|
838
|
+
const PROVENANCE_PARAM = { type: 'boolean', description: 'Include node provenance (source/derivation). Default false.' };
|
|
839
|
+
const EDGE_IDS_PARAM = { type: 'boolean', description: 'Include edge ids in edge output. Default false.' };
|
|
840
|
+
const STATE_PARAM = { type: 'string', enum: [...STATE_VALUES], description: 'Lifecycle state.' };
|
|
841
|
+
const STABILITY_PARAM = { type: 'string', enum: [...STABILITY_VALUES], description: 'Stability.' };
|
|
842
|
+
const IO_PARAMS = { format: FORMAT_PARAM, compact_keys: COMPACT_KEYS_PARAM };
|
|
531
843
|
export function getMcpToolDefinitions() {
|
|
532
844
|
return [
|
|
533
845
|
{
|
|
534
846
|
name: 'list_nodes',
|
|
535
|
-
description: '
|
|
847
|
+
description: 'Root nodes matching a filter, as slim summaries. Prefer search_nodes for keyword discovery; use this for exhaustive filtered inventories.',
|
|
536
848
|
inputSchema: {
|
|
537
849
|
type: 'object',
|
|
538
850
|
properties: {
|
|
539
851
|
filter: {
|
|
540
852
|
type: 'object',
|
|
541
|
-
description: 'Filter criteria',
|
|
542
853
|
properties: {
|
|
543
|
-
templates: {
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
},
|
|
548
|
-
exclude_templates: {
|
|
549
|
-
type: 'array',
|
|
550
|
-
items: { type: 'string' },
|
|
551
|
-
description: 'Exclude these template types',
|
|
552
|
-
},
|
|
553
|
-
component: { type: 'string', description: 'Filter by component name' },
|
|
554
|
-
state: {
|
|
555
|
-
description: 'Filter by lifecycle state as a string or array',
|
|
556
|
-
oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
|
|
557
|
-
},
|
|
558
|
-
stability: {
|
|
559
|
-
description: 'Filter by stability as a string or array',
|
|
560
|
-
oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
|
|
561
|
-
},
|
|
854
|
+
templates: { type: 'array', items: { type: 'string' }, description: 'Include only these templates (OR).' },
|
|
855
|
+
exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these templates.' },
|
|
856
|
+
component: { type: 'string', description: 'Filter by component.' },
|
|
857
|
+
state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
|
|
858
|
+
stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
|
|
562
859
|
},
|
|
563
860
|
},
|
|
564
|
-
include_provenance:
|
|
565
|
-
branch:
|
|
566
|
-
|
|
567
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
861
|
+
include_provenance: PROVENANCE_PARAM,
|
|
862
|
+
branch: BRANCH_READ_PARAM,
|
|
863
|
+
...IO_PARAMS,
|
|
568
864
|
},
|
|
569
865
|
},
|
|
570
866
|
},
|
|
571
867
|
{
|
|
572
868
|
name: 'list_templates',
|
|
573
|
-
description: 'List loaded
|
|
869
|
+
description: 'List loaded templates with summary metadata (name, version, core, abstract, extends, description).',
|
|
574
870
|
inputSchema: {
|
|
575
871
|
type: 'object',
|
|
576
872
|
properties: {
|
|
577
|
-
branch:
|
|
578
|
-
|
|
579
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
873
|
+
branch: BRANCH_READ_PARAM,
|
|
874
|
+
...IO_PARAMS,
|
|
580
875
|
},
|
|
581
876
|
},
|
|
582
877
|
},
|
|
583
878
|
{
|
|
584
879
|
name: 'get_template',
|
|
585
|
-
description: '
|
|
880
|
+
description: 'Full definition of one template: property schema, owned sections, edge-type constraints, role.',
|
|
586
881
|
inputSchema: {
|
|
587
882
|
type: 'object',
|
|
588
883
|
required: ['name'],
|
|
589
884
|
properties: {
|
|
590
|
-
name: { type: 'string', description: 'Template name' },
|
|
591
|
-
|
|
592
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
885
|
+
name: { type: 'string', description: 'Template name.' },
|
|
886
|
+
...IO_PARAMS,
|
|
593
887
|
},
|
|
594
888
|
},
|
|
595
889
|
},
|
|
596
890
|
{
|
|
597
891
|
name: 'get_cluster',
|
|
598
|
-
description: '
|
|
892
|
+
description: 'Structural detail of ONE node. Returns the root with its collapsed schemas/enums (compact JSON-schema form, not child nodes) by default. Owned descendants (operations, commands, events) are opt-in via include_descendants:true and can be large — narrow with node_types. To follow relationships across nodes use get_lineage instead.',
|
|
599
893
|
inputSchema: {
|
|
600
894
|
type: 'object',
|
|
601
895
|
required: ['node_id'],
|
|
602
896
|
properties: {
|
|
603
|
-
node_id: { type: 'string', description: 'Fully qualified node ID' },
|
|
604
|
-
edge_types: {
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
},
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
description: 'Allowlist of node templates to include in the descendant set. Useful for limiting to specific types (e.g. ["DomainOperation", "DomainEvent"]).',
|
|
615
|
-
},
|
|
616
|
-
include_edges: { type: 'boolean', description: 'Include the edge list in the response. Default false.' },
|
|
617
|
-
include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
|
|
618
|
-
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
619
|
-
branch: { type: 'string', description: 'Branch ref to load the cluster from' },
|
|
620
|
-
overlay_refs: {
|
|
621
|
-
type: 'array',
|
|
622
|
-
items: { type: 'string' },
|
|
623
|
-
description: 'Branch refs to overlay. Returns ghost field data alongside the cluster.',
|
|
624
|
-
},
|
|
625
|
-
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
626
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
897
|
+
node_id: { type: 'string', description: 'Fully qualified node ID.' },
|
|
898
|
+
edge_types: { type: 'array', items: { type: 'string' }, description: 'External-node edge types to follow. Default: all semantic.' },
|
|
899
|
+
collapse_schemas: { type: 'boolean', description: 'Collapse schema/enum children into compact schemas+enums blocks on the root. Default true.' },
|
|
900
|
+
include_descendants: { type: 'boolean', description: 'Include owned descendants (operations, commands, events). Opt-in; can be large. Default false.' },
|
|
901
|
+
node_types: { type: 'array', items: { type: 'string' }, description: 'Restrict descendants to these templates.' },
|
|
902
|
+
include_edges: { type: 'boolean', description: 'Include the edge list. Default false.' },
|
|
903
|
+
include_edge_ids: EDGE_IDS_PARAM,
|
|
904
|
+
include_provenance: PROVENANCE_PARAM,
|
|
905
|
+
branch: BRANCH_READ_PARAM,
|
|
906
|
+
overlay_refs: { type: 'array', items: { type: 'string' }, description: 'Branch refs to overlay as ghost field data.' },
|
|
907
|
+
...IO_PARAMS,
|
|
627
908
|
},
|
|
628
909
|
},
|
|
629
910
|
},
|
|
630
911
|
{
|
|
631
912
|
name: 'get_graph',
|
|
632
|
-
description: '
|
|
913
|
+
description: 'Semantic nodes across the whole graph (structural templates/edges excluded); include_edges adds semantic edges. Whole-graph payload is large — prefer search_nodes or get_lineage for targeted work.',
|
|
633
914
|
inputSchema: {
|
|
634
915
|
type: 'object',
|
|
635
916
|
properties: {
|
|
@@ -643,130 +924,314 @@ export function getMcpToolDefinitions() {
|
|
|
643
924
|
stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
|
|
644
925
|
},
|
|
645
926
|
},
|
|
646
|
-
include_edges: { type: 'boolean', description: 'Include
|
|
647
|
-
include_provenance:
|
|
648
|
-
branch:
|
|
649
|
-
|
|
650
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
927
|
+
include_edges: { type: 'boolean', description: 'Include semantic edges. Default false.' },
|
|
928
|
+
include_provenance: PROVENANCE_PARAM,
|
|
929
|
+
branch: BRANCH_READ_PARAM,
|
|
930
|
+
...IO_PARAMS,
|
|
651
931
|
},
|
|
652
932
|
},
|
|
653
933
|
},
|
|
654
934
|
{
|
|
655
935
|
name: 'get_graph_metadata',
|
|
656
|
-
description: '
|
|
936
|
+
description: 'Discover graph contents: template names, node templates in use, edge types in use. Call first; only traverse edge types listed in edge_types_in_use. include_static_enums:true adds valid edge types, states, stabilities, directions, formats.',
|
|
657
937
|
inputSchema: {
|
|
658
938
|
type: 'object',
|
|
659
939
|
properties: {
|
|
660
|
-
include_static_enums: { type: 'boolean', description: '
|
|
661
|
-
branch:
|
|
662
|
-
|
|
663
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
940
|
+
include_static_enums: { type: 'boolean', description: 'Also return valid edge types, states, stabilities, directions, formats. Default false.' },
|
|
941
|
+
branch: BRANCH_READ_PARAM,
|
|
942
|
+
...IO_PARAMS,
|
|
664
943
|
},
|
|
665
944
|
},
|
|
666
945
|
},
|
|
667
946
|
{
|
|
668
947
|
name: 'get_lineage',
|
|
669
|
-
description: '
|
|
948
|
+
description: 'BFS traversal from origin node(s); returns reachable nodes annotated with depth and the edge/node they arrived via. Batch multiple node_ids in one call — results merge and dedupe. Lean by default; scope with direction, depth, and edge_types.',
|
|
670
949
|
inputSchema: {
|
|
671
950
|
type: 'object',
|
|
672
951
|
required: ['node_ids'],
|
|
673
952
|
properties: {
|
|
674
|
-
node_ids: {
|
|
675
|
-
type: 'array',
|
|
676
|
-
items: { type: 'string' },
|
|
677
|
-
description: 'Fully-qualified IDs of origin nodes. All expand in parallel.',
|
|
678
|
-
},
|
|
953
|
+
node_ids: { type: 'array', items: { type: 'string' }, description: 'Origin node IDs; all expand in parallel.' },
|
|
679
954
|
depth: { type: 'number', description: 'Max hops. Default 2.' },
|
|
680
|
-
direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: '
|
|
955
|
+
direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: 'Default downstream.' },
|
|
681
956
|
edge_types: { type: 'array', items: { type: 'string' }, description: 'Edge types to traverse. Default: all non-structural.' },
|
|
682
|
-
node_types: { type: 'array', items: { type: 'string' }, description: '
|
|
683
|
-
exclude_node_types: { type: 'array', items: { type: 'string' }, description: '
|
|
684
|
-
include_dangling_edges: { type: 'boolean', description: 'Include dangling edges
|
|
685
|
-
reads_outbound_only: { type: 'boolean', description: '
|
|
686
|
-
lean: { type: 'boolean', description: '
|
|
687
|
-
include_edges: { type: 'boolean', description: 'Include
|
|
688
|
-
include_edge_ids:
|
|
689
|
-
include_provenance:
|
|
690
|
-
branch:
|
|
691
|
-
|
|
692
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
957
|
+
node_types: { type: 'array', items: { type: 'string' }, description: 'Template allowlist.' },
|
|
958
|
+
exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Template denylist.' },
|
|
959
|
+
include_dangling_edges: { type: 'boolean', description: 'Include dangling edges. Default false.' },
|
|
960
|
+
reads_outbound_only: { type: 'boolean', description: 'Skip inbound reads/uses-type in upstream traversal. Default true.' },
|
|
961
|
+
lean: { type: 'boolean', description: 'Minimal node shape (ids + traversal annotations only). Default true.' },
|
|
962
|
+
include_edges: { type: 'boolean', description: 'Include edges. Default false.' },
|
|
963
|
+
include_edge_ids: EDGE_IDS_PARAM,
|
|
964
|
+
include_provenance: PROVENANCE_PARAM,
|
|
965
|
+
branch: BRANCH_READ_PARAM,
|
|
966
|
+
...IO_PARAMS,
|
|
693
967
|
},
|
|
694
968
|
},
|
|
695
969
|
},
|
|
696
970
|
{
|
|
697
971
|
name: 'get_linked_fields',
|
|
698
|
-
description: '
|
|
972
|
+
description: 'All maps-to edges touching fields owned by the given root node.',
|
|
699
973
|
inputSchema: {
|
|
700
974
|
type: 'object',
|
|
701
975
|
required: ['node_id'],
|
|
702
976
|
properties: {
|
|
703
|
-
node_id: { type: 'string', description: 'Fully qualified root node ID' },
|
|
704
|
-
include_edge_ids:
|
|
705
|
-
include_provenance:
|
|
706
|
-
branch:
|
|
707
|
-
|
|
708
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
977
|
+
node_id: { type: 'string', description: 'Fully qualified root node ID.' },
|
|
978
|
+
include_edge_ids: EDGE_IDS_PARAM,
|
|
979
|
+
include_provenance: PROVENANCE_PARAM,
|
|
980
|
+
branch: BRANCH_READ_PARAM,
|
|
981
|
+
...IO_PARAMS,
|
|
709
982
|
},
|
|
710
983
|
},
|
|
711
984
|
},
|
|
712
985
|
{
|
|
713
986
|
name: 'get_graph_summary',
|
|
714
|
-
description: '
|
|
987
|
+
description: 'High-level stats: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
|
|
715
988
|
inputSchema: {
|
|
716
989
|
type: 'object',
|
|
717
990
|
properties: {
|
|
718
|
-
branch:
|
|
719
|
-
|
|
720
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
991
|
+
branch: BRANCH_READ_PARAM,
|
|
992
|
+
...IO_PARAMS,
|
|
721
993
|
},
|
|
722
994
|
},
|
|
723
995
|
},
|
|
724
996
|
{
|
|
725
997
|
name: 'search_nodes',
|
|
726
|
-
description: '
|
|
998
|
+
description: 'Ranked fuzzy search for root nodes by ID segment. Returns slim summaries (id, template, component, state, stability). Preferred discovery entry point; use list_nodes only for exhaustive filtered inventories.',
|
|
727
999
|
inputSchema: {
|
|
728
1000
|
type: 'object',
|
|
729
1001
|
required: ['queries'],
|
|
730
1002
|
properties: {
|
|
731
|
-
queries: {
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
},
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
full_nodes: { type: 'boolean', description: 'Include properties on each result node. Default false.' },
|
|
742
|
-
include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
|
|
743
|
-
branch: { type: 'string', description: 'Branch ref to search within' },
|
|
744
|
-
format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
|
|
745
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
1003
|
+
queries: { type: 'array', items: { type: 'string' }, description: 'Search terms (OR).' },
|
|
1004
|
+
templates: { type: 'array', items: { type: 'string' }, description: 'Template allowlist.' },
|
|
1005
|
+
exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Template denylist.' },
|
|
1006
|
+
page_size: { type: 'number', description: 'Max results. Default 10.' },
|
|
1007
|
+
offset: { type: 'number', description: 'Pagination offset. Default 0.' },
|
|
1008
|
+
search_properties: { type: 'boolean', description: 'Also match name/description/x-aka. Default false.' },
|
|
1009
|
+
full_nodes: { type: 'boolean', description: 'Add every property to each result — far larger output; leave off unless you need the bodies. Default false.' },
|
|
1010
|
+
include_provenance: PROVENANCE_PARAM,
|
|
1011
|
+
branch: BRANCH_READ_PARAM,
|
|
1012
|
+
...IO_PARAMS,
|
|
746
1013
|
},
|
|
747
1014
|
},
|
|
748
1015
|
},
|
|
749
1016
|
{
|
|
750
1017
|
name: 'list_branches',
|
|
751
|
-
description: 'List branches available from the
|
|
1018
|
+
description: 'List branches available from the graph source and their load status.',
|
|
752
1019
|
inputSchema: {
|
|
753
1020
|
type: 'object',
|
|
754
1021
|
properties: {
|
|
755
|
-
|
|
756
|
-
compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
|
|
1022
|
+
...IO_PARAMS,
|
|
757
1023
|
},
|
|
758
1024
|
},
|
|
759
1025
|
},
|
|
760
1026
|
{
|
|
761
1027
|
name: 'diff_branch',
|
|
762
|
-
description: 'Diff a branch against the default branch.',
|
|
1028
|
+
description: 'Diff a branch against the default branch. Rename-aware: old IDs resolve through the rename trail, so a branch holding an old name overlays the renamed node rather than showing add+remove. warnings flags branches editing a retired name — rebase the branch or apply the rename.',
|
|
763
1029
|
inputSchema: {
|
|
764
1030
|
type: 'object',
|
|
765
1031
|
required: ['branch'],
|
|
766
1032
|
properties: {
|
|
767
|
-
branch: { type: 'string', description: 'Branch ref to diff against the default branch' },
|
|
768
|
-
|
|
769
|
-
|
|
1033
|
+
branch: { type: 'string', description: 'Branch ref to diff against the default branch.' },
|
|
1034
|
+
...IO_PARAMS,
|
|
1035
|
+
},
|
|
1036
|
+
},
|
|
1037
|
+
},
|
|
1038
|
+
{
|
|
1039
|
+
name: 'start_changes',
|
|
1040
|
+
description: 'Open a write session — required before any mutation; while open, reads reflect uncommitted state. Mutations persist only at commit_changes; discard_changes aborts. autosave defaults OFF. Git default branches are read-only: pass a writable branch or create:true to fork from default head. Errors if a session with pending changes is already open (commit or discard first).',
|
|
1041
|
+
inputSchema: {
|
|
1042
|
+
type: 'object',
|
|
1043
|
+
properties: {
|
|
1044
|
+
branch: { type: 'string', description: 'Branch to load and commit to. Default: source default.' },
|
|
1045
|
+
create: { type: 'boolean', description: 'Fork a new branch from default head (git only). Default false.' },
|
|
1046
|
+
autosave: { type: 'boolean', description: 'Persist each mutation (file: write-through; git: WIP checkpoint commit). Default false.' },
|
|
1047
|
+
...IO_PARAMS,
|
|
1048
|
+
},
|
|
1049
|
+
},
|
|
1050
|
+
},
|
|
1051
|
+
{
|
|
1052
|
+
name: 'apply_cluster',
|
|
1053
|
+
description: 'Upsert a cluster-style nested document (same shape as cluster YAML: root fields + owned sections of named children). merge: patch only what is present (null property clears a key). replace: WARNING document is AUTHORITATIVE — children and owned sections absent from it are DELETED (an absent section means an empty section). A changed child key is delete+add, never a rename — use rename_node. Needs an open session.',
|
|
1054
|
+
inputSchema: {
|
|
1055
|
+
type: 'object',
|
|
1056
|
+
required: ['document', 'mode'],
|
|
1057
|
+
properties: {
|
|
1058
|
+
document: { type: 'object', description: 'Root node plus owned sections with named children.' },
|
|
1059
|
+
mode: { type: 'string', enum: ['merge', 'replace'], description: 'merge: patch present fields. replace: authoritative — absent children/sections DELETED.' },
|
|
1060
|
+
...IO_PARAMS,
|
|
1061
|
+
},
|
|
1062
|
+
},
|
|
1063
|
+
},
|
|
1064
|
+
{
|
|
1065
|
+
name: 'create_node',
|
|
1066
|
+
description: 'Create a root cluster (omit parent_id; document needs id+template) or an owned child (pass parent_id+section+name; document is the child body). Nested owned children and structural edges (has-field, has-value) generate automatically. Defaults: state proposed, stability unstable. Needs an open session.',
|
|
1067
|
+
inputSchema: {
|
|
1068
|
+
type: 'object',
|
|
1069
|
+
required: ['document'],
|
|
1070
|
+
properties: {
|
|
1071
|
+
document: { type: 'object', description: 'Root: {id, template, properties?, ...ownedSections}. Child: the body (properties flattened, optional nested sections).' },
|
|
1072
|
+
parent_id: { type: 'string', description: 'Owning parent ID — omit for a root cluster.' },
|
|
1073
|
+
section: { type: 'string', description: 'Owned section under parent (e.g. fields, schemas); required with parent_id.' },
|
|
1074
|
+
name: { type: 'string', description: 'Local name of the new child; required with parent_id.' },
|
|
1075
|
+
...IO_PARAMS,
|
|
1076
|
+
},
|
|
1077
|
+
},
|
|
1078
|
+
},
|
|
1079
|
+
{
|
|
1080
|
+
name: 'update_node',
|
|
1081
|
+
description: 'Patch a node\'s properties/state/stability (properties is a patch; null clears a key). Cannot rename — use rename_node. Needs an open session.',
|
|
1082
|
+
inputSchema: {
|
|
1083
|
+
type: 'object',
|
|
1084
|
+
required: ['id'],
|
|
1085
|
+
properties: {
|
|
1086
|
+
id: { type: 'string', description: 'Fully qualified node ID.' },
|
|
1087
|
+
properties: { type: 'object', description: 'Property patch; null clears a key.' },
|
|
1088
|
+
state: STATE_PARAM,
|
|
1089
|
+
stability: STABILITY_PARAM,
|
|
1090
|
+
...IO_PARAMS,
|
|
1091
|
+
},
|
|
1092
|
+
},
|
|
1093
|
+
},
|
|
1094
|
+
{
|
|
1095
|
+
name: 'rename_node',
|
|
1096
|
+
description: 'Rename a node (replace the last ID segment). Descendant IDs, parentId, and edge endpoints rewrite automatically; a cluster root\'s file moves at commit. Records a rename trail (previousIds + renamed-from edge) when the old name is shared history on default; record_trail overrides. The ONLY rename path — apply_cluster and imports never infer renames. Needs an open session.',
|
|
1097
|
+
inputSchema: {
|
|
1098
|
+
type: 'object',
|
|
1099
|
+
required: ['id', 'new_name'],
|
|
1100
|
+
properties: {
|
|
1101
|
+
id: { type: 'string', description: 'Node ID to rename.' },
|
|
1102
|
+
new_name: { type: 'string', description: 'New last segment (grammar [A-Za-z0-9_-], no dots).' },
|
|
1103
|
+
record_trail: { type: 'boolean', description: 'Force (true) or suppress (false) the rename trail.' },
|
|
1104
|
+
...IO_PARAMS,
|
|
1105
|
+
},
|
|
1106
|
+
},
|
|
1107
|
+
},
|
|
1108
|
+
{
|
|
1109
|
+
name: 'delete_node',
|
|
1110
|
+
description: 'Delete a node and its owned subtree. Soft delete (state removed, stays queryable) when the node is shared history on default; hard delete (removes subtree + touching edges) otherwise. purge:true forces hard; record_trail overrides (true soft, false hard). Needs an open session.',
|
|
1111
|
+
inputSchema: {
|
|
1112
|
+
type: 'object',
|
|
1113
|
+
required: ['id'],
|
|
1114
|
+
properties: {
|
|
1115
|
+
id: { type: 'string', description: 'Node ID to delete.' },
|
|
1116
|
+
purge: { type: 'boolean', description: 'Force hard delete. Default false.' },
|
|
1117
|
+
record_trail: { type: 'boolean', description: 'true forces soft delete, false forces hard.' },
|
|
1118
|
+
...IO_PARAMS,
|
|
1119
|
+
},
|
|
1120
|
+
},
|
|
1121
|
+
},
|
|
1122
|
+
{
|
|
1123
|
+
name: 'create_fields',
|
|
1124
|
+
description: 'Batch create multiple fields across schemas in one operation. Each field becomes a proper Field node with structural edges. Fields sharing a parent_id/schema_name are merged and applied together atomically; fields under different parents are applied as separate atomic groups (a failure in one parent\'s group does not roll back another parent\'s group). Defaults: state proposed, stability unstable. Needs an open session.',
|
|
1125
|
+
inputSchema: {
|
|
1126
|
+
type: 'object',
|
|
1127
|
+
required: ['fields'],
|
|
1128
|
+
properties: {
|
|
1129
|
+
fields: {
|
|
1130
|
+
type: 'array',
|
|
1131
|
+
description: 'Array of field definitions',
|
|
1132
|
+
items: {
|
|
1133
|
+
type: 'object',
|
|
1134
|
+
required: ['parent_id', 'schema_name', 'name', 'type'],
|
|
1135
|
+
properties: {
|
|
1136
|
+
parent_id: { type: 'string', description: 'Root node ID (e.g. orders.DomainModel.order).' },
|
|
1137
|
+
schema_name: { type: 'string', description: 'Schema name within the root (e.g. order, order-placed-payload).' },
|
|
1138
|
+
name: { type: 'string', description: 'Field name.' },
|
|
1139
|
+
type: { type: 'string', description: 'Field type (e.g. uuid, decimal, string).' },
|
|
1140
|
+
nullable: { type: 'boolean', description: 'Whether field is nullable. Default false.' },
|
|
1141
|
+
description: { type: 'string', description: 'Optional field description.' },
|
|
1142
|
+
state: STATE_PARAM,
|
|
1143
|
+
stability: STABILITY_PARAM,
|
|
1144
|
+
},
|
|
1145
|
+
},
|
|
1146
|
+
},
|
|
1147
|
+
...IO_PARAMS,
|
|
1148
|
+
},
|
|
1149
|
+
},
|
|
1150
|
+
},
|
|
1151
|
+
{
|
|
1152
|
+
name: 'create_edges',
|
|
1153
|
+
description: 'Batch create multiple edges as one atomic operation: every edge is validated (including duplicates within the batch) before any edge is created, so an invalid edge aborts the whole call with no partial writes. Same per-edge validation as a single edge create (see delete_edge/update_edge). Needs an open session.',
|
|
1154
|
+
inputSchema: {
|
|
1155
|
+
type: 'object',
|
|
1156
|
+
required: ['edges'],
|
|
1157
|
+
properties: {
|
|
1158
|
+
edges: {
|
|
1159
|
+
type: 'array',
|
|
1160
|
+
description: 'Array of edge definitions',
|
|
1161
|
+
items: {
|
|
1162
|
+
type: 'object',
|
|
1163
|
+
required: ['from', 'to', 'type'],
|
|
1164
|
+
properties: {
|
|
1165
|
+
from: { type: 'string', description: 'Source node ID.' },
|
|
1166
|
+
to: { type: 'string', description: 'Target node ID.' },
|
|
1167
|
+
type: { type: 'string', description: 'Edge type.' },
|
|
1168
|
+
state: STATE_PARAM,
|
|
1169
|
+
stability: STABILITY_PARAM,
|
|
1170
|
+
notes: { type: 'string', description: 'Free-text note.' },
|
|
1171
|
+
properties: { type: 'object', description: 'Edge properties.' },
|
|
1172
|
+
},
|
|
1173
|
+
},
|
|
1174
|
+
},
|
|
1175
|
+
...IO_PARAMS,
|
|
1176
|
+
},
|
|
1177
|
+
},
|
|
1178
|
+
},
|
|
1179
|
+
{
|
|
1180
|
+
name: 'update_edge',
|
|
1181
|
+
description: 'Patch an edge\'s state/stability/notes/properties (null clears notes or a property key). Endpoints and type are immutable — delete+create to change them. Needs an open session.',
|
|
1182
|
+
inputSchema: {
|
|
1183
|
+
type: 'object',
|
|
1184
|
+
required: ['id'],
|
|
1185
|
+
properties: {
|
|
1186
|
+
id: { type: 'string', description: 'Edge ID ({from}__{type}__{to}).' },
|
|
1187
|
+
state: STATE_PARAM,
|
|
1188
|
+
stability: STABILITY_PARAM,
|
|
1189
|
+
notes: { description: 'New notes; null clears them.' },
|
|
1190
|
+
properties: { type: 'object', description: 'Property patch; null clears a key.' },
|
|
1191
|
+
...IO_PARAMS,
|
|
1192
|
+
},
|
|
1193
|
+
},
|
|
1194
|
+
},
|
|
1195
|
+
{
|
|
1196
|
+
name: 'delete_edge',
|
|
1197
|
+
description: 'Hard-delete an edge (edges carry no subtree). To soft-remove, use update_edge with state removed. Needs an open session.',
|
|
1198
|
+
inputSchema: {
|
|
1199
|
+
type: 'object',
|
|
1200
|
+
required: ['id'],
|
|
1201
|
+
properties: {
|
|
1202
|
+
id: { type: 'string', description: 'Edge ID ({from}__{type}__{to}).' },
|
|
1203
|
+
...IO_PARAMS,
|
|
1204
|
+
},
|
|
1205
|
+
},
|
|
1206
|
+
},
|
|
1207
|
+
{
|
|
1208
|
+
name: 'pending_changes',
|
|
1209
|
+
description: 'Show the session\'s change journal and a summary diff (added/modified/removed counts) vs base. Needs an open session.',
|
|
1210
|
+
inputSchema: {
|
|
1211
|
+
type: 'object',
|
|
1212
|
+
properties: {
|
|
1213
|
+
...IO_PARAMS,
|
|
1214
|
+
},
|
|
1215
|
+
},
|
|
1216
|
+
},
|
|
1217
|
+
{
|
|
1218
|
+
name: 'discard_changes',
|
|
1219
|
+
description: 'Abort the session without committing, dropping in-memory changes. Autosaved file-source writes are NOT rolled back. Needs an open session.',
|
|
1220
|
+
inputSchema: {
|
|
1221
|
+
type: 'object',
|
|
1222
|
+
properties: {
|
|
1223
|
+
...IO_PARAMS,
|
|
1224
|
+
},
|
|
1225
|
+
},
|
|
1226
|
+
},
|
|
1227
|
+
{
|
|
1228
|
+
name: 'commit_changes',
|
|
1229
|
+
description: 'Lint, serialise, and commit the working graph, then close the session. Error diagnostics BLOCK the commit (session stays open to fix); warnings ride along. Git autosave WIP checkpoints squash into one commit unless an external commit interleaved. Fails if the branch head moved externally. Needs an open session.',
|
|
1230
|
+
inputSchema: {
|
|
1231
|
+
type: 'object',
|
|
1232
|
+
properties: {
|
|
1233
|
+
message: { type: 'string', description: 'Commit message. Default: journal summary.' },
|
|
1234
|
+
...IO_PARAMS,
|
|
770
1235
|
},
|
|
771
1236
|
},
|
|
772
1237
|
},
|
|
@@ -827,7 +1292,7 @@ export async function startMcpServer(options = {}) {
|
|
|
827
1292
|
return {
|
|
828
1293
|
description: 'Corum graph query orientation guide',
|
|
829
1294
|
messages: [
|
|
830
|
-
{ role: 'user', content: { type: 'text', text:
|
|
1295
|
+
{ role: 'user', content: { type: 'text', text: buildUsageGuidePrompt([...graph.templates.keys()].sort()) } },
|
|
831
1296
|
],
|
|
832
1297
|
};
|
|
833
1298
|
});
|
|
@@ -865,6 +1330,32 @@ export async function startMcpServer(options = {}) {
|
|
|
865
1330
|
return await handlers.list_branches(args);
|
|
866
1331
|
case 'diff_branch':
|
|
867
1332
|
return await handlers.diff_branch(args);
|
|
1333
|
+
case 'start_changes':
|
|
1334
|
+
return await handlers.start_changes(args);
|
|
1335
|
+
case 'apply_cluster':
|
|
1336
|
+
return await handlers.apply_cluster(args);
|
|
1337
|
+
case 'create_node':
|
|
1338
|
+
return await handlers.create_node(args);
|
|
1339
|
+
case 'update_node':
|
|
1340
|
+
return await handlers.update_node(args);
|
|
1341
|
+
case 'rename_node':
|
|
1342
|
+
return await handlers.rename_node(args);
|
|
1343
|
+
case 'delete_node':
|
|
1344
|
+
return await handlers.delete_node(args);
|
|
1345
|
+
case 'create_fields':
|
|
1346
|
+
return await handlers.create_fields(args);
|
|
1347
|
+
case 'create_edges':
|
|
1348
|
+
return await handlers.create_edges(args);
|
|
1349
|
+
case 'update_edge':
|
|
1350
|
+
return await handlers.update_edge(args);
|
|
1351
|
+
case 'delete_edge':
|
|
1352
|
+
return await handlers.delete_edge(args);
|
|
1353
|
+
case 'pending_changes':
|
|
1354
|
+
return await handlers.pending_changes(args);
|
|
1355
|
+
case 'discard_changes':
|
|
1356
|
+
return await handlers.discard_changes(args);
|
|
1357
|
+
case 'commit_changes':
|
|
1358
|
+
return await handlers.commit_changes(args);
|
|
868
1359
|
default:
|
|
869
1360
|
return { content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }], isError: true };
|
|
870
1361
|
}
|