Metadata-Version: 2.4
Name: instana-proxy-wrapper
Version: 1.0.1
Summary: Proxy wrapper for official mcp-instana server that fixes WatsonX JSON stringification bug
Project-URL: Homepage, https://github.com/your-org/instana-proxy-wrapper
Project-URL: Repository, https://github.com/your-org/instana-proxy-wrapper
Author: DB2 DBA Team
Keywords: instana,mcp,proxy,watsonx,wrapper
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
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 Proxy Wrapper for WatsonX

A transparent proxy that sits between WatsonX Orchestrator and the official `mcp-instana` server, fixing WatsonX's JSON stringification bug while providing access to all 46 Instana tools.

## 🎯 Problem Solved

**WatsonX Bug**: WatsonX's MCP client auto-parses JSON string parameters, breaking the official `mcp-instana` server which expects JSON strings.

**Solution**: This proxy:
1. Accepts objects from WatsonX (after auto-parsing)
2. Converts them back to JSON strings
3. Forwards to official `mcp-instana` server
4. Returns results to WatsonX

## ✨ Features

- ✅ **All 46 Tools**: Full access to official `mcp-instana` tools
- ✅ **Zero Configuration**: Automatically starts and manages `mcp-instana` server
- ✅ **Transparent Proxy**: No changes needed to tool calls
- ✅ **WatsonX Compatible**: Fixes JSON stringification bug
- ✅ **Easy Installation**: Single package install

## 📦 Installation

### Prerequisites

1. Install `mcp-instana` (the official server):
```bash
pip install mcp-instana
```

2. Set environment variables:
```bash
export INSTANA_BASE_URL="https://your-tenant.instana.io"
export INSTANA_API_TOKEN="your_api_token"
```

### Install Proxy

```bash
pip install instana-proxy-wrapper
```

## 🚀 Usage

### Import to WatsonX Cloud

```
1. Go to Skills → Import
2. Select "MCP Server"
3. Package name: instana-proxy-wrapper
4. Version: 1.0.0
5. Click Import
```

### Environment Variables

The proxy requires the same environment variables as `mcp-instana`:

```bash
INSTANA_BASE_URL=https://your-tenant.instana.io
INSTANA_API_TOKEN=your_api_token
```

Set these in your WatsonX Cloud environment.

### Local Testing

```bash
# Set credentials
export INSTANA_BASE_URL="https://your-tenant.instana.io"
export INSTANA_API_TOKEN="your_api_token"

# Run the proxy
python -m instana_proxy_wrapper.server
```

## 🔧 How It Works

### Architecture

```
WatsonX → Proxy Wrapper → Official mcp-instana → Instana API
          (Fixes JSON)     (46 tools)
```

### JSON Fix Example

**WatsonX sends** (after auto-parsing):
```python
{
    "payload": {
        "metrics": ["cpu.utilization"],
        "timeFrame": {"windowSize": 3600000}
    }
}
```

**Proxy converts to**:
```python
{
    "payload": '{"metrics": ["cpu.utilization"], "timeFrame": {"windowSize": 3600000}}'
}
```

**Official server receives**: JSON string (as expected)

## 📋 Available Tools

All 46 tools from `mcp-instana` are available:

### Infrastructure Tools
- `analyze_infrastructure_elicitation` - Two-pass infrastructure analysis
- `get_action_matches` - Get automation action matches
- `get_actions` - List automation actions
- `get_action_details` - Get action details
- And 42 more...

### Application Tools
- `manage_instana_resources` - Unified resource manager
- Application metrics, alerts, configurations

### Event Tools
- `get_event` - Get specific event
- `get_issues` - Get issue events
- `get_incidents` - Get incident events
- `get_changes` - Get change events
- `get_kubernetes_info_events` - Get K8s events

### Dashboard Tools
- `manage_custom_dashboards` - CRUD operations
- `get_custom_dashboards` - List dashboards
- `get_custom_dashboard` - Get specific dashboard

### Website Monitoring Tools
- `get_websites` - List websites
- `get_website` - Get specific website
- `get_website_beacons` - Get website beacons
- And more...

## 🧪 Testing

### Test Infrastructure Query

```python
# Query DB2 databases
{
    "entity_type": "db2Database",
    "metrics": ["db2.name"],
    "aggregation": "sum",
    "filters": [
        {
            "name": "host.name",
            "value": "your-hostname"
        }
    ],
    "group_by": ["db2.name"],
    "time_range": "7d"
}
```

### Test Two-Pass Analysis

**Pass 1** - Get schema:
```python
{
    "intent": "maximum heap size of JVM on host galactica1",
    "entity": "jvm"
}
```

**Pass 2** - Get results:
```python
{
    "selections": {
        "entity_type": "jvmRuntimePlatform",
        "metrics": ["jvm.heap.maxSize"],
        "aggregation": "max",
        "filters": [{"name": "host.name", "value": "galactica1"}]
    }
}
```

## 🐛 Troubleshooting

### Issue: Proxy won't start

**Error**: "Missing required environment variables"

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

### Issue: Tools not working

**Error**: Tool calls fail

**Solution**: Ensure `mcp-instana` is installed:
```bash
pip install mcp-instana
```

### Issue: Import fails in WatsonX

**Error**: "Package not found"

**Solution**: Wait 5-10 minutes for PyPI CDN propagation

## 📊 Comparison

| Feature | instana-proxy-wrapper | instana-watsonx-wrapper |
|---------|----------------------|------------------------|
| Tools | 46 (all from mcp-instana) | 11 (custom subset) |
| Metric Discovery | ✅ Yes | ❌ No |
| Two-Pass Analysis | ✅ Yes | ❌ No |
| Complexity | Low (transparent proxy) | Medium (custom implementation) |
| Maintenance | Low (follows mcp-instana) | High (manual updates) |
| Use Case | Full Instana access | Simple queries only |

## 🎯 When to Use

### Use Proxy Wrapper When:
- ✅ Need all 46 Instana tools
- ✅ Need metric discovery
- ✅ Need two-pass infrastructure analysis
- ✅ Want automatic updates with mcp-instana
- ✅ Need complex queries

### Use Direct Wrapper When:
- ✅ Only need 11 basic tools
- ✅ Know exact metrics to query
- ✅ Want simpler implementation
- ✅ Don't need advanced features

## 📚 Documentation

- [Official mcp-instana Documentation](https://github.com/instana/mcp-instana)
- [WatsonX Orchestrator Documentation](https://www.ibm.com/docs/en/watsonx/watson-orchestrate)
- [MCP Protocol Specification](https://modelcontextprotocol.io)

## 🤝 Contributing

This is a simple proxy wrapper. For tool improvements, contribute to the official `mcp-instana` project.

## 📝 License

MIT License - See LICENSE file for details

## 🙏 Acknowledgments

- Official `mcp-instana` server by Instana team
- Model Context Protocol by Anthropic
- WatsonX Orchestrator by IBM

---

**Made with Bob - Your AI Software Engineer**