# 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"*.

This server isn't meant to be a complete wrapper around the NDB API. Instead, it focuses on the day-to-day operations that DBAs, DevOps, SysAdmins, and L2 support teams actually reach for, exposed in the simplest and safest way possible — confirmation before changes and a stop-and-ask policy on errors are built into every tool by default.

## Custom Instructions Support

Tailor the assistant's guidance to your context via `NDB_CUSTOM_INSTRUCTIONS` — a pipe-separated list of free-text guidelines (security practices, deployment preferences, compliance notes, etc.) that gets appended to the server's instructions and surfaced to the MCP client.

## Quick Start

🚀 **[5-Minute Setup Guide](docs/quick-start.md)** - Get started immediately with 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
   ```

The configuration wizard (`npm run configure`) sets up NDB connection settings plus the custom instructions above — industry-specific examples are covered in the [Configuration Guide](docs/configuration-guide.md).

## 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 |

## 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 & Tools** (`src/index.ts`)
   - McpServer setup, protocol handling
   - 61 tool registrations (Zod schemas, annotations, handlers)

2. **NDB Client** (`src/ndb_client.ts`)
   - HTTP client for NDB API
   - Authentication management
   - Request retries and error handling

3. **Zod Schemas** (`src/schemas.ts`)
   - Validation schemas for complex multi-parameter tools (clone, provision, restore)

4. **Type Definitions** (`src/types.ts`)
   - TypeScript interfaces
   - API response types
   - Configuration schemas

5. **Utilities** (`src/utils.ts`)
   - Helper functions (tag mapping, pagination, missing-parameter collection)
   - Data transformations

6. **Custom Instructions** (`src/custom_instructions.ts`)
   - Loads `NDB_CUSTOM_INSTRUCTIONS` and builds the system prompt

## Documentation

**Configuration & Setup:**
- [Quick Start Guide](docs/quick-start.md) - 5-minute setup with examples
- [Configuration Guide](docs/configuration-guide.md) - Advanced configuration and custom instructions
- [Complete Setup Guide](docs/setup-and-configuration.md) - Detailed installation, configuration, and security

**Technical Reference:**
- [Tools Reference](docs/tools-reference.md) - Complete documentation of all available tools
- [Usage Examples](docs/usage-examples.md) - Real-world scenarios and workflows
- [Claude Desktop Integration](docs/claude-desktop-integration.md) - Claude Desktop-specific configuration

## Support & Contributing

- 🐞 **Bug Reports & Feature Requests**: [Open an issue](https://github.com/rouxton/ndb-mcp-server/issues)
- 🤝 **Contributing**: See our [contributing guide](CONTRIBUTING.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.