@datasynx/agentic-ai-cartography 1.1.1 → 2.0.0

package/README.md

@@ -9,13 +9,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Node.js >=20](https://img.shields.io/badge/Node.js-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org)
 [![CI](https://github.com/datasynx/agentic-ai-cartography/actions/workflows/ci.yml/badge.svg)](https://github.com/datasynx/agentic-ai-cartography/actions/workflows/ci.yml)
-[![Built with Claude](https://img.shields.io/badge/Built_with-Claude_Agent_SDK-D4A017?style=flat-square&logo=anthropic&logoColor=white)](https://github.com/anthropics/claude-code)
+[![Release](https://github.com/datasynx/agentic-ai-cartography/actions/workflows/release.yml/badge.svg)](https://github.com/datasynx/agentic-ai-cartography/actions/workflows/release.yml)
+[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)](https://github.com/semantic-release/semantic-release)
+[![MCP](https://img.shields.io/badge/MCP-server-6E56CF?style=flat-square)](https://modelcontextprotocol.io)
+[![Provenance](https://img.shields.io/badge/npm-provenance_signed-3B7DBD?style=flat-square&logo=npm&logoColor=white)](https://docs.npmjs.com/generating-provenance-statements)
+[![Agentic AI](https://img.shields.io/badge/Agentic_AI-Provider_Agnostic-D4A017?style=flat-square)](https://github.com/datasynx/agentic-ai-cartography)
 [![LinkedIn](https://img.shields.io/badge/LinkedIn-Datasynx_AI-0077B5?style=flat-square&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/datasynx-ai/)
 [![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-blue?style=flat-square)](https://github.com/datasynx/agentic-ai-cartography)
 
 <br/>
 
-*Claude IS the agent — it decides which read-only commands to run, analyses the output, and stores results via custom MCP tools into SQLite. No hand-written parsers, diff logic, or decision trees.*
+*A **Model Context Protocol server** that gives any AI agent read-only awareness of your complete system landscape — local services, databases, SaaS tools, installed apps and their dependencies — with progressive disclosure, recursive dependency traversal and semantic search. Discovery runs deterministically (no LLM required) or via an optional Claude-driven loop. Provider-agnostic: works with Claude, OpenAI, Ollama, or any MCP-compatible host.*
 
 <br/>
 
@@ -25,6 +29,107 @@
 
 ---
 
+## Contents
+
+[MCP-first quick start](#-mcp-first--install-once-every-agent-knows-your-landscape) ·
+[Connect your client](#connect-your-client-copy-paste) ·
+[Embed in your app](#embed-in-your-own-app) ·
+[What it does](#what-it-does) ·
+[Cross-platform](#cross-platform-support) ·
+[Features](#features) ·
+[CLI commands](#commands) ·
+[Architecture](#architecture) ·
+[Safety](#safety) ·
+[Public API](#public-api) ·
+[Releasing](#releasing)
+
+---
+
+## 🤖 MCP-first — install once, every agent knows your landscape
+
+> **v2.0** inverts the architecture: the package's primary interface is now a
+> production **Model Context Protocol (MCP) server**. Any MCP host — Claude Code,
+> Cursor, Cline, Windsurf, VS Code Copilot, the Vercel AI SDK, LangGraph — connects
+> to it and gains read-only awareness of your complete system landscape. The bundled
+> Claude-driven discovery loop is now one optional turnkey adapter; the server needs
+> **no LLM dependency of its own**.
+
+The topology is exposed with **progressive disclosure** so agents never blow their
+context window:
+
+- **Resources** (read-only context): `cartography://graph/summary` (low-token index — read first), `cartography://nodes/{id}`, `cartography://services`, `cartography://databases`, `cartography://dependencies/{id}`.
+- **Tools** (parameterized queries): `query_infrastructure`, `search_topology` (semantic), `get_dependencies` (recursive graph traversal), `list_services`, `get_node`, `get_summary`, `run_discovery`.
+- **Prompts**: `audit-attack-surface`, `map-service-dependencies`, `onboard-to-system`.
+
+### Quick start
+
+```bash
+# 1. Discover your system (read-only, deterministic — no LLM required)
+npx -p @datasynx/agentic-ai-cartography cartography-mcp --help
+datasynx-cartography discover          # or the richer Claude-driven loop
+
+# 2. Run the MCP server (stdio by default)
+npx -p @datasynx/agentic-ai-cartography cartography-mcp
+```
+
+### Connect your client (copy-paste)
+
+**Claude Code**
+```bash
+claude mcp add cartography -- npx -p @datasynx/agentic-ai-cartography cartography-mcp
+```
+
+**Cursor / Windsurf / Cline** — `mcp.json` (or `~/.codeium/windsurf/mcp_config.json`):
+```json
+{
+  "mcpServers": {
+    "cartography": {
+      "command": "npx",
+      "args": ["-p", "@datasynx/agentic-ai-cartography", "cartography-mcp"]
+    }
+  }
+}
+```
+
+**VS Code (Copilot)** — `.vscode/mcp.json` (note: `servers`, not `mcpServers`):
+```json
+{
+  "servers": {
+    "cartography": { "command": "npx", "args": ["-p", "@datasynx/agentic-ai-cartography", "cartography-mcp"] }
+  }
+}
+```
+
+**Remote / team use** — Streamable HTTP (localhost-bound, DNS-rebind protected):
+```bash
+cartography-mcp --http --port 3737      # → http://127.0.0.1:3737/mcp
+```
+
+**Vercel AI SDK** (provider-agnostic):
+```ts
+import { experimental_createMCPClient } from 'ai';
+const mcp = await experimental_createMCPClient({
+  transport: { type: 'sse', url: 'http://127.0.0.1:3737/mcp' },
+});
+const tools = await mcp.tools(); // MCP tools → AI SDK tools, any model
+```
+
+### Embed in your own app
+
+```ts
+import { createMcpServer, runStdio, createSemanticSearch, localDiscoveryFn, CartographyDB } from '@datasynx/agentic-ai-cartography';
+
+const db = new CartographyDB('/path/to/cartography.db');
+const server = createMcpServer({
+  db,
+  search: await createSemanticSearch(db),   // semantic (sqlite-vec) + lexical fallback
+  discovery: localDiscoveryFn(),            // deterministic, LLM-free scanners
+});
+await runStdio(server);
+```
+
+---
+
 ## What it does
 
 ```
@@ -68,7 +173,7 @@ Cartography runs natively on **Linux**, **macOS**, and **Windows** — no WSL re
 | **DB service detection** | CLI probes (psql, mysql, etc.) | CLI probes | `Get-Service` + CLI probes |
 | **Browser bookmarks** | `~/.config/google-chrome` + Snap/Flatpak | `~/Library/Application Support/...` | `%LOCALAPPDATA%\Google\Chrome\User Data` |
 | **Firefox profiles** | `~/.mozilla/firefox` + Snap/Flatpak | `~/Library/.../Firefox/Profiles` | `%APPDATA%\Mozilla\Firefox\Profiles` |
-| **Safety hook** | Blocks `rm`, `mv`, `kill`, etc. | Blocks `rm`, `mv`, `kill`, etc. | Blocks `Remove-Item`, `Stop-Process`, etc. |
+| **Safety policy** | Read-only **allowlist** (POSIX parser) | Read-only **allowlist** (POSIX parser) | Read-only allowlist (PowerShell mutating-cmdlet denylist) |
 
 ---
 
@@ -82,19 +187,20 @@ Cartography runs natively on **Linux**, **macOS**, and **Windows** — no WSL re
 | **Cloud Scanning** | AWS (EC2/RDS/EKS/S3), GCP (Compute/GKE/Cloud Run), Azure (AKS/WebApps), Kubernetes |
 | **Human-in-the-Loop** | Chat with the agent mid-discovery: type `"hubspot windsurf"` to search for specific tools |
 | **Export Formats** | Mermaid topology, D3.js interactive graph, Backstage YAML, JSON |
-| **Safety First** | `PreToolUse` hook blocks all destructive commands — Unix AND PowerShell. 100% read-only |
+| **Safety First** | Strict read-only **allowlist** (not a denylist): only known-safe commands run — shell-aware for POSIX *and* PowerShell, enforced at the command runner as defense-in-depth. 100% read-only |
 
 ---
 
 ## Requirements
 
-- **Node.js >= 20** (Linux, macOS, or Windows)
-- **Claude CLI** — the Agent SDK starts it as a subprocess
-
-```bash
-npm install -g @anthropic-ai/claude-code
-claude login
-```
+- **Node.js >= 20** (Linux, macOS, or Windows) — that's it for the MCP server and the
+  deterministic, read-only discovery. **No LLM and no API key required.**
+- **Optional — Claude CLI**, only for the richer Claude-driven discovery loop
+  (`datasynx-cartography discover`): `npm install -g @anthropic-ai/claude-code && claude login`.
+- **Optional — semantic search** auto-upgrades when `sqlite-vec` and a local embedder
+  (`@huggingface/transformers`) are present; otherwise it falls back to lexical search.
+  These ship as `optionalDependencies` and are lazy-loaded, so installs that skip them
+  pay no cost.
 
 ---
 
@@ -114,7 +220,7 @@ npm install -g @datasynx/agentic-ai-cartography
 # Check all requirements (platform-aware)
 datasynx-cartography doctor
 
-# Discover your full infrastructure (one-shot, Claude Sonnet)
+# Discover your full infrastructure (autonomous agent scan)
 # → scans bookmarks, installed apps, local services, cloud, config files
 # → then interactive follow-up: type tool names to search further
 datasynx-cartography discover
@@ -142,7 +248,7 @@ datasynx-cartography discover [options]
   --entry <hosts...>    Start hosts          (default: localhost)
   --depth <n>           Max crawl depth      (default: 8)
   --max-turns <n>       Max agent turns      (default: 50)
-  --model <m>           Claude model         (default: claude-sonnet-4-5-...)
+  --model <m>           LLM model            (default: claude-sonnet-4-5-...)
   --org <name>          Org name for Backstage YAML
   -o, --output <dir>    Output directory     (default: ./datasynx-output)
   -v, --verbose         Show agent reasoning
@@ -196,33 +302,49 @@ datasynx-output/
 
 ## Architecture
 
+The **MCP server is the headline interface** — LLM-agnostic and the same SQLite graph
+underneath every entry point. Discovery (deterministic scanners or the optional Claude
+loop) writes the graph; any MCP host reads it.
+
 ```
-CLI (Commander.js)
-  └── Preflight: Claude CLI + API key check
-      └── Platform Detection (src/platform.ts)
-          ├── Shell: /bin/sh (Unix) | PowerShell (Windows)
-          ├── Commands: which (Unix) | Get-Command (Windows)
-          └── Agent Orchestrator (src/agent.ts)
-              └── runDiscovery()     Claude Sonnet + Bash + MCP Tools
-                  ├── scan_bookmarks()          browser bookmark extraction (all platforms)
-                  ├── scan_browser_history()     anonymized hostname extraction
-                  ├── scan_installed_apps()      platform-native app detection
-                  ├── scan_local_databases()     DB service + file scanning
-                  ├── scan_k8s_resources()       kubectl (readonly)
-                  ├── scan_aws/gcp/azure()       cloud CLI scans (readonly)
-                  ├── ask_user()                 human-in-the-loop questions
-                  └── Custom MCP Tools → CartographyDB (SQLite WAL)
+                         ┌──────────────────────────────────────────┐
+   MCP hosts ───────────►│  MCP server (src/mcp) — primary interface │
+   (Claude Code,         │    Resources · Tools · Prompts            │
+    Cursor, Cline,       │    stdio + Streamable HTTP transports     │
+    Windsurf, VS Code,   └───────────────────┬──────────────────────┘
+    Vercel AI SDK, …)                        │
+                                             ▼
+                              CartographyDB (SQLite WAL, src/db)
+                         recursive-CTE traversal · search · summary
+                                             ▲
+                ┌────────────────────────────┴────────────────────────────┐
+                │                                                          │
+   Deterministic discovery (src/discovery, src/scanners)     Optional Claude loop (src/agent)
+     bookmarks · installed-apps · local ports · DBs            runDiscovery() — human-in-the-loop
+     LLM-free, registry-driven                                 LLM + Bash + custom MCP tools
+                │                                                          │
+                └──────────────────────────┬───────────────────────────────┘
+                                           ▼
+                    Platform layer (src/platform) + read-only allowlist (src/allowlist)
+                    Shell/commands resolved per-OS · every command vetted before it runs
 ```
 
 ### Safety
 
-Every Bash call is guarded by a `PreToolUse` hook that blocks destructive commands:
-
-**Unix:** `rm`, `mv`, `dd`, `chmod`, `kill`, `docker rm/run/exec`, `kubectl delete/apply/exec`, redirects (`>`), and more.
+v2.0 replaces the old "block bad commands" denylist with a **strict read-only allowlist**
+(`src/allowlist.ts`): a command runs only if it is explicitly known to be safe. The check
+is shell-aware and enforced in two places — the command runner itself (defense-in-depth)
+and the Claude loop's `PreToolUse` hook.
 
-**Windows/PowerShell:** `Remove-Item`, `Move-Item`, `Stop-Process`, `Stop-Service`, `Restart-Computer`, `Format-Volume`, `Out-File`, `Set-Content`, and more.
+- **POSIX:** parses the command line, resolves `sudo`/`env`/command-runners and brace
+  groups, and allows only read-only tools (`ss`, `lsof`, `ps`, `which`, `find`, DB
+  probes, cloud `describe/list/get`, `kubectl get/describe`, …). Redirections, pipes to
+  writers, and anything unrecognized are rejected.
+- **Windows/PowerShell:** allows read-only cmdlets and rejects mutating ones
+  (`Remove-Item`, `Move-Item`, `Stop-Process`, `Stop-Service`, `Restart-Computer`,
+  `Format-Volume`, `Out-File`, `Set-Content`, …).
 
-**Claude only reads — never writes, never deletes.**
+**Cartography only reads — never writes, never deletes.**
 
 ---
 
@@ -243,6 +365,42 @@ await runDiscovery(config, db, sessionId, onEvent, onAskUser, 'hubspot windsurf'
 
 ---
 
+## Releasing
+
+[`release.yml`](.github/workflows/release.yml) publishes to npm automatically on every push
+to `main`, in one of **two modes** — auto-selected by which secrets are present:
+
+- **`RELEASE_TOKEN` present → full [semantic-release](https://github.com/semantic-release/semantic-release).**
+  Version, `CHANGELOG.md`, git tag `v<version>`, GitHub Release and the provenance-signed npm
+  publish are all derived from [Conventional Commits](https://www.conventionalcommits.org/)
+  since the last tag (`fix:` → patch, `feat:` → minor, `feat!:`/`BREAKING CHANGE:` → major;
+  `docs/chore/refactor/test/ci` → no release). No manual version bumps. PR titles are linted
+  by [`pr-title.yml`](.github/workflows/pr-title.yml) so the squash-merge commit stays analyzable.
+- **`RELEASE_TOKEN` absent → idempotent npm publish.** The `package.json` version is published
+  (provenance-signed) only when it isn't already on npm — so doc/refactor merges are no-ops.
+  Bump the version + merge to release.
+
+> **Why two modes:** every commit here carries `.github/workflows/` files, and the Actions
+> `GITHUB_TOKEN` may not push a git ref that touches workflow files (it can't hold the
+> `workflow` scope). semantic-release pushes a tag, so it needs a workflow-scoped
+> `RELEASE_TOKEN`. Until one exists, the idempotent publish keeps releases flowing with only
+> `NPM_TOKEN`; adding `RELEASE_TOKEN` later upgrades to the full flow with no other changes.
+
+Quality is gated independently by [`ci.yml`](.github/workflows/ci.yml) on every PR and push:
+**lint/typecheck → test matrix (Node 20/22) + coverage → audit + license check → build &
+validate (publint, [are-the-types-wrong](https://github.com/arethetypeswrong/arethetypeswrong.github.io),
+ESM/CJS consumer smoke tests)**.
+
+**Repository secrets** (*Settings → Secrets and variables → Actions*):
+
+| Secret | Required | Purpose |
+|---|---|---|
+| `NPM_TOKEN` | **yes** | npm *Automation*/granular token with publish rights for the `@datasynx` scope. Provenance signing itself needs no secret (OIDC). |
+| `RELEASE_TOKEN` | optional | PAT (classic: `repo` + `workflow`) or deploy key. Unlocks full semantic-release (auto-versioning, changelog, tags, GitHub Releases). Without it, the idempotent npm publish is used. |
+| `CODECOV_TOKEN` | optional | Upload coverage to Codecov (non-blocking if absent). |
+
+---
+
 ## Built by
 
 <div align="center">
@@ -256,3 +414,9 @@ await runDiscovery(config, db, sessionId, onEvent, onAskUser, 'hubspot windsurf'
 ## License
 
 MIT — © [Datasynx AI](https://www.linkedin.com/company/datasynx-ai/)
+
+---
+
+## Related Projects
+
+- [**agentic-ai-shadowing**](https://github.com/datasynx/agentic-ai-shadowing) — AI-powered agent session shadowing & replay

package/dist/bookmarks-VS56KVCO.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import {
+  chromeLikeHistoryPaths,
+  chromeLikePaths,
+  cleanupTempFiles,
+  extractHost,
+  readChromeLike,
+  readFirefoxHistory,
+  scanAllBookmarks,
+  scanAllHistory,
+  walkChrome
+} from "./chunk-CJ2PITFA.js";
+import "./chunk-UGSNG3QJ.js";
+export {
+  chromeLikeHistoryPaths,
+  chromeLikePaths,
+  cleanupTempFiles,
+  extractHost,
+  readChromeLike,
+  readFirefoxHistory,
+  scanAllBookmarks,
+  scanAllHistory,
+  walkChrome
+};
+//# sourceMappingURL=bookmarks-VS56KVCO.js.map