Metadata-Version: 2.4
Name: instana-comprehensive-wrapper
Version: 1.0.1
Summary: Comprehensive Instana MCP wrapper with all 46+ tools - WatsonX compatible
Author-email: DB2 DBA Team <dba@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/instana-comprehensive-wrapper
Project-URL: Repository, https://github.com/yourusername/instana-comprehensive-wrapper
Project-URL: Issues, https://github.com/yourusername/instana-comprehensive-wrapper/issues
Keywords: mcp,instana,watsonx,monitoring,observability,db2
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 Comprehensive Wrapper

A comprehensive MCP (Model Context Protocol) wrapper for all 46+ Instana monitoring tools, designed for seamless integration with WatsonX Orchestrator Cloud.

## 🎯 Key Features

- **Complete Coverage**: All 46+ tools from official `mcp-instana==0.7.1` server
- **WXO Cloud Compatible**: Designed to work with WatsonX Orchestrator connections
- **No Hardcoded Credentials**: Relies on environment variables from WXO Cloud
- **Simple Pass-Through**: Direct mapping to official Instana tools
- **Production Ready**: Clean architecture, proper error handling

## 📦 Installation

### For WatsonX Orchestrator Cloud

```bash
# Import as toolkit
Package: instana-comprehensive-wrapper==1.0.1
Command: uvx instana-comprehensive-wrapper==1.0.1 --transport stdio
Connection: Select your Instana connection (with INSTANA_API_TOKEN and INSTANA_BASE_URL)
```

### For Local Development

```bash
pip install instana-comprehensive-wrapper
```

## 🛠️ Available Tools (46+ Tools)

### Infrastructure Monitoring (1 tool)
- `analyze_infrastructure_elicitation` - Two-pass infrastructure analysis for any entity type

### Event Monitoring (8 tools)
- `get_event` - Get specific event details by ID
- `get_kubernetes_info_events` - Kubernetes events with analysis
- `get_agent_monitoring_events` - Agent monitoring events
- `get_issues` - Warning and issue events
- `get_incidents` - Critical incident events
- `get_changes` - Deployment and configuration changes
- `get_events_by_ids` - Batch event retrieval

### Automation/Actions (9 tools)
- `get_action_matches` - Find matching actions for scenarios
- `get_actions` - List all available actions
- `get_action_details` - Get action details by ID
- `get_action_types` - List action types
- `get_action_tags` - List action tags
- `submit_automation_action` - Execute automation action
- `get_action_instance_details` - Get action run details
- `list_action_instances` - List action run history
- `delete_action_instance` - Delete action run result

### Dashboard Management (1 tool)
- `manage_custom_dashboards` - Complete dashboard CRUD operations

### Application Resources (1 tool)
- `manage_instana_resources` - Unified resource manager for metrics, alerts, settings, catalog

### Website Monitoring (26 tools)
- `get_website_beacon_groups` - Grouped website metrics
- `get_website_beacons` - All website beacons
- `get_website_catalog_metrics` - Metrics catalog
- `get_website_catalog_tags` - Tags catalog
- `get_website_tag_catalog` - Tag catalog for beacon type
- `get_websites` - List all websites
- `get_website` - Get website by ID
- `create_website` - Create new website
- `delete_website` - Delete website
- `rename_website` - Rename website
- `get_website_geo_location_configuration` - Get geo-location config
- `update_website_geo_location_configuration` - Update geo-location config
- `get_website_ip_masking_configuration` - Get IP masking config
- `update_website_ip_masking_configuration` - Update IP masking config
- `get_website_geo_mapping_rules` - Get geo mapping rules
- `set_website_geo_mapping_rules` - Set geo mapping rules
- `upload_source_map_file` - Upload source map
- `clear_source_map_upload_configuration` - Clear source map config
- `get_website_page_load` - Get page load details
- `get_website_beacon_metrics_v2` - Get beacon metrics (v2 API)

## 🚀 Usage Examples

### Infrastructure Monitoring

```python
# Query host metrics
{
  "tool": "analyze_infrastructure_elicitation",
  "arguments": {
    "selections": {
      "entity_type": "host",
      "metrics": ["cpu.used", "memory.used"],
      "aggregation": "mean",
      "filters": [{"name": "host.name", "value": "my-server"}],
      "timeRange": "6h"
    }
  }
}
```

### Database Discovery

```python
# List all databases on a host
{
  "tool": "analyze_infrastructure_elicitation",
  "arguments": {
    "selections": {
      "entity_type": "db2Database",
      "metrics": ["db2.database.name"],
      "aggregation": "mean",
      "filters": [{"name": "host.name", "value": "db-server"}],
      "timeRange": "1h",
      "groupBy": ["db2.database.name"]
    }
  }
}
```

### Event Monitoring

```python
# Get incidents from last 24 hours
{
  "tool": "get_incidents",
  "arguments": {
    "time_range": "last 24 hours",
    "max_events": 50
  }
}
```

### Application Monitoring

```python
# Get application metrics
{
  "tool": "manage_instana_resources",
  "arguments": {
    "resource_type": "metrics",
    "operation": "application",
    "params": {
      "tag_filter_expression": {
        "type": "TAG_FILTER",
        "name": "application.name",
        "operator": "EQUALS",
        "entity": "DESTINATION",
        "value": "my-app"
      },
      "metrics": ["calls", "latency"],
      "time_frame": {"windowSize": 3600000}
    }
  }
}
```

## 🔧 Configuration

### Environment Variables

The wrapper expects these environment variables (provided by WXO Cloud connection):

```bash
INSTANA_API_TOKEN=your_api_token_here
INSTANA_BASE_URL=https://your-instance.instana.io
```

### WatsonX Orchestrator Setup

1. **Create Connection**:
   - Go to WXO Cloud → Connections
   - Create new connection named "instana"
   - Add Key-Value Pairs:
     - `INSTANA_API_TOKEN`: Your Instana API token
     - `INSTANA_BASE_URL`: Your Instana instance URL

2. **Import Toolkit**:
   - Go to WXO Cloud → Toolkits
   - Click "Import Toolkit"
   - Package: `instana-comprehensive-wrapper==1.0.1`
   - Command: `uvx instana-comprehensive-wrapper==1.0.1 --transport stdio`
   - Connection: Select "instana"

3. **Test**:
   - Create or open an agent
   - Try query: "Get CPU usage for [hostname] for the last 6 hours"

## 🏗️ Architecture

```
WXO Cloud Agent
    ↓
instana-comprehensive-wrapper (reads env vars from WXO connection)
    ↓
Spawns: uvx mcp-instana==0.7.1 (with credentials)
    ↓
Official Instana MCP Server
    ↓
Instana API
```

### Key Design Principles

1. **No Hardcoded Credentials**: All credentials from environment
2. **Simple Pass-Through**: Direct mapping to official tools
3. **Minimal Transformation**: Only JSON parsing for WXO compatibility
4. **Error Transparency**: Errors passed through from official server

## 📚 Documentation

### Tool Categories

- **Infrastructure**: Host, database, container, Kubernetes monitoring
- **Events**: Incidents, issues, changes, Kubernetes events
- **Automation**: Action catalog, execution, history
- **Dashboards**: Custom dashboard management
- **Applications**: Metrics, alerts, settings, catalog
- **Websites**: Beacon monitoring, configuration, source maps

### Common Patterns

**Two-Pass Infrastructure Analysis**:
1. Pass 1: Provide `intent` and `entity` to get schema
2. Pass 2: Provide `selections` with exact parameters

**Time Ranges**:
- Natural language: "last 24 hours", "last 2 days"
- Milliseconds: 3600000 (1 hour), 86400000 (1 day)
- String format: "1h", "24h", "7d"

**Filtering**:
```json
{
  "filters": [
    {"name": "host.name", "value": "my-server"},
    {"name": "db2.database.name", "value": "MYDB"}
  ]
}
```

## 🔍 Troubleshooting

### "Environment variables not set" Error

**Cause**: WXO Cloud connection not properly configured
**Solution**: 
1. Verify connection has `INSTANA_API_TOKEN` and `INSTANA_BASE_URL`
2. Ensure connection is selected when importing toolkit
3. Check connection status (should show green checkmarks)

### "401 Unauthorized" Error

**Cause**: Invalid or expired API token
**Solution**: Update API token in WXO Cloud connection

### "Host not found" Error

**Cause**: Hostname doesn't match Instana records
**Solution**: Use exact hostname from Instana (case-sensitive)

### Empty Results

**Cause**: Time range too narrow or filters too restrictive
**Solution**: Increase time range or broaden filters

## 🤝 Contributing

This wrapper is designed for the DB2 DBA team's Slack bot automation project. For issues or enhancements, please contact the team.

## 📄 License

MIT License

## 🔗 Related Projects

- **Official Instana MCP**: https://github.com/instana/mcp-instana
- **MCP Protocol**: https://modelcontextprotocol.io/
- **WatsonX Orchestrator**: https://www.ibm.com/docs/en/watsonx/watson-orchestrate

## 📊 Version History

### 1.0.1 (2026-04-14)
- **CRITICAL FIX**: Corrected tool name from `analyze_infrastructure` to `analyze_infrastructure_elicitation`
- Fixed infrastructure analysis tool to match official mcp-instana server
- All infrastructure queries now work correctly

### 1.0.0 (2026-04-14)
- Initial release (had critical bug with wrong tool name)
- All 46+ tools from official mcp-instana server
- WXO Cloud compatible (no hardcoded credentials)
- Simple pass-through architecture
- Comprehensive documentation

---

**Built for**: DB2 DBA Team Slack Bot Automation
**Status**: Production Ready
**Support**: Internal Team Support
