# NDB MCP Server
A Model Context Protocol server that enables Claude Desktop and other MCP-compatible AI assistants to manage Nutanix Database Service (NDB) environments through natural language with **custom instructions support**.
Transform complex database operations into simple conversations: *"Create a clone of the sales database for testing"* or *"Show me all databases with backup issues"*.
## 🆕 New in v1.3.0: Custom Instructions Support
**Configure your NDB assistant's behavior:**
- ✅ **Confirmation prompts** before creation operations
- ⏸️ **Pause on errors** with user guidance options
- 📝 **Customizable response styles** (concise, verbose, structured)
- 🛠️ **Behavioral instructions** via environment variables
## Quick Start
🚀 **[5-Minute Setup Guide](docs/quick-start.md)** - Get started immediately with presets and examples
### Prerequisites
- **Node.js** 18.0.0 or later
- **NDB Environment** with API access
- **Valid credentials** with appropriate permissions
### Installation
1. **Clone and setup**:
```bash
git clone https://github.com/rouxton/ndb-mcp-server.git
cd ndb-mcp-server
# Run the automated setup script
./scripts/setup.sh # Unix/Linux/macOS
# or
PowerShell -ExecutionPolicy Bypass -File scripts/setup.ps1 # Windows PowerShell
```
The setup script handles everything: dependencies, building, configuration, testing, and prepares for Claude Desktop integration.
2. **Configure Claude Desktop**:
```bash
./scripts/configure-claude.sh # Unix/Linux/macOS
# or
.\scripts\configure-claude.ps1 # Windows PowerShell
```
3. **Start using**:
- Restart Claude Desktop to load the new configuration
- Try asking Claude: "List all databases in NDB"
**Manual configuration** (if needed):
```bash
npm run configure # Interactive configuration wizard with custom instructions
npm run test:connection # Test NDB connectivity
npm run test:configuration # Test configuration validity
npm run test:mcp # Test MCP functionality
```
## 🛠️ Enhanced Configuration Wizard
The configuration wizard now includes comprehensive setup for custom instructions:
```bash
npm run configure
```
### Configuration Features
**🔧 Basic Settings:**
- NDB connection and authentication
- SSL verification and timeouts
- Multi-environment support
**📋 Custom Instructions:**
- **Preset configurations** for common scenarios (production, development, security, performance)
- **Industry-specific examples** (financial, healthcare, e-commerce, SaaS)
- **Database engine preferences** (PostgreSQL, Oracle, MongoDB)
- **Infrastructure patterns** (microservices, data lakes, edge computing)
**⚙️ Behavior Controls:**
- **Confirmation settings** for high-impact operations
- **Error handling** with pause/continue options
- **Response styles** (concise, verbose, structured)
### Quick Start Examples
**Production Environment:**
```bash
npm run configure
# Choose: production preset
# Result: Clustered deployments, security focus, confirmation required
```
**Development Environment:**
```bash
npm run configure
# Choose: development preset
# Result: Cost-effective, PostgreSQL preference, minimal confirmations
```
**Custom Setup:**
```bash
npm run configure
# Choose: custom
# Add your specific organizational guidelines
```
🗣️ **"Show me all PostgreSQL databases in production"**
📋 Lists all PostgreSQL databases with production status and health indicators
🗣️ **"Create a clone of the customer-data database for testing"**
🔄 Creates a fresh clone using the latest snapshot, ready for development use
🗣️ **"Take a snapshot of the critical-app database"**
📸 Creates an immediate backup snapshot with automatic retention policies
🗣️ **"Check which time machines had backup failures"**
🚨 Analyzes time machine health and reports any backup issues
## What You Can Do
| **Databases** | **Clones** | **Backups** | **Infrastructure** |
|---------------|------------|-------------|-------------------|
| List & monitor | Create & refresh | Snapshots & recovery | Cluster monitoring |
| Provision new | Manage lifecycle | Time machine status | Server health |
| Register existing | Resource allocation | Retention policies | Alerts & operations |
| Update properties | Cleanup & removal | Health monitoring | Capacity planning |
## Documentation
📖 **[Complete Setup Guide](docs/setup-and-configuration.md)** - Detailed installation, configuration, and security
🔧 **[Tools Reference](docs/tools-reference.md)** - Complete documentation of all available tools
💡 **[Usage Examples](docs/usage-examples.md)** - Real-world scenarios and workflows
## Architecture Overview
### High-Level Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Conversational │◄──►│ MCP │◄──►│ NDB │
│ Agent │ │ Server │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
MCP Protocol NDB REST API Database
(stdio/websocket) (HTTP/HTTPS) Operations
```
### Core Components
1. **MCP Server Core** (`src/index.ts`)
- Protocol handling and tool registration
- Request/response management
- Error handling and logging
2. **NDB Client** (`src/ndb-client.ts`)
- HTTP client for NDB API
- Authentication management
- Request retries and error handling
3. **Tool Definitions** (`src/tools.ts`)
- 30+ tool implementations
- Parameter validation
- Response formatting
4. **Type Definitions** (`src/types.ts`)
- TypeScript interfaces
- API response types
- Configuration schemas
5. **Utilities** (`src/utils.ts`)
- Helper functions
- Data transformations
- Validation logic
## 📚 Documentation
**📖 Configuration & Setup:**
- 🚀 [Quick Start Guide](docs/quick-start.md) - 5-minute setup with presets and examples
- [Configuration Guide](docs/configuration-guide.md) - Advanced configuration and custom instructions
- [Custom Instructions Examples](docs/custom-instructions-examples.md) - Industry-specific and use case examples
- [Migration Guide v1.3.0](docs/migration-guide-v1.3.0.md) - Upgrading to v1.3.0 with custom instructions
- [Custom Instructions API](docs/custom-instructions-api.md) - Technical API reference
**🔧 Technical Reference:**
- [Complete Setup Guide](docs/setup-and-configuration.md) - Detailed installation, configuration, and security
- [Tools Reference](docs/tools-reference.md) - Complete documentation of all available tools
- [Usage Examples](docs/usage-examples.md) - Real-world scenarios and workflows
## Support & Contributing
- 🐞 **Bug Reports**: [Create an issue](https://github.com/rouxton/ndb-mcp-server/issues/new?template=bug_report.md)
- 💡 **Feature Requests**: [Request a feature](https://github.com/rouxton/ndb-mcp-server/issues/new?template=feature_request.md)
- ❓ **Questions**: [Get support](https://github.com/rouxton/ndb-mcp-server/issues/new?template=support.md)
- 🤝 **Contributing**: See our [development guide](docs/development.md)
## License
MIT License - see [LICENSE](LICENSE) for details.
---
**Ready to transform your database management with AI?** 🚀
Start with the [setup guide](docs/setup-and-configuration.md) for detailed instructions.
