@mithung/vunet-mcp-server 2.0.0

package/README.md

@@ -0,0 +1,679 @@
+# @vunet/mcp-server
+
+[![npm version](https://badge.fury.io/js/%40vunet%2Fmcp-server.svg)](https://badge.fury.io/js/%40vunet%2Fmcp-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 similar to Dynatrace MCP.
+
+Query metrics, traces, logs, and data models from your Vunet tenants using natural language through AI assistants like Claude, ChatGPT, or any MCP-compatible client.
+
+---
+
+## 🚀 Features
+
+- ✅ **Multi-Tenant Support** - Connect to multiple Vunet tenants simultaneously
+- 🔐 **Secure Authentication** - Session-based authentication with automatic token refresh
+- 📊 **Comprehensive Data Access** - Query 80+ data models including:
+  - Kubernetes metrics
+  - Application traces
+  - Transaction volumes
+  - Infrastructure metrics
+  - Custom data models
+- ⚡ **Flexible Querying** - Support for:
+  - Relative time ranges (`15m`, `1h`, `1d`, `1w`, `1M`, `1y`)
+  - Absolute time ranges (epoch timestamps)
+  - Dynamic filters and field selection
+  - Time-shift comparisons
+  - Threshold data inclusion
+- 🔄 **Automatic Session Management** - Handles login, token refresh, and logout
+- 🌐 **SSL/TLS Support** - Configurable SSL certificate verification
+- 📦 **Easy Installation** - npm package ready for global or local use
+
+---
+
+## 📋 Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [VS Code Configuration](#vs-code-configuration)
+  - [Multiple Tenants](#multiple-tenants)
+- [Usage](#usage)
+  - [Available Tools](#available-tools)
+  - [Query Examples](#query-examples)
+- [Data Models](#data-models)
+- [Environment Variables](#environment-variables)
+- [Troubleshooting](#troubleshooting)
+- [Examples](#examples)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## 📦 Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g @vunet/mcp-server
+```
+
+### Local Installation
+
+```bash
+npm install @vunet/mcp-server
+```
+
+### From Source
+
+```bash
+git clone https://github.com/vunet-systems/vunet-mcp-server.git
+cd vunet-mcp-server
+npm install
+npm link
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Configure VS Code (or any MCP client)
+
+Add to your `settings.json` or `.vscode/mcp.json`:
+
+**Option A: Username/Password Authentication**
+```json
+{
+  "mcpServers": {
+    "vunet": {
+      "command": "npx",
+      "args": ["@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"
+      }
+    }
+  }
+}
+```
+
+**Option B: Bearer Token Authentication (Recommended for CI/CD)**
+```json
+{
+  "mcpServers": {
+    "vunet": {
+      "command": "npx",
+      "args": ["@vunet/mcp-server"],
+      "env": {
+        "VUNET_TENANT_URL": "https://your-tenant.vunetsystems.com",
+        "VUNET_BEARER_TOKEN": "your-bearer-token-here",
+        "VUNET_BU_ID": "1",
+        "VUNET_VERIFY_SSL": "true"
+      }
+    }
+  }
+}
+```
+
+### 2. Reload VS Code
+
+Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac), then run:
+```
+Developer: Reload Window
+```
+
+### 3. Start Using!
+
+Open GitHub Copilot Chat or any MCP client and ask:
+- "Show me Kubernetes metrics for the last 15 minutes"
+- "What traces are taking more than 5 seconds?"
+- "Get transaction volume for the last 24 hours"
+
+---
+
+## ⚙️ Configuration
+
+### VS Code Configuration
+
+#### Single Tenant
+
+Create or edit `.vscode/mcp.json` in your workspace:
+
+**Using Username/Password:**
+```json
+{
+  "mcpServers": {
+    "vunet": {
+      "command": "npx",
+      "args": ["@vunet/mcp-server"],
+      "env": {
+        "VUNET_TENANT_URL": "https://your-tenant.com",
+        "VUNET_USERNAME": "your-username",
+        "VUNET_PASSWORD": "your-password",
+        "VUNET_BU_ID": "1",
+        "VUNET_VERIFY_SSL": "true"
+      }
+    }
+  }
+}
+```
+
+**Using Bearer Token:**
+```json
+{
+  "mcpServers": {
+    "vunet": {
+      "command": "npx",
+      "args": ["@vunet/mcp-server"],
+      "env": {
+        "VUNET_TENANT_URL": "https://your-tenant.com",
+        "VUNET_BEARER_TOKEN": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+        "VUNET_BU_ID": "1",
+        "VUNET_VERIFY_SSL": "true"
+      }
+    }
+  }
+}
+```
+
+#### Multiple Tenants
+
+```json
+{
+  "mcpServers": {
+    "vunet-production": {
+      "command": "npx",
+      "args": ["@vunet/mcp-server"],
+      "env": {
+        "VUNET_TENANT_URL": "https://prod.company.com",
+        "VUNET_USERNAME": "prod-user",
+        "VUNET_PASSWORD": "prod-password",
+        "VUNET_BU_ID": "1",
+        "VUNET_VERIFY_SSL": "true"
+      }
+    },
+    "vunet-staging": {
+      "command": "npx",
+      "args": ["@vunet/mcp-server"],
+      "env": {
+        "VUNET_TENANT_URL": "https://staging.company.com",
+        "VUNET_USERNAME": "staging-user",
+        "VUNET_PASSWORD": "staging-password",
+        "VUNET_BU_ID": "1",
+        "VUNET_VERIFY_SSL": "true"
+      }
+    },
+    "vunet-dev": {
+      "command": "node",
+      "args": ["C:\\path\\to\\local\\vunet-mcp-server\\index.js"],
+      "env": {
+        "VUNET_TENANT_URL": "https://dev.company.com",
+        "VUNET_USERNAME": "dev-user",
+        "VUNET_PASSWORD": "dev-password",
+        "VUNET_BU_ID": "1",
+        "VUNET_VERIFY_SSL": "false"
+      }
+    }
+  }
+}
+```
+
+### Windows Path Format
+
+For local installations on Windows, use double backslashes or forward slashes:
+
+```json
+{
+  "command": "C:\\Program Files\\nodejs\\node.exe",
+  "args": ["C:\\Projects\\vunet-mcp-server\\index.js"]
+}
+```
+
+Or:
+
+```json
+{
+  "command": "C:/Program Files/nodejs/node.exe",
+  "args": ["C:/Projects/vunet-mcp-server/index.js"]
+}
+```
+
+---
+
+## 🛠️ Usage
+
+### Available Tools
+
+#### 1. `vunet_query_metric`
+
+Query any Vunet data model with flexible time ranges and filters.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description | Example |
+|-----------|------|----------|-------------|---------|
+| `metric_name` | string | ✅ | Data model name | `"Trace Map Data"` |
+| `relative_time` | string | ❌ | Relative time range | `"1h"`, `"24h"`, `"7d"` |
+| `start_time` | string | ❌ | Start timestamp | `"1770886639"`, `"now-1h"` |
+| `end_time` | string | ❌ | End timestamp | `"1770973039"`, `"now"` |
+| `filters` | object | ❌ | Dynamic filters | `{"service": "ibmb"}` |
+| `include` | string | ❌ | Include specific fields | `"timestamp,duration"` |
+| `exclude` | string | ❌ | Exclude specific fields | `"raw_data"` |
+| `thresholds` | boolean | ❌ | Include thresholds | `true` |
+| `formatting` | string | ❌ | Response format | `"lama"` |
+| `add_on_time_intervals` | array | ❌ | Additional time comparisons | `["1h_ago", "1d_ago"]` |
+| `time_shift` | string | ❌ | Time shift for comparison | `"1d"` |
+
+#### 2. `vunet_get_status`
+
+Get current connection status and tenant information.
+
+**Returns:**
+- Connection status
+- Tenant URL
+- Authentication status
+- Session expiry
+
+#### 3. `vunet_list_data_models`
+
+List common Vunet data models organized by category.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description | Example |
+|-----------|------|----------|-------------|---------|
+| `category` | string | ❌ | Filter by category | `"all"`, `"apm"`, `"infrastructure"`, `"database"` |
+
+**Categories:**
+- `all` - All data models (default)
+- `apm` - Application Performance Monitoring
+- `infrastructure` - Kubernetes, servers, system resources
+- `database` - Database performance metrics
+- `network` - Network monitoring
+- `business` - Business KPIs
+- `logs` - Log analytics
+- `security` - Security events
+
+**Returns:**
+- List of common data models by category
+- Total count of listed models
+- Usage instructions
+
+---
+
+### Query Examples
+
+#### Example 1: Get Traces (Last 2 Days)
+
+```
+Show me all traces from the last 2 days
+```
+
+**Behind the scenes:**
+```json
+{
+  "metric_name": "Trace Map Data",
+  "relative_time": "2d"
+}
+```
+
+#### Example 2: Filter Slow Traces
+
+```
+Show traces with duration > 5 seconds in the last 24 hours
+```
+
+**Post-processing with filters:**
+```json
+{
+  "metric_name": "Trace Map Data",
+  "relative_time": "24h"
+}
+```
+Then filter where `duration > 5000` (milliseconds)
+
+#### Example 3: Kubernetes Metrics
+
+```
+Get Kubernetes pod metrics for the last 15 minutes
+```
+
+```json
+{
+  "metric_name": "Kubernetes Pod Metrics",
+  "relative_time": "15m"
+}
+```
+
+#### Example 4: Transaction Volume by Service
+
+```
+Show transaction volume by service for last hour
+```
+
+```json
+{
+  "metric_name": "Traces Transaction Volume",
+  "relative_time": "1h",
+  "filters": {
+    "service": "ibmb"
+  }
+}
+```
+
+#### Example 5: Compare Performance (Time Shift)
+
+```
+Compare current hour performance with 1 day ago
+```
+
+```json
+{
+  "metric_name": "Trace Map Data",
+  "relative_time": "1h",
+  "time_shift": "1d"
+}
+```
+
+---
+
+## 📊 Data Models
+
+Common data models available (80+ total).
+
+> **📖 Complete Reference:** See [DATA_MODELS.md](DATA_MODELS.md) for comprehensive list and examples.
+
+> **🔧 Programmatic Access:** Use the `vunet_list_data_models` tool to get the curated list with category filtering.
+
+### Application Performance
+- `Trace Map Data` - Individual trace spans with duration
+- `Traces Transaction Volume` - Aggregated transaction counts
+- `Application Response Time` - Response time metrics
+- `Error Rate` - Error tracking and analysis
+
+### Infrastructure
+- `Kubernetes Pod Metrics` - Pod-level metrics
+- `Kubernetes Node Metrics` - Node-level metrics
+- `Kubernetes Deployment Metrics` - Deployment tracking
+- `CPU Usage` - CPU utilization
+- `Memory Usage` - Memory consumption
+- `Disk I/O` - Disk operations
+
+### Business Metrics
+- `VuBank Metrics` - Custom business metrics
+- `Transaction Success Rate` - Success/failure tracking
+- `User Sessions` - Session analytics
+
+### Database
+- `MySQL Performance` - MySQL metrics
+- `Hibernate Query Performance` - ORM performance
+
+### Custom
+- Custom data models defined in your tenant
+
+**Quick Discovery:**
+```
+# List all categories
+vunet_list_data_models
+
+# Filter by category
+vunet_list_data_models --category apm
+vunet_list_data_models --category infrastructure
+```
+
+**Natural Language:**
+```
+"What data models are available for APM?"
+"Show me infrastructure metrics"
+"List database performance models"
+```
+
+---
+
+## 🔐 Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VUNET_TENANT_URL` | ✅ | - | Vunet tenant URL (e.g., `https://tenant.com`) |
+| `VUNET_USERNAME` | ✅* | - | Username for authentication (*required if no bearer token) |
+| `VUNET_PASSWORD` | ✅* | - | Password for authentication (*required if no bearer token) |
+| `VUNET_BEARER_TOKEN` | ✅* | - | API bearer token (*required if no username/password) |
+| `VUNET_BU_ID` | ❌ | `"1"` | Business Unit ID |
+| `VUNET_VERIFY_SSL` | ❌ | `"true"` | Enable SSL verification (`"true"` or `"false"`) |
+
+**Security Note:** Never commit credentials to version control. Use environment variables or secure credential stores.
+
+### Authentication Methods
+
+**Method 1: Username/Password** (Auto-managed sessions)
+- The server automatically logs in and manages session tokens
+- Session tokens are refreshed automatically on expiry
+- Ideal for interactive use
+
+**Method 2: Bearer Token** (Long-lived API tokens)
+- Use pre-generated API tokens from Vunet
+- No session management needed
+- Ideal for CI/CD, automation, and service accounts
+- **How to get:** Generate from Vunet UI → Settings → API Tokens
+
+**Note:** Provide either `VUNET_USERNAME`+`VUNET_PASSWORD` **OR** `VUNET_BEARER_TOKEN`, not both.
+
+---
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### 1. "Node is not recognized as internal or external command"
+
+**Solution:** Add Node.js to your system PATH or use full path:
+
+```json
+{
+  "command": "C:\\Program Files\\nodejs\\node.exe",
+  "args": ["path\\to\\index.js"]
+}
+```
+
+#### 2. "Failed to authenticate to Vunet"
+
+**Check:**
+- ✅ Credentials are correct
+- ✅ Tenant URL is accessible
+- ✅ SSL verification settings match your environment
+- ✅ Business Unit ID is correct
+
+**Debug:**
+```bash
+# Test authentication manually
+curl -X POST https://your-tenant.com/vuSmartMaps/api/1/bu/1/auth/users/login/ \
+  -H "Content-Type: application/json" \
+  -d '{"username":"your-user","password":"your-pass"}'
+```
+
+#### 3. "SSL Certificate Verification Failed"
+
+**Solution:** For self-signed certificates or internal environments:
+
+```json
+{
+  "env": {
+    "VUNET_VERIFY_SSL": "false"
+  }
+}
+```
+
+#### 4. MCP Server Not Showing in VS Code
+
+**Steps:**
+1. Check `.vscode/mcp.json` or `settings.json` syntax
+2. Reload VS Code window (`Ctrl+Shift+P` → "Developer: Reload Window")
+3. Check VS Code output panel for errors
+4. Verify package is installed: `npm list -g @vunet/mcp-server`
+
+#### 5. Empty or Missing Data
+
+**Check:**
+- ✅ Data model name is correct (case-sensitive)
+- ✅ Time range has data
+- ✅ Filters are not too restrictive
+- ✅ Fields exist in the data model
+
+---
+
+## 📚 Examples
+
+### Example 1: Performance Analysis
+
+```
+Create a report of all traces taking more than 5 seconds in the last 2 days
+```
+
+**Result:** HTML report with:
+- Slowest traces ranked
+- Performance percentiles
+- Error analysis
+- Recommendations
+
+### Example 2: Multi-Tenant Monitoring
+
+**Production:**
+```
+@vunet-production show error rate for last hour
+```
+
+**Staging:**
+```
+@vunet-staging compare current performance with 1 day ago
+```
+
+### Example 3: Kubernetes Dashboard
+
+```
+Create a Kubernetes dashboard showing pod health for the last 30 minutes
+```
+
+**Result:** Interactive HTML dashboard with metrics visualization
+
+---
+
+## 🔧 Development
+
+### Run Locally
+
+```bash
+git clone https://github.com/vunet-systems/vunet-mcp-server.git
+cd vunet-mcp-server
+npm install
+
+# Set environment variables
+export VUNET_TENANT_URL="https://your-tenant.com"
+export VUNET_USERNAME="your-username"
+export VUNET_PASSWORD="your-password"
+
+# Run
+npm start
+```
+
+### Watch Mode (Development)
+
+```bash
+npm run dev
+```
+
+### Package for Distribution
+
+```bash
+npm pack
+```
+
+---
+
+## 📝 API Reference
+
+### VunetMCPServer Class
+
+```javascript
+class VunetMCPServer {
+  constructor()
+  async login()
+  async logout()
+  async ensureAuthenticated()
+  async queryMetric(metricName, queryParams)
+  buildQueryParams(args)
+  normalizeTenantUrl(url)
+}
+```
+
+### Query Response Format
+
+```json
+{
+  "metricData": [
+    {
+      "start_time": 1770886639,
+      "end_time": 1770973039,
+      "label": "Primary relative time",
+      "data": [
+        {
+          "timestamp": "2026-02-13 07:02:18.494",
+          "field1": "value1",
+          "field2": "value2"
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Commit changes: `git commit -m 'Add amazing feature'`
+4. Push to branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+---
+
+## 🙏 Acknowledgments
+
+- Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
+- Inspired by [Dynatrace MCP Server](https://github.com/dynatrace/mcp-server)
+- Powered by [Vunet vuSmartMaps](https://vunetsystems.com)
+
+---
+
+## 🔗 Links
+
+- **Vunet Systems:** https://vunetsystems.com
+- **MCP Protocol:** https://modelcontextprotocol.io
+- **npm Package:** https://www.npmjs.com/package/@vunet/mcp-server
+- **GitHub:** https://github.com/vunet-systems/vunet-mcp-server
+- **Issues:** https://github.com/vunet-systems/vunet-mcp-server/issues
+
+---
+
+## 📞 Support
+
+- **Documentation:** [GitHub Wiki](https://github.com/vunet-systems/vunet-mcp-server/wiki)
+- **Issues:** [GitHub Issues](https://github.com/vunet-systems/vunet-mcp-server/issues)
+- **Email:** support@vunetsystems.com
+
+---
+
+**Made with ❤️ by Vunet Systems**