Metadata-Version: 2.4
Name: instana-wxo-wrapper
Version: 1.0.2
Summary: WatsonX Orchestrator-compatible wrapper for Instana MCP server with simplified tool interfaces
Author-email: Abhishek Erande <abhishek.erande@ibm.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/instana-wxo-wrapper
Project-URL: Documentation, https://github.com/yourusername/instana-wxo-wrapper#readme
Project-URL: Repository, https://github.com/yourusername/instana-wxo-wrapper
Project-URL: Issues, https://github.com/yourusername/instana-wxo-wrapper/issues
Keywords: instana,mcp,watsonx,orchestrator,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
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: instana>=3.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
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"
Dynamic: license-file

# Instana WXO Wrapper

A WatsonX Orchestrator-compatible wrapper for Instana monitoring that provides simplified tool interfaces by handling the two-pass infrastructure analysis workflow internally.

## Problem Solved

The official `mcp-instana` server uses a two-pass workflow for infrastructure queries:
1. **Pass 1**: Get schema with `entity` + `intent` parameters
2. **Pass 2**: Execute query with `selections` parameter

WatsonX Orchestrator cannot handle this workflow because it sees all parameters as independent options and cannot infer that they represent different workflow steps. This wrapper solves the problem by:

- Handling the two-pass workflow internally
- Exposing simple, single-purpose tools
- Providing formatted, readable results
- Working immediately in WXO without guidelines or training

## Features

### 17 Simplified Tools

**Database Tools (3)**:
- `list_databases` - List all databases on a host
- `get_database_metrics` - Detailed metrics for a specific database
- `get_database_health` - Health status with warnings

**Host Tools (3)**:
- `list_hosts` - List all monitored hosts
- `get_host_metrics` - Detailed metrics for a specific host
- `get_host_health` - Health status with warnings

**Event Tools (4)**:
- `get_incidents` - Critical incidents
- `get_issues` - Non-critical issues
- `get_changes` - Change events (deployments, config changes)
- `get_kubernetes_events` - Kubernetes events

**Kubernetes Tools (3)**:
- `list_kubernetes_pods` - List all pods
- `list_kubernetes_nodes` - List all nodes
- `get_pod_metrics` - Detailed pod metrics

**Service Tools (2)**:
- `list_services` - List all services
- `get_service_metrics` - Detailed service metrics

**Application Tools (2)**:
- `list_applications` - List all applications
- `get_application_metrics` - Detailed application metrics

## Installation

### From PyPI (Recommended)

```bash
pip install instana-wxo-wrapper
```

### From Source

```bash
git clone https://github.com/yourusername/instana-wxo-wrapper
cd instana-wxo-wrapper
pip install -e .
```

## Configuration

Set environment variables:

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

Or create a `.env` file:

```env
INSTANA_BASE_URL=https://your-instance.instana.io
INSTANA_API_TOKEN=your_api_token
```

## Usage

### Running the Server

```bash
# Using the installed command
instana-wxo-wrapper

# Or using Python module
python -m instana_wxo_wrapper.server
```

### Testing with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "instana-wxo": {
      "command": "instana-wxo-wrapper",
      "env": {
        "INSTANA_BASE_URL": "https://your-instance.instana.io",
        "INSTANA_API_TOKEN": "your_api_token"
      }
    }
  }
}
```

### Using with WatsonX Orchestrator

1. **Import Toolkit**:
   - Go to WXO Cloud → Toolkits
   - Click "Import Toolkit"
   - Select "MCP Server"
   - Enter command: `uvx instana-wxo-wrapper`
   - Add environment variables

2. **Use in Agent**:
   ```
   List all databases on t3992-dev1-db-node01-par01-dev
   ```
   
   The agent will automatically use the `list_databases` tool with the hostname parameter.

## Example Queries

### Database Monitoring

```
# List all databases on a host
List databases on t3992-dev1-db-node01-par01-dev

# Get detailed metrics for a specific database
Get metrics for database PDWDBT on t3992-dev1-db-node01-par01-dev

# Check database health
Check database health on t3992-dev1-db-node01-par01-dev
```

### Host Monitoring

```
# List all hosts
List all monitored hosts

# Get host metrics
Get metrics for host t3992-dev1-db-node01-par01-dev

# Check host health
Check health of t3992-dev1-db-node01-par01-dev
```

### Event Monitoring

```
# Get recent incidents
Show incidents from the last 24 hours

# Get issues for a specific host
Show issues for t3992-dev1-db-node01-par01-dev in the last hour

# Get recent changes
Show changes from the last 24 hours
```

### Kubernetes Monitoring

```
# List pods in a namespace
List pods in namespace production

# Get pod metrics
Get metrics for pod my-app-pod in namespace production

# List all nodes
List all Kubernetes nodes
```

## Tool Details

### list_databases

Lists all databases on a specific host with status and connection count.

**Parameters**:
- `hostname` (required): Hostname or FQDN
- `time_range` (optional): Time range (default: "1h")

**Example Output**:
```
Databases on t3992-dev1-db-node01-par01-dev:

  • PDWDBT
    Status: ACTIVE
    Connections: 45
  • SAMPLE
    Status: ACTIVE
    Connections: 12
```

### get_database_health

Gets health status of all databases on a host with warnings.

**Parameters**:
- `hostname` (required): Hostname or FQDN
- `time_range` (optional): Time range (default: "1h")

**Example Output**:
```
Database Health on t3992-dev1-db-node01-par01-dev:

  ✓ Healthy PDWDBT
  ⚠ Warning TESTDB

Warnings:
  • TESTDB: High log utilization (85.3%)
```

## Architecture

### Two-Pass Workflow (Internal)

The wrapper handles the Instana two-pass workflow internally:

1. **Client Layer** (`client.py`):
   - Manages Instana API authentication
   - Implements `two_pass_query()` method
   - Handles time range parsing
   - Constructs proper API payloads

2. **Tools Layer** (`tools.py`):
   - Implements 17 simplified tools
   - Calls client with appropriate parameters
   - Formats results for readability
   - Handles errors gracefully

3. **Server Layer** (`server.py`):
   - Registers tools with MCP
   - Routes tool calls to implementations
   - Manages server lifecycle

### Why This Works in WXO

- **Simple Parameters**: Each tool has clear, single-purpose parameters
- **No Workflow**: No need to understand multi-step processes
- **Formatted Output**: Results are human-readable
- **Error Handling**: Clear error messages
- **No Training Needed**: Works immediately without guidelines

## Comparison with Official Server

| Feature | Official mcp-instana | instana-wxo-wrapper |
|---------|---------------------|---------------------|
| Tools | 46+ tools | 17 tools |
| Workflow | Two-pass (manual) | Two-pass (automatic) |
| WXO Compatible | ❌ No | ✅ Yes |
| Claude Desktop | ✅ Yes | ✅ Yes |
| Output Format | Raw JSON | Formatted text |
| Use Case | Advanced queries | Common operations |

## Development

### Setup

```bash
# Clone repository
git clone https://github.com/yourusername/instana-wxo-wrapper
cd instana-wxo-wrapper

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

### Testing

```bash
# Run tests
pytest

# Run with coverage
pytest --cov=instana_wxo_wrapper
```

### Building

```bash
# Build package
python -m build

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

## Troubleshooting

### Server Won't Start

**Error**: `INSTANA_BASE_URL and INSTANA_API_TOKEN must be set`

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

### No Data Returned

**Error**: `No databases found on hostname`

**Possible Causes**:
1. Hostname is incorrect (check FQDN)
2. No data in specified time range (try longer range like "24h")
3. Instana agent not reporting data

**Solution**: Verify hostname and try:
```
List databases on t3992-dev1-db-node01-par01-dev with time range 24h
```

### API Errors

**Error**: `401 Unauthorized`

**Solution**: Check API token is valid and has correct permissions

**Error**: `404 Not Found`

**Solution**: Verify Instana base URL is correct

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

- GitHub Issues: https://github.com/yourusername/instana-wxo-wrapper/issues
- Documentation: https://github.com/yourusername/instana-wxo-wrapper#readme

## Acknowledgments

- Built on top of the official [mcp-instana](https://github.com/instana/mcp-instana) server
- Designed for [WatsonX Orchestrator](https://www.ibm.com/products/watsonx-orchestrate)
- Uses the [Model Context Protocol](https://modelcontextprotocol.io/)
