Mongtap

🚀 MongTap - MongoDB MCP Server for LLMs

MongTap is a Model Context Protocol (MCP) server that offers MongoDB-compatible database functionality through statistical modeling. It enables LLMs like Claude to create, query, and manage databases using natural language, eliminating the need for actual data storage.

Demo video on YouTube:

By SmallMinds LLC Co

Repository: github.com/smallmindsco/MongTap
Website: smallminds.co
Contact: andrew@smallminds.co

✨ Features

• 🚀 MongoDB Wire Protocol: Fully compatible with MongoDB drivers and tools.
• 🧠 Statistical Modeling: Employs DataFlood technology to generate realistic data on-the-fly.
• 🔧 MCP Integration: Works seamlessly with Claude Desktop and other MCP-compatible LLMs.
• 📊 Natural Language: Allows training models from descriptions or sample data.
• ⚡ High Performance: Capable of generating 20,000+ documents per second.
• 🎯 Zero Storage: Data is generated statistically, not stored.

📚 Documentation

• Generation Control Parameters: Control document generation with $seed and $entropy.
• MCPB Installation: Guide for MCPB bundle installation.

📦 Installation

Prerequisites

• Node.js 20+
• Claude Desktop (for MCP integration)
• No MongoDB installation required!

Quick Start

1. Clone the repository:

git clone https://github.com/smallmindsco/MongTap.git
cd MongTap

2. Install dependencies (minimal):

npm install

3. Test the installation:

node src/mcp/index.js

4. Start MongoDB server (optional):

node start-mongodb-server.js

💻 Claude Desktop Configuration

To use MongTap with Claude Desktop, you need to configure it as an MCP server.

1. Locate Claude Desktop Configuration

Find your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add MongTap to Configuration

Edit the configuration file and add MongTap to the mcpServers section:

{
  "mcpServers": {
    "mongtap": {
      "command": "node",
      "args": [
        "/absolute/path/to/MongTap/src/mcp/index.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Important: Replace /absolute/path/to/MongTap with the actual path to your MongTap installation.

3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop for the changes to take effect.

💻 Using MongTap in Claude Desktop

Once configured, MongTap provides powerful tools for database operations and data generation.

Quick Reference

MCP Tools Reference

1. generateDataModel

Description: Create a statistical model from sample documents or a text description for data generation.

Parameters:

• name (required): Name for the model
• description (optional): Natural language description of the data structure
• samples (optional): Array of sample documents to train the model

Example:

generateDataModel({
  name: "users",
  description: "User profiles with name, email, age, and signup date"
})
// OR with samples
generateDataModel({
  name: "products",
  samples: [
    { name: "Laptop", price: 999, category: "Electronics" },
    { name: "Desk", price: 299, category: "Furniture" }
  ]
})

2. startMongoServer

Description: Start a local MongoDB-compatible server that generates data from statistical models.

Parameters:

• port (optional): Port to listen on (0 for auto-assign, default: 27017)
• database (optional): Default database name (default: "mcp")

Example:

startMongoServer({ port: 27017, database: "myapp" })
// Returns: { port: 27017, status: "running" }

3. stopMongoServer

Description: Stop a running MongoDB-compatible server instance by port number.

Parameters:

• port (required): Port of the server to stop

Example:

stopMongoServer({ port: 27017 })
// Returns: { success: true, message: "Server stopped" }

4. listActiveServers

Description: Get a list of all currently running MongoDB-compatible server instances.

Parameters: None

Example:

listActiveServers()
// Returns: { count: 2, servers: [
//   { port: 27017, database: "test", status: "running", uptime: 3600 },
//   { port: 27018, database: "dev", status: "running", uptime: 1800 }
// ]}

5. queryModel

Description: Generate documents from a statistical model with optional query filters and generation control.

Parameters:

• model (required): Name of the model to query
• query (optional): MongoDB-style query with special parameters:
  • $seed: Number for reproducible generation
  • $entropy: Number 0 - 1 to control randomness level
• count (optional): Number of documents to generate (default: 10)

Example:

queryModel({
  model: "users",
  query: { age: { $gte: 18 }, $seed: 42, $entropy: 0.3 },
  count: 5
})
// Returns 5 consistently generated adult users with low randomness

6. trainModel

Description: Update an existing statistical model with additional sample documents to improve generation quality.

Parameters:

• model (required): Name of the model to train
• documents (required): Array of documents to train with

Example:

trainModel({
  model: "products",
  documents: [
    { name: "Mouse", price: 29, category: "Electronics" },
    { name: "Chair", price: 199, category: "Furniture" }
  ]
})
// Returns: { success: true, samplesAdded: 2, totalSamples: 4 }

7. listModels

Description: Get a list of all available statistical models stored locally.

Parameters: None

Example:

listModels()
// Returns: ["users", "products", "orders", "inventory"]

8. getModelInfo

Description: Retrieve detailed schema and statistics for a specific statistical model.

Parameters:

• model (required): Name of the model

Example:

getModelInfo({ model: "users" })
// Returns: {
//   name: "users",
//   schema: { type: "object", properties: { ... } },
//   sampleCount: 100,
//   lastUpdated: "2025-01-15T10:30:00Z",
//   fields: ["name", "email", "age", "signupDate"]
// }

MCP Prompts

MongTap includes pre-built prompts for common database scenarios:

1. create_ecommerce_db

Description: Create a complete e-commerce database with products, customers, and orders.

Usage: Ask Claude to "use the create_ecommerce_db prompt" to instantly set up a full e-commerce database structure.

2. create_user_profile

Description: Create a user profile model with authentication and preferences.

Usage: Perfect for quickly setting up user management systems.

3. analyze_model

Description: Analyze an existing model and provide insights about its structure.

Usage: Understand the patterns and distributions in your statistical models.

4. generation_control

Description: Learn about using $seed and $entropy parameters for controlled generation.

Usage: Get detailed information about reproducible and controlled data generation.

MCP Resources

MongTap provides read-only resources for monitoring:

1. models://list

Description: List of all trained DataFlood models
Type: application/json
Returns: Array of model names and metadata

2. servers://status

Description: Status of all MongoDB servers
Type: application/json
Returns: Server ports, databases, and connection counts

3. models://{name}/schema

Description: Get the JSON schema for a specific model
Type: application/json
Returns: Complete JSON Schema definition

4. models://{name}/sample

Description: Get sample data from a model
Type: application/json
Returns: Array of sample documents

5. docs://generation-control

Description: Documentation for $seed and $entropy query parameters
Type: text/markdown
Returns: Detailed usage guide

Example Conversations with Claude

Creating a Data Model from Description

You: Create a data model for a user profile with name, email, age, and registration date.

Claude: I'll create a user profile model for you using MongTap.

[Uses generateDataModel tool]

I've created a user profile model with the following structure:
- name (string)
- email (string, email format)
- age (integer, 0 - 120)
- registrationDate (string, date - time format)

The model is now ready to generate realistic user data.

Starting a MongoDB Server

You: Start a MongoDB server for my application on port 27017.

Claude: I'll start a MongoDB server for you.

[Uses startMongoServer tool]

MongoDB server started successfully:
- Port: 27017
- Database: test
- Connection string: mongodb://localhost:27017/test

You can now connect to this server using any MongoDB client or driver.

The server supports advanced generation control through $seed and $entropy parameters in queries.

Generating Sample Data

You: Generate 100 user profiles from the model we created.

Claude: I'll generate 100 user profiles for you.

[Uses queryModel tool]

Generated 100 user profiles. Here's a sample:
1. { name: "John Smith", email: "john.smith@example.com", age: 28, registrationDate: "2024-01-15T10:30:00Z" }
2. { name: "Jane Doe", email: "jane.doe@example.com", age: 34, registrationDate: "2024-02-20T14:45:00Z" }
...

All documents follow the statistical patterns of your model.

Training from Sample Data

You: Here are some product samples. Train a model from them:
- { name: "Widget", price: 19.99, category: "tools", stock: 100 }
- { name: "Gadget", price: 29.99, category: "electronics", stock: 50 }
- { name: "Gizmo", price: 39.99, category: "tools", stock: 75 }

Claude: I'll train a product model from your samples.

[Uses generateDataModel tool with samples]

Model trained successfully! The model learned:
- name: product names (string patterns)
- price: range 19.99 - 39.99 (number distribution)
- category: "tools" or "electronics" (enum)
- stock: range 50 - 100 (integer distribution)

The model can now generate similar products with realistic variations.

💻 Connecting with MongoDB Clients

MongTap servers are fully compatible with MongoDB clients. Once you've started a server through Claude:

Using MongoDB Shell (mongosh)

mongosh "mongodb://localhost:27017/test"

Using Node.js MongoDB Driver

const { MongoClient } = require('mongodb');

async function connect() {
    const client = new MongoClient('mongodb://localhost:27017');
    await client.connect();
    
    const db = client.db('test');
    const collection = db.collection('users');
    
    // Insert triggers model training
    await collection.insertMany([
        { name: 'Alice', age: 30 },
        { name: 'Bob', age: 25 }
    ]);
    
    // Find generates data from the model
    const users = await collection.find({}).toArray();
    console.log(users); // Statistically generated users
    
    // Use generation control parameters
    const consistentData = await collection.find({
        $seed: 12345,  // Consistent results
        $entropy: 0.5  // Moderate randomness
    }).toArray();
    
    await client.close();
}

Using Python (pymongo)

from pymongo import MongoClient

client = MongoClient('mongodb://localhost:27017/')
db = client['test']
collection = db['users']

# Insert trains the model
collection.insert_many([
    {'name': 'Alice', 'age': 30},
    {'name': 'Bob', 'age': 25}
])

# Find generates from the model
for user in collection.find():
    print(user)  # Statistically generated users
    
# Use generation control
for user in collection.find({'$seed': 12345, '$entropy': 0.3}):
    print(user)  # Consistent, low - entropy generation

💻 Advanced Usage

Multiple Server Instances

You can run multiple MongoDB servers simultaneously:

You: Start three MongoDB servers for development, testing, and staging environments.

Claude: I'll start three separate MongoDB servers for you.

[Uses startMongoServer multiple times]

Started 3 MongoDB servers:
1. Development - Port: 27017, Database: dev
2. Testing - Port: 27018, Database: test  
3. Staging - Port: 27019, Database: staging

Each server maintains its own models and can be accessed independently.

Model Persistence

Models are automatically saved and can be reused across sessions:

You: List all available models.

Claude: [Uses listModels tool]

Available models:
1. users - User profiles with name, email, age
2. products - Product catalog with pricing
3. orders - Order management system
4. customers - Customer database

You can query any of these models or train new ones.

Constrained Generation

Generate data with specific constraints and control parameters:

You: Generate 50 users aged between 25 and 35 with consistent results using seed 12345.

Claude: I'll generate users with those specific constraints and seed control.

[Uses queryModel with constraints and generation parameters]

Generated 50 users with consistent results:
- All aged between 25 - 35  
- Using seed 12345 for reproducible generation
- $entropy parameter controls randomness level
- Same query will always return identical results

⚙️ Configuration Options

Environment Variables

• LOG_LEVEL: Logging level (error, warn, info, debug, trace)
• MONGTAP_PORT: Default port for MCP server (default: 3000)
• MONGTAP_STORAGE: Path for model storage (default: ./welldb-models)
• MONGTAP_MAX_SERVERS: Maximum concurrent MongoDB servers (default: 10)

MCP Server Modes

The MCP server can run in different modes:

# Standard I/O mode (for Claude Desktop)
node src/mcp/index.js

# TCP mode (for network access)
node src/mcp/index.js tcp --port 3000

# Standalone mode (for testing)
node src/mcp/index.js standalone

🔧 Technical Details

MongTap consists of three main components:

1. DataFlood-JS: Statistical modeling engine that learns from samples
2. WellDB-Node: MongoDB wire protocol implementation
3. MCP Server: Integration layer for LLM tools

┌─────────────────┐     MCP Protocol      ┌──────────────┐
│ Claude Desktop  │ ◄──────────────────► │  MCP Server  │
└─────────────────┘                       └──────┬───────┘
                                                 │
                                                 ▼
┌─────────────────┐     MongoDB Wire     ┌──────────────┐
│ MongoDB Client  │ ◄──────────────────► │ WellDB-Node  │
└─────────────────┘                       └──────┬───────┘
                                                 │
                                                 ▼
                                          ┌──────────────┐
                                          │ DataFlood-JS │
                                          │  (Modeling)  │
                                          └──────────────┘

🛠️ Troubleshooting

Claude Desktop doesn't show MongTap tools

1. Check the configuration file path is correct
2. Ensure the path to MongTap is absolute, not relative
3. Restart Claude Desktop completely
4. Check logs: tail -f ~/Library/Logs/Claude/mcp-*.log (macOS)

MongoDB client can't connect

1. Verify the server is running: Use "listActiveServers" in Claude
2. Check the port is not in use: lsof -i :27017
3. Ensure firewall allows local connections
4. Try connecting with IP: mongodb://127.0.0.1:27017

Model generation seems incorrect

1. Provide more sample data for better training
2. Use consistent data formats in samples
3. Check model info to see learned patterns
4. Retrain with additional constraints if needed

💻 Development

Running Tests

# Run all tests
npm test

# Run specific test suite
node test/mcp/test-mcp-server.js
node test/welldb-node/test-mongodb-server.js
node test/dataflood-js/test-inferrer.js

# Run integration tests
node test/welldb-node/test-integration.js

Project Structure

MongTap/
├── src/
│   ├── mcp/                 # MCP server implementation
│   │   ├── mcp-server.js    # Core MCP server
│   │   ├── prompt-analyzer.js # NLP for prompts
│   │   └── server-manager.js # Multi-server management
│   ├── welldb-node/         # MongoDB protocol
│   │   ├── server/          # MongoDB server implementation
│   │   └── storage/         # DataFlood storage adapter
│   └── dataflood-js/        # Statistical modeling
│       ├── schema/          # Schema inference
│       ├── generator/       # Document generation
│       └── training/        # Model training
└── README.md               # This file

📄 License

MIT License - See LICENSE file for details.

🔒 Privacy Policy

MongTap is designed with privacy as a fundamental principle:

Data Collection

• NO personal data collection: MongTap does not collect any user data
• NO analytics or tracking: No usage statistics are gathered
• NO external connections: All operations are performed locally
• NO data persistence: Models are statistical representations, not actual data

Data Storage

• All models are stored locally on your machine
• Storage locations are fully configurable via mongtap.config.json
• No cloud services or external storage is used
• Generated data is synthetic and does not represent real information

Data Security

• Local-only operation ensures data never leaves your machine
• No authentication required (no credentials to compromise)
• Open source code allows full security auditing
• Input validation prevents injection attacks

🔒 Security

MongTap implements comprehensive security measures:

• Input Validation: All inputs are validated before processing
• Error Handling: Graceful error handling prevents information leakage
• No External Dependencies: Core functionality has minimal dependencies
• Local Operation: No network exposure unless explicitly configured
• Open Source: Full code transparency for security auditing

For detailed security information, see docs/SECURITY_AUDIT.md.

🛠️ Support

• Issues: GitHub Issues
• Documentation: docs/
• Status: DesignDocuments/STATUS.claude
• Contact: SmallMinds LLC Co - smallminds.co - andrew@smallminds.co

🙏 Acknowledgments

• DataFlood technology for statistical modeling
• MongoDB for protocol specification
• Anthropic for MCP protocol
• Claude Desktop for LLM integration

⚠️ Important Note

MongTap generates data statistically and does not store actual data. It's perfect for development, testing, and demonstration purposes where you need realistic data without the overhead of actual storage.