agentic-ai-cartography

<div align="center">

<a href="https://github.com/datasynx/agentic-ai-cartography">
  <img src="https://raw.githubusercontent.com/datasynx/agentic-ai-cartography/main/docs/assets/datasynx-logo.png" alt="Datasynx" width="340" />
</a>

# Datasynx Cartography

**AI-powered Infrastructure Discovery & Agentic AI Cartography**

[![npm version](https://img.shields.io/npm/v/@datasynx/agentic-ai-cartography?style=flat-square&color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/@datasynx/agentic-ai-cartography)
[![npm downloads](https://img.shields.io/npm/dm/@datasynx/agentic-ai-cartography?style=flat-square&color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/@datasynx/agentic-ai-cartography)
[![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)
[![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)
[![Docs](https://img.shields.io/badge/docs-live-2E8555?style=flat-square&logo=readthedocs&logoColor=white)](https://datasynx.github.io/agentic-ai-cartography/)
[![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/>

*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/>

**[📖 Documentation](https://datasynx.github.io/agentic-ai-cartography/) · [📦 npm](https://www.npmjs.com/package/@datasynx/agentic-ai-cartography) · [💼 LinkedIn](https://www.linkedin.com/company/datasynx-ai/) · [🐛 Issues](https://github.com/datasynx/agentic-ai-cartography/issues)**

</div>

---

## 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) ·
[Star History](#star-history)

---

## 🤖 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
```

### Auto-install into your client

Let the harness write the correct config for your host — it parses the existing
file and merges in the server entry **without clobbering** your other servers:

```bash
datasynx-cartography list-clients                          # supported hosts
# claude-code · cursor · vscode · codex · windsurf · cline · roo
# zed · junie · gemini · goose · openhands · claude-desktop
datasynx-cartography install --client claude-code          # global/user config
datasynx-cartography install --client claude-code --project # project-local (.mcp.json)
datasynx-cartography install --client claude-code --dry-run # preview the merge diff
```

Flags: `--global` (default) / `--project` scope, `--dry-run` (no write), `--name <server>`,
`--http`/`--url <url>` (register the HTTP endpoint), `--db <path>`, `--session <id>`,
`--deeplink` (print a one-click Cursor/VS Code install link instead of writing).

```bash
datasynx-cartography install --client cursor --deeplink   # cursor://… one-click link
datasynx-cartography install --client vscode --deeplink   # vscode://… + `code --add-mcp`
```

> Thirteen hosts are supported today (see `list-clients`). The server is also
> deployable on [Smithery](https://smithery.ai) (TypeScript runtime, `smithery.yaml`)
> and published to the official MCP Registry (`server.json`).
>
> **Smithery scope:** the hosted runtime needs no secrets (`smithery.yaml` declares
> `env: {}`) because it serves a read-only catalog from an in-memory or supplied
> SQLite database. The cloud scanners (`scan_aws_resources`, `scan_gcp_resources`,
> `scan_azure_resources`, `scan_k8s_resources`) require the respective CLI and its
> credentials on the host, so they are intended for local/self-hosted runs, not the
> managed Smithery instance.

**Claude Desktop one-click** — build the portable bundle and double-click it
(Settings → Extensions → Install), or drag it onto the window:
```bash
npm run build:mcpb     # → dist/cartography.mcpb (validated against the mcpb v0.3 schema)
```

### Connect your client (copy-paste)

**Claude Code** — install as a plugin from the Datasynx marketplace (recommended):
```text
/plugin marketplace add datasynx/claude-plugins
/plugin install cartography@datasynx
```
This wires up the MCP server in one step (verify with `/mcp`) — the same flow as
[`shadowing`](https://github.com/datasynx/agentic-ai-shadowing). The plugin lives
in [`plugin/`](plugin/). Prefer to wire it by hand instead?
```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 (loopback, no auth)

# Exposing beyond loopback requires BOTH an explicit Host allowlist (CVE-2025-66414)
# AND a bearer token — clients must send `Authorization: Bearer <token>`:
export CARTOGRAPHY_HTTP_TOKEN=$(openssl rand -hex 32)
cartography-mcp --http --host 0.0.0.0 --port 3737 \
  --allowed-hosts cartography.internal:3737 --token "$CARTOGRAPHY_HTTP_TOKEN"
```
> Binding a non-loopback `--host` **without** `--allowed-hosts` (DNS-rebinding) **or without
> `--token`** (`CARTOGRAPHY_HTTP_TOKEN`) is refused on purpose — it would leave the scanning
> tools open to anyone who can reach the host. Put it behind TLS / a reverse proxy for real
> deployments. The same flags work on `datasynx-cartography mcp` and the Smithery deployment.

**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
```

**Frameworks without a config file** (CrewAI, AutoGen/MAF, LangGraph, Pydantic AI,
OpenAI Agents SDK, Smolagents, Vercel AI SDK) load MCP tools via their own adapters —
copy-paste snippets in **[docs/adapters.md](docs/adapters.md)**.

> Full documentation lives at **[datasynx.github.io/agentic-ai-cartography](https://datasynx.github.io/agentic-ai-cartography/)**
> — quickstart, the client matrix, MCP tools and CLI reference. Drop **[AGENTS.md](AGENTS.md)**
> into a repo to give coding agents the standard config block.

### Embed in your own app

```ts
import { createMcpServer, runStdio, createS