Metadata-Version: 2.4
Name: instana-watsonx-wrapper
Version: 2.0.4
Summary: WatsonX-compatible wrapper for Instana MCP server with comprehensive read tools
Project-URL: Homepage, https://github.com/your-org/instana-watsonx-wrapper
Project-URL: Repository, https://github.com/your-org/instana-watsonx-wrapper
Author: DB2 DBA Team
Keywords: infrastructure,instana,mcp,monitoring,watsonx
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Instana WatsonX Wrapper v2.0.0

A WatsonX-compatible MCP server wrapper for Instana monitoring with comprehensive read-only tools.

## Overview

This wrapper solves the WatsonX MCP client bug that auto-parses JSON string parameters. It provides 11 essential read-only tools for monitoring infrastructure, events, dashboards, and websites.

### The Problem

WatsonX's MCP client has a bug where it:
1. Auto-parses JSON strings to objects
2. Removes parameter name wrappers
3. Breaks the MCP protocol specification

This makes the official `mcp-instana` package incompatible with WatsonX.

### The Solution

This wrapper:
- Accepts parameters as **objects** (what WatsonX sends)
- Calls Instana REST API directly
- Returns properly formatted results
- Provides 11 essential read-only tools

## Features

### ✅ 11 Read-Only Tools

**Infrastructure Analysis**
- `analyze_infrastructure` - Query metrics for hosts, databases, JVMs, etc.

**Event Monitoring**
- `get_event` - Get specific event by ID
- `get_issues` - Get issue events
- `get_incidents` - Get incident events
- `get_changes` - Get change events
- `get_kubernetes_info_events` - Get Kubernetes events

**Dashboard Management**
- `get_custom_dashboards` - List all custom dashboards
- `get_custom_dashboard` - Get specific dashboard by ID

**Website Monitoring**
- `get_websites` - List all monitored websites
- `get_website` - Get specific website by ID
- `get_website_beacons` - Get website performance beacons

### ✅ WatsonX Compatible

- Works with WatsonX Orchestrator Cloud
- No JSON string parsing issues
- Simple object parameters
- Reliable and predictable

### ✅ Production Ready

- Direct REST API calls (no SDK dependency issues)
- Proper error handling
- Type hints throughout
- Comprehensive documentation

## Installation

### Option 1: From PyPI (Recommended)

```bash
pip install instana-watsonx-wrapper
```

### Option 2: From Source

```bash
git clone <repository-url>
cd instana-watsonx-wrapper
pip install -e .
```

## Quick Start

### 1. Set Environment Variables

```bash
export INSTANA_BASE_URL="https://your-instance.instana.io"
export INSTANA_API_TOKEN="your_api_token"
```

### 2. Run the Server

```bash
python -m instana_watsonx_wrapper.server
```

### 3. Import to WatsonX

1. Go to WatsonX Orchestrator Cloud
2. Navigate to **Connections** → **Add Connection**
3. Select **MCP Server**
4. Configure:
   - **Name**: Instana Monitoring
   - **Command**: `python -m instana_watsonx_wrapper.server`
   - **Environment Variables**:
     - `INSTANA_BASE_URL`: Your Instana URL
     - `INSTANA_API_TOKEN`: Your API token

### 4. Test with Agent

Create an agent and add the Instana toolkit. Test with:

```
"List all databases on server t3992-dev1-db-node01-par01-dev"
```

## Tool Reference

### 1. analyze_infrastructure

Query infrastructure metrics from Instana.

**Parameters:**
- `entity_type` (required): Entity type (e.g., "db2Database", "host", "jvmRuntimePlatform")
- `metrics` (required): List of metric names
- `aggregation` (required): Aggregation type ("mean", "sum", "max", "min")
- `filters` (optional): List of filters with name/value pairs
- `group_by` (optional): List of tag names to group by
- `time_range` (optional): Time range string (e.g., "1h", "24h", "7d")
- `order_by` (optional): Metric name to order by
- `order_direction` (optional): Sort direction ("ASC" or "DESC")

**Example:**
```json
{
  "entity_type": "db2Database",
  "metrics": ["databases.status", "databases.connectionsCount"],
  "aggregation": "mean",
  "filters": [{"name": "host.name", "value": "server1"}],
  "group_by": ["db2.name"],
  "time_range": "7d"
}
```

### 2. get_event

Get a specific event by ID.

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

**Example:**
```json
{
  "event_id": "abc123"
}
```

### 3. get_issues

Get issue events from Instana.

**Parameters:**
- `from_time` (optional): Start timestamp in milliseconds
- `to_time` (optional): End timestamp in milliseconds
- `time_range` (optional): Natural language time range (e.g., "1h", "24h", "7d")
- `max_events` (optional): Maximum events to return (default: 50)

**Example:**
```json
{
  "time_range": "24h",
  "max_events": 100
}
```

### 4. get_incidents

Get incident events from Instana.

**Parameters:** Same as `get_issues`

### 5. get_changes

Get change events from Instana.

**Parameters:** Same as `get_issues`

### 6. get_kubernetes_info_events

Get Kubernetes info events from Instana.

**Parameters:** Same as `get_issues`

### 7. get_custom_dashboards

Get all custom dashboards.

**Parameters:** None

### 8. get_custom_dashboard

Get a specific custom dashboard by ID.

**Parameters:**
- `dashboard_id` (required): Dashboard ID

**Example:**
```json
{
  "dashboard_id": "dashboard123"
}
```

### 9. get_websites

Get all monitored websites.

**Parameters:** None

### 10. get_website

Get a specific website by ID.

**Parameters:**
- `website_id` (required): Website ID

**Example:**
```json
{
  "website_id": "website123"
}
```

### 11. get_website_beacons

Get website performance beacons.

**Parameters:**
- `website_name` (optional): Website name to filter by
- `beacon_type` (optional): Beacon type (default: "PAGELOAD")
- `time_range` (optional): Time range string (default: "1h")

**Example:**
```json
{
  "website_name": "my-app",
  "beacon_type": "PAGELOAD",
  "time_range": "24h"
}
```

## Common Use Cases

### Monitor Database Health

```
"Show me the status and connection count for all databases on server X over the last 7 days"
```

Agent will use:
```json
{
  "entity_type": "db2Database",
  "metrics": ["databases.status", "databases.connectionsCount"],
  "aggregation": "mean",
  "filters": [{"name": "host.name", "value": "server-x"}],
  "group_by": ["db2.name"],
  "time_range": "7d"
}
```

### Check Recent Incidents

```
"Show me all incidents from the last 24 hours"
```

Agent will use:
```json
{
  "time_range": "24h"
}
```

### Monitor Website Performance

```
"Show me page load beacons for my-app website in the last hour"
```

Agent will use:
```json
{
  "website_name": "my-app",
  "beacon_type": "PAGELOAD",
  "time_range": "1h"
}
```

## Comparison with Official Package

| Aspect | Official mcp-instana | This Wrapper |
|--------|---------------------|--------------|
| **WatsonX** | ❌ Broken (parameter bug) | ✅ Works |
| **Tools** | 46+ tools | 11 essential read tools |
| **Complexity** | High (SDK dependencies) | Low (direct REST API) |
| **Maintenance** | Complex | Simple |
| **Use Case** | All operations | Read-only monitoring |
| **Dependencies** | instana-python-sdk | requests only |

## Troubleshooting

### Connection Issues

**Problem**: "Missing required environment variables"

**Solution**: Ensure both environment variables are set:
```bash
export INSTANA_BASE_URL="https://your-instance.instana.io"
export INSTANA_API_TOKEN="your_api_token"
```

### API Errors

**Problem**: "401 Unauthorized"

**Solution**: Verify your API token has the correct permissions in Instana.

### Time Range Issues

**Problem**: No data returned

**Solution**: Try different time ranges:
- Use "7d" for databases (they update less frequently)
- Use "1h" for real-time metrics
- Use "24h" for events

## Development

### Running Tests

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

# Run tests
pytest
```

### Building Package

```bash
# Install build tools
pip install build twine

# Build package
python -m build

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

## Architecture

```
WatsonX Agent
    ↓
    ↓ (sends object parameters)
    ↓
Instana WatsonX Wrapper
    ↓
    ↓ (converts to REST API calls)
    ↓
Instana REST API
    ↓
    ↓ (returns JSON)
    ↓
WatsonX Agent (receives formatted results)
```

## Version History

### v2.0.0 (Current)
- Added 10 new read-only tools
- Infrastructure analysis
- Event monitoring (issues, incidents, changes, Kubernetes)
- Dashboard management
- Website monitoring
- Direct REST API calls (no SDK dependency)

### v1.0.1
- Fixed tool name bug
- Single tool: analyze_infrastructure_elicitation

### v1.0.0
- Initial release
- Single tool with wrong name

## License

MIT License

## Support

For issues and questions:
1. Check the troubleshooting section
2. Review the tool reference
3. Test with the official Instana API documentation
4. Submit bug reports with detailed error messages

## Contributing

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

## Acknowledgments

- Built to work around WatsonX MCP client limitations
- Uses Instana REST API directly for reliability
- Designed for production DB2 DBA monitoring workflows