npm package: @mithung/vunet-mcp-server
Description: Model Context Protocol (MCP) Server for Vunet vuSmartMaps - Multi-tenant observability platform integration
Author: Vunet Systems
Latest version: 2.2.1

# @mithung/vunet-mcp-server

[![npm version](https://badge.fury.io/js/@mithung%2Fvunet-mcp-server.svg)](https://www.npmjs.com/package/@mithung/vunet-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)

**Model Context Protocol (MCP) Server for Vunet vuSmartMaps** - A multi-tenant observability platform integration.

Query metrics, traces, logs, and data models from your Vunet tenants using natural language through AI assistants like Claude, GitHub Copilot, or any MCP-compatible client.

> **Latest Version:** 2.2.0 - Added `vunet_fetch_datamodels` tool for live data model discovery from the VuNet API.

---

## 🚀 Features

- ✅ **Multi-Tenant Support** - Connect to multiple Vunet tenants simultaneously
- 🔐 **Secure Authentication** - Session-based auth with automatic token refresh
- 📊 **Comprehensive Data Access** - Query 600+ data models including:
  - Journey Metrics (IBMB, UPI, CBS, FRM)
  - Application traces and exceptions
  - Infrastructure metrics (CPU, Memory, Disk)
  - Kubernetes metrics
  - Alert data and RCA metrics
- ⚡ **Flexible Querying** - Support for:
  - Relative time ranges (`5m`, `15m`, `1h`, `2h`, `1d`, `1w`, `1M`)
  - Absolute time ranges (epoch timestamps)
  - Dynamic filters and field selection
- 🔄 **Auto Session Management** - Handles login, token refresh, and logout
- 🌐 **Proxy Support** - Works with Traefik and other reverse proxies

---

## 📦 Installation

### Using npx (Recommended - No Installation Required)

```bash
npx @mithung/vunet-mcp-server
```

### Global Installation

```bash
npm install -g @mithung/vunet-mcp-server
```

### Local Installation

```bash
npm install @mithung/vunet-mcp-server
```

---

## 🛠️ Configuration

### VS Code / GitHub Copilot Setup

Create `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "vunet": {
      "command": "npx",
      "args": ["@mithung/vunet-mcp-server"],
      "env": {
        "VUNET_TENANT_URL": "https://your-tenant.vunetsystems.com",
        "VUNET_USERNAME": "your-username",
        "VUNET_PASSWORD": "your-password",
        "VUNET_BU_ID": "1",
        "VUNET_VERIFY_SSL": "true"
      }
    }
  }
}
```

### Multiple Tenants

```json
{
  "servers": {
    "vunet-prod": {
      "command": "npx",
      "args": ["@mithung/vunet-mcp-server"],
      "env": {
        "VUNET_TENANT_URL": "https://prod.vunetsystems.com",
        "VUNET_USERNAME": "prod-user",
        "VUNET_PASSWORD": "prod-password",
        "VUNET_BU_ID": "1",
        "VUNET_VERIFY_SSL": "true"
      }
    },
    "vunet-uat": {
      "command": "npx",
      "args": ["@mithung/vunet-mcp-server"],
      "env": {
        "VUNET_TENANT_URL": "https://uat.vunetsystems.com",
        "VUNET_USERNAME": "uat-user",
        "VUNET_PASSWORD": "uat-password",
        "VUNET_BU_ID": "1",
        "VUNET_VERIFY_SSL": "false"
      }
    }
  }
}
```

### Running from Source

If you've cloned the repository:

```json
{
  "servers": {
    "vunet": {
      "command": "node",
      "args": ["c:\\path\\to\\vunet-mcp-server\\index.js"],
      "env": {
        "VUNET_TENANT_URL": "https://your-tenant.vunetsystems.com",
        "VUNET_USERNAME": "your-username",
        "VUNET_PASSWORD": "your-password",
        "VUNET_BU_ID": "1",
        "VUNET_VERIFY_SSL": "false"
      }
    }
  }
}
```

---

## 📊 Available MCP Tools

### 1. `vunet_get_status`
Check the current connection status and tenant information.

```
Example: "Check if Vunet connection is working"
```

### 2. `vunet_list_data_models`
List common Vunet data models organised by category (APM, Infrastructure, Database, Network, etc.).

**Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `category` | No | Filter by category: `apm`, `infrastructure`, `database`, `network`, `business`, `all` (default: `all`) |

```
Example: "List all available Vunet data models"
Example: "Show me infrastructure data models in Vunet"
```

### 3. `vunet_fetch_datamodels`
Fetch the actual **live** DataModels (signals) configured in this VuNet tenant via `/api/vuaccel/datamodel/`. Returns real signal names, types (Metric/Event/Log), data sources, and column details. Use this to discover what data is available before querying with `vunet_query_metric`.

**Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `limit` | No | Number of results per page (default: 10, max: 100) |
| `offset` | No | Pagination offset — records to skip (default: 0) |
| `search` | No | Search keyword to filter by name (e.g., `UPI`, `CPU`, `transaction`) |
| `signal_type` | No | Filter by type: `Metric`, `Event`, or `Log` |
| `ordering` | No | Sort field (e.g., `signal_name`, `-creation_time`) |

```
Example: "Fetch all live data models from VuNet"
Example: "Find data models related to UPI in VuNet"
Example: "List all Event type data models"
```

### 4. `vunet_query_metric`
Query a specific metric with time range and filters.

**Parameters:**
| Parameter | Required | Description |
|-----------|----------|-------------|
| `metric_name` | Yes | Name of the data model to query |
| `relative_time` | No | Time range: `5m`, `15m`, `1h`, `2h`, `1d`, `1w`, `1M`, `1y` |
| `start_time` | No | Start epoch timestamp or `now`, `now-1h` (use with `end_time`) |
| `end_time` | No | End epoch timestamp or `now` (use with `start_time`) |
| `filters` | No | JSON object with field:value pairs for filtering |
| `fields` | No | Comma-separated fields to include in response |
| `exclude_fields` | No | Comma-separated fields to exclude from response |
| `include_thresholds` | No | Include threshold data in response (default: false) |
| `format` | No | Response format — use `lama` for Log Analytics format |
| `compare_intervals` | No | Additional time intervals for comparison (e.g., `1h_ago`, `1d_ago`) |
| `join_models` | No | Comma-separated additional data models to join |
| `time_shift` | No | Time shift for comparison (e.g., `1h`, `1d`, `1w`) |

---

## 💬 Usage Examples

### Check Connection Status
```
"Is the Vunet MCP server connected?"
```

### Discover Live Data Models
```
"Fetch all available data models from VuNet"
"Show me all Metric type data models"
"Find data models related to UPI payments"
"Search for CPU-related data models in VuNet"
```

### List Categorised Data Models
```
"What data models are available in Vunet?"
"Show me infrastructure data models"
"List all APM data models"
```

### Query Journey Metrics
```
"Show me IBMB Journey Metrics for the last 2 hours"
"Get UPI Volume data for the last 1 hour"
"Query CBS TAT metrics for the last 30 minutes"
```

### Query Alerts
```
"Get all critical alerts from the last 1 hour"
"Show warning alerts with group values for the last 15 minutes"
```

### Query with Filters
```
"Query IBMB Journey Metrics where name equals CBS for the last 30 minutes"
"Get Linux CPU Utilization filtered by hostname for the last 2 hours"
```

### Infrastructure Monitoring
```
"Show CPU utilization for IBMB servers in the last hour"
"Get memory utilization for CBS servers in the last 2 hours"
"Show MSSQL blocking sessions for the last 30 minutes"
```

### RCA Analysis
```
"Get Technical Decline data for IBMB in the last 2 hours"
"Show RCA root cause data for the last 1 hour"
"Query RCA lead indicators for the last 4 hours"
```

### Time Comparison
```
"Compare UPI Volume for the last 1 hour vs same time yesterday"
"Show IBMB TAT with 1-day comparison"
```

---

## 🔧 Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `VUNET_TENANT_URL` | Yes | - | Vunet tenant URL |
| `VUNET_USERNAME` | Yes | - | Username for authentication |
| `VUNET_PASSWORD` | Yes | - | Password for authentication |
| `VUNET_BU_ID` | Yes | `1` | Business Unit ID |
| `VUNET_VERIFY_SSL` | No | `true` | Verify SSL certificates |

---

## 📈 Common Data Models

### Journey Metrics
- `IBMB Journey Metrics` - Internet/Mobile Banking metrics
- `UPI Journey Metrics` - UPI payment metrics
- `CBS Journey Metrics` - Core Banking metrics
- `FRM Journey Metrics` - Fraud Risk Management

### RCA (Root Cause Analysis)
- `RCA IBMB TD` - Technical Decline breakdown
- `RCA CPU Utilization IBMB` - Server CPU metrics
- `RCA Memory Utilization IBMB` - Server memory metrics
- `Linux Disk Utilization IBMB` - Disk usage

### Alerts
- `Alert data` - All active alerts with severity
- `IBMB Exceptions` - Application exceptions

### Infrastructure
- `Kubernetes Pod Metrics`
- `Linux Host Metrics`
- `Network Metrics`

---

## 🔥 Troubleshooting

### Authentication Failed (401)
```
Error: www-authenticate: Basic realm="traefik"
```
**Solution:** Your environment may have a Traefik proxy. The MCP server v2.1.0+ handles this automatically.

### Session Expired
The server automatically refreshes sessions. If issues persist, restart the MCP server.

### SSL Certificate Errors
Set `VUNET_VERIFY_SSL` to `false` for self-signed certificates:
```json
"VUNET_VERIFY_SSL": "false"
```

### Data Model Not Found
Use `vunet_list_data_models` to see available metrics. Names are case-sensitive.

---

## 🚀 Quick Start Commands

```bash
# Install globally
npm install -g @mithung/vunet-mcp-server

# Or run directly with npx
npx @mithung/vunet-mcp-server

# Check installed version
npm list -g @mithung/vunet-mcp-server
```

---

## 📄 Changelog

### v2.2.0 (2026-03-18)
- ✅ Added `vunet_fetch_datamodels` tool — live data model discovery via `/api/vuaccel/datamodel/`
- ✅ Supports pagination, search, signal type filter, and ordering
- ✅ Fixed `package.json` bin entries (`npm pkg fix`)

### v2.1.1 (2026-02-18)
- ✅ Updated repository URLs to correct GitHub organization
- ✅ Fixed package metadata

### v2.1.0 (2026-02-17)
- ✅ Authentication improvements with proxy support
- ✅ Auto-reconnect on session expiry
- ✅ Better error handling

### v2.0.8
- Initial stable release
- Multi-tenant support
- Comprehensive data model access

---

## 📝 License

MIT License - see [LICENSE](LICENSE) file.

---

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📧 Support

- **GitHub Issues:** [https://github.com/mithung-vunet/vunet-mcp-server/issues](https://github.com/mithung-vunet/vunet-mcp-server/issues)
- **npm Package:** [https://www.npmjs.com/package/@mithung/vunet-mcp-server](https://www.npmjs.com/package/@mithung/vunet-mcp-server)

---

Made with ❤️ by [Vunet Systems](https://vunetsystems.com)