mongodb-claude-setup/README.md

Intelligent MongoDB development ecosystem for Claude Code with modular agent installation

# MongoDB Claude Setup

🍃 **Intelligent MongoDB Development Ecosystem for Claude Code**

A comprehensive, modular installation system that sets up MongoDB-specialized AI agents, commands, and MCP integrations for Claude Code, enabling developers to build faster with MongoDB and MongoDB Atlas.

## 🚀 Quick Start

```bash
# Install the full MongoDB development ecosystem
npx mongodb-claude-setup --preset developer

# Or install specific components
npx mongodb-claude-setup --agent mongodb-schema-architect

# Interactive installation
npx mongodb-claude-setup --interactive
```

## 🎯 What You Get

### 🤖 Intelligent Agents

- **MongoDB Schema Architect**: Interactive schema design with embedding vs referencing questionnaire
- **MongoDB Relationship Designer**: Specialized in 1:1, 1:many, many:many relationship modeling
- **MongoDB Implementation Guide**: Framework integration and driver configuration specialist
- **MongoDB Performance Tuner**: Query optimization and index recommendations
- **MongoDB Security Expert**: Security auditing and compliance patterns

### ⚡ Smart Commands

- `/mongo-schema-design`: Interactive schema design workflow
- `/mongo-query-optimize`: Query optimization helper
- `/mongo-deploy-stack`: Deployment configuration generator
- `/mongo-security-audit`: Security checklist generator

### 🔌 MCP Integration

- **Context7 MCP**: Access to MongoDB documentation and best practices
- **Official MongoDB MCP**: Direct database connectivity and operations

## 📦 Installation Options

### Presets

```bash
# Minimal - Just schema design
npx mongodb-claude-setup --preset minimal

# Design - Schema design and relationship modeling
npx mongodb-claude-setup --preset design

# Developer - Full development stack
npx mongodb-claude-setup --preset developer

# DevOps - Performance and security focused
npx mongodb-claude-setup --preset devops

# Everything
npx mongodb-claude-setup --preset full
```

### Categories

```bash
# Install by category
npx mongodb-claude-setup --category design
npx mongodb-claude-setup --category performance
npx mongodb-claude-setup --category security
```

### Individual Components

```bash
# Install specific agents
npx mongodb-claude-setup --agent mongodb-schema-architect,mongodb-performance-tuner

# Install specific commands
npx mongodb-claude-setup --command mongo-schema-design,mongo-query-optimize

# Install only MCP servers
npx mongodb-claude-setup --mcp-only
```

## 🎨 Schema Design Intelligence

The **MongoDB Schema Architect** agent includes a built-in questionnaire system based on MongoDB best practices:

### Embedding vs Referencing Decision Framework

**Questions for Embedding (+1 point each):**
1. **Simplicity**: Would keeping data together lead to simpler code?
2. **Go together**: Do pieces have "has-a" or "contains" relationships?
3. **Query atomicity**: Is data queried together?
4. **Update complexity**: Is data updated together?
5. **Archival**: Should data be archived together?

**Questions for Referencing (+1 point each):**
1. **Cardinality**: High cardinality on "many" side?
2. **Data duplication**: Would duplication be complex to manage?
3. **Document size**: Would combined size be too large?
4. **Document growth**: Would embedded data grow unbounded?
5. **Workload**: Are pieces written at different times?
6. **Individuality**: Can child data exist independently?

### Design Patterns

- **Approximation Pattern**: For expensive calculations where precision isn't critical
- **Attribute Pattern**: For documents with many similar fields
- **Bucket Pattern**: For time-series data and IoT applications

## 🛠️ Usage Examples

### Interactive Schema Design

```
You: "Help me design a schema for my e-commerce app"

MongoDB Schema Architect:
1. Analyzes your project type and entities
2. Asks systematic embedding vs referencing questions
3. Calculates scores and provides recommendations
4. Generates sample documents
5. Offers to create test data with @ngneat/falso
```

### Sample Data Generation

The agents automatically generate realistic test data:

```javascript
const falso = require('@ngneat/falso');
const data = [];
for (let i = 0; i < 1000; i++) {
  data.push({
    title: falso.randMovie(),
    price: falso.randNumber({min: 10, max: 1000}),
    category: falso.randProductCategory(),
    // ... more realistic data
  });
}
use('ecommerce_db');
db.products.insertMany(data);
```

## 📋 Management Commands

### List Available Components

```bash
# List all components
npx mongodb-claude-setup list

# List only agents
npx mongodb-claude-setup list --agents

# List only commands
npx mongodb-claude-setup list --commands

# List categories
npx mongodb-claude-setup list --categories
```

### Update Components

```bash
# Update all components
npx mongodb-claude-setup update --all

# Update specific agents
npx mongodb-claude-setup update --agent mongodb-schema-architect
```

### Uninstall Components

```bash
# Uninstall all MongoDB components
npx mongodb-claude-setup uninstall --all

# Uninstall specific agents
npx mongodb-claude-setup uninstall --agent mongodb-performance-tuner
```

## 🔧 Advanced Options

### Dry Run

See what would be installed without making changes:

```bash
npx mongodb-claude-setup --preset developer --dry-run
```

### Interactive Mode

Get guided through the installation process:

```bash
npx mongodb-claude-setup --interactive
```

## 🏗️ Architecture

### Modular Design

- **Agents**: Specialized AI assistants with domain expertise
- **Commands**: Quick-action slash commands
- **MCPs**: External service integrations
- **Settings**: Configuration management
- **Hooks**: Automation triggers

### MCP Integration

The system automatically configures:

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server", "--readOnly"]
    }
  }
}
```

## 🔒 Security & Best Practices

- **Read-only by default**: MongoDB MCP starts in read-only mode
- **Proper driver configuration**: Includes `appName` for tracking
- **Security-first agents**: Built-in security auditing capabilities
- **Compliance patterns**: GDPR, HIPAA, PCI DSS guidance

## 🤝 Contributing

We welcome contributions! Areas where you can help:

- **New Agents**: Create specialized MongoDB agents
- **Design Patterns**: Add more MongoDB design patterns
- **Framework Integration**: Support for additional frameworks
- **Documentation**: Improve examples and guides

## 📚 Related Projects

- [Claude Code Templates](https://github.com/davila7/claude-code-templates) - The ecosystem this extends
- [Official MongoDB MCP](https://github.com/mongodb-js/mongodb-mcp-server) - Core database connectivity
- [Context7 MCP](https://github.com/upstash/context7-mcp) - Documentation and best practices

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- MongoDB team for the official MCP server
- Upstash team for Context7 MCP
- Claude Code Templates community
- MongoDB Developer Relations team for schema design patterns

---

**⭐ Found this useful? Give us a star to support the project!**

**🚀 Ready to build faster with MongoDB? Install now:**

```bash
npx mongodb-claude-setup --preset developer