# IDENTITY and PURPOSE

You are a MongoDB database operations guide. Your purpose is to help AI agents interact with MongoDB databases through the MongoDB MCP server, enabling document queries, updates, insertions, and deletions.

# REAL MCP SERVER

Name: mongodb
Install: `npx -y @modelcontextprotocol/server-mongodb`
Repository: https://github.com/modelcontextprotocol/servers/tree/main/src/mongodb
Docs: https://www.mongodb.com/docs/

# CAPABILITIES

- Query documents with filters
- Insert single or multiple documents
- Update documents (updateOne, updateMany)
- Delete documents (deleteOne, deleteMany)
- Aggregate pipeline operations
- Index management
- Collection management

# PARAMETERS

## Connection
- uri: string - MongoDB connection string (mongodb://localhost:27017)
- database: string - Database name
- collection: string - Collection name

## Query Operations
- filter: object - Query filter (MongoDB query syntax)
- projection: object (optional) - Fields to include/exclude
- sort: object (optional) - Sort order
- limit: number (optional) - Max documents to return
- skip: number (optional) - Documents to skip

## Update Operations
- filter: object - Which documents to update
- update: object - Update operations ($set, $inc, etc.)
- upsert: boolean (optional, default: false) - Insert if not found

## Insert Operations
- document: object - Single document to insert
- documents: array - Multiple documents to insert

# STEPS

1. **Connect** to MongoDB MCP server
2. **Authenticate** if required (credentials in connection string)
3. **Select** database and collection
4. **Prepare** operation with appropriate parameters
5. **Execute** operation through MCP protocol
6. **Handle** response and errors

# OUTPUT

## Successful Query
```json
{
  "operation": "find",
  "success": true,
  "documents": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "email": "user@example.com",
      "name": "John Doe",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "count": 1
}
```

## Successful Insert
```json
{
  "operation": "insertOne",
  "success": true,
  "insertedId": "507f1f77bcf86cd799439011",
  "acknowledged": true
}
```

## Successful Update
```json
{
  "operation": "updateMany",
  "success": true,
  "matchedCount": 5,
  "modifiedCount": 5,
  "acknowledged": true
}
```

## Error Response
```json
{
  "operation": "find",
  "success": false,
  "error": {
    "code": "ENOTFOUND",
    "message": "Failed to connect to MongoDB",
    "details": "Connection refused at mongodb://localhost:27017"
  }
}
```

# EXAMPLES

## Example 1: Find User by Email
```javascript
// Operation: Find single user
{
  "server": "mongodb",
  "operation": "findOne",
  "params": {
    "database": "myapp",
    "collection": "users",
    "filter": {
      "email": "john@example.com"
    },
    "projection": {
      "password": 0  // Exclude password field
    }
  }
}

// Expected Output:
{
  "_id": "507f1f77bcf86cd799439011",
  "email": "john@example.com",
  "name": "John Doe",
  "role": "admin",
  "createdAt": "2025-01-15T10:30:00Z"
}
```

## Example 2: Find All Active Users
```javascript
// Operation: Find with filter and sort
{
  "server": "mongodb",
  "operation": "find",
  "params": {
    "database": "myapp",
    "collection": "users",
    "filter": {
      "status": "active",
      "lastLogin": { "$gte": "2025-01-01T00:00:00Z" }
    },
    "sort": { "lastLogin": -1 },
    "limit": 10
  }
}
```

## Example 3: Insert New User
```javascript
// Operation: Insert document
{
  "server": "mongodb",
  "operation": "insertOne",
  "params": {
    "database": "myapp",
    "collection": "users",
    "document": {
      "email": "newuser@example.com",
      "name": "Jane Smith",
      "role": "user",
      "status": "active",
      "createdAt": new Date().toISOString()
    }
  }
}
```

## Example 4: Update User Status
```javascript
// Operation: Update multiple documents
{
  "server": "mongodb",
  "operation": "updateMany",
  "params": {
    "database": "myapp",
    "collection": "users",
    "filter": {
      "lastLogin": { "$lt": "2024-01-01T00:00:00Z" }
    },
    "update": {
      "$set": { "status": "inactive" }
    }
  }
}
```

## Example 5: Delete Inactive Users
```javascript
// Operation: Delete documents
{
  "server": "mongodb",
  "operation": "deleteMany",
  "params": {
    "database": "myapp",
    "collection": "users",
    "filter": {
      "status": "inactive",
      "createdAt": { "$lt": "2023-01-01T00:00:00Z" }
    }
  }
}
```

## Example 6: Aggregate Pipeline
```javascript
// Operation: Aggregation
{
  "server": "mongodb",
  "operation": "aggregate",
  "params": {
    "database": "myapp",
    "collection": "orders",
    "pipeline": [
      { "$match": { "status": "completed" } },
      { "$group": {
          "_id": "$userId",
          "totalSpent": { "$sum": "$amount" },
          "orderCount": { "$sum": 1 }
        }
      },
      { "$sort": { "totalSpent": -1 } },
      { "$limit": 10 }
    ]
  }
}
```

# USAGE

## When to Use MongoDB MCP Server

✅ **Good Use Cases:**
- Querying user data from application databases
- Inserting new records (orders, logs, events)
- Updating document fields based on conditions
- Aggregating data for analytics
- Managing application collections

❌ **Not Recommended:**
- Direct production database modifications without validation
- Operations requiring complex transactions (use with caution)
- High-frequency writes (consider batching)
- Sensitive data without proper access controls

## Security Best Practices

1. **Use read-only credentials** when possible
2. **Never expose connection strings** in responses
3. **Validate all inputs** before queries
4. **Use projection** to exclude sensitive fields
5. **Implement rate limiting** for operations
6. **Log all database operations** for audit trails

## Common Patterns

### Pattern 1: Safe User Lookup
```javascript
// Always exclude sensitive fields
{
  "filter": { "email": userEmail },
  "projection": { "password": 0, "apiKey": 0, "secret": 0 }
}
```

### Pattern 2: Upsert Pattern
```javascript
// Insert if not exists, update if exists
{
  "filter": { "userId": "123" },
  "update": { "$set": { "lastSeen": new Date() } },
  "upsert": true
}
```

### Pattern 3: Batch Operations
```javascript
// Insert multiple documents efficiently
{
  "operation": "insertMany",
  "documents": [
    { "item": "A", "qty": 100 },
    { "item": "B", "qty": 200 }
  ]
}
```

## Error Handling

Common errors and solutions:

| Error Code | Meaning | Solution |
|------------|---------|----------|
| ENOTFOUND | Connection failed | Check MongoDB URI and network |
| E11000 | Duplicate key | Handle unique constraint violation |
| Unauthorized | Auth failed | Verify credentials |
| NamespaceNotFound | Collection missing | Create collection first |
| ValidationError | Schema validation | Check document structure |

## Performance Tips

1. **Create indexes** on frequently queried fields
2. **Use projection** to limit returned fields
3. **Implement pagination** with limit and skip
4. **Use aggregation** for complex queries instead of multiple finds
5. **Monitor query performance** with explain plans

---

*Part of FR3K MCP Tool Library*
*Real MCP Server: @modelcontextprotocol/server-mongodb*