• Designing a new MongoDB schema from scratch
• Migrating from SQL/relational databases to MongoDB
• Reviewing existing data models for performance issues
• Troubleshooting slow queries or growing document sizes
• Deciding between embedding and referencing
• Modeling relationships (one-to-one, one-to-many, many-to-many)
• Implementing tree/hierarchical structures
• Seeing Atlas Schema Suggestions or Performance Advisor warnings
• Hitting the 16MB document limit
• Adding schema validation to existing collections

• antipattern-unbounded-arrays

  - Never allow arrays to grow without limit

• antipattern-bloated-documents

  - Keep documents under 16KB for working set

• antipattern-massive-arrays

  - Arrays over 1000 elements hurt performance

• antipattern-unnecessary-collections

  - Fewer collections, more embedding

• antipattern-excessive-lookups

  - Reduce $lookup by denormalizing

• antipattern-schema-drift

  - Enforce consistent structure across documents

• antipattern-unnecessary-indexes

  - Audit and remove unused or redundant indexes

• fundamental-embed-vs-reference

  - Decision framework for relationships

• fundamental-data-together

  - Data accessed together stored together

• fundamental-document-model

  - Embrace documents, avoid SQL patterns

• fundamental-schema-validation

  - Enforce structure with JSON Schema

• fundamental-16mb-awareness

  - Design around BSON document limit

• relationship-one-to-one

  - Embed for simplicity, reference for independence

• relationship-one-to-few

  - Embed bounded arrays (addresses, phone numbers)

• relationship-one-to-many

  - Reference for large/unbounded relationships

• relationship-one-to-squillions

  - Reference massive child sets, store summaries

• relationship-many-to-many

  - Two-way referencing for bidirectional access

• relationship-tree-structures

  - Parent/child/materialized path patterns

• pattern-archive

  - Move historical data to separate storage for performance

• pattern-attribute

  - Collapse many optional fields into key-value attributes

• pattern-bucket

  - Group time-series or IoT data into buckets

• pattern-time-series-collections

  - Use native time series collections when available

• pattern-extended-reference

  - Cache frequently-accessed related data

• pattern-subset

  - Store hot data in main doc, cold data elsewhere

• pattern-computed

  - Pre-calculate expensive aggregations

• pattern-outlier

  - Handle documents with exceptional array sizes

• pattern-polymorphic

  - Store heterogeneous documents with a type discriminator

• pattern-schema-versioning

  - Evolve schemas safely with version fields

• validation-json-schema

  - Validate data types and structure at database level

• validation-action-levels

  - Choose warn vs error mode for validation

• validation-rollout-strategy

  - Introduce validation safely in production

"Data that is accessed together should be stored together."

rules/antipattern-unbounded-arrays.md
rules/relationship-one-to-many.md
rules/_sections.md

• Brief explanation of why it matters
• Incorrect code example with explanation
• Correct code example with explanation
• "When NOT to use" exceptions
• Performance impact and metrics
• Verification diagnostics

1. A recommendation based on best practices
2. A verification checklist of things that should be confirmed
3. Commands to verify so you can check before implementing
4. MCP integration for automatic verification when connected

• Fixing an "unbounded array" that's actually small and bounded
• Restructuring a schema that works well for your access patterns
• Adding validation when documents already conform to the schema

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net/mydb"
      }
    }
  }
}

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb://localhost:27017/mydb"
      }
    }
  }
}

--readOnly

• Infer schema via

  mcp__mongodb__collection-schema

• Measure document/array sizes via

  mcp__mongodb__aggregate

• Check collection statistics via

  mcp__mongodb__db-stats

find

aggregate

collection-schema

db-stats

count

update-many

insert-many

create-collection

delete-many

drop-collection

drop-database

1. I'll explain what I want to do and why
2. I'll show you the exact command
3. I'll wait for your approval before executing
4. If you say "go ahead" or "yes", only then will I run it

1. Run the verification commands I provide
2. Share the output with me
3. I'll adjust my recommendation based on your actual data