@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.
@@ -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 { USAGE_GUIDE_PROMPT } from './prompts/usage-guide.js';
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(graph);
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(graph);
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
- score: result.score,
182
- node: wantFull
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(graph);
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(graph);
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 = graph.templates.get(name);
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 !== false;
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(graph).catch(err => errorResult(err));
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(graph);
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(graph);
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(graph);
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(graph);
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: 'List nodes in the graph. Returns id, template, component, state, stability for each matched node.',
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
- type: 'array',
545
- items: { type: 'string' },
546
- description: 'Include only these template types (OR semantics)',
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: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
565
- branch: { type: 'string', description: 'Branch ref to load nodes from' },
566
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
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 graph templates. Returns name, version, core, abstract, extends, and description for each template.',
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: { type: 'string', description: 'Branch ref to load templates from' },
578
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
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: 'Get full details for a loaded graph template.',
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
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
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: 'Use when you need the full structural contents of a single node - its schema, fields, and owned children. Not suited for following relationships across the graph; use get_lineage for that.\n\nBy default returns only the root node with its collapsed schema and enums blocks (descendants and edges excluded). Pass include_descendants: true to include owned operations/commands/events. Pass include_edges: true to include the edge list.',
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
- type: 'array',
606
- items: { type: 'string' },
607
- description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
608
- },
609
- 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.' },
610
- include_descendants: { type: 'boolean', description: 'Include descendant nodes (operations, commands, events, and cross-component nodes). Default true.' },
611
- node_types: {
612
- type: 'array',
613
- items: { type: 'string' },
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: 'Return semantic nodes (and optionally edges) across the graph. Excludes structural templates and structural edge types by default. Pass include_edges: true to include the semantic edge list.',
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 the semantic edge list in the response. Default false.' },
647
- include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
648
- branch: { type: 'string', description: 'Branch ref to load the graph from' },
649
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
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: 'Return discoverable graph metadata: template names, node templates in use, edge types in use. Call this first before making traversal queries. The edge_types_in_use field tells you which edge types are actually modelled in the current graph - there is no value traversing edge types that have no entries. Pass include_static_enums: true to also receive valid_edge_types, states, stabilities, lineage_directions, and output_formats.',
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: 'Include static enum reference fields (valid_edge_types, states, stabilities, lineage_directions, output_formats). Default false.' },
661
- branch: { type: 'string', description: 'Branch ref to load metadata from' },
662
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
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: 'Traverse the graph from one or more origin nodes via BFS and return annotated lineage results. Pass multiple node_ids to expand all origins in parallel in a single call rather than making separate calls - results are merged and deduplicated automatically.\n\nCommon patterns:\n- Event fan-out - direction: downstream, depth: 2 from an event node to see all triggered commands and the operations they invoke.\n- Find all writers to an aggregate - direction: upstream from a DomainModel node to see every command and operation that writes to it.\n- Full event chain - direction: downstream, depth: 3 or more to trace event -> command -> operation -> produced event chains.',
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: 'Traversal direction. Default downstream.' },
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: 'Allowlist of node templates.' },
683
- exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Denylist of node templates.' },
684
- include_dangling_edges: { type: 'boolean', description: 'Include dangling edges in the response when present. Default false.' },
685
- reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads/uses-type edges in upstream traversal. Default true.' },
686
- lean: { type: 'boolean', description: 'Return minimal lineage node shape. Default true.' },
687
- include_edges: { type: 'boolean', description: 'Include the edges list in the response. Default false.' },
688
- include_edge_ids: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
689
- include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
690
- branch: { type: 'string', description: 'Branch ref to load the lineage from' },
691
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
692
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
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: 'Get all maps-to edges touching fields owned by the given root node.',
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: { type: 'boolean', description: 'Include edge id field in edge output. Default false.' },
705
- include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
706
- branch: { type: 'string', description: 'Branch ref to load linked fields from' },
707
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
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: 'Return high-level statistics: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
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: { type: 'string', description: 'Branch ref to load the summary from' },
719
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
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: 'Fuzzy search for root-level nodes by ID segments. Returns slim node summaries (id, template, component, state, stability) by default. Pass full_nodes: true to include properties. Prefer this over list_nodes when you have a domain term to search for - it returns ranked, targeted results without noise. Use list_nodes only when you need a complete inventory of nodes matching specific filter criteria.',
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
- type: 'array',
733
- items: { type: 'string' },
734
- description: 'Search terms. OR semantics; any matching term qualifies the node.',
735
- },
736
- templates: { type: 'array', items: { type: 'string' }, description: 'Include only these template types.' },
737
- exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these template types.' },
738
- page_size: { type: 'number', description: 'Max results to return. Default 10.' },
739
- offset: { type: 'number', description: 'Result offset for pagination. Default 0.' },
740
- search_properties: { type: 'boolean', description: 'Also match name, description, and x-aka properties.' },
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 configured graph source and their load status.',
1018
+ description: 'List branches available from the graph source and their load status.',
752
1019
  inputSchema: {
753
1020
  type: 'object',
754
1021
  properties: {
755
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
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
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
769
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
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: USAGE_GUIDE_PROMPT } },
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
  }