@datasynx/agentic-ai-cartography 2.11.0 → 2.12.1

package/dist/mcp-bin.js

@@ -2,7 +2,7 @@
 import {
   parseMcpArgs,
   startMcp
-} from "./chunk-FFUUNSWP.js";
+} from "./chunk-OIDAXUW5.js";
 import "./chunk-LO6YFS6H.js";
 import "./chunk-QQOQBE2A.js";
 import "./chunk-2SZ5QHGH.js";

package/llms-full.txt

@@ -157,38 +157,318 @@ reusable **prompts**.
 
 # CLI reference
 
-`datasynx-cartography <command>` (the discovery/management CLI) and
-`cartography-mcp` (the MCP server binary).
+Two binaries ship with Cartography:
 
-| Command | Purpose |
-| --- | --- |
-| `discover` | Scan and map your infrastructure (`--output-format text\|json\|stream-json`, `--name <name>`). |
-| `diff [base] [current]` | Compare two sessions for drift (`--format text\|json\|mermaid`). |
-| `schedule --config <file>` | Run discovery recurringly and record per-run drift (`--once` / `--watch`, config-file driven). |
-| `seed` | Manually add known tools/DBs/APIs. |
-| `install --client <id>` | Register the MCP server into a host's config. |
-| `list-clients` | List supported hosts. |
-| `mcp` | Run the MCP server (stdio by default; `--http` for Streamable HTTP). |
-| `export [session]` | Export Mermaid / JSON / YAML / HTML. |
-| `show [session]` | Show session details. |
-| `sessions` | List all sessions. |
-| `overview` | Aggregate overview across sessions. |
-| `bookmarks` | View browser bookmarks. |
-| `doctor` | Check requirements (kubectl, aws, gcloud, az). |
-| `prune` | Remove old sessions. |
-| `docs` | Full in-terminal feature reference. |
-
-## `mcp` flags
+- `datasynx-cartography <command>` — the discovery & management CLI documented below.
+- `cartography-mcp` — starts the MCP server directly (equivalent to `datasynx-cartography mcp`; used by `server.json` via `npx`).
+
+Global flags: `--version`, `--help`. `--db <path>` selects the catalog on most
+commands; absent, the default catalog is used. All progress/log output goes to
+stderr; machine-readable output goes to stdout.
+
+Commands are grouped below by purpose: **Discovery**, **Analysis & insight**,
+**Inspection**, **Consent & sync (collector client)**, **Servers**, and
+**Setup & maintenance**.
+
+---
+
+## Discovery
+
+### `discover`
+
+Scan and map your infrastructure (agentic by default; `--update` runs a deterministic local rescan).
+
+`datasynx-cartography discover [options]`
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--entry <hosts...>` | `localhost` | Entry points to scan from. |
+| `--depth <n>` | `8` | Max crawl depth (1–50). |
+| `--max-turns <n>` | `50` | Max agent turns (1–500). |
+| `--provider <name>` | `claude` | Agent provider: `claude`, `openai`, `ollama` (or `CARTOGRAPHY_PROVIDER`). |
+| `--model <m>` | `claude-sonnet-4-5-20250929` | Agent model. |
+| `--org <name>` | — | Organization/tenant name (scopes the session; used for Backstage). |
+| `-o, --output <dir>` | `./datasynx-output` | Output directory. |
+| `--db <path>` | default catalog | DB path. |
+| `--name <name>` | auto-derived | Custom session name. |
+| `--update [sessionId]` | — | Re-scan an existing session in place (deterministic local scan; default target: latest discover session). |
+| `--output-format <fmt>` | `text` | Progress/result format: `text`, `json`, `stream-json`. |
+| `-v, --verbose` | off | Show agent reasoning. |
+
+### `schedule`
+
+Run discovery recurringly and record per-run topology drift (headless, read-only, no agent loop).
+
+`datasynx-cartography schedule --config <file> [options]`
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--config <file>` | **required** | JSON config file with a `schedule` block. |
+| `--once` | on (default) | Run a single pass and exit (cron-driver friendly). |
+| `--watch` | off | Run continuously on the configured cron schedule. Mutually exclusive with `--once`; requires `schedule.cron`. |
+| `--output-format <fmt>` | config / `json` | Result format: `text`, `json`, `stream-json` (overrides config). |
+| `--db <path>` | config | DB path (overrides config). |
+
+### `seed`
+
+Manually add known infrastructure (tools, DBs, APIs, etc.).
+
+`datasynx-cartography seed [options]`
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--file <path>` | — | JSON file with node definitions. |
+| `--session <id>` | new session | Add to an existing session. |
+| `--org <name>` | `local` | Tenant/organization to scope the session to. |
+| `--db <path>` | default catalog | DB path. |
+
+---
+
+## Analysis & insight
+
+### `diff [base] [current]`
+
+Compare two discovery sessions (drift detection). Defaults to the two most recent.
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--format <fmt>` | `text` | Output format: `text`, `json`, `mermaid`. |
+| `-o, --output <file>` | stdout | Write to a file instead of stdout. |
+| `--db <path>` | default catalog | DB path. |
+
+### `drift [base] [current]`
+
+Classify drift between two sessions into a severity-ranked alert and emit it to configured sinks (default: stdout). Defaults to the two most recent. A single-session catalog is a clean no-op (exit 0).
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--min-severity <s>` | `info` | Minimum severity to emit: `info`, `warning`, `critical`. |
+| `--webhook <url>` | — | Outbound webhook URL (overrides config; token via `CARTOGRAPHY_DRIFT_TOKEN`). |
+| `--db <path>` | default catalog | DB path. |
+
+### `compliance [session-id]`
+
+Score a session against a compliance ruleset (CIS / SOC 2 / ISO 27001 starter sets). Defaults to the latest session.
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--ruleset <name>` | `baseline` | Ruleset: `baseline`, `cis`, `soc2`, `iso27001`. |
+| `--format <fmt>` | `text` | Output format: `text`, `json`, `markdown`, `mermaid`. |
+| `-o, --output <file>` | stdout | Write to a file instead of stdout. |
+| `--db <path>` | default catalog | DB path. |
+
+### `cost`
+
+Import cost/owner attribution from a CSV and enrich a session (FinOps).
+
+`datasynx-cartography cost --file <path> [options]`
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--file <path>` | **required** | CSV: `nodeId,owner,amount,currency,period[,source]`. |
+| `--session <id>` | latest | Session to enrich. |
+| `--match <strategy>` | `nodeId` | Row→node match: `nodeId`, `name`, `tag`. |
+| `--db <path>` | default catalog | DB path. |
+
+### `export [session-id]`
+
+Generate all output files (Mermaid / JSON / YAML / HTML / map / cost). Defaults to the latest session.
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `-o, --output <dir>` | `./datasynx-output` | Output directory. |
+| `--format <fmt...>` | `mermaid json yaml html map` | Formats: `mermaid`, `json`, `yaml`, `html`, `map`, `cost`. |
+
+---
+
+## Inspection
+
+### `show [session-id]`
+
+Show session details (mode, timing, node/edge/event counts, recent activity). Defaults to the latest session. No flags.
+
+### `sessions`
+
+List all sessions. No flags.
+
+### `overview`
+
+Aggregate overview across all cartography sessions.
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--db <path>` | default catalog | DB path. |
+
+### `chat [session-id]`
+
+Interactive chat about your mapped infrastructure (uses `@anthropic-ai/sdk`; requires `ANTHROPIC_API_KEY`). Defaults to the latest completed session.
 
 | Flag | Default | Purpose |
 | --- | --- | --- |
-| `--http` | off | Use Streamable HTTP instead of stdio. |
+| `--db <path>` | default catalog | DB path. |
+| `--model <m>` | fast helper model | Model. |
+
+### `bookmarks`
+
+View all browser bookmarks (Chrome, Chromium, Edge, Brave, Vivaldi, Opera, Firefox). No flags.
+
+### `docs`
+
+Print the full in-terminal feature reference and all commands. No flags.
+
+---
+
+## Consent & sync (collector client)
+
+These commands are the consent-gated outbound pipeline to a central collector.
+They are opt-in; `sync` is inert unless `centralDb` is configured. Nothing leaves
+the machine without an explicit approval or a remembered rule.
+
+### `consent`
+
+Manage the per-employee data-sharing policy (`none` | `anonymized` | `full`) + admin anonymization. Sub-commands:
+
+| Sub-command | Purpose | Flags |
+| --- | --- | --- |
+| `consent default <level>` | Set the global default sharing level (`none`/`anonymized`/`full`). | `--db <path>` |
+| `consent set <pattern> <level>` | Set a pattern override (glob over the node id; `*` = within-segment, `**` = any). | `--db <path>` |
+| `consent clear <pattern>` | Remove a pattern override (the global default cannot be cleared). | `--db <path>` |
+| `consent list` | Show the global default + every pattern override. | `--db <path>` |
+| `consent preview [session]` | Show exactly what would leave the machine for a session (default: latest). | `--db <path>`, `--org <name>` |
+| `consent key rotate` | Rotate the org key (prior reversal entries become unrecoverable). | `--org <name>` |
+| `consent reverse <token>` | Admin: recover the original plaintext behind a pseudonym token. | `--db <path>`, `--org <name>` |
+
+`--org <name>` selects the organization namespace for the org key.
+
+### `sync`
+
+Central-DB outbound sync: review queued items and push approved deltas (opt-in). Sub-commands:
+
+| Sub-command | Purpose | Flags |
+| --- | --- | --- |
+| `sync status` | Show the pending-review queue (counts by status + pending items). | `--db <path>` |
+| `sync review` | Interactively approve/withhold each pending item (decisions are remembered). | `--db <path>` |
+| `sync push` | Push approved deltas to the central ingest endpoint (bearer-auth HTTPS). | `--db <path>`, `--dry-run` |
+
+---
+
+## Servers
+
+### `mcp`
+
+Run the Model Context Protocol server (stdio by default) — the primary interface for AI agents. `--server-mode` turns the binary into a self-hostable central collector. The separate `cartography-mcp` binary is equivalent.
+
+`datasynx-cartography mcp [options]`
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--http` | off | Use Streamable HTTP transport instead of stdio. |
 | `--port <n>` | `3737` | HTTP port. |
 | `--host <h>` | `127.0.0.1` | HTTP host. |
-| `--allowed-hosts <list>` | — | Host allowlist (required for non-loopback `--host`). |
-| `--db <path>` | default catalog | Catalog to serve. |
-| `--session <id>` | `latest` | Session to serve. |
+| `--allowed-hosts <list>` | — | Comma-separated Host allowlist (required for non-loopback `--host`). |
+| `--token <secret>` | — | Bearer token required on HTTP requests (or `CARTOGRAPHY_HTTP_TOKEN`); mandatory for non-loopback `--host`. |
+| `--db <path>` | default catalog | DB path. |
+| `--session <id>` | `latest` | Session to serve (id or `"latest"`). |
+| `--tenant <id>` | `local` | Tenant/organization whose topology to serve (alias: `--org`). |
+| `--org <id>` | — | Alias for `--tenant`. |
 | `--no-semantic` | — | Disable semantic (vector) search. |
+| `--plugins <list>` | — | Comma-separated scanner plugin package names to load (opt-in; or `CARTOGRAPHY_PLUGINS`). |
+| `--server-mode` | off | Run as a central collector: enable the authenticated `POST /ingest` write route + org-wide summary (implies `--http`). |
+| `--anon-mode <mode>` | `reject` | On ingest, `reject` \| `strip` un-anonymized identifying fragments (server-mode). |
+| `--auth-required` | off | Reject unauthenticated requests even on loopback (RBAC required mode). |
+| `--store-backend <kind>` | `sqlite` | Central store backend: `sqlite` \| `graph` (Neo4j/Memgraph, opt-in). |
+| `--graph-url <url>` | — | Bolt URL for `--store-backend graph` (or `CARTOGRAPHY_GRAPH_URL`). |
+| `--graph-user <user>` | — | Graph DB user (or `CARTOGRAPHY_GRAPH_USER`). |
+| `--graph-password <pw>` | — | Graph DB password (or `CARTOGRAPHY_GRAPH_PASSWORD`). |
+
+### `api`
+
+Run the read-only REST/GraphQL API server over the topology store.
+
+`datasynx-cartography api [options]`
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--http` | on | Use HTTP transport (default; kept for symmetry with `mcp`). |
+| `--port <n>` | `3737` | HTTP port. |
+| `--host <h>` | `127.0.0.1` | HTTP host. |
+| `--allowed-hosts <list>` | — | Comma-separated Host allowlist (required for non-loopback `--host`). |
+| `--allowed-origins <list>` | same-origin | Comma-separated CORS Origin allowlist. |
+| `--token <secret>` | — | Bearer token required on requests (or `CARTOGRAPHY_HTTP_TOKEN`); mandatory for non-loopback `--host`. |
+| `--db <path>` | default catalog | DB path. |
+| `--session <id>` | `latest` | Session to serve (id or `"latest"`). |
+| `--tenant <id>` | `local` | Default tenant whose topology to serve (alias: `--org`). |
+| `--org <id>` | — | Alias for `--tenant`. |
+| `--no-graphql` | — | Disable the `/graphql` endpoint (REST only). |
+| `--no-dashboard` | — | Disable the web dashboard at `/` and `/app`. |
+| `--auth-required` | off | Reject unauthenticated requests even on loopback (RBAC required mode). |
+
+### `operator`
+
+Run the Kubernetes operator: continuous in-cluster discovery + drift reporting.
+
+`datasynx-cartography operator [options]`
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--config <file>` | — | JSON config file (drift sinks, db path). |
+| `--interval <sec>` | `300` | Reconcile interval in seconds. |
+| `--once` | off | Run a single reconcile and exit (CronJob-driver friendly). |
+| `--db <path>` | config | DB path (overrides config). |
+
+---
+
+## Setup & maintenance
+
+### `auth`
+
+Manage RBAC credentials for the HTTP surfaces (MCP transport + API server). Sub-commands:
+
+| Sub-command | Purpose | Flags |
+| --- | --- | --- |
+| `auth add <subject>` | Create a credential and print its bearer token **once** (only the hash is stored). | `--role <role>` (`viewer`/`operator`/`admin`, default `viewer`), `--tenant <id>` (default `local`), `--token <secret>`, `--db <path>` |
+| `auth list` | List credentials (subjects/roles/tenants — token hashes only, never the raw token). | `--db <path>` |
+| `auth revoke <subject>` | Revoke all credentials for a subject. | `--db <path>` |
+
+### `install`
+
+Register the Cartography MCP server into an AI host's config (parse-merge, never clobber).
+
+`datasynx-cartography install --client <id> [options]`
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--client <id>` | **required** | Target host id (see `list-clients`). |
+| `--global` | on (default) | Write the global/user config. |
+| `--project` | off | Write the project-local config instead. |
+| `--dry-run` | off | Show the merge diff without writing. |
+| `--deeplink` | off | Print a one-click install deeplink instead of writing (Cursor / VS Code). |
+| `--name <name>` | default server name | Server name to register. |
+| `--http` | off | Register the Streamable HTTP endpoint instead of stdio. |
+| `--url <url>` | — | HTTP endpoint (with `--http`). |
+| `--db <path>` | — | Pass `--db <path>` to the server. |
+| `--session <id>` | — | Pass `--session <id>` to the server. |
+
+### `list-clients`
+
+List the AI hosts the installer can configure. No flags.
+
+### `doctor`
+
+Check all requirements and cloud CLIs (kubectl, aws, gcloud, az). No flags.
+
+### `prune`
+
+Delete old sessions and their data.
+
+`datasynx-cartography prune [options]`
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `--older-than <days>` | `30` | Delete sessions older than N days. |
+| `--events-older-than <days>` | — | Compact the audit trail: delete activity events older than N days. |
+| `--db <path>` | default catalog | DB path. |
+| `--dry-run` | off | Show what would be deleted without deleting. |
 
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datasynx/agentic-ai-cartography",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "description": "MCP-first infrastructure & agentic-AI cartography — install once, every AI agent knows your system landscape. Read-only discovery exposed over the Model Context Protocol.",
   "type": "module",
   "sideEffects": false,

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.datasynx/cartography",
   "description": "MCP-first read-only discovery of your infra & SaaS landscape as MCP resources, tools and prompts.",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "repository": {
     "url": "https://github.com/datasynx/agentic-ai-cartography",
     "source": "github"
@@ -12,7 +12,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@datasynx/agentic-ai-cartography",
-      "version": "2.11.0",
+      "version": "2.12.1",
       "runtimeHint": "npx",
       "transport": { "type": "stdio" },
       "runtimeArguments": [