edge-connect-mcp/MCP_UI.md

# MCP UI Integration

This document describes the MCP UI integration in the Edge Connect MCP server, which provides interactive web-based visualizations for Edge Connect resources.

## Overview

The Edge Connect MCP server now includes support for [MCP-UI](https://github.com/think-ahead-technologies/mcp-ui), a protocol that enables servers to deliver interactive web components through the Model Context Protocol. When users query Edge Connect resources, they receive both traditional text-based responses and rich, interactive HTML dashboards.

## What is MCP-UI?

MCP-UI brings interactive web components to the Model Context Protocol, allowing MCP servers to deliver rich, dynamic UI resources directly to clients. Instead of receiving only plain text or JSON, users get beautifully rendered, interactive visualizations of their data.

## Features

### 1. Applications Dashboard (`list_apps` tool)

When listing Edge Connect applications, users receive an interactive dashboard featuring:

- **Statistics Cards**:
  - Total application count
  - Docker application count
  - Kubernetes application count
  - Serverless-enabled applications count

- **Application Cards Grid**:
  - Organization and application name
  - Version badge
  - Deployment type badge (Docker/Kubernetes)
  - Serverless badge (if enabled)
  - Image path (truncated for display)
  - Access ports configuration
  - Interactive buttons for viewing details and deletion

- **Visual Design**:
  - Purple gradient background (#667eea to #764ba2)
  - Responsive grid layout (auto-adjusts to screen size)
  - Hover effects and smooth transitions
  - Card-based design with shadows

### 2. Application Detail View (`show_app` tool)

When viewing a specific application, users receive a detailed view with:

- **Property Grid**:
  - Organization, name, and version
  - Region information
  - Deployment type with colored badge
  - Image type and full image path
  - Access ports configuration
  - Serverless status with colored badge

- **Raw JSON Viewer**:
  - Syntax-highlighted JSON display
  - Complete application object for reference
  - Dark theme code viewer

### 3. Application Instances Dashboard (`list_app_instances` tool)

When listing application instances, users receive an interactive dashboard featuring:

- **Statistics Cards**:
  - Total instances count
  - Running instances count
  - Stopped instances count

- **Instances Table**:
  - Instance name and organization
  - Cloudlet location (org/name)
  - Associated application and version
  - Power state with status badges (Running/Stopped/Unknown)
  - Flavor information
  - Quick action buttons

- **Visual Design**:
  - Blue/purple gradient background (#4f46e5 to #7c3aed)
  - Professional table layout
  - Status badges with semantic colors
  - Hover effects on rows

## Technical Implementation

### Architecture

```
┌─────────────────────────────────────────────┐
│  MCP Client (Claude Desktop, etc.)          │
│  - Requests tool execution                  │
│  - Renders embedded UI resources            │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────┐
│  Edge Connect MCP Server                    │
│  ┌──────────────────────────────────────┐   │
│  │ tools.go                             │   │
│  │ - Executes Edge Connect API calls   │   │
│  │ - Calls UI generation functions      │   │
│  │ - Returns text + embedded resources  │   │
│  └──────────────┬───────────────────────┘   │
│                 │                            │
│  ┌──────────────▼───────────────────────┐   │
│  │ ui.go                                │   │
│  │ - createAppListUI()                  │   │
│  │ - createAppDetailUI()                │   │
│  │ - createAppInstanceListUI()          │   │
│  │ - Generates HTML with inline CSS    │   │
│  └──────────────┬───────────────────────┘   │
│                 │                            │
│  ┌──────────────▼───────────────────────┐   │
│  │ mcp-ui Go SDK                        │   │
│  │ - CreateUIResource()                 │   │
│  │ - Validates UI URIs                  │   │
│  │ - Encodes HTML content               │   │
│  └──────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
```

### Files Modified

#### 1. `go.mod` and `go.sum`
Added dependency on the mcp-ui Go SDK:

```go
require (
    github.com/MCP-UI-Org/mcp-ui/sdks/go/server v0.0.1
)

replace github.com/MCP-UI-Org/mcp-ui/sdks/go/server =>
    github.com/think-ahead-technologies/mcp-ui/sdks/go/server v0.0.0-20260112091603-a8343491b666
```

#### 2. `ui.go` (New File)
Contains all UI generation logic:

**Key Functions**:

- `createAppListUI(apps []v2.App, region string) (*mcpuiserver.UIResource, error)`
  - Generates interactive dashboard for application listings
  - Returns a UIResource with HTML content

- `createAppDetailUI(app v2.App, region string) (*mcpuiserver.UIResource, error)`
  - Generates detailed view for a single application
  - Includes property grid and JSON viewer

- `createAppInstanceListUI(instances []v2.AppInstance, region string) (*mcpuiserver.UIResource, error)`
  - Generates dashboard for application instances
  - Includes statistics and interactive table

**Helper Functions**:
- `generateAppCard(app v2.App) string` - Creates HTML for individual app cards
- `generateInstanceRow(inst v2.AppInstance) string` - Creates HTML table row for instance
- `countDeploymentType()`, `countServerlessApps()`, `countPowerState()` - Statistics helpers
- `getAccessPorts()`, `getServerlessBadgeClass()`, `getServerlessStatus()` - Display helpers

#### 3. `tools.go`
Enhanced three tool handlers to include UI resources:

**Modified Functions**:

1. **`registerListAppsTool()`** (lines ~197-223):
```go
// Create UI resource for apps list
uiResource, err := createAppListUI(apps, region)
if err != nil {
    // Fallback to text-only response
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: result}},
    }, nil, nil
}

// Convert UIResource to MCP EmbeddedResource
resourceContents := &mcp.ResourceContents{
    URI:      uiResource.Resource.URI,
    MIMEType: uiResource.Resource.MimeType,
    Text:     uiResource.Resource.Text,
}

// Return both text and UI resource
return &mcp.CallToolResult{
    Content: []mcp.Content{
        &mcp.TextContent{Text: result},
        &mcp.EmbeddedResource{Resource: resourceContents},
    },
}, nil, nil
```

2. **`registerShowAppTool()`** (lines ~143-166):
   - Similar pattern for app detail view

3. **`registerListAppInstancesTool()`** (lines ~609-635):
   - Similar pattern for instance dashboard

### UI Resource Structure

Each UI resource follows the MCP-UI protocol structure:

```json
{
  "type": "resource",
  "resource": {
    "uri": "ui://apps-dashboard",
    "mimeType": "text/html",
    "text": "<html>...</html>"
  }
}
```

**URI Patterns**:
- `ui://apps-dashboard` - Application listing dashboard
- `ui://app-detail/{org}/{name}/{version}` - Single app detail view
- `ui://app-instances-dashboard` - Instance listing dashboard

## Configuration

### How Clients Discover UI Support

Tools that support UI rendering advertise this capability in their metadata via the `tools/list` response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "result": {
    "tools": [
      {
        "name": "list_apps",
        "description": "List all Edge Connect applications matching the specified filter. Supports UI rendering when _meta.ui_standard is set to 'mcpui'.",
        "_meta": {
          "ui_support": "mcpui"
        },
        "inputSchema": {...}
      },
      {
        "name": "show_app",
        "description": "Retrieve a specific Edge Connect application by its key. Supports UI rendering when _meta.ui_standard is set to 'mcpui'.",
        "_meta": {
          "ui_support": "mcpui"
        },
        "inputSchema": {...}
      },
      {
        "name": "list_app_instances",
        "description": "List all Edge Connect application instances. Supports UI rendering when _meta.ui_standard is set to 'mcpui'.",
        "_meta": {
          "ui_support": "mcpui"
        },
        "inputSchema": {...}
      }
    ]
  }
}
```

The `_meta.ui_support` field indicates which UI standard(s) the tool supports. Clients can use this information to decide whether to request UI rendering when calling the tool.

### UI Standard Flag (Per-Call Control)

The server respects the client's UI rendering preferences via the `_meta.ui_standard` field in individual tool call requests. This allows **MCP clients** to control whether UI resources should be rendered on a **per-call basis**.

**Available UI Standards**:
- `"mcpui"` - MCP-UI protocol (renders interactive HTML dashboards)
- `""` (empty string) or omitted - No UI rendering (text-only responses)
- Custom standards can be added in the future

**How Clients Request UI Rendering**:

Clients specify their UI preference in the `_meta` field of the `tools/call` request:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_apps",
    "arguments": {
      "region": "EU"
    },
    "_meta": {
      "ui_standard": "mcpui"
    }
  }
}
```

**Examples**:

**To enable MCP-UI rendering for a specific call**:
```json
{
  "method": "tools/call",
  "params": {
    "name": "list_apps",
    "arguments": {...},
    "_meta": {
      "ui_standard": "mcpui"
    }
  }
}
```

**To disable UI rendering** (text-only response):
```json
{
  "method": "tools/call",
  "params": {
    "name": "list_apps",
    "arguments": {...}
    // No _meta field, or _meta.ui_standard omitted/empty
  }
}
```

**Server Implementation**:

The server checks the client's `_meta.ui_standard` preference on each tool call:

```go
// Extract client's UI standard preference from tool call _meta
func getUIStandardFromRequest(req *mcp.CallToolRequest) string {
    if req.Params == nil || req.Params.Meta == nil {
        return ""
    }
    uiStandard, ok := req.Params.Meta["ui_standard"]
    // ... return the string value
}

// Check if client wants UI rendering for this call
if !shouldRenderUI(req, "mcpui") {
    // Return text-only response
    return &mcp.CallToolResult{
        Content: []mcp.Content{&mcp.TextContent{Text: result}},
    }, nil, nil
}

// ... proceed with UI generation
```

**Default Behavior**:
- If the client does not include `_meta.ui_standard` in the tool call, the server returns text-only responses
- The three tools (`list_apps`, `show_app`, `list_app_instances`) support UI rendering when requested
- If UI rendering fails, the tools gracefully fall back to text-only responses
- The `shouldRenderUI()` helper function checks the call's `_meta` field before attempting UI generation

**Benefits**:
- **Per-Call Control**: Clients decide on each call whether they want UI rendering
- **No Configuration Required**: Clients don't need to set preferences during initialization
- **Flexibility**: Support multiple UI standards in the future
- **Discovery**: Clients learn about UI support from `tools/list` response
- **Backward Compatibility**: Existing clients without UI support work seamlessly
- **Graceful Degradation**: Always provides text-based fallback
- **Performance**: Avoid UI generation overhead when clients don't request it

## Usage

### Prerequisites

1. **MCP Client Support**: Your MCP client must support UI resources (embedded resources in tool responses)
2. **Edge Connect Configuration**: Server must be properly configured with Edge Connect credentials
3. **Client UI Capability**: Client must include `_meta.ui_standard` field in tool call requests to receive UI resources

### Example Workflow

1. **Client Discovers Tools**:
   - Client sends `tools/list` request
   - Server responds with tool list including `_meta.ui_support` field
   - Client sees that `list_apps`, `show_app`, and `list_app_instances` support `"mcpui"`

2. **List Applications with UI**:
   - User asks: "List all Edge Connect applications"
   - Client calls `list_apps` with `_meta.ui_standard: "mcpui"`
   - Server returns: Text summary + Interactive HTML dashboard

3. **View Application Details with UI**:
   - User asks: "Show me details for app myorg/myapp:1.0.0"
   - Client calls `show_app` with `_meta.ui_standard: "mcpui"`
   - Server returns: JSON data + Interactive detail view

4. **List Instances without UI**:
   - User asks: "Show all application instances as text"
   - Client calls `list_app_instances` without `_meta.ui_standard`
   - Server returns: Text-only response (no UI)

**Key Points**:
- Each tool call can independently request UI rendering or not
- Clients that don't support UI simply omit the `_meta.ui_standard` field
- Clients can mix UI and non-UI calls based on context or user preferences

### Graceful Degradation

The implementation includes graceful degradation:

1. If UI resource creation fails, the server returns text-only content
2. Clients that don't support UI resources can still use the text content
3. No breaking changes to existing tool behavior

## Design Principles

### Visual Design

- **Modern Aesthetics**: Gradient backgrounds, card-based layouts, smooth shadows
- **Professional Color Scheme**: Purple/blue palette with semantic colors for status indicators
- **Typography**: System font stack for optimal rendering across platforms
- **Responsive Design**: Layouts adapt to different screen sizes using CSS Grid

### User Experience

- **Information Hierarchy**: Most important info at the top, details below
- **Scannable Content**: Clear labels, consistent spacing, visual grouping
- **Interactive Elements**: Hover effects, clickable cards (prepared for future actions)
- **Status Indicators**: Color-coded badges for quick status recognition

### Code Quality

- **Separation of Concerns**: UI logic isolated in `ui.go`
- **Error Handling**: Graceful fallbacks if UI generation fails
- **HTML Safety**: All user content is escaped using `html.EscapeString()`
- **Performance**: String concatenation in loops (acceptable for small datasets)

## Security Considerations

### HTML Escaping

All dynamic content is properly escaped to prevent XSS vulnerabilities:

```go
html.EscapeString(app.Key.Name)
html.EscapeString(app.ImagePath)
html.EscapeString(inst.PowerState)
```

### URI Validation

The mcp-ui SDK validates that all resource URIs start with `ui://` to prevent unauthorized resource access.

### Content Isolation

UI resources are rendered in isolated contexts by MCP clients, preventing cross-site scripting or malicious code execution.

## Future Enhancements

### Planned Features

1. **Interactive Actions**:
   - Add UI action handlers for delete, update, refresh operations
   - Use `UIActionResultToolCall()` to trigger backend operations from UI

2. **Real-time Updates**:
   - WebSocket integration for live status updates
   - Auto-refresh dashboards when resources change

3. **Advanced Visualizations**:
   - Charts for resource utilization
   - Geographic maps for cloudlet locations
   - Timeline views for deployment history

4. **Forms and Input**:
   - Create/update forms embedded in UI
   - Validation and error feedback
   - Wizard-style multi-step processes

5. **Customization**:
   - Theme selection (light/dark mode)
   - User-configurable layouts
   - Saved filter preferences

### Extensibility

To add UI resources to other tools:

1. Create a new UI generation function in `ui.go`:
```go
func createMyResourceUI(data MyData) (*mcpuiserver.UIResource, error) {
    htmlContent := fmt.Sprintf(`
        <!DOCTYPE html>
        <html>
        <head>
            <style>/* Your CSS */</style>
        </head>
        <body>
            <!-- Your HTML -->
        </body>
        </html>
    `, /* your data */)

    return mcpuiserver.CreateUIResource(
        "ui://my-resource",
        &mcpuiserver.RawHTMLPayload{
            Type:       mcpuiserver.ContentTypeRawHTML,
            HTMLString: htmlContent,
        },
        mcpuiserver.EncodingText,
    )
}
```

2. Call it from your tool handler in `tools.go`:
```go
uiResource, err := createMyResourceUI(data)
if err == nil {
    resourceContents := &mcp.ResourceContents{
        URI:      uiResource.Resource.URI,
        MIMEType: uiResource.Resource.MimeType,
        Text:     uiResource.Resource.Text,
    }
    // Add to result.Content
}
```

## Troubleshooting

### UI Not Displaying

**Problem**: UI resources aren't showing up in the client.

**Solutions**:
1. Verify your MCP client supports UI resources
2. Check server logs for UI generation errors
3. Ensure HTML content is valid (no syntax errors)
4. Verify URI starts with `ui://`

### Styling Issues

**Problem**: UI looks broken or unstyled.

**Solutions**:
1. Check for CSS syntax errors in HTML
2. Verify inline styles are properly escaped
3. Test HTML in a browser independently
4. Ensure percentage signs are doubled in `fmt.Sprintf()` (e.g., `%%`)

### Build Errors

**Problem**: Compilation fails after integrating mcp-ui.

**Solutions**:
1. Run `go mod tidy` to resolve dependencies
2. Verify replace directive in `go.mod` points to correct commit
3. Check import paths in `ui.go` and `tools.go`
4. Ensure mcp-ui SDK version is compatible

## References

- [MCP-UI GitHub Repository](https://github.com/think-ahead-technologies/mcp-ui)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Edge Connect API Documentation](https://edp.buildth.ing/)

## Changelog

### 2026-01-12 - Initial MCP-UI Integration

**Added**:
- `ui.go` with three UI generation functions
- MCP-UI Go SDK dependency
- Interactive dashboards for apps and instances
- Graceful fallback to text-only responses

**Modified**:
- `tools.go`: Enhanced `list_apps`, `show_app`, `list_app_instances` tools
- `go.mod`: Added mcp-ui dependency with replace directive
- `go.sum`: Updated checksums

**Files**:
- New: `ui.go` (~780 lines)
- Modified: `tools.go` (+70 lines), `go.mod` (+3 lines)