MongoDB Doctor

MongoDB codebase health scanner — 0–100 score

One command scans your MongoDB codebase for query anti-patterns, schema issues, security vulnerabilities, and transaction correctness. Outputs an actionable 0–100 health score.

Install

npx mongodb-doctor@latest .

Use --verbose to see affected files and line numbers:

npx mongodb-doctor@latest . --verbose

Options

Usage: mongodb-doctor [directory] [options]

Options:
  -v, --version       display the version number
  --uri <string>      MongoDB connection string for live DB checks
  --no-code           skip code analysis
  --no-db             skip database analysis
  --verbose           show file details per rule
  --score             output only the score (for CI)
  -y, --yes           skip interactive prompts
  --diff [base]       scan only files changed vs base branch
  --offline           skip telemetry
  -h, --help          display help

Score Thresholds

| Score | Label | Meaning | |-------|-------|---------| | 75–100 | Great | Follows MongoDB best practices | | 50–74 | Needs Work | Notable issues to address | | 0–49 | Critical | Critical anti-patterns detected |

What It Checks (25 rules)

Code analysis (static AST, always runs):

• Missing projections on find/findOne
• N+1 query patterns (query inside loop)
• $where usage (injection risk)
• Hardcoded connection strings
• Unbounded $push (16MB document limit risk)
• Missing transaction session propagation
• Missing TransientTransactionError retry
• Missing UnknownTransactionCommitResult handling
• Unanchored regex (collection scan)
• $ne/$nin anti-index operators
• Batch operation anti-patterns
• AI/Vector Search rules (when $vectorSearch detected)

Live DB analysis (optional, with --uri):

• Collections with no indexes (COLLSCAN risk)
• Unused indexes (write overhead)
• Unbounded arrays in documents
• Bloated documents (>1MB avg)
• Schema drift (inconsistent field structure)
• Missing JSON Schema validation

Config analysis (always runs):

• Outdated MongoDB driver (< v6)
• Hardcoded credentials in .env files

Install for Your Coding Agent

Teach your coding agent MongoDB best practices:

# Claude Code
/plugin marketplace add romiluz13/mongodb-agent-skills

# Any agent (via skills CLI)
npx skills add romiluz13/mongodb-agent-skills --skill mongodb-doctor -a claude-code

Node.js API

import { scan } from 'mongodb-doctor/api';

const result = await scan('./path/to/project');
console.log(result.score);       // { score: 72, label: 'Needs Work' }
console.log(result.diagnostics); // Array of Diagnostic objects

License

MIT