@datasynx/agentic-ai-cartography 1.1.1 → 2.2.0

package/llms.txt

@@ -0,0 +1,24 @@
+# @datasynx/agentic-ai-cartography
+
+> MCP-first infrastructure & agentic-AI cartography — install once, every AI agent knows your system landscape. Read-only discovery exposed over the Model Context Protocol.
+
+Cartography discovers your services, databases, SaaS tools and dependencies
+(read-only, deterministic) and exposes the topology over the Model Context
+Protocol. Install once and any MCP host or agent framework can query it.
+
+## Getting started
+
+- [Quickstart](https://datasynx.github.io/agentic-ai-cartography/#quickstart): From zero to an agent that knows your system.
+- [Install into a client](https://datasynx.github.io/agentic-ai-cartography/#install): Write the MCP config for any supported host.
+
+## Reference
+
+- [MCP tools & resources](https://datasynx.github.io/agentic-ai-cartography/#tools): Resources, tools and prompts the server exposes.
+- [CLI](https://datasynx.github.io/agentic-ai-cartography/#cli): datasynx-cartography commands and flags.
+- [Supported clients](https://datasynx.github.io/agentic-ai-cartography/#clients): The host install matrix.
+- [Non-MCP frameworks](https://datasynx.github.io/agentic-ai-cartography/#adapters): LangGraph, CrewAI, Vercel AI SDK and more.
+
+## Explanation
+
+- [Why MCP-first](https://datasynx.github.io/agentic-ai-cartography/#architecture): The design rationale.
+- [Threat model](https://github.com/datasynx/agentic-ai-cartography/blob/main/docs/explanation/threat-model.md): Attacker model, trust boundaries and mitigations.

package/package.json

@@ -1,32 +1,54 @@
 {
   "name": "@datasynx/agentic-ai-cartography",
-  "version": "1.1.1",
-  "description": "AI-powered infrastructure cartography CLI — built on Claude Agent SDK",
+  "version": "2.2.0",
+  "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,
+  "mcpName": "io.github.datasynx/cartography",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "bin": {
-    "datasynx-cartography": "./dist/cli.js"
+    "datasynx-cartography": "./dist/cli.js",
+    "cartography-mcp": "./dist/mcp-bin.js"
   },
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "scripts",
+    "server.json",
     "README.md",
-    "LICENSE"
+    "AGENTS.md",
+    "LICENSE",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "scripts": {
     "build": "tsup",
+    "build:mcpb": "node scripts/build-mcpb.mjs",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "docs:llms": "node scripts/build-llms.mjs",
+    "docs:tables": "tsx scripts/gen-docs.ts",
+    "docs:build": "npm run docs:tables && npm run docs:llms",
     "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run lint && npm run test && npm run build",
-    "postinstall": "node scripts/postinstall.mjs"
+    "typecheck": "tsc --noEmit",
+    "release": "semantic-release",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -35,14 +57,18 @@
     "infrastructure",
     "cartography",
     "discovery",
-    "sop",
-    "claude",
+    "topology",
     "ai-agent",
+    "agentic-ai",
+    "mcp",
     "devops",
+    "platform-engineering",
     "mermaid",
     "backstage",
+    "cmdb",
     "network-topology",
-    "observability"
+    "observability",
+    "shadow-it"
   ],
   "author": {
     "name": "Datasynx AI",
@@ -50,29 +76,53 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/datasynx/agentic-ai-cartography.git"
+    "url": "git+https://github.com/datasynx/agentic-ai-cartography.git"
   },
   "homepage": "https://github.com/datasynx/agentic-ai-cartography#readme",
   "bugs": {
     "url": "https://github.com/datasynx/agentic-ai-cartography/issues"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "license": "MIT",
+  "overrides": {
+    "tmp": "^0.2.7",
+    "hono": "^4.12.25"
+  },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.59",
-    "@anthropic-ai/sdk": "^0.78.0",
-    "better-sqlite3": "^12.6.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
     "commander": "^14.0.0",
-    "ora": "^9.3.0",
-    "picocolors": "^1.1.1",
-    "zod": "^4.3.6"
+    "smol-toml": "^1.6.1",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.2.70 <0.4.0",
+    "@anthropic-ai/sdk": "^0.104.0",
+    "@huggingface/transformers": "^4.2.0",
+    "openai": "^4.104.0",
+    "sqlite-vec": "^0.1.9"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "@arethetypeswrong/cli": "^0.18.2",
+    "ajv": "^8.20.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
     "@types/better-sqlite3": "^7.6.12",
     "@types/node": "^22.10.0",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.0",
+    "license-checker": "^25.0.1",
+    "publint": "^0.3.0",
+    "semantic-release": "^24.2.0",
     "tsup": "^8.3.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.2",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   }
 }

package/scripts/build-llms.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Generate llms.txt (a curated, LLM-friendly navigation map) and llms-full.txt
+ * (the full documentation text in one file) from the docs/ sources, per the
+ * llmstxt.org convention. Canonical output lives at the repo root so the files
+ * ship in the npm package and are agent-discoverable; `docs:build` also copies
+ * them into docs/public so the site serves them at its domain root.
+ *
+ * Run via `npm run docs:llms`. Kept in lockstep with the docs by a drift test.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const SITE = 'https://datasynx.github.io/agentic-ai-cartography';
+
+/** Curated documentation index. Links point to anchors on the single-page site. */
+const SECTIONS = [
+  {
+    heading: 'Getting started',
+    pages: [
+      { file: 'docs/tutorials/index.md', url: `${SITE}/#quickstart`, title: 'Quickstart', desc: 'From zero to an agent that knows your system.' },
+      { file: 'docs/how-to/install.md', url: `${SITE}/#install`, title: 'Install into a client', desc: 'Write the MCP config for any supported host.' },
+    ],
+  },
+  {
+    heading: 'Reference',
+    pages: [
+      { file: 'docs/reference/mcp.md', url: `${SITE}/#tools`, title: 'MCP tools & resources', desc: 'Resources, tools and prompts the server exposes.' },
+      { file: 'docs/reference/cli.md', url: `${SITE}/#cli`, title: 'CLI', desc: 'datasynx-cartography commands and flags.' },
+      { file: 'docs/reference/clients.md', url: `${SITE}/#clients`, title: 'Supported clients', desc: 'The host install matrix.' },
+      { file: 'docs/adapters.md', url: `${SITE}/#adapters`, title: 'Non-MCP frameworks', desc: 'LangGraph, CrewAI, Vercel AI SDK and more.' },
+    ],
+  },
+  {
+    heading: 'Explanation',
+    pages: [
+      { file: 'docs/explanation/index.md', url: `${SITE}/#architecture`, title: 'Why MCP-first', desc: 'The design rationale.' },
+      { file: 'docs/explanation/threat-model.md', url: 'https://github.com/datasynx/agentic-ai-cartography/blob/main/docs/explanation/threat-model.md', title: 'Threat model', desc: 'Attacker model, trust boundaries and mitigations.' },
+    ],
+  },
+];
+
+const stripFrontmatter = (s) => s.replace(/^---\n[\s\S]*?\n---\n/, '');
+
+/** Pure: build both files' contents from the docs sources. Side-effect free. */
+export function generate() {
+  const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+  const SUMMARY = pkg.description;
+
+  const llms = [`# ${pkg.name}`, '', `> ${SUMMARY}`, ''];
+  llms.push(
+    'Cartography discovers your services, databases, SaaS tools and dependencies',
+    '(read-only, deterministic) and exposes the topology over the Model Context',
+    'Protocol. Install once and any MCP host or agent framework can query it.',
+    '',
+  );
+  for (const section of SECTIONS) {
+    llms.push(`## ${section.heading}`, '');
+    for (const p of section.pages) llms.push(`- [${p.title}](${p.url}): ${p.desc}`);
+    llms.push('');
+  }
+  const llmsTxt = llms.join('\n');
+
+  const full = [`# ${pkg.name} — full documentation`, '', `> ${SUMMARY}`, ''];
+  for (const section of SECTIONS) {
+    for (const p of section.pages) {
+      full.push('', '---', '', `<!-- source: ${p.file} -->`, '', stripFrontmatter(readFileSync(resolve(root, p.file), 'utf8')).trim(), '');
+    }
+  }
+  const llmsFullTxt = full.join('\n') + '\n';
+  return { llmsTxt, llmsFullTxt };
+}
+
+/** Write the canonical root files and mirror them into docs/ so Pages serves them at its root. */
+export function write() {
+  const { llmsTxt, llmsFullTxt } = generate();
+  writeFileSync(resolve(root, 'llms.txt'), llmsTxt);
+  writeFileSync(resolve(root, 'llms-full.txt'), llmsFullTxt);
+  copyFileSync(resolve(root, 'llms.txt'), resolve(root, 'docs', 'llms.txt'));
+  copyFileSync(resolve(root, 'llms-full.txt'), resolve(root, 'docs', 'llms-full.txt'));
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  write();
+  console.log('✓ Wrote llms.txt and llms-full.txt (+ docs/public mirror)');
+}

package/scripts/build-mcpb.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Build the Claude Desktop one-click bundle: keep `mcpb/manifest.json` in sync
+ * with package.json's version, then pack `mcpb/` into `dist/cartography.mcpb`
+ * using the official @anthropic-ai/mcpb CLI.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+const manifestPath = resolve(root, 'mcpb', 'manifest.json');
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+
+// Single source of truth: the npm version drives the manifest version.
+if (manifest.version !== pkg.version) {
+  manifest.version = pkg.version;
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  console.log(`Synced manifest version → ${pkg.version}`);
+}
+
+mkdirSync(resolve(root, 'dist'), { recursive: true });
+const out = resolve(root, 'dist', 'cartography.mcpb');
+
+const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+execFileSync(npx, ['mcpb', 'validate', manifestPath], { stdio: 'inherit', cwd: root });
+execFileSync(npx, ['mcpb', 'pack', resolve(root, 'mcpb'), out], { stdio: 'inherit', cwd: root });
+console.log(`\n✓ Wrote ${out}`);

package/scripts/gen-docs.ts

@@ -0,0 +1,123 @@
+/**
+ * Regenerate the auto-generated documentation blocks from the single source of
+ * truth (the code), so the tool table and client matrix can never drift:
+ *
+ *  - docs/reference/mcp.md      → AUTO-GENERATED:tools       (live MCP tool list)
+ *  - docs/reference/clients.md  → AUTO-GENERATED:clients     (registry matrix)
+ *                               → AUTO-GENERATED:quickstarts (per-host config block)
+ *  - AGENTS.md                  → the standard config block for agent context
+ *
+ * Run via `npm run docs:tables`. Guarded against drift by a test.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { createMcpServer } from '../src/mcp/server.js';
+import { CartographyDB } from '../src/db.js';
+import { defaultConfig } from '../src/types.js';
+import { listClients, getClient, planInstall, defaultServerEntry } from '../src/installer/index.js';
+import type { ResolveContext } from '../src/installer/index.js';
+
+const root = resolve(import.meta.dirname, '..');
+
+function replaceBlock(content: string, name: string, body: string): string {
+  const re = new RegExp(`(<!-- AUTO-GENERATED:${name} START[^\\n]*-->\\n)[\\s\\S]*?(<!-- AUTO-GENERATED:${name} END -->)`);
+  if (!re.test(content)) throw new Error(`marker ${name} not found`);
+  return content.replace(re, `$1${body}\n$2`);
+}
+
+/** Live tool list from the running MCP server (single source of truth). */
+async function toolTable(): Promise<string> {
+  const db = new CartographyDB(':memory:');
+  db.createSession('discover', defaultConfig());
+  const server = createMcpServer({ db, discovery: async () => ({ nodes: 0, edges: 0 }) });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: 'gen-docs', version: '1.0.0' });
+  await Promise.all([client.connect(ct), server.connect(st)]);
+  const { tools } = await client.listTools();
+  await client.close();
+  db.close();
+  const rows = tools
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((t) => `| \`${t.name}\` | ${t.annotations?.readOnlyHint ? '✅' : '—'} | ${(t.description ?? '').split('\n')[0]} |`);
+  return ['| Tool | Read-only | Description |', '| --- | --- | --- |', ...rows].join('\n');
+}
+
+function clientMatrix(): string {
+  const rows = listClients().map((c) => `| \`${c.id}\` | ${c.label} | ${c.format} | ${c.note ?? ''} |`);
+  return ['| id | Host | Format | Notes |', '| --- | --- | --- | --- |', ...rows].join('\n');
+}
+
+function quickstarts(): string {
+  const ctx: ResolveContext = { scope: 'global', os: 'linux', home: '~', cwd: '.', env: {} };
+  const entry = defaultServerEntry();
+  const out: string[] = [];
+  for (const c of listClients()) {
+    const spec = getClient(c.id)!;
+    const plan = planInstall(spec, ctx, { entry });
+    const lang = plan.format === 'json' ? 'json' : plan.format;
+    out.push(`### ${c.label} (\`${c.id}\`)`, '', `\`${plan.path}\``, '', '```' + lang, plan.after.trim(), '```', '');
+  }
+  return out.join('\n');
+}
+
+function agentsMd(): string {
+  const entry = defaultServerEntry();
+  const block = JSON.stringify({ mcpServers: { cartography: { command: entry.command, args: entry.args } } }, null, 2);
+  return `# Working with Cartography
+
+This project can use **Cartography** — an MCP server that maps the system landscape
+(services, datastores, SaaS tools, dependencies) read-only.
+
+## Enable it
+
+\`\`\`json
+${block}
+\`\`\`
+
+Or run \`datasynx-cartography install --client <id>\` (see \`list-clients\`).
+
+## Use it
+
+- Read \`cartography://graph/summary\` first — a low-token overview.
+- Then drill in with \`query_infrastructure\`, \`get_dependencies\`, \`get_node\`.
+- All tools are read-only; run \`run_discovery\` to (re)scan the local system.
+
+<!-- Generated by \`npm run docs:tables\`; edit scripts/gen-docs.ts, not this file. -->
+`;
+}
+
+export interface GeneratedDocs {
+  mcpPath: string;
+  mcp: string;
+  clientsPath: string;
+  clients: string;
+  agentsPath: string;
+  agents: string;
+}
+
+/** Pure: compute the regenerated file contents from the current sources. */
+export async function buildDocs(): Promise<GeneratedDocs> {
+  const mcpPath = resolve(root, 'docs/reference/mcp.md');
+  const mcp = replaceBlock(readFileSync(mcpPath, 'utf8'), 'tools', await toolTable());
+
+  const clientsPath = resolve(root, 'docs/reference/clients.md');
+  let clients = readFileSync(clientsPath, 'utf8');
+  clients = replaceBlock(clients, 'clients', clientMatrix());
+  clients = replaceBlock(clients, 'quickstarts', quickstarts());
+
+  return { mcpPath, mcp, clientsPath, clients, agentsPath: resolve(root, 'AGENTS.md'), agents: agentsMd() };
+}
+
+export async function generateDocs(): Promise<void> {
+  const d = await buildDocs();
+  writeFileSync(d.mcpPath, d.mcp);
+  writeFileSync(d.clientsPath, d.clients);
+  writeFileSync(d.agentsPath, d.agents);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  generateDocs().then(() => console.log('✓ Regenerated tool table, client matrix, quickstarts, AGENTS.md'));
+}

package/scripts/validate-server-json.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Validate server.json before it ships:
+//   (1) version parity with package.json            [hard fail]
+//   (2) required-field structure                    [hard fail]
+//   (3) JSON-schema validation against $schema       [hard on real violations,
+//       warn-and-skip on network/$ref errors so CI never flakes]
+// Authoritative schema validation also runs at publish time via mcp-publisher
+// (.github/workflows/mcp-publish.yml).
+
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+const server = JSON.parse(readFileSync(resolve(root, 'server.json'), 'utf8'));
+
+const fail = (m) => { console.error(`::error::${m}`); process.exitCode = 1; };
+
+// (1) version parity
+if (server.version !== pkg.version) {
+  fail(`server.json version (${server.version}) != package.json version (${pkg.version})`);
+}
+
+// (2) required structure
+for (const key of ['$schema', 'name', 'version', 'packages']) {
+  if (server[key] === undefined) fail(`server.json missing required field: ${key}`);
+}
+if (Array.isArray(server.packages)) {
+  server.packages.forEach((p, i) => {
+    for (const k of ['identifier', 'version', 'transport']) {
+      if (p[k] === undefined) fail(`server.json packages[${i}] missing: ${k}`);
+    }
+  });
+} else if (server.packages !== undefined) {
+  fail('server.json packages must be an array');
+}
+
+// (3) best-effort schema validation
+try {
+  const { default: Ajv } = await import('ajv');
+  const res = await fetch(server.$schema, { signal: AbortSignal.timeout(10_000) });
+  if (!res.ok) throw new Error(`schema fetch ${res.status}`);
+  const schema = await res.json();
+  const ajv = new Ajv({ strict: false, allErrors: true, validateFormats: false });
+  const validate = ajv.compile(schema);
+  if (!validate(server)) {
+    for (const e of validate.errors ?? []) fail(`schema: ${e.instancePath || '/'} ${e.message}`);
+  }
+} catch (err) {
+  console.warn(`::warning::Skipped remote schema validation (${err instanceof Error ? err.message : String(err)}); parity + structure checks still enforced.`);
+}
+
+if (!process.exitCode) console.log(`server.json OK — version parity + structure (${pkg.version})`);

package/server.json

@@ -0,0 +1,28 @@
+{
+  "$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.2.0",
+  "repository": {
+    "url": "https://github.com/datasynx/agentic-ai-cartography",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@datasynx/agentic-ai-cartography",
+      "version": "2.2.0",
+      "runtimeHint": "npx",
+      "transport": { "type": "stdio" },
+      "runtimeArguments": [
+        { "type": "named", "name": "--package", "value": "@datasynx/agentic-ai-cartography", "isRequired": true },
+        { "type": "positional", "value": "cartography-mcp", "isRequired": true }
+      ],
+      "packageArguments": [
+        { "type": "named", "name": "--db", "description": "Path to the SQLite catalog", "isRequired": false },
+        { "type": "named", "name": "--session", "description": "Session id to serve, or 'latest'", "isRequired": false }
+      ]
+    }
+  ]
+}

package/dist/bookmarks-BWNVQGPG.js

@@ -1,14 +0,0 @@
-#!/usr/bin/env node
-import {
-  cleanupTempFiles,
-  readFirefoxHistory,
-  scanAllBookmarks,
-  scanAllHistory
-} from "./chunk-QKNYI3SU.js";
-export {
-  cleanupTempFiles,
-  readFirefoxHistory,
-  scanAllBookmarks,
-  scanAllHistory
-};
-//# sourceMappingURL=bookmarks-BWNVQGPG.js.map