2026-01-12 13:24:56 +01:00

14 KiB

Raw Permalink Blame History

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, 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:

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:

registerListAppsTool() (lines ~197-223):

// 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

registerShowAppTool() (lines ~143-166):
- Similar pattern for app detail view
registerListAppInstancesTool() (lines ~609-635):
- Similar pattern for instance dashboard

UI Resource Structure

Each UI resource follows the MCP-UI protocol structure:

{
  "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

Usage

Prerequisites

MCP Client Support: Your MCP client must support UI resources (embedded resources in tool responses)
Edge Connect Configuration: Server must be properly configured with Edge Connect credentials

Example Workflow

List Applications:

# User asks: "List all Edge Connect applications"
# Server executes list_apps tool
# Returns: Text summary + Interactive HTML dashboard

View Application Details:

# User asks: "Show me details for app myorg/myapp:1.0.0"
# Server executes show_app tool
# Returns: JSON data + Interactive detail view

List Instances:

# User asks: "Show all application instances"
# Server executes list_app_instances tool
# Returns: Text summary + Interactive dashboard

Graceful Degradation

The implementation includes graceful degradation:

If UI resource creation fails, the server returns text-only content
Clients that don't support UI resources can still use the text content
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:

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

Interactive Actions:
- Add UI action handlers for delete, update, refresh operations
- Use UIActionResultToolCall() to trigger backend operations from UI
Real-time Updates:
- WebSocket integration for live status updates
- Auto-refresh dashboards when resources change
Advanced Visualizations:
- Charts for resource utilization
- Geographic maps for cloudlet locations
- Timeline views for deployment history
Forms and Input:
- Create/update forms embedded in UI
- Validation and error feedback
- Wizard-style multi-step processes
Customization:
- Theme selection (light/dark mode)
- User-configurable layouts
- Saved filter preferences

Extensibility

To add UI resources to other tools:

Create a new UI generation function in ui.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,
    )
}

Call it from your tool handler in tools.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:

Verify your MCP client supports UI resources
Check server logs for UI generation errors
Ensure HTML content is valid (no syntax errors)
Verify URI starts with ui://

Styling Issues

Problem: UI looks broken or unstyled.

Solutions:

Check for CSS syntax errors in HTML
Verify inline styles are properly escaped
Test HTML in a browser independently
Ensure percentage signs are doubled in fmt.Sprintf() (e.g., %%)

Build Errors

Problem: Compilation fails after integrating mcp-ui.

Solutions:

Run go mod tidy to resolve dependencies
Verify replace directive in go.mod points to correct commit
Check import paths in ui.go and tools.go
Ensure mcp-ui SDK version is compatible

References

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)

14 KiB Raw Permalink Blame History

MCP UI Integration

Overview

What is MCP-UI?

Features

1. Applications Dashboard (list_apps tool)

2. Application Detail View (show_app tool)

3. Application Instances Dashboard (list_app_instances tool)

Technical Implementation

Architecture

Files Modified

1. go.mod and go.sum

2. ui.go (New File)

3. tools.go

UI Resource Structure

Usage

Prerequisites

Example Workflow

Graceful Degradation

Design Principles

Visual Design

User Experience

Code Quality

Security Considerations

HTML Escaping

URI Validation

Content Isolation

Future Enhancements

Planned Features

Extensibility

Troubleshooting

UI Not Displaying

Styling Issues

Build Errors

References

Changelog

2026-01-12 - Initial MCP-UI Integration

14 KiB

Raw Permalink Blame History

1. Applications Dashboard (`list_apps` tool)

2. Application Detail View (`show_app` tool)

3. Application Instances Dashboard (`list_app_instances` tool)

1. `go.mod` and `go.sum`

2. `ui.go` (New File)

3. `tools.go`