Metadata-Version: 2.4
Name: instana-wrapper-mcp-server
Version: 1.1.2
Summary: Instana MCP wrapper - simple pass-through to Instana MCP server
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/instana-wrapper-mcp-server
Project-URL: Repository, https://github.com/yourusername/instana-wrapper-mcp-server
Project-URL: Issues, https://github.com/yourusername/instana-wrapper-mcp-server/issues
Keywords: mcp,instana,watsonx,monitoring,observability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=0.9.0
Requires-Dist: mcp-instana==0.7.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# Instana Wrapper MCP Server

A Model Context Protocol (MCP) server that wraps the Instana MCP toolkit with simplified, WatsonX-compatible interfaces. This wrapper solves parameter stringification issues and provides user-friendly tool interfaces for infrastructure monitoring, application performance, and event management.

## Version 1.1.0 - Phase 1 Expansion

**Tool Coverage**: 13 tools (28.3% of 46 total Instana tools)

### What's New in v1.1.0
- ✨ **8 new tools** added (Phase 1 expansion)
- 🎯 **Flexible infrastructure monitoring** for any entity type
- 🔍 **Event management** with batch retrieval and detailed analysis
- 📊 **Dashboard management** with full CRUD operations
- 🌐 **Website monitoring** with beacon and metrics support
- ☸️ **Kubernetes events** with automatic problem detection

## Features

### Infrastructure Monitoring
- **get_infrastructure_metrics**: Query any entity type (hosts, databases, containers, K8s nodes)
  - Multi-metric queries (up to 10 metrics)
  - Flexible filtering by any tag
  - Optional grouping for discovery
  - Time range support (1h, 24h, 7d, etc.)

- **get_host_metrics**: Simplified host monitoring (CPU, memory, disk)
- **get_application_metrics**: Application performance (calls, latency, errors)

### Event Management
- **get_incidents**: Critical incidents and alerts
- **get_issues**: Warnings and issues
- **get_changes**: Deployment and configuration changes
- **get_event_details**: Detailed event information by ID
- **get_events_by_ids**: Batch event retrieval
- **get_kubernetes_events**: K8s events with analysis
- **get_agent_monitoring_events**: Agent health monitoring

### Dashboard Management
- **manage_dashboards**: Full CRUD operations
  - get_all: List all dashboards
  - get: Get specific dashboard
  - create: Create new dashboard
  - update: Update existing dashboard
  - delete: Remove dashboard

### Website Monitoring
- **get_website_beacons**: Retrieve website beacons
- **get_website_metrics**: Grouped website metrics (page load, errors)

## Installation

### From PyPI
```bash
pip install instana-wrapper-mcp-server
```

### From Source
```bash
git clone <repository-url>
cd instana-wrapper-mcp-server
pip install -e .
```

## Configuration

### Hardcoded Credentials (Demo Mode)
The wrapper includes hardcoded Instana credentials for quick demos:
- **API Token**: `ixAVRRLLQSS1P2W1cDSA7A`
- **Base URL**: `https://cp4ba-dbainternal.instana.io`

### Environment Variables (Production)
For production use, set environment variables:
```bash
export INSTANA_API_TOKEN="your-token"
export INSTANA_BASE_URL="https://your-instana-instance.io"
```

## Usage Examples

### 1. Infrastructure Monitoring - DB2 Database Health

**Query 8 key DB2 metrics for PDWDBT database:**
```json
{
  "entity_type": "db2Database",
  "metrics": "[\"databases.connectionsCount\", \"databases.queries\", \"databases.commits\", \"databases.rollbacks\", \"vmonlockstats.deadlocks\", \"vmonlockstats.activeLockWaits\", \"databases.rowsRead\", \"databases.rowsReturned\"]",
  "filters": "[{\"name\": \"host.name\", \"value\": \"t3992-dev1-db-node01-par01-dev\"}, {\"name\": \"db2.name\", \"value\": \"PDWDBT\"}]",
  "aggregation": "mean",
  "time_range": "1h"
}
```

**Result:**
- Connections: 3.5
- Queries: 386.8/sec
- Commits: 103.5/sec
- Rollbacks: 0.0
- Deadlocks: 0.0 ✅
- Lock Waits: 0.0 ✅
- Rows Read: 1,088,000/sec
- Rows Returned: 1,088,000/sec

### 2. Database Discovery

**List all databases on a host:**
```json
{
  "entity_type": "db2Database",
  "metrics": "[\"databases.connectionsCount\"]",
  "filters": "[{\"name\": \"host.name\", \"value\": \"t3992-dev1-db-node01-par01-dev\"}]",
  "group_by": "[\"db2.name\"]",
  "time_range": "24h"
}
```

**Result:** 16 databases discovered (PDWDBT, PDWDBT2, ..., PDWDBT16)

### 3. Host Resource Monitoring

**Check CPU, memory, and disk:**
```json
{
  "hostname": "t3992-dev1-db-node01-par01-dev",
  "metrics": "[\"cpu.used\", \"memory.used\", \"memory.available\", \"disk.used\", \"disk.available\"]",
  "time_range": "1h"
}
```

**Result:**
- CPU: 93.3% ⚠️ (High)
- Memory: 88.7% ⚠️ (High)
- Available Memory: 3.8 GB

### 4. Application Performance

**Get top endpoints for an application:**
```json
{
  "application_name": "t2916-dev1-cpe-sso",
  "metrics": "[{\"metric\": \"calls\", \"aggregation\": \"SUM\"}, {\"metric\": \"latency\", \"aggregation\": \"MEAN\"}]",
  "time_range": "1h"
}
```

### 5. Event Management

**Get incident details:**
```json
{
  "event_id": "abc123xyz"
}
```

**Get multiple events:**
```json
{
  "event_ids": "event1,event2,event3"
}
```

**Get Kubernetes events:**
```json
{
  "time_range": "last 24 hours",
  "max_events": 50
}
```

### 6. Dashboard Management

**List all dashboards:**
```json
{
  "operation": "get_all"
}
```

**Get specific dashboard:**
```json
{
  "operation": "get",
  "dashboard_id": "dashboard-123"
}
```

**Create dashboard:**
```json
{
  "operation": "create",
  "dashboard_config": "{\"title\": \"My Dashboard\", \"widgets\": []}"
}
```

### 7. Website Monitoring

**Get website beacons:**
```json
{
  "website_name": "robot-shop",
  "beacon_type": "PAGELOAD",
  "time_range": "1h"
}
```

**Get website metrics:**
```json
{
  "website_name": "robot-shop",
  "metrics": "[\"beaconCount\", \"pageLoadTime\"]",
  "group_by": "beacon.page.name",
  "time_range": "1h"
}
```

## Tool Reference

### Infrastructure Monitoring Tools

#### get_infrastructure_metrics
**Most flexible tool** - Query any entity type with multiple metrics and filters.

**Parameters:**
- `entity_type` (required): Entity type (e.g., "host", "db2Database", "dockerContainer")
- `metrics` (required): JSON array of metric names
- `filters` (required): JSON array of filter objects with name/value
- `aggregation` (optional): "mean", "max", "min", "sum" (default: "mean")
- `time_range` (optional): "1h", "24h", "7d" (default: "1h")
- `group_by` (optional): JSON array of tag names for grouping

**Use Cases:**
- DB2 health monitoring (8 metrics)
- Database discovery (groupBy db2.name)
- Container monitoring
- Kubernetes node monitoring

#### get_host_metrics
**Simplified host monitoring** - Quick CPU, memory, disk checks.

**Parameters:**
- `hostname` (required): Hostname or IP
- `metrics` (required): JSON array of metrics
- `time_range` (optional): Time range (default: "1h")

#### get_application_metrics
**Application performance** - Calls, latency, errors.

**Parameters:**
- `application_name` (required): Application name
- `metrics` (required): JSON array of metrics
- `time_range` (optional): Time range (default: "1h")

### Event Management Tools

#### get_incidents
Get critical incidents and alerts.

**Parameters:**
- `query` (optional): Filter query
- `time_range` (optional): Time range (default: "24h")
- `max_results` (optional): Max results (default: 50)

#### get_issues
Get warnings and issues.

**Parameters:** Same as get_incidents

#### get_changes
Get deployment and configuration changes.

**Parameters:** Same as get_incidents

#### get_event_details
Get detailed information about a specific event.

**Parameters:**
- `event_id` (required): Event ID

#### get_events_by_ids
Get multiple events in a single request.

**Parameters:**
- `event_ids` (required): Comma-separated IDs or JSON array

#### get_kubernetes_events
Get Kubernetes info events with analysis.

**Parameters:**
- `time_range` (optional): Natural language (default: "last 24 hours")
- `max_events` (optional): Max events (default: 50)

#### get_agent_monitoring_events
Get agent monitoring events.

**Parameters:**
- `query` (optional): Query string
- `time_range` (optional): Natural language (default: "last 24 hours")
- `max_events` (optional): Max events (default: 50)

### Dashboard Management Tools

#### manage_dashboards
Full CRUD operations for custom dashboards.

**Parameters:**
- `operation` (required): "get_all", "get", "create", "update", "delete"
- `dashboard_id` (optional): Required for get, update, delete
- `dashboard_config` (optional): Required for create, update

### Website Monitoring Tools

#### get_website_beacons
Get website monitoring beacons.

**Parameters:**
- `website_name` (required): Website name
- `beacon_type` (optional): "PAGELOAD", "ERROR", "RESOURCE" (default: "PAGELOAD")
- `time_range` (optional): Time range (default: "1h")

#### get_website_metrics
Get grouped website metrics.

**Parameters:**
- `website_name` (required): Website name
- `metrics` (required): JSON array of metrics
- `group_by` (optional): Tag to group by (default: "beacon.page.name")
- `time_range` (optional): Time range (default: "1h")

## WatsonX Integration

### Import to WatsonX Orchestrator

1. **Via GUI:**
   - Navigate to Skills → Import
   - Select "MCP Toolkit"
   - Enter: `uvx instana-wrapper-mcp-server==1.1.0 --transport stdio`
   - Click Import

2. **Via CLI:**
   ```bash
   wxo toolkit import \
     --name "Instana Monitoring" \
     --command "uvx instana-wrapper-mcp-server==1.1.0 --transport stdio"
   ```

### Agent Training Tips

1. **Proactive Metric Selection**: Train agent to automatically select useful metrics
   - DB2 Health: 8 metrics (connections, queries, commits, rollbacks, deadlocks, lock waits, rows)
   - Host Resources: 5 metrics (CPU, memory used/available, disk used/available)

2. **Tool Selection Rules**:
   - Infrastructure keywords (host, server, CPU, memory, database) → `get_infrastructure_metrics`
   - Application keywords (application, service, endpoint, API) → `get_application_metrics`

3. **Multi-Metric Queries**: Agent can query up to 10 metrics simultaneously

4. **Natural Language Time Ranges**: Support "last 24 hours", "last 2 days", etc.

## Architecture

```
┌─────────────────────────────────────────┐
│   WatsonX Orchestrator / Bob            │
│   (Calls wrapper tools)                 │
└──────────────┬──────────────────────────┘
               │
               │ MCP Protocol
               │
┌──────────────▼──────────────────────────┐
│   Instana Wrapper MCP Server (v1.1.0)   │
│   - 13 simplified tools                 │
│   - Parameter normalization             │
│   - JSON parsing                        │
└──────────────┬──────────────────────────┘
               │
               │ MCP Protocol
               │
┌──────────────▼──────────────────────────┐
│   Original Instana MCP Server (v0.7.1)  │
│   - 46 native tools                     │
│   - Direct Instana API calls            │
└──────────────┬──────────────────────────┘
               │
               │ REST API
               │
┌──────────────▼──────────────────────────┐
│   Instana Backend                       │
│   - Metrics storage                     │
│   - Event management                    │
│   - Dashboard configuration             │
└─────────────────────────────────────────┘
```

## Development

### Building from Source
```bash
# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Build package
python -m build

# Upload to PyPI
python -m twine upload dist/*
```

### Testing Locally
```bash
# Test with Bob (MCP client)
# Add to Bob's MCP settings:
{
  "mcpServers": {
    "instana-wrapper": {
      "command": "uvx",
      "args": ["instana-wrapper-mcp-server==1.1.0", "--transport", "stdio"]
    }
  }
}
```

## Roadmap

### Phase 2 (Planned)
Add remaining 33 tools for complete 46-tool coverage:

- **Action Catalog** (4 tools): Automation actions, action matches, execution
- **Application Resources** (13 tools): Alert configs, perspectives, services, endpoints
- **Custom Dashboards** (5 tools): Shareable users/tokens, advanced operations
- **Website Monitoring** (11 tools): Configuration, source maps, IP masking, geo-location

**Target**: 100% tool coverage (46/46 tools)

## Troubleshooting

### Common Issues

1. **"Unknown tool" error**
   - Ensure you're using v1.1.0 or later
   - Check tool name spelling

2. **"Invalid JSON" error**
   - Ensure JSON strings are properly escaped
   - Use single quotes around JSON in shell commands

3. **Empty results**
   - Check time range (may need longer range)
   - Verify filter values (hostname, database name)
   - Ensure entity exists in Instana

4. **Connection timeout**
   - Verify Instana credentials
   - Check network connectivity
   - Ensure Instana instance is accessible

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## License

MIT License - See LICENSE file for details

## Support

- **Issues**: GitHub Issues
- **Documentation**: See CHANGELOG.md for version history
- **Examples**: See INSTANA_DB2_AGENT_TESTING_GUIDE.md

## Acknowledgments

Built on top of the excellent [mcp-instana](https://github.com/instana/mcp-instana) toolkit.

---

**Version**: 1.1.0  
**Last Updated**: 2026-04-13  
**Status**: Phase 1 Complete (13/46 tools)
