documentdb-agent-kit

Guide users through installing and configuring the DocumentDB MCP server for Azure DocumentDB. Use this skill when a user wants to wire the DocumentDB MCP server into an agentic client (Claude Code, Claude Desktop, Cursor, Copilot CLI, Gemini CLI, VS Code) and define a `CONNECTION_PROFILES` entry, or when they hit MCP connection / auth / profile errors.

Optimize MongoDB client connection configuration (pools, timeouts, patterns) for Azure DocumentDB. Use this skill when working on functions that instantiate or configure a MongoDB client (e.g., calling `connect()`), configuring connection pools, troubleshooting connection errors (ECONNREFUSED, timeouts, pool exhaustion), optimizing connection-related performance issues. Includes scenarios like building serverless functions, creating API endpoints, optimizing high-traffic applications, or debugging connection failures.

Full-text search best practices for Azure DocumentDB using the `createSearchIndexes` command and `$search` aggregation stage — BM25 keyword scoring, fuzzy search (`maxEdits`), phrase search with `slop`, custom analyzers (keyword + lowerCase + asciiFolding + edgeGram) for prefix / ID matching, `pathHierarchy` tokenizer for hierarchical IDs, multi-field search indexes, and hybrid (BM25 + vector) retrieval via Reciprocal Rank Fusion. Use when building search experiences, adding typo tolerance, matching phrases or prefixes on IDs / SKUs / part numbers, or combining lexical and semantic retrieval on the same collection.

Vector search best practices for Azure DocumentDB using `cosmosSearch` — choosing between DiskANN / HNSW / IVF, creating indexes, tuning `lBuild` / `lSearch` / `maxDegree`, Product Quantization (up to 16,000 dims), half-precision (fp16) indexing, and normalizing embeddings for cosine similarity. Use when building RAG / semantic-search applications, creating a vector index, tuning recall/latency, or reducing vector-index memory footprint.

Index-type selection and shape guidance for Azure DocumentDB — when to use single-field, compound (ESR), multikey, wildcard, hashed, 2dsphere, TTL, and vector indexes; query-pattern → index-shape cookbook; per-collection index budget; DocumentDB-specific preference for `textSearch` over community `$text`. Use when designing or reviewing indexes, choosing an index type for a query pattern, or deciding whether an additional index is worth the write cost.

Generate read-only DocumentDB/MongoDB queries (find) or aggregation pipelines using natural language, with collection schema context and sample documents. Use this skill whenever the user asks to write, create, or generate queries for Azure DocumentDB, wants to filter/query/aggregate data, asks "how do I query...", needs help with query syntax, or discusses finding/filtering/grouping documents. Also use for translating SQL-like requests to MongoDB syntax. Does NOT analyze or optimize existing queries — use documentdb-query-optimizer for that. Requires DocumentDB MCP server.

Horizontal sharding (partitioning) for Azure DocumentDB collections — when to shard vs stay single-shard, how to pick a shard key for read-heavy vs write-heavy workloads, the logical/physical shard mental model, scaling out vs scaling up, hot-partition diagnosis, and the `sh.shardCollection` / `sh.reshardCollection` commands. Use when deciding whether to shard a collection, choosing or changing a shard key, sizing a cluster, or troubleshooting uneven storage / throughput across physical shards.

Storage configuration guidance for Azure DocumentDB — when and how to use Premium SSD v2 high-performance storage, IOPS/bandwidth caps that are gated by compute tier (not disk size), Premium SSD v2 limitations (no CMK, migration paths, disk-hydration sequencing), and storage capacity change limits. Use when picking a storage type at cluster creation, sizing for I/O-intensive workloads, migrating from Premium SSD to Premium SSD v2, or sequencing compute/storage/HA changes on a Premium SSD v2 cluster.

High availability, business-continuity, and disaster-recovery best practices for Azure DocumentDB — enabling in-region HA with availability zones (99.99% SLA), adding active-passive cross-region replica clusters (99.995% SLA), and understanding automatic backup retention. Use when designing production topology, planning failover, provisioning DR, picking regions, or reviewing cluster architecture.

Deploy an Azure DocumentDB cluster (`Microsoft.DocumentDB/mongoClusters`) end-to-end — Bicep (primary), Azure CLI one-shot, Terraform, or portal. Covers resource-group creation, cluster parameters (tier, storage, server version, sharding, HA), firewall rule configuration, retrieving the connection string, and teardown. Use when the user asks to provision, create, deploy, or spin up an Azure DocumentDB cluster, or wants infrastructure-as-code for one.

Data modeling patterns for Azure DocumentDB — embed vs reference, 16 MB document limit, denormalization for read-heavy workloads, schema versioning. Use when designing new schemas, reviewing existing data models, migrating from SQL, deciding between embedding and referencing, modeling one-to-one / one-to-many / many-to-many relationships, or troubleshooting document-size and query-performance problems that stem from the data model.

MongoDB driver and SDK best practices for Azure DocumentDB — singleton `MongoClient`, connection reuse, connection-pool fundamentals. Use when writing code that instantiates a MongoDB client, reviewing driver initialization, or diagnosing connection-related bugs. For full connection-pool tuning (serverless vs OLTP vs OLAP, timeouts, retries), see the `documentdb-connection` skill.

Best practices for running Azure DocumentDB locally for development — choosing between the Gateway Docker image and the psql-only image, docker-compose setup, connection config (port 10260, TLS, SCRAM-SHA-256), env-driven configuration, sample-data management (`SKIP_INIT_DATA` / `INIT_DATA_PATH`), port bindings, and dev/prod parity via versioned seed and schema scripts. Use when setting up a new local dev environment, writing sample apps, building integration tests, or diagnosing local connection problems.

Monitoring and diagnostics best practices for Azure DocumentDB — enabling diagnostic settings and slow-query logs, analyzing them in Log Analytics, and alerting on CPU / memory / IOPS / storage / connection saturation per cluster tier. Use when setting up observability on a new cluster, investigating production incidents, or tuning alert thresholds.

Query and aggregation-pipeline optimization rules for Azure DocumentDB — using `explain("executionStats")` to verify index usage and avoid `COLLSCAN`. Use when reviewing a specific query, diagnosing a slow query, or validating that an index is actually being used. For full index-design workflow, see the `documentdb-query-optimizer` skill.

Help with DocumentDB/MongoDB query optimization and indexing for Azure DocumentDB. Use only when the user asks for optimization or performance: "How do I optimize this query?", "How do I index this?", "Why is this query slow?", "Can you fix my slow queries?", etc. Do not invoke for general query writing unless user asks for performance or index help. Prefer indexing as optimization strategy. Use DocumentDB MCP when available.

Security best practices for Azure DocumentDB — TLS enforcement, Private Endpoint / firewall configuration, Microsoft Entra ID + RBAC for authentication, and customer-managed keys (CMK) for encryption at rest. Use when reviewing production security posture, configuring networking, setting up authentication / authorization, or preparing for compliance audits.