@atolis-hq/corum 0.1.52 → 0.1.53
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 +8 -388
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -89,394 +89,14 @@ If you only want the web UI:
|
|
|
89
89
|
corum web
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
-
##
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
Options:
|
|
102
|
-
--no-web Suppress the web UI
|
|
103
|
-
--watch Reload file-backed graphs on local file changes
|
|
104
|
-
--graph <path> Override the graph directory
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
Notes:
|
|
108
|
-
- `corum mcp` starts the web UI unless you pass `--no-web`.
|
|
109
|
-
- `--watch` applies to filesystem graphs. Git-backed graphs reload through polling instead.
|
|
110
|
-
|
|
111
|
-
### `corum web`
|
|
112
|
-
|
|
113
|
-
Start the web UI only.
|
|
114
|
-
|
|
115
|
-
```bash
|
|
116
|
-
corum web [options]
|
|
117
|
-
|
|
118
|
-
Options:
|
|
119
|
-
--port <n> Port to listen on (default: 3000)
|
|
120
|
-
--graph <path> Override the graph directory
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
Notes:
|
|
124
|
-
- Filesystem graphs can be watched for local YAML changes with `CORUM_FILE_WATCHER=true` or `CORUM_WATCH=true`.
|
|
125
|
-
- Git-backed graphs reload through polling when `git_poll_seconds` / `CORUM_GIT_POLL_SECONDS` is set.
|
|
126
|
-
|
|
127
|
-
### `corum lint`
|
|
128
|
-
|
|
129
|
-
Lint the graph and report diagnostics.
|
|
130
|
-
|
|
131
|
-
```bash
|
|
132
|
-
corum lint [options]
|
|
133
|
-
|
|
134
|
-
Options:
|
|
135
|
-
--graph <path> Override the graph directory
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
### `corum init`
|
|
139
|
-
|
|
140
|
-
Scaffold a `.corum/` project structure and install the four default template packs (`core`, `domain`, `rest`, `messaging`). Skips any step where the target already exists.
|
|
141
|
-
|
|
142
|
-
```bash
|
|
143
|
-
corum init
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
Creates:
|
|
147
|
-
- `.corum/config.yaml` - project configuration
|
|
148
|
-
- `.corum/graph/graph.yaml` - graph definition
|
|
149
|
-
- `.corum/graph/components/` and `.corum/graph/edges/` - empty directories ready for nodes
|
|
150
|
-
- `.corum/packs/` - downloaded template packs
|
|
151
|
-
- `.corum/packs.yaml` - local manifest of installed packs
|
|
152
|
-
|
|
153
|
-
### `corum pack install`
|
|
154
|
-
|
|
155
|
-
Install a template pack from the registry into `.corum/packs/`. Appends the pack to `.corum/graph/graph.yaml` and records it in `.corum/packs.yaml`.
|
|
156
|
-
|
|
157
|
-
```bash
|
|
158
|
-
corum pack install <name> # install latest tag
|
|
159
|
-
corum pack install <name>@<ref> # install a specific tag
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Examples:
|
|
163
|
-
|
|
164
|
-
```bash
|
|
165
|
-
corum pack install domain
|
|
166
|
-
corum pack install domain@v0.1.5
|
|
167
|
-
corum pack install extract # required for corum-extract import adapter
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
### `corum pack list`
|
|
171
|
-
|
|
172
|
-
List installed packs with their resolved version and install date.
|
|
173
|
-
|
|
174
|
-
```bash
|
|
175
|
-
corum pack list
|
|
176
|
-
```
|
|
177
|
-
|
|
178
|
-
### `corum import`
|
|
179
|
-
|
|
180
|
-
Import specifications into the graph.
|
|
181
|
-
|
|
182
|
-
```bash
|
|
183
|
-
corum import --config <path> Import using a config YAML file
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
#### Import config file
|
|
187
|
-
|
|
188
|
-
The `--config` flag accepts a YAML file that can combine multiple imports in a single run and configure cross-adapter options:
|
|
189
|
-
|
|
190
|
-
```yaml
|
|
191
|
-
# Optional: remap extracted component names before node IDs are built.
|
|
192
|
-
# Useful when the same component appears under different names in different specs
|
|
193
|
-
# (e.g. "order-shipping" from a URI segment vs "ordershipping" from a topic name).
|
|
194
|
-
componentNameReplacements:
|
|
195
|
-
- from: ordershipping
|
|
196
|
-
to: order-shipping
|
|
197
|
-
|
|
198
|
-
# Optional: deduplicate nodes emitted by different adapters after all imports
|
|
199
|
-
# complete. For each rule, keep nodes from the primary adapter and merge/drop
|
|
200
|
-
# matching nodes from the secondary adapter.
|
|
201
|
-
deduplication:
|
|
202
|
-
- primary: openapi
|
|
203
|
-
secondary: corum
|
|
204
|
-
|
|
205
|
-
imports:
|
|
206
|
-
- adapter: openapi
|
|
207
|
-
spec: ./specs/order-shipping.openapi.yaml
|
|
208
|
-
componentMapping:
|
|
209
|
-
strategy: uri-segment
|
|
210
|
-
segment: 0
|
|
211
|
-
|
|
212
|
-
- adapter: asyncapi
|
|
213
|
-
spec: ./specs/order-shipping.asyncapi.yaml
|
|
214
|
-
componentMapping:
|
|
215
|
-
strategy: channel-segment
|
|
216
|
-
separator: "."
|
|
217
|
-
segment: 0
|
|
218
|
-
messageNaming:
|
|
219
|
-
strategy: name-segment
|
|
220
|
-
separator: "."
|
|
221
|
-
segment: -1
|
|
222
|
-
```
|
|
223
|
-
|
|
224
|
-
Replacements are applied in order; the first matching `from` wins. Unmatched names are passed through unchanged.
|
|
225
|
-
Deduplication rules are applied after all adapters finish. They are intended for
|
|
226
|
-
cross-adapter reconciliation, for example keeping OpenAPI endpoints as canonical
|
|
227
|
-
while merging matching extractor-emitted Corum nodes into them.
|
|
228
|
-
|
|
229
|
-
#### `corum import openapi <spec>`
|
|
230
|
-
|
|
231
|
-
Import an OpenAPI spec directly.
|
|
232
|
-
|
|
233
|
-
```bash
|
|
234
|
-
corum import openapi <spec> [options]
|
|
235
|
-
|
|
236
|
-
Options:
|
|
237
|
-
--component-strategy <strategy> Component mapping: uri-segment (default), tag, hardcoded
|
|
238
|
-
--segment <n> URI segment index (uri-segment strategy)
|
|
239
|
-
--pattern <regex> Regex pattern (uri-segment strategy)
|
|
240
|
-
--component <name> Component name (hardcoded strategy)
|
|
241
|
-
--graph <path> Override the graph directory
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
#### `corum import asyncapi <spec>`
|
|
245
|
-
|
|
246
|
-
Import an AsyncAPI spec directly.
|
|
247
|
-
|
|
248
|
-
```bash
|
|
249
|
-
corum import asyncapi <spec> [options]
|
|
250
|
-
|
|
251
|
-
Options:
|
|
252
|
-
--component-strategy <strategy> Component mapping: channel-segment (default), channel-pattern,
|
|
253
|
-
name-segment, name-pattern, tag, hardcoded
|
|
254
|
-
--separator <char> Separator for segment strategies (default: .)
|
|
255
|
-
--segment <n> Segment index (negative counts from end)
|
|
256
|
-
--pattern <regex> Regex pattern for pattern strategies
|
|
257
|
-
--component <name> Component name (hardcoded strategy)
|
|
258
|
-
--event-classification <mode> always-integration (default) or always-domain
|
|
259
|
-
--include-consumed Also import receive (consumed) operations
|
|
260
|
-
--graph <path> Override the graph directory
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
#### `corum import corum <spec>`
|
|
264
|
-
|
|
265
|
-
Import a corum interchange file (`*.corum.yaml`) produced by `corum-extract` or compatible extraction tooling.
|
|
266
|
-
|
|
267
|
-
```bash
|
|
268
|
-
corum import corum <spec> [options]
|
|
269
|
-
|
|
270
|
-
Options:
|
|
271
|
-
--graph <path> Override the graph directory
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
The interchange format is self-describing - no component mapping strategy is needed. Node IDs, template names, and field references are already corum-native. Gaps reported by the extractor (unresolved types, name collisions) are surfaced as warnings.
|
|
275
|
-
|
|
276
|
-
Requires the `extract` pack to be active in your graph:
|
|
277
|
-
|
|
278
|
-
```bash
|
|
279
|
-
corum pack install extract
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
You can also configure corum imports in a config file:
|
|
283
|
-
|
|
284
|
-
```yaml
|
|
285
|
-
# .corum/imports.yaml
|
|
286
|
-
imports:
|
|
287
|
-
- adapter: corum
|
|
288
|
-
spec: path/to/output.corum.yaml
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
## Configuration
|
|
292
|
-
|
|
293
|
-
Run `corum init` to generate a `.corum/config.yaml` with all available options. Corum walks up from the current directory to find it, so you can place it at your project root.
|
|
294
|
-
|
|
295
|
-
**Precedence (highest to lowest):** CLI flags -> environment variables -> `.corum/config.yaml`
|
|
296
|
-
|
|
297
|
-
| Config key | Environment variable | Description |
|
|
298
|
-
|---|---|---|
|
|
299
|
-
| `pack_registry` | - | URL of the pack registry YAML (set by `corum init`) |
|
|
300
|
-
| `source` | `CORUM_SOURCE` | Source mode: `file` / `filesystem` / `fs` (default) or `git` |
|
|
301
|
-
| `graph` | `CORUM_GRAPH_PATH` | Path to the graph directory |
|
|
302
|
-
| `git_local_path` | `CORUM_GIT_LOCAL_PATH` | Local git repo path |
|
|
303
|
-
| `git_remote_url` | `CORUM_GIT_REMOTE_URL` | Remote git repo URL |
|
|
304
|
-
| `git_branch` | `CORUM_GIT_BRANCH` | Default branch ref used when loading a git-backed graph |
|
|
305
|
-
| `git_poll_seconds` | `CORUM_GIT_POLL_SECONDS` | Poll interval, in seconds, for git-backed web reloads |
|
|
306
|
-
| `git_token` | `CORUM_GIT_TOKEN` | Auth token for private repos |
|
|
307
|
-
| `git_username` | `CORUM_GIT_USERNAME` | Auth username (default: `x-access-token`) |
|
|
308
|
-
|
|
309
|
-
Additional environment-only runtime settings:
|
|
310
|
-
|
|
311
|
-
| Environment variable | Description |
|
|
312
|
-
|---|---|
|
|
313
|
-
| `CORUM_WEB_PORT` | Default port for `corum web` |
|
|
314
|
-
| `CORUM_FILE_WATCHER` | Enable local file watching for filesystem graphs when running the web UI |
|
|
315
|
-
| `CORUM_WATCH` | Alias for `CORUM_FILE_WATCHER` |
|
|
316
|
-
|
|
317
|
-
### File source (default)
|
|
318
|
-
|
|
319
|
-
```yaml
|
|
320
|
-
# .corum/config.yaml
|
|
321
|
-
source: file
|
|
322
|
-
graph: .corum/graph
|
|
323
|
-
```
|
|
324
|
-
|
|
325
|
-
Use this when the graph lives directly on the local filesystem with no git source abstraction.
|
|
326
|
-
|
|
327
|
-
### Git source
|
|
328
|
-
|
|
329
|
-
```yaml
|
|
330
|
-
# .corum/config.yaml
|
|
331
|
-
source: git
|
|
332
|
-
git_remote_url: https://github.com/org/design-repo
|
|
333
|
-
git_branch: main
|
|
334
|
-
git_poll_seconds: 30
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
Or for a local git repository:
|
|
338
|
-
|
|
339
|
-
```yaml
|
|
340
|
-
# .corum/config.yaml
|
|
341
|
-
source: git
|
|
342
|
-
git_local_path: /path/to/repo
|
|
343
|
-
git_branch: main
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
Rules:
|
|
347
|
-
- Set exactly one of `git_local_path` or `git_remote_url`.
|
|
348
|
-
- `git_branch` selects the default branch Corum loads for read operations and the web UI.
|
|
349
|
-
- `git_poll_seconds` is only used for git-backed web reloads.
|
|
350
|
-
|
|
351
|
-
For private repositories, set `CORUM_GIT_TOKEN` as an environment variable rather than storing it in the config file.
|
|
352
|
-
|
|
353
|
-
## MCP Client Configuration
|
|
354
|
-
|
|
355
|
-
Configure your MCP client to run Corum. For Claude Code or Claude Desktop:
|
|
356
|
-
|
|
357
|
-
```json
|
|
358
|
-
{
|
|
359
|
-
"mcpServers": {
|
|
360
|
-
"corum": {
|
|
361
|
-
"command": "npx",
|
|
362
|
-
"args": ["@atolis-hq/corum", "mcp", "--no-web"],
|
|
363
|
-
"env": {
|
|
364
|
-
"CORUM_GRAPH_PATH": "/path/to/your/graph"
|
|
365
|
-
}
|
|
366
|
-
}
|
|
367
|
-
}
|
|
368
|
-
}
|
|
369
|
-
```
|
|
370
|
-
|
|
371
|
-
Or if installed globally:
|
|
372
|
-
|
|
373
|
-
```json
|
|
374
|
-
{
|
|
375
|
-
"mcpServers": {
|
|
376
|
-
"corum": {
|
|
377
|
-
"command": "corum",
|
|
378
|
-
"args": ["mcp", "--no-web"],
|
|
379
|
-
"env": {
|
|
380
|
-
"CORUM_GRAPH_PATH": "/path/to/your/graph"
|
|
381
|
-
}
|
|
382
|
-
}
|
|
383
|
-
}
|
|
384
|
-
}
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
## MCP Tools
|
|
388
|
-
|
|
389
|
-
| Tool | Description |
|
|
390
|
-
|---|---|
|
|
391
|
-
| `list_nodes` | List graph nodes using a `filter` object with `templates`, `exclude_templates`, `component`, `state`, and `stability` |
|
|
392
|
-
| `list_templates` | List loaded templates with summary metadata |
|
|
393
|
-
| `get_template` | Return full details for a template |
|
|
394
|
-
| `get_cluster` | Return a node's structural contents. By default, schema and enum child nodes are collapsed into compact `schemas` and `enums` blocks on the root. Pass `collapse_schemas: false` to restore the full node-per-field representation |
|
|
395
|
-
| `get_graph` | Return the semantic graph as `{ nodes, edges }`, excluding structural templates and structural edges by default |
|
|
396
|
-
| `get_graph_metadata` | Return discoverable metadata: template names, node templates in use, edge types, and valid enum values |
|
|
397
|
-
| `get_lineage` | Traverse lineage from one or more start nodes. Lean nodes and no `edges` by default; opt in to fuller payloads when needed |
|
|
398
|
-
| `get_graph_summary` | Return high-level graph statistics: node count, component count, orphan breakdown, edge counts, diagnostics |
|
|
399
|
-
| `search_nodes` | Fuzzy-search root-level nodes by ID, with optional template filters and property search |
|
|
400
|
-
| `get_linked_fields` | Return `maps-to` edges touching fields owned by a root node |
|
|
401
|
-
| `list_branches` | List available branches and their load status from the configured source |
|
|
402
|
-
| `diff_branch` | Diff a branch against the default branch |
|
|
403
|
-
| `start_changes` | Open a working mutation session |
|
|
404
|
-
| `apply_cluster` | Upsert a cluster-style document in `merge` or `replace` mode |
|
|
405
|
-
| `create_node` | Create a root cluster or owned child node |
|
|
406
|
-
| `update_node` | Patch node properties, state, or stability |
|
|
407
|
-
| `rename_node` | Rename a node while preserving identity trail metadata |
|
|
408
|
-
| `delete_node` | Soft-delete or hard-delete a node subtree |
|
|
409
|
-
| `create_edges` | Batch-create explicit edges as one atomic operation |
|
|
410
|
-
| `update_edge` | Patch an explicit edge |
|
|
411
|
-
| `delete_edge` | Delete an explicit edge |
|
|
412
|
-
| `create_fields` | Batch-create fields across schemas (grouped and applied per parent) |
|
|
413
|
-
| `pending_changes` | Show the open session's journal and summary diff |
|
|
414
|
-
| `discard_changes` | Abort the working session |
|
|
415
|
-
| `commit_changes` | Lint, serialize, and persist the session's changes |
|
|
416
|
-
|
|
417
|
-
All tools accept an optional `format` argument: `toon` (default; leanest for the LLM), `yaml`, or `json`. All tools also accept `compact_keys: true` to shorten common keys before serialization, reducing token usage further.
|
|
418
|
-
|
|
419
|
-
All node-returning MCP tools accept `include_provenance: true` to include `extractedFrom`, `lastModifiedAt`, `derivation`, and `derivedBy`. These fields are omitted by default. `schemaVersion` is never returned by MCP.
|
|
420
|
-
|
|
421
|
-
Common notes:
|
|
422
|
-
- `branch` is supported on graph-query tools when Corum is running against a source-backed graph.
|
|
423
|
-
- `list_nodes` is a breaking-change surface from older builds: use `filter.templates` instead of top-level `template`.
|
|
424
|
-
- `search_nodes` accepts `queries: string[]`.
|
|
425
|
-
- `get_graph_metadata` should usually be your first call. Use `edge_types_in_use` to avoid traversing edge types that do not exist in the current graph.
|
|
426
|
-
- `get_graph_metadata` returns `valid_edge_types`, `states`, `stabilities`, `lineage_directions`, and `output_formats` when you pass `include_static_enums: true`.
|
|
427
|
-
- Prefer `search_nodes` over `list_nodes` for discovery. Use `list_nodes` when you need a full inventory under explicit filters.
|
|
428
|
-
- `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, `reads_outbound_only`, `lean`, and `include_edges`.
|
|
429
|
-
- `get_lineage` defaults to `lean: true` and `include_edges: false`. Lean lineage nodes contain only `id`, `origin_id`, `depth`, `via_edge_type`, and `via_node_id`.
|
|
430
|
-
- Pass multiple `node_ids` to `get_lineage` in one call instead of making separate traversal calls.
|
|
431
|
-
- Use `get_cluster` only when you need full structural contents for one node. By default it returns compact `schemas` and `enums` blocks on the root rather than individual field nodes, which keeps response size manageable for large aggregates. Use `get_lineage` for relationship traversal.
|
|
432
|
-
- Read tools reflect the open working session while one exists. Unbranched reads, and branch-scoped reads for that same session branch, show uncommitted changes.
|
|
433
|
-
- The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists; agents should treat naming and schema similarity as hypotheses and then verify via cluster inspection or source material.
|
|
434
|
-
|
|
435
|
-
## MCP Write Workflow
|
|
436
|
-
|
|
437
|
-
Corum's write tools are session-based:
|
|
438
|
-
|
|
439
|
-
1. Call `start_changes`.
|
|
440
|
-
2. Make one or more mutations with `apply_cluster`, `create_node`, `update_node`, `rename_node`, `delete_node`, `create_edges`, `update_edge`, `delete_edge`, or `create_fields`.
|
|
441
|
-
3. Inspect the session with `pending_changes`.
|
|
442
|
-
4. Finish with `commit_changes` or abort with `discard_changes`.
|
|
443
|
-
|
|
444
|
-
Important behavior:
|
|
445
|
-
- No write tool works without an open session.
|
|
446
|
-
- `rename_node` is the only rename path. `apply_cluster` and imports never infer renames.
|
|
447
|
-
- `apply_cluster` `replace` mode is authoritative for the root's owned sections: absent children are deleted, and an absent owned section means "empty section".
|
|
448
|
-
- `delete_node` defaults to soft delete for nodes that already exist on the default branch, and hard delete for branch-local design work.
|
|
449
|
-
- `discard_changes` closes the session. On file-backed autosave sessions it does not roll back mutations already written through to disk.
|
|
450
|
-
|
|
451
|
-
Source-mode defaults:
|
|
452
|
-
- Filesystem source: `start_changes` defaults `autosave` on. Each mutation writes through immediately; `commit_changes` mainly lint-gates and closes the session.
|
|
453
|
-
- Git source: `start_changes` defaults `autosave` off. Changes stay in memory until `commit_changes`.
|
|
454
|
-
- Git source with `autosave: true`: each mutation creates a `corum-wip:` checkpoint commit; `commit_changes` squashes that run when no external commit interleaved.
|
|
455
|
-
|
|
456
|
-
Typical sequence:
|
|
457
|
-
|
|
458
|
-
```yaml
|
|
459
|
-
start_changes:
|
|
460
|
-
branch: feat/order-design
|
|
461
|
-
create: true
|
|
462
|
-
|
|
463
|
-
rename_node:
|
|
464
|
-
id: orders.Schema.invoice
|
|
465
|
-
new_name: bill
|
|
466
|
-
|
|
467
|
-
pending_changes: {}
|
|
468
|
-
|
|
469
|
-
commit_changes:
|
|
470
|
-
message: rename invoice schema to bill
|
|
471
|
-
```
|
|
472
|
-
|
|
473
|
-
## MCP Prompts
|
|
474
|
-
|
|
475
|
-
The server also exposes a discoverable MCP prompt:
|
|
476
|
-
|
|
477
|
-
| Prompt | Description |
|
|
478
|
-
|---|---|
|
|
479
|
-
| `usage-guide` | Orientation guide covering graph structure, read and write workflow, output-format choices, graph-completeness caveats, and inference guidance |
|
|
92
|
+
## Documentation
|
|
93
|
+
|
|
94
|
+
- [Getting started](docs/getting-started.md) - install, initialise, connect an agent
|
|
95
|
+
- [Concepts](docs/concepts.md) - nodes, edges, clusters, IDs, lineage, branches
|
|
96
|
+
- [Templates and packs](docs/templates-and-packs.md) - defining and extending node types
|
|
97
|
+
- [Importing](docs/importing.md) - OpenAPI, AsyncAPI and extractor output
|
|
98
|
+
- [Working with agents](docs/working-with-agents.md) - reading and changing the graph
|
|
99
|
+
- [MCP tools](docs/mcp-tools.md), [CLI](docs/cli.md), [Configuration](docs/configuration.md) - reference
|
|
480
100
|
|
|
481
101
|
## Contributing
|
|
482
102
|
|