mcp-instana 0.3.1__tar.gz → 0.6.2__tar.gz

mcp_instana-0.6.2/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+### 0.6.0
+
+-   **Fix:** Improved accuracy across Application, Infrastructure, and
+    Event tools by fixing broken functionality.
+-   **Enhancement:** Added multi-architecture Docker image support.
+
+### 0.5.0
+
+-   **New Feature:** Added support for using MCP Instana as an extension
+    within AI MCP clients.
+
+### 0.4.0
+
+-   **New Feature:** Added Website Monitoring tools.
+-   **Enhancement:** Enhanced Event capabilities with new issue,
+    incident, and change retrieval tools.
+
+### 0.3.1
+
+-   **Enhancement:** Optimized Docker image to reduce storage footprint.
+
+### 0.3.0
+
+-   **Enhancement:** Added prompt enable/disable functionality.
+-   **New Feature:** Introduced Application Alert Global tools.
+-   **New Feature:** Added automation tools.
+-   **Fix:** Resolved application analyze tools for better handling of
+    payloads.
+-   **Enhancement:** Added Docker support.
+
+### 0.2.0
+
+-   **New Feature:** Added comprehensive Application Settings tools.
+-   **New Feature:** Introduced the MCP Instana CLI.
+
+### 0.1.0
+
+-   Initial public release of the MCP Server for IBM
+    Instana.
+-   **New Feature:** Introduced core Monitoring Capabilities
+    (Application, Infrastructure, and Event Monitoring).

mcp_instana-0.6.2/DOCKER.md

@@ -0,0 +1,187 @@
+# Docker Guide for MCP Instana
+
+This guide documents everything Docker-related for MCP Instana. Use it when you need more than the quick blurb in `README.md`.
+
+## Overview
+
+- Two-stage image defined in `Dockerfile`: a builder installs only runtime dependencies (via `pyproject-runtime.toml` + `uv`), and the runtime stage copies the installed packages plus `src/`.
+- Runtime image is `python:3.11-slim`, runs as non-root `mcpuser`, exposes `8080`, and ships with a health check that curls `http://127.0.0.1:8080/health`.
+- Entry point runs `python -m src.core.server --transport streamable-http`, so clients provide Instana credentials over HTTP headers rather than baking them into the container.
+- `build_multiplatform.sh` automates multi-architecture builds (amd64 + arm64) with Docker Buildx, QEMU, and optional pushes.
+
+## Quickstart
+
+```bash
+# Build a local image (single architecture)
+docker build -t mcp-instana .
+
+# Run it (streamable HTTP transport on port 8080)
+docker run --rm -p 8080:8080 mcp-instana
+
+# Override the HTTP port exposed by the container
+docker run --rm -e PORT=9090 -p 9090:9090 mcp-instana
+```
+
+### Docker Compose snippet
+
+```yaml
+version: '3.8'
+services:
+  mcp-instana:
+    build: .
+    ports:
+      - "8080:8080"
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "python", "-c", "import requests; requests.get('http://127.0.0.1:8080/health', timeout=5)"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+```
+
+## Image anatomy (`Dockerfile`)
+
+| Component | Details |
+| --- | --- |
+| Builder stage | Based on `python:3.11-slim`, installs `uv`, copies `pyproject-runtime.toml`, `pyproject.toml`, `src/`, `README.md`, then runs `pip install .` (runtime deps only). |
+| Runtime stage | Reuses `python:3.11-slim`, copies site-packages and binaries from builder, then copies `src/` only. |
+| User | Non-root `mcpuser` owns `/app`. |
+| Entry point | `python -m src.core.server --transport streamable-http`. Override with `docker run ... -- entrypoint` or `CMD`. |
+| Health check | `python -c "import requests; requests.get('http://127.0.0.1:8080/health', timeout=5)"` every 30s with retries. |
+| Exposed port | `8080` (override with `PORT`). |
+
+### Configuration reference
+
+| Variable / flag | Default | Notes |
+| --- | --- | --- |
+| `PORT` | `8080` | Align host port mapping when overriding. |
+| `PYTHONUNBUFFERED` | `1` | Keeps logs unbuffered. Usually leave as-is. |
+| `PYTHONPATH` | `/app` | Ensures `src/` is importable. |
+| `--transport` (CMD arg) | `streamable-http` | Change via `docker run ... -- --transport <mode>`. |
+
+## Building images
+
+### Single-architecture build (default Docker)
+
+```bash
+docker build -t mcp-instana .
+```
+
+### Manual multi-architecture build with Buildx
+
+```bash
+# One-time builder setup
+docker buildx create --name multiarch --driver docker-container --use
+docker buildx inspect --bootstrap
+
+# Build & push (amd64 + arm64)
+docker buildx build \
+  --platform linux/amd64,linux/arm64 \
+  -t username/mcp-instana:latest \
+  --push .
+```
+
+### Using `build_multiplatform.sh`
+
+```bash
+chmod +x build_multiplatform.sh
+# Build local arch (loads result when host is linux/*)
+./build_multiplatform.sh
+
+# Build and push multi-arch manifest
+./build_multiplatform.sh --registry username/ --tag v1.0 --push
+```
+
+The script:
+
+1. Installs QEMU emulation via `tonistiigi/binfmt` (required on macOS/Windows for cross-builds).
+2. Creates/bootstraps a Buildx builder named `multiplatform`.
+3. Disables SBOM/attestation for faster builds (can be re-enabled if needed).
+4. Builds the requested platforms; if `--push` is omitted on non-Linux hosts, it falls back to building only the current platform and warns accordingly.
+5. When `--push` is set, it verifies the manifest and performs `docker pull` for both amd64/arm64.
+
+#### Script options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `-n, --name` | Image name | `mcp-instana` |
+| `-t, --tag` | Image tag | `latest` |
+| `-r, --registry` | Registry prefix (e.g., `username/` or `registry.example.com/`) | empty |
+| `-p, --platforms` | Comma-separated platforms | `linux/amd64,linux/arm64` |
+| `--push` | Push manifest to the registry | disabled |
+| `-h, --help` | Show usage and exit | — |
+
+## Security posture
+
+- Non-root runtime user (`mcpuser`) limits container privileges.
+- Health check ensures orchestration platforms can restart unhealthy pods.
+- No credentials or secrets inside the image; MCP clients supply Instana headers at request time.
+- Runtime dependency set trimmed to ~20 packages, yielding ~266 MB images vs >1 GB for dev installs.
+- Multi-stage build keeps compilers and build artifacts out of the final layer.
+
+## Testing & troubleshooting
+
+```bash
+# Inspect container status (health column)
+docker ps
+
+# Hit MCP endpoint directly
+curl http://localhost:8080/mcp/
+
+# Test using MCP Inspector
+npx @modelcontextprotocol/inspector http://localhost:8080/mcp/
+
+# Logs
+docker logs -f <container_id>
+
+# Debug shell (container already has /bin/bash from python:slim)
+docker exec -it <container_id> /bin/bash
+```
+
+## Production deployment
+
+1. Keep Instana credentials outside the container; pass them through MCP-compatible clients (Claude Desktop, GitHub Copilot, etc.).
+2. Rely on the built-in HTTP health endpoint (`/health`) for orchestration probes.
+3. Configure persistent logging/metrics at the orchestrator level (CloudWatch, ELK, etc.).
+4. Run at least two replicas and enable rolling updates to avoid downtime.
+5. Regularly rebuild to pick up upstream `python:3.11-slim` security patches.
+
+### Kubernetes example
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mcp-instana
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: mcp-instana
+  template:
+    metadata:
+      labels:
+        app: mcp-instana
+    spec:
+      containers:
+      - name: mcp-instana
+        image: mcp-instana:latest
+        ports:
+        - containerPort: 8080
+        env:
+        - name: PORT
+          value: "8080"
+        livenessProbe:
+          httpGet:
+            path: /health
+            port: 8080
+          initialDelaySeconds: 30
+          periodSeconds: 10
+        readinessProbe:
+          httpGet:
+            path: /health
+            port: 8080
+          initialDelaySeconds: 5
+          periodSeconds: 5
+```

mcp_instana-0.6.2/Dockerfile

@@ -0,0 +1,60 @@
+# Stage 1: Build stage with minimal runtime dependencies
+FROM docker.io/library/python:3.11-slim AS builder
+
+# Install system dependencies needed for building
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy only the runtime dependency file and source code needed for the build
+COPY pyproject-runtime.toml pyproject.toml
+COPY src ./src
+COPY README.md ./
+
+# Install uv for dependency management
+RUN pip install --no-cache-dir uv
+
+# Install only runtime dependencies using the minimal pyproject-runtime.toml
+RUN pip install --no-cache-dir .
+
+# Stage 2: Runtime stage
+FROM python:3.11-slim AS runtime
+
+# Set working directory
+WORKDIR /app
+
+# Create a non-root user for security
+RUN groupadd -r mcpuser && useradd -r -g mcpuser mcpuser
+
+# Copy only the Python packages from builder (no source code needed)
+COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy only the source code needed for runtime
+COPY src ./src
+
+# Set ownership to non-root user
+RUN chown -R mcpuser:mcpuser /app
+
+# Switch to non-root user
+USER mcpuser
+
+# Expose the default port (configurable via PORT env var)
+EXPOSE 8080
+
+# Set environment variables (no hardcoded secrets)
+ENV PYTHONPATH=/app
+ENV PYTHONUNBUFFERED=1
+ENV PORT=8080
+
+# Health check using container's internal network
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+    CMD python -c "import requests; requests.get('http://127.0.0.1:8080/health', timeout=5)" || exit 1
+
+# Run the server
+ENTRYPOINT ["python", "-m", "src.core.server"]
+CMD ["--transport", "streamable-http"]

mcp_instana-0.6.2/OBSERVABILITY.md

@@ -0,0 +1,344 @@
+# MCP Observability Configuration Guide
+
+This document provides comprehensive instructions for enabling and configuring observability in the MCP Instana Server using Traceloop SDK for distributed tracing.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Environment Variables](#environment-variables)
+  - [Client-Specific Configurations](#client-specific-configurations)
+    - [GitHub Copilot](#github-copilot)
+    - [Claude Desktop](#claude-desktop)
+    - [Custom MCP Client](#custom-mcp-client)
+- [Starting the Server](#starting-the-server)
+- [Viewing Traces in Instana](#viewing-traces-in-instana)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+MCP-Instana Observability integrates with the Traceloop SDK to provide distributed tracing for your MCP server and client interactions.
+
+## Prerequisites
+
+Before enabling observability, ensure you have:
+
+- Traceloop SDK installed (see [Installation](#installation))
+- Access to an Instana instance for viewing spans
+
+## Installation
+
+### Install Traceloop SDK
+
+If you don't already have it:
+
+```bash
+# Using pip
+pip install traceloop-sdk==0.47.5
+
+# Using uv
+uv add traceloop-sdk==0.47.5
+```
+
+Without this, you'll see warnings like:
+```
+Traceloop requested but not installed. Install with: pip install traceloop-sdk
+```
+
+## Configuration
+
+### Environment Variables
+
+Observability in MCP-Instana is feature-flag controlled. It will only be enabled if the environment variable `ENABLE_MCP_OBSERVABILITY` is set.
+
+#### Main Feature Flag
+
+| Variable | Default |
+|----------|---------|
+| `ENABLE_MCP_OBSERVABILITY` | `false` | 
+
+**Accepted values:**
+- `true`, `1`, `yes`, `on` → enables observability
+- `false`, `0`, `no`, `off` → disables observability (default)
+
+**Important:** If this flag is not set (or set to false), MCP observability will remain completely disabled, even if Traceloop and Instana configs are present.
+
+#### Traceloop Configuration Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `TRACELOOP_BASE_URL` | Your Instana OTLP endpoint URL | `https://otlp-pink-saas.instana.rocks:4317` |
+| `TRACELOOP_HEADERS` | Authentication header for Instana | `x-instana-key=your_instana_key` |
+| `OTEL_EXPORTER_OTLP_INSECURE` | Whether to use insecure connection | `false` (recommended) |
+
+#### Export Modes
+
+You can export traces to Instana in two different modes:
+
+**Agent Mode :**
+
+Export traces to a local Instana agent running on your machine:
+
+```bash
+export TRACELOOP_BASE_URL=<instana-agent-host>:4317
+export TRACELOOP_HEADERS="api-key=<api-key>""
+export OTEL_EXPORTER_OTLP_INSECURE=true
+```
+
+**Agentless Mode (Direct to Backend):**
+
+Export traces directly to the Instana backend:
+
+```bash
+export TRACELOOP_BASE_URL=<instana-otlp-endpoint>:4317
+export TRACELOOP_HEADERS="x-instana-key=<agent-key>"
+export OTEL_EXPORTER_OTLP_INSECURE=false
+```
+
+**Note:** Replace the values with your actual Instana configuration:
+- For agentless mode, use your Instana backend OTLP endpoint and API key
+- For agent mode, ensure your local Instana agent is running and accessible
+
+### Client-Specific Configurations
+
+Depending on your client (GitHub Copilot, Claude Desktop, or a custom MCP client), configuration differs for HTTP mode and STDIO mode. In all cases, ensure the flag `ENABLE_MCP_OBSERVABILITY=true` is set.
+
+#### GitHub Copilot
+
+##### HTTP Mode (mcp.json)
+
+For Streamable HTTP mode, configure `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "Instana MCP Server": {
+      "command": "npx",
+      "args": [
+        "mcp-remote", "http://0.0.0.0:8080/mcp/",
+        "--allow-http",
+        "--header", "instana-base-url: <your-instana-url>",
+        "--header", "instana-api-token: <your-instana-token>"
+      ],
+      "env": {
+        "ENABLE_MCP_OBSERVABILITY": "true",
+        "TRACELOOP_BASE_URL": "<your-instana-otlp-url>",
+        "TRACELOOP_HEADERS": "x-instana-key=<your-instana-key>",
+        "OTEL_EXPORTER_OTLP_INSECURE": "false"
+      }
+    }
+  }
+}
+```
+
+**Note:** Replace the following values:
+- `<your-instana-url>`: Your Instana instance URL (e.g., `https://your-instance.instana.io`)
+- `<your-instana-token>`: Your Instana API token
+- `<your-instana-otlp-url>`: Your Instana OTLP endpoint (for ex - `https://otlp-pink-saas.instana.rocks:4317`)
+- `<your-instana-key>`: Your Instana authentication key
+
+##### STDIO Mode (mcp.json)
+
+For STDIO mode, configure `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "Instana MCP Server": {
+      "command": "uv",
+      "args": [
+        "run",
+        "src/core/server.py",
+        "--tools", "infra"
+      ],
+      "cwd": "<path-to-mcp-instana>",
+      "env": {
+        "INSTANA_BASE_URL": "<your-instana-url>",
+        "INSTANA_API_TOKEN": "<your-instana-token>",
+        "ENABLE_MCP_OBSERVABILITY": "true",
+        "TRACELOOP_BASE_URL": "<your-instana-otlp-url>",
+        "TRACELOOP_HEADERS": "x-instana-key=<your-instana-key>",
+        "OTEL_EXPORTER_OTLP_INSECURE": "false"
+      }
+    }
+  }
+}
+```
+
+**Note:** Replace `<path-to-mcp-instana>` with the absolute path to your mcp-instana project directory.
+
+#### Claude Desktop
+
+##### HTTP Mode (claude_desktop_config.json)
+
+For Streamable HTTP mode, configure Claude Desktop:
+
+**File Locations:**
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "Instana MCP Server": {
+      "command": "npx",
+      "args": [
+        "mcp-remote", "http://0.0.0.0:8080/mcp/",
+        "--allow-http",
+        "--header", "instana-base-url: <your-instana-url>",
+        "--header", "instana-api-token: <your-instana-token>"
+      ],
+      "env": {
+        "ENABLE_MCP_OBSERVABILITY": "true",
+        "TRACELOOP_BASE_URL": "<your-instana-otlp-url>",
+        "TRACELOOP_HEADERS": "x-instana-key=<your-instana-key>",
+        "OTEL_EXPORTER_OTLP_INSECURE": "false"
+      }
+    }
+  }
+}
+```
+
+##### STDIO Mode (claude_desktop_config.json)
+
+For STDIO mode:
+
+```json
+{
+  "mcpServers": {
+    "Instana MCP Server": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "<path-to-mcp-instana>",
+        "run",
+        "src/core/server.py"
+      ],
+      "cwd": "<path-to-mcp-instana>",
+      "env": {
+        "INSTANA_BASE_URL": "<your-instana-url>",
+        "INSTANA_API_TOKEN": "<your-instana-token>",
+        "ENABLE_MCP_OBSERVABILITY": "true",
+        "TRACELOOP_BASE_URL": "<your-instana-otlp-url>",
+        "TRACELOOP_HEADERS": "x-instana-key=<your-instana-key>",
+        "OTEL_EXPORTER_OTLP_INSECURE": "false"
+      }
+    }
+  }
+}
+```
+
+#### Custom MCP Client
+
+For custom MCP clients:
+
+- **HTTP Mode** → Use the same setup as GitHub Copilot HTTP (JSON config with headers + observability env vars)
+- **STDIO Mode** → Use the same setup as Claude STDIO (JSON config with server command, env vars, and observability flag)
+
+## Starting the Server
+
+After updating configurations, you'll need to restart components. The steps differ by mode:
+
+### Streamable HTTP Mode
+
+**Step 1: Export Environment Variables (if needed)**
+
+In case the environment variables are not taking effect, export them in the mcp-instana server terminal:
+
+```bash
+export ENABLE_MCP_OBSERVABILITY=true
+export TRACELOOP_BASE_URL=<your-instana-otlp-url>
+export TRACELOOP_HEADERS="x-instana-key=<your-instana-key>"
+export OTEL_EXPORTER_OTLP_INSECURE=false
+```
+
+**Note:** `TRACELOOP_BASE_URL` should be your Instana OTLP URL (e.g., `https://otlp-pink-saas.instana.rocks:4317`)
+
+**Step 2: Start the Server**
+
+Start the server explicitly with streamable HTTP transport:
+
+```bash
+# Using development installation
+uv run src/core/server.py --transport streamable-http
+
+# Using PyPI installation
+mcp-instana --transport streamable-http
+```
+
+**Step 3: Restart the Client**
+
+Restart the client (e.g., GitHub Copilot, Claude Desktop, or custom MCP client) using its configuration file.
+
+### STDIO Mode
+
+In STDIO mode, you don't need to start the MCP server manually. The client (GitHub Copilot, Claude Desktop, or custom MCP client) will directly launch the MCP server process based on its configuration file.
+
+Simply start the client, and it will take care of invoking the server under the hood.
+
+**Important Note:** In some clients, the root span may not appear automatically unless the session is fully closed:
+
+- **Claude Desktop** → Quit the Claude Desktop app after finishing your session
+- **GitHub Copilot** → Stop the MCP server process after your workflow
+
+If the session remains open, the root span will be missing from traces.
+
+## Viewing Traces in Instana
+
+Once observability is enabled and the server is running, you can view traces in Instana:
+
+1. **Log in to Instana**
+2. **Navigate to Analytics** → Enable "Show internal calls" (bottom left)
+3. **Add Filter**: Service Name → `Instana-MCP-Server` (the app name you used with `traceloop.init()`)
+4. **Explore traces**:
+   - Filter by time range
+   - Drill into individual spans
+   - Analyze request flows end-to-end
+
+This visualization makes it easy to trace requests and identify performance bottlenecks.
+
+### Key Benefits
+
+Enabling observability brings immediate advantages:
+
+- **End-to-End Visibility** – See client-to-server flows
+- **Performance Optimization** – Identify bottlenecks with real data
+- **Error Tracking** – Pinpoint failure points quickly
+- **System Understanding** – Learn how components interact
+
+## Troubleshooting
+
+### No Spans Visible?
+
+If you don't see any spans in Instana:
+
+1. **Verify the feature flag is set:**
+   ```bash
+   echo $ENABLE_MCP_OBSERVABILITY
+   # Should output: true
+   ```
+
+2. **Check Traceloop SDK installation:**
+   ```bash
+   pip show traceloop-sdk
+   ```
+
+3. **Confirm Instana configuration:**
+   - Verify `TRACELOOP_BASE_URL` is correct
+   - Verify `TRACELOOP_HEADERS` contains valid authentication key
+   - Check `OTEL_EXPORTER_OTLP_INSECURE` is set appropriately
+
+4. **Check server logs for errors:**
+   - Look for Traceloop initialization messages
+   - Check for connection errors to Instana
+
+### Environment Variables Not Taking Effect?
+
+If environment variables don't seem to work:
+
+1. **For HTTP mode:** Export variables in the server terminal before starting
+2. **For STDIO mode:** Ensure variables are in the client configuration file
+3. **Restart both server and client** after configuration changes
+4. **Check for typos** in variable names (they are case-sensitive)