# DataStax OpsCenter MCP Server

A Model Context Protocol (MCP) server that provides access to DataStax OpsCenter API for monitoring and managing Apache Cassandra and DataStax Enterprise clusters.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io/)

## 🚀 Features

This MCP server provides tools to:

- **Cluster Management**: Get cluster configurations and detailed information
- **Metrics Collection**: Retrieve performance metrics at cluster, node, and table levels
- **Node Monitoring**: Query individual node information and metrics
- **Schema Information**: Access keyspace and table schemas
- **Event Tracking**: Monitor cluster events and alerts
- **Comprehensive Metrics**: Support for 100+ metrics including:
  - Cluster metrics (read/write ops, latency, memory usage)
  - Thread pool metrics (pending/active tasks)
  - Table metrics (disk usage, SSTable counts, latency)
  - OS metrics (CPU, memory, disk, network)

## 📋 Prerequisites

- **Node.js**: Version 18.x, 20.x, or 22.x
- **DataStax OpsCenter**: Version 6.8.x or compatible
- **Access**: Network connectivity to your OpsCenter instance

## � Documentation

- **[Cassandra Troubleshooting Guide](.github/copilot-troubleshooting-guide.md)** - Comprehensive guide for production troubleshooting with 9-phase workflow, critical thresholds, and emergency procedures
- **[Metrics Coverage Analysis](METRICS_COVERAGE_ANALYSIS.md)** - Complete coverage report of all 340+ OpsCenter metrics
- **[Metrics Quick Reference](METRICS_QUICK_REFERENCE.md)** - Fast lookup guide for metric names to MCP tools
- **[GitHub Copilot Instructions](.github/copilot-instructions.md)** - Development guidelines and project architecture

## �🔧 Installation

### 1. Clone the Repository

```bash
git clone https://github.com/yourusername/datastax-opscenter-mcp.git
cd datastax-opscenter-mcp
```

### 2. Install Dependencies

```bash
npm install
```

### 3. Build the Project

```bash
npm run build
```

This compiles TypeScript to JavaScript in the `build/` directory.

## ⚙️ Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OPSCENTER_URL` | Yes | `http://localhost:8888` | OpsCenter base URL |
| `OPSCENTER_USERNAME` | No | - | Username for authentication (if enabled) |
| `OPSCENTER_PASSWORD` | No | - | Password for authentication (if enabled) |

---

## 🔌 Setup for VS Code with GitHub Copilot

### 1. Locate Your VS Code MCP Settings File

**macOS/Linux:**
```bash
code ~/.vscode/mcp-settings.json
```

**Windows:**
```powershell
code %APPDATA%\Code\User\mcp-settings.json
```

If the file doesn't exist, create it.

### 2. Add Server Configuration

Add the following to your `mcp-settings.json`:

```json
{
  "mcpServers": {
    "datastax-opscenter": {
      "command": "node",
      "args": [
        "/absolute/path/to/datastax-opscenter-mcp/build/index.js"
      ],
      "env": {
        "OPSCENTER_URL": "http://your-opscenter-host:8888",
        "OPSCENTER_USERNAME": "your_username",
        "OPSCENTER_PASSWORD": "your_password"
      }
    }
  }
}
```

**⚠️ Important:** 
- Replace `/absolute/path/to/datastax-opscenter-mcp` with the actual path where you cloned the repo
- Update `OPSCENTER_URL`, `OPSCENTER_USERNAME`, and `OPSCENTER_PASSWORD` with your values
- On Windows, use forward slashes or escaped backslashes in paths: `C:/Users/YourName/datastax-opscenter-mcp/build/index.js`

### 3. Restart VS Code

Close and reopen VS Code for the changes to take effect.

### 4. Verify Installation

1. Open GitHub Copilot Chat in VS Code
2. Type `@datastax-opscenter` and you should see the server available
3. Try a test command:
   ```
   @datastax-opscenter get_cluster_configs
   ```

---

## 🖥️ Setup for Claude Desktop

### 1. Locate Claude Desktop Configuration

**macOS:**
```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**
```powershell
%APPDATA%\Claude\claude_desktop_config.json
```

**Linux:**
```bash
~/.config/Claude/claude_desktop_config.json
```

### 2. Edit Configuration File

Open the configuration file and add the MCP server:

```json
{
  "mcpServers": {
    "datastax-opscenter": {
      "command": "node",
      "args": [
        "/absolute/path/to/datastax-opscenter-mcp/build/index.js"
      ],
      "env": {
        "OPSCENTER_URL": "http://localhost:8888",
        "OPSCENTER_USERNAME": "admin",
        "OPSCENTER_PASSWORD": "password"
      }
    }
  }
}
```

**⚠️ Configuration Notes:**
- Use **absolute paths** for the `args` parameter
- Remove `OPSCENTER_USERNAME` and `OPSCENTER_PASSWORD` if your OpsCenter doesn't require authentication
- Update `OPSCENTER_URL` to match your OpsCenter instance

### 3. Restart Claude Desktop

Completely quit and restart the Claude Desktop application.

### 4. Verify Installation

In Claude Desktop, you should see the MCP server connected. Try:
```
Can you get the cluster configurations from OpsCenter?
```

---

## 🐳 Docker Setup (Optional)

If you prefer running the MCP server in a container:

### 1. Create Dockerfile

```dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

ENV OPSCENTER_URL=http://localhost:8888

CMD ["node", "build/index.js"]
```

### 2. Build and Run

```bash
docker build -t datastax-opscenter-mcp .

docker run -it \
  -e OPSCENTER_URL=http://your-opscenter:8888 \
  -e OPSCENTER_USERNAME=admin \
  -e OPSCENTER_PASSWORD=password \
  datastax-opscenter-mcp
```

---

## 📖 Quick Start Examples

Once configured, you can use the MCP server to monitor your Cassandra clusters:

## Available Tools

### Cluster Operations

#### `get_cluster_configs`
Get configuration information for all clusters managed by OpsCenter.

#### `get_cluster_info`
Get detailed information about a specific cluster.
- **Parameters**: `cluster_id`

#### `get_nodes`
Get list of all nodes in a cluster with their properties.
- **Parameters**: `cluster_id`
- **Note**: Returns full node details (can be large for big clusters)

#### `get_nodes_summary` ✨ **NEW**
Get a concise summary of nodes organized by datacenter.
- **Parameters**: 
  - `cluster_id` (required)
  - `datacenter` (optional) - Filter by specific datacenter
- **Returns**: Node counts, IPs, hostnames, racks by datacenter
- **Use Case**: Quick cluster topology overview without large payloads
- **Example**:
  ```json
  {
    "total_nodes": 68,
    "datacenter_counts": {
      "us-east1-v1": 15,
      "us-central1-v1": 15,
      "HD_ATC": 18,
      "HD_SSC": 20
    }
  }
  ```

#### `get_node_info`
Get detailed information about a specific node.
- **Parameters**: `cluster_id`, `node_ip`

### Metrics Collection

#### `get_cluster_metrics`
Retrieve cluster-wide metrics.
- **Parameters**: 
  - `cluster_id` (required)
  - `datacenter` (default: "all")
  - `metric` (required) - e.g., "write-ops", "read-ops", "data-load"
  - `start` - Unix timestamp in seconds
  - `end` - Unix timestamp in seconds
  - `step` - Time interval in minutes (1, 5, 120, or 1440)
  - `function` - Aggregation: "min", "max", or "average"

**Example metrics**:
- `write-ops`: Write requests per second
- `read-ops`: Read requests per second
- `data-load`: Live disk space used
- `heap-used`: Java heap memory usage
- `pending-compaction-tasks`: Pending compactions

#### `get_node_metrics`
Retrieve metrics for a specific node.
- **Parameters**: Same as cluster metrics, plus `node_ip`

#### `get_bulk_node_metrics` ✨ **NEW**
Retrieve metrics for ALL nodes in a datacenter with automatic aggregation.
- **Parameters**:
  - `cluster_id` (required)
  - `datacenter` (required) - e.g., "us-east1-v1"
  - `metric` (required) - e.g., "read-ops", "write-ops"
  - `start` (optional) - Defaults to 1 hour ago
  - `end` (optional) - Defaults to current time
  - `step` (optional) - Default: 5 minutes
  - `function` (optional) - Default: "average"
- **Returns**:
  - Aggregate time-series (total, average, min, max per timestamp)
  - Overall statistics
  - Per-node details and error status
- **Use Case**: Get total read/write volume for entire datacenter
- **Example**: 
  ```json
  {
    "cluster_id": "Production_Cluster",
    "datacenter": "us-east1-v1",
    "metric": "read-ops",
    "nodes": {"total": 15, "with_data": 15},
    "overall_statistics": {
      "total_sum": 785160,
      "average": 14.54,
      "max": 17.89
    }
  }
  ```

#### `get_table_metrics`
Retrieve metrics for a specific table.
- **Parameters**: 
  - `cluster_id`, `datacenter`, `keyspace`, `table`, `metric`
  - Time range and aggregation parameters

**Example table metrics**:
- `cf-write-ops`: Table write operations per second
- `cf-read-ops`: Table read operations per second
- `cf-live-disk-used`: Disk space used by table
- `cf-live-sstables`: Number of SSTables

#### `get_new_metrics`
Retrieve multiple metrics using the unified API.
- **Parameters**:
  - `cluster_id`, `metrics` (comma-separated)
  - `nodes` or `node_group` ("*" for all)
  - `step` in seconds (60, 300, 7200, or 86400)
  - `node_aggregation` (0 or 1)

#### `list_available_metrics`
List all available metric types with descriptions.
- **Parameters**: `category` (optional) - "cluster", "threadpool", "table", "os"

### Schema Operations

#### `get_keyspaces`
Get list of all keyspaces in a cluster.
- **Parameters**: `cluster_id`

#### `get_keyspace_schema`
Get schema information for a specific keyspace.
- **Parameters**: `cluster_id`, `keyspace`

### Event Monitoring

#### `get_events`
Get events and alerts for a cluster.
- **Parameters**: `cluster_id`, `limit` (default: 100)

---

## 📖 Quick Start Examples

Once configured, you can use the MCP server to monitor your Cassandra clusters:

### Example 1: List All Clusters
**In VS Code Copilot Chat:**
```
@datastax-opscenter get_cluster_configs
```

**In Claude Desktop:**
```
Show me all Cassandra clusters managed by OpsCenter
```

### Example 2: Get Cluster Topology Overview ✨ **NEW**
```
Get a summary of all nodes in "Production_Cluster" organized by datacenter
```

**Using get_nodes_summary tool:**
- Shows node counts per datacenter
- Lists node IPs, hostnames, racks
- Lightweight response (no large payloads)

### Example 3: Analyze Datacenter Read Volume ✨ **NEW**
```
What is the total read request volume for all nodes in us-east1-v1 
datacenter of "Production_Cluster" for the last hour?
```

**Using get_bulk_node_metrics tool:**
- Automatically queries all 15 nodes in us-east1-v1
- Aggregates metrics across all nodes
- Returns total, average, min, max statistics
- Includes per-timestamp breakdown

### Example 4: Check Cluster Health
```
Get detailed information about the cluster "Production_Cluster"
```

### Example 5: Monitor Read Performance
```
Show me read operations per second for "Production_Cluster" 
in the last 3 hours with 5-minute intervals
```

### Example 6: Analyze Table Performance
```
What is the disk usage and read latency for the table 
"users" in keyspace "app_data" on cluster "Production_Cluster"?
```

### Example 7: Node Health Check
```
Get heap memory usage and CPU metrics for node 10.0.1.50 
in cluster "Production_Cluster" for the last hour
```

---

### Example 1: Get Cluster Information
```typescript
// Get all clusters
await callTool("get_cluster_configs", {});

// Get specific cluster details
await callTool("get_cluster_info", {
  cluster_id: "Test_Cluster"
});
```

### Example 2: Monitor Write Performance
```typescript
// Get write operations per second for last hour
const now = Math.floor(Date.now() / 1000);
const oneHourAgo = now - 3600;

await callTool("get_cluster_metrics", {
  cluster_id: "Test_Cluster",
  datacenter: "all",
  metric: "write-ops",
  start: oneHourAgo,
  end: now,
  step: 5, // 5-minute intervals
  function: "average"
});
```

### Example 3: Check Node Health
```typescript
// Get node CPU usage
await callTool("get_node_metrics", {
  cluster_id: "Test_Cluster",
  node_ip: "10.11.12.150",
  metric: "os-cpu-user",
  start: oneHourAgo,
  end: now
});
```

### Example 4: Analyze Table Performance
```typescript
// Get table read latency
await callTool("get_table_metrics", {
  cluster_id: "Test_Cluster",
  datacenter: "all",
  keyspace: "Keyspace1",
  table: "Users",
  metric: "cf-read-latency-op",
  function: "max"
});
```

### Example 5: Discover Available Metrics
```typescript
// List all cluster metrics
await callTool("list_available_metrics", {
  category: "cluster"
});

// List all available metrics
await callTool("list_available_metrics", {});
```

## Metric Categories

### Cluster Metrics
Performance metrics aggregated across the cluster:
- Operations: `write-ops`, `read-ops`, `write-failures`, `read-failures`
- Latency: `write-histogram`, `read-histogram`
- Memory: `heap-used`, `heap-max`, `nonheap-used`
- Cache: `key-cache-hit-rate`, `row-cache-hit-rate`
- Compaction: `pending-compaction-tasks`, `total-bytes-compacted`

### Thread Pool Metrics
Thread pool activity and queue depths:
- Pending: `pending-read-stage`, `pending-mutation-stage`, `pending-flushes`
- Active: `active-read-stage`, `active-mutation-stage`
- Completed: `completed-read-stage`, `completed-mutation-stage`

### Table Metrics
Per-table performance and storage:
- Operations: `cf-write-ops`, `cf-read-ops`
- Latency: `cf-write-latency-op`, `cf-read-latency-op`
- Storage: `cf-live-disk-used`, `cf-total-disk-used`, `cf-live-sstables`
- SSTable stats: `cf-sstables-per-read`, `cf-partition-size`

### Operating System Metrics
Host-level resource utilization:
- CPU: `os-cpu-user`, `os-cpu-system`, `os-cpu-idle`, `os-load`
- Memory: `os-memory-used`, `os-memory-free`
- Disk: `os-disk-used`, `os-disk-free`, `os-disk-read-throughput`
- Network: `os-net-received`, `os-net-sent`

## Time Range Parameters

All metric queries support time range filtering:
- `start`: Unix timestamp in seconds (beginning of range)
- `end`: Unix timestamp in seconds (end of range)
- `step`: Data point interval
  - For legacy API: minutes (1, 5, 120, 1440)
  - For new-metrics API: seconds (60, 300, 7200, 86400)

## Aggregation Functions

Metrics can be aggregated using:
- `min`: Minimum value in the time period
- `max`: Maximum value in the time period  
- `average`: Average value in the time period

## API Reference

Based on DataStax OpsCenter 6.8 API:
- [Metrics API Documentation](https://docs.datastax.com/en/opscenter/6.8/api/metrics.html)
- [OpsCenter API Reference](https://docs.datastax.com/en/opscenter/6.8/api/opscenter-api-reference.html)

## 🛠️ Development

### Project Structure

```
datastax-opscenter-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── build/                # Compiled JavaScript output
│   ├── index.js
│   └── index.d.ts
├── .github/
│   └── copilot-instructions.md  # AI coding assistant guide
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md
```

### Development Commands

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development (auto-rebuild on changes)
npm run watch

# Run the compiled server
npm start

# Run directly with environment variables
OPSCENTER_URL=http://localhost:8888 npm start
```

### Making Changes

1. Edit TypeScript source in `src/index.ts`
2. Run `npm run build` or `npm run watch`
3. Restart VS Code or Claude Desktop to pick up changes

### Adding New Tools

To add a new MCP tool:

1. Add the tool definition to the `tools` array in `src/index.ts`
2. Add the handler case in the `CallToolRequestSchema` handler
3. Update the README with usage examples
4. Rebuild: `npm run build`

---

## 📚 API Reference

### Available MCP Tools

## 🔍 Troubleshooting

### Common Issues

#### ❌ "Cannot connect to OpsCenter"

**Problem:** `Error: connect ECONNREFUSED`

**Solutions:**
1. Verify OpsCenter is running:
   ```bash
   curl http://localhost:8888/cluster-configs
   ```
2. Check the `OPSCENTER_URL` in your configuration
3. Verify firewall allows connections to OpsCenter port (default: 8888)
4. Test network connectivity:
   ```bash
   telnet your-opscenter-host 8888
   ```

#### ❌ "Authentication Failed"

**Problem:** `401 Unauthorized`

**Solutions:**
1. Verify OpsCenter requires authentication (check OpsCenter settings)
2. Set correct `OPSCENTER_USERNAME` and `OPSCENTER_PASSWORD`
3. Remove authentication env vars if OpsCenter doesn't require them
4. Check credentials by logging into OpsCenter web UI

#### ❌ "MCP Server Not Showing Up"

**VS Code:**
1. Check the path in `mcp-settings.json` is absolute and correct
2. Verify the file exists: `ls /path/to/datastax-opscenter-mcp/build/index.js`
3. Check for syntax errors in `mcp-settings.json`
4. Restart VS Code completely
5. Check VS Code Output panel for MCP errors

**Claude Desktop:**
1. Verify configuration file location matches your OS
2. Use absolute paths in the configuration
3. Quit Claude Desktop completely (not just close window)
4. Check Claude Desktop logs:
   - **macOS:** `~/Library/Logs/Claude/`
   - **Windows:** `%APPDATA%\Claude\logs\`

#### ❌ "Metric Not Found"

**Problem:** `API Error (400): Invalid metric`

**Solutions:**
1. Use the `list_available_metrics` tool to see valid metrics:
   ```
   @datastax-opscenter list_available_metrics
   ```
2. Check metric spelling and hyphens (e.g., `read-ops` not `read_ops`)
3. Verify the metric category matches your request:
   - Cluster metrics: use `get_cluster_metrics`
   - Node metrics: use `get_node_metrics`
   - Table metrics: use `get_table_metrics`

#### ❌ "Build Errors"

**Problem:** TypeScript compilation fails

**Solutions:**
1. Ensure Node.js version is compatible:
   ```bash
   node --version  # Should be 18.x, 20.x, or 22.x
   ```
2. Clear and reinstall dependencies:
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   npm run build
   ```
3. Check TypeScript version:
   ```bash
   npm list typescript
   ```

#### 🐛 Debug Mode

Enable verbose logging by checking stderr output:

**VS Code:**
- Check Output panel → Select "MCP" from dropdown

**Claude Desktop:**
- Check logs directory for your OS (see above)

**Manual Testing:**
```bash
OPSCENTER_URL=http://localhost:8888 node build/index.js
```

---

## 🤝 Contributing

Contributions are welcome! Here's how you can help:

### Reporting Issues

1. Search existing issues first
2. Include:
   - OpsCenter version
   - Node.js version
   - Error messages and stack traces
   - Steps to reproduce

### Submitting Pull Requests

1. Fork the repository
2. Create a feature branch:
   ```bash
   git checkout -b feature/your-feature-name
   ```
3. Make your changes
4. Test thoroughly:
   ```bash
   npm run build
   # Test with VS Code or Claude Desktop
   ```
5. Commit with clear messages:
   ```bash
   git commit -m "Add feature: description"
   ```
6. Push and create a pull request

### Development Guidelines

- Follow existing TypeScript code style
- Add JSDoc comments for new functions
- Update README.md with new features
- Test with both authenticated and unauthenticated OpsCenter
- Ensure backwards compatibility

---

## 📄 License

MIT License - see LICENSE file for details

---

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
- [DataStax OpsCenter](https://www.datastax.com/products/opscenter) API Documentation
- [Apache Cassandra](https://cassandra.apache.org/) Community

---

## 📞 Support

- **Issues:** [GitHub Issues](https://github.com/yourusername/datastax-opscenter-mcp/issues)
- **Discussions:** [GitHub Discussions](https://github.com/yourusername/datastax-opscenter-mcp/discussions)
- **OpsCenter API Docs:** [DataStax Documentation](https://docs.datastax.com/en/opscenter/6.8/api/)

---

## 🗺️ Roadmap

- [ ] Support for DataStax OpsCenter 7.x
- [ ] Grafana-style dashboard generation
- [ ] Alert configuration tools
- [ ] Backup/restore operations
- [ ] Repair management
- [ ] Performance recommendations
- [ ] WebSocket support for real-time metrics

---

**Made with ❤️ for the Cassandra community**