{
  "markdown": "# documentdb-agent-kit\n\n[![Status: Public Preview](https://img.shields.io/badge/Status-Public%20Preview-orange?style=flat)](https://azure.microsoft.com/support/legal/preview-supplemental-terms/)\n\n> [!IMPORTANT]\n> **Public Preview.** This project is currently in Public Preview. APIs,\n> configuration, on-disk layout, skill contents, and installer behavior may\n> change in breaking ways before General Availability. There is no SLA.\n> Provided \"as-is\"; see the [Azure Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/).\n> Not recommended for production workloads.\n\nA bundle of agent skills + an MCP server for **Azure DocumentDB (MongoDB-compatible)** — the fully managed Azure service built on the open-source [DocumentDB](https://github.com/documentdb/documentdb) project (Postgres-backed, 99.03% MongoDB-compatible).\n\nSkills follow the [Agent Skills](https://agentskills.io/) format and the kit ships with plugin manifests for Claude Code, Cursor, Codex, Gemini CLI, and GitHub Copilot.\n\n👉 **Capabilities and skill catalog:** [`docs/SKILLS.md`](docs/SKILLS.md)\n\n## Diagnostic Toolbox — Quickstart\n\nBeyond the text skills, the kit ships **deterministic diagnostic scripts** and a\n**knowledge-base router** that inspect a *local* DocumentDB container and return\nevidence-based answers (reading both the MongoDB API and the PostgreSQL engine\nunderneath). They need only `docker`, `bash`, and `python3` — no MCP server, no\ncloud, no API keys. Full guide: [`docs/DIAGNOSTICS.md`](docs/DIAGNOSTICS.md).\n\n### The tools (`scripts/`)\n\nAll are **read-only** (they never modify data) and **cross-layer** (MongoDB API +\nPostgreSQL engine). Each takes `--db <name>`; add `--json` for a compact\nmachine-readable result (what the router consumes).\n\n| Script | Answers | `--json` |\n|--------|---------|:--:|\n| `document-bloat-advisor.sh` | Which collections have large text TOASTed and detoasted on every scan; which field to split out. | ✅ |\n| `index-redundancy-finder.sh` | Redundant (prefix/duplicate/reverse) or unused indexes safe to drop. | ✅ |\n| `db-config-advisor.sh` | Working set vs cache, TOAST share, cache-hit ratios — evidence-based config review. | ✅ |\n| `perf-advisor.sh` | Overall health: collection-scan audit, query timing, PG I/O / locks / config. | ✅ |\n| `data-integrity-check.sh` | Orphaned foreign-key references and mixed-type fields (hard structural integrity). | ✅ |\n\nCommon flags: `--container NAME`, `--password PASS`, `--port`, `--pg-port`; env\nvars `DB_USER` / `DB_PASSWORD` / `PORT` / `PG_PORT` are also honored. **No password\nis baked in** — set `DB_PASSWORD` (or pass `--password`).\n\n### Quickstart\n\n```bash\n# 0. start a local DocumentDB container (choose any password; the scripts read it)\ndocker run -dt --name documentdb-local -p 10260:10260 \\\n  -e USERNAME=docdbadmin -e PASSWORD=Test1234 \\\n  ghcr.io/microsoft/documentdb/documentdb-local:latest\nexport DB_PASSWORD=Test1234          # the scripts require this (or --password)\n\n# 1. seed demo data\nbash scenarios/ecommerce/seed.sh           # -> \"ecommerce\"\nbash scenarios/contoso/seed.sh             # -> \"contoso\" (TOAST demo)\n\n# 2. diagnose (read-only; add --json for machine output)\nbash scripts/document-bloat-advisor.sh --db contoso\nbash scripts/index-redundancy-finder.sh --db ecommerce\n\n# 3. or ask in natural language — the router picks the tool (no LLM, no container)\nbash knowledge-base/kb-route.sh --db contoso \"why are my aggregations slow even though I have indexes\"\n```\n\nDemo datasets are seeders under [`scenarios/`](scenarios/) (they plant the\nproblems the tools find). The regression suite in [`testing/`](testing/README.md)\nguards the scripts.\n\n- **Router:** [`knowledge-base/README.md`](knowledge-base/README.md) · **Demo datasets:** [`scenarios/`](scenarios/)\n- **Regression tests:** [`testing/README.md`](testing/README.md) · **Token study:** [`token-tests/RESULTS.md`](token-tests/RESULTS.md)\n\n## Repo Structure\n\n```\nskills/\n  <category>/            # rule-folder skill (data-modeling, vector-search, …)\n    <rule>.md            # one markdown file per rule\n    references/          # deep-dive reference docs (optional)\n  <skill>/               # standalone skill (mcp-setup, query-optimizer, …)\n    SKILL.md             # agent-facing activation + instructions\n    references/          # reference docs the skill loads at runtime\nscripts/                 # diagnostic toolbox — read-only analyzers + seeders\nknowledge-base/          # NL → script router (kb.json + kb_route.py) + demo\nscenarios/contoso/       # ready-to-run TOAST demo dataset (+ optional scaling-benchmark/)\ntesting/                 # fixture-first regression suite for the scripts (pytest)\ntoken-tests/             # measured token savings of scripts vs text-skill workflows\ndocs/                    # SKILLS.md (catalog) + DIAGNOSTICS.md (toolbox guide)\n```\n\n## Installation\n\nThe kit ships with a one-command installer that wires both the **skills** and\nthe [`microsoft/documentdb-mcp`](https://github.com/microsoft/documentdb-mcp)\nserver into every detected MCP client. Pick your platform:\n\n| OS | Guide |\n|---|---|\n| macOS | [`docs/installation/macos.md`](docs/installation/macos.md) |\n| Linux | [`docs/installation/linux.md`](docs/installation/linux.md) |\n| Windows | [`docs/installation/windows.md`](docs/installation/windows.md) |\n\n### Skills-only (any agent)\n\nTo install just the skill catalog into whichever agent you're using — no MCP server — via the [skills.sh](https://skills.sh/) CLI:\n\n```bash\nnpx skills add Azure/documentdb-agent-kit\n```\n\nThis drops the rule docs into your agent's skill directory but **does not** install the MCP server. Use one of the per-OS guides above if you want the DB tools too.\n\n> To update later, re-run the same `npx skills add Azure/documentdb-agent-kit` command — it re-fetches the latest `main` and overlays updated rule files. For installer-based updates and per-agent plugin update commands, see [`docs/installation/updating.md`](docs/installation/updating.md).\n\n> 💡 **Accept the optional `find-skills` helper when prompted.** During `npx skills add` the installer will ask whether to install [`find-skills`](https://github.com/skills-sh/find-skills) — say **yes**. It's a tiny meta-skill that lets agents auto-discover the right DocumentDB skill for a task (e.g. *\"how do I create a BM25 index?\"* → auto-loads `documentdb-full-text-search`) instead of relying on you to invoke skills by name. It's especially useful here because the kit ships 17 skills, more than agents reliably route on their own from `AGENTS.md` alone. If you skipped it, re-run `npx skills add find-skills` to add it later.\n\nFor uninstall, troubleshooting, manual install, updating, and per-agent plugin marketplaces, see [`docs/installation/`](docs/installation/README.md).\n\n## Configuration\n\nThe MCP server is administrator-controlled: tools never accept runtime connection strings. Set `DOCUMENTDB_CONNECTION_PROFILES` in your shell before launching the agent.\n\n### Microsoft Entra / OIDC (recommended)\n\n```bash\nexport DOCUMENTDB_CONNECTION_PROFILES='{\"sandbox\":{\"authMode\":\"entra\",\"endpoint\":\"<cluster>.mongocluster.cosmos.azure.com\",\"tokenScope\":\"https://ossrdbms-aad.database.windows.net/.default\",\"allowedHosts\":[\"*.mongocluster.cosmos.azure.com\"]}}'\n\naz login --tenant <tenant-id>\n```\n\nIn Azure hosting, use managed identity or workload identity and grant that identity access to the backend database. The server uses `DefaultAzureCredential`, so the same profile shape works for local Azure CLI login and managed deployments.\n\n### Local / sandbox SCRAM\n\n```bash\nexport DOCUMENTDB_CONNECTION_PROFILES='{\"local\":{\"uriEnv\":\"DOCUMENTDB_LOCAL_URI\"}}'\nexport DOCUMENTDB_LOCAL_URI='mongodb://localhost:27017'\n```\n\n### Tool capability gates\n\nRead tools are enabled by default. Higher-impact tools are opt-in:\n\n```bash\nexport ENABLE_WRITE_TOOLS=true        # insert / update / delete / find_and_modify\nexport ENABLE_MANAGEMENT_TOOLS=true   # drop_database, drop_collection, create_index, ...\n```\n\nOr edit [`mcp.json`](mcp.json) directly. See the [DocumentDB MCP Server docs](https://github.com/microsoft/documentdb-mcp) for the full configuration surface.\n\n## Compatibility\n\nWorks with Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and other Agent Skills–compatible tools.\n\n## License\n\nMIT\n",
  "bytes": 8336,
  "sha": "9bd3eccb433dff805fcf1aaadbf67bf56fe3538e7318ce37f584ea7a1248c779",
  "repo_slug": "azure/documentdb-agent-kit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_azure_documentdb_agent_kit_07a66096/readme"
}