supermodel-ui-client

v0.0.1

Published

4 months ago

SuperModel MCP UI Client SDK - privacy-first client-side rendering with template-based widgets

0High
0Medium
0Low

supermodel-ai

mcp model-context-protocol ui client privacy templates supermodel

SuperModel MCP-UI Client SDK

🔒 Privacy-first client-side UI rendering for MCP data

SuperModel Client SDK provides a privacy-focused alternative to server-side UI generation. Instead of sending sensitive data to remote servers for rendering, it fetches generic templates once and performs all data binding and rendering locally in the browser.

🌟 Key Features

🔒 Privacy-First: Your sensitive data never leaves the client
⚡ Performance: Templates cached locally, fast rendering
🎨 Flexible: 6+ widget types with auto-detection
🔌 MCP Compatible: Works with any MCP data server
⚛️ React Ready: Built-in React components and hooks
🌐 Framework Agnostic: Web components for any framework
📱 Responsive: Mobile-first design patterns

🏗️ Architecture

graph TB
    A[MCP Data Server] -->|Raw JSON Data| B[SuperModel Client SDK]
    C[Template Server] -->|Generic Templates| B
    B -->|Local Rendering| D[UI Components]
    
    B -.->|One-time fetch| C
    B -->|Privacy Boundary| E[Your Browser]
    
    style E fill:#e1f5fe
    style B fill:#f3e5f5
    style A fill:#e8f5e8

🚀 Quick Start

Installation

npm install supermodel-client

React Usage

import React from 'react';
import { SuperModelResourceRenderer, useSuperModelRenderer } from 'supermodel-client';

function MyApp() {
  const { renderWidget, detectPattern } = useSuperModelRenderer();
  
  const userData = [
    { name: 'Alice', department: 'Engineering', salary: 95000 },
    { name: 'Bob', department: 'Marketing', salary: 72000 }
  ];

  return (
    <SuperModelResourceRenderer
      data={userData}
      config={{ title: 'Team Members', responsive: true }}
      templateServer={{ url: 'http://localhost:3001' }}
    />
  );
}

Web Components Usage

<!DOCTYPE html>
<html>
<head>
    <script type="module">
        import { superModelWebComponents } from 'supermodel-client';
        
        // Register all components
        await superModelWebComponents.registerAll();
        
        // Use components
        const tableWidget = document.querySelector('supermodel-table');
        tableWidget.data = [
            { name: 'Alice', role: 'Engineer' },
            { name: 'Bob', role: 'Designer' }
        ];
    </script>
</head>
<body>
    <supermodel-table></supermodel-table>
</body>
</html>

📚 Widget Types

| Widget | Best For | Auto-Detection | |--------|----------|---------------| | Table | Structured data, lists of objects | ✅ Homogeneous object arrays | | Card | Key-value data, profiles, summaries | ✅ Single objects | | List | Simple collections, arrays | ✅ Arrays of primitives | | Chart | Numerical data, analytics | ✅ Label-value pairs | | Timeline | Events, chronological data | ✅ Date/timestamp fields | | Form | Interactive forms, schemas | ✅ Form field definitions |

🔧 Configuration

Template Server Setup

Start the Template Server:

cd supermodel-mcp-ui-template-server
npm start

Configure Client:

const config = {
  templateServer: {
    url: 'http://localhost:3001',
    timeout: 5000,
    cache: true,
    cacheDuration: 300000 // 5 minutes
  }
};

Data Pattern Detection

import { DataPatternDetector } from 'supermodel-client';

const detector = new DataPatternDetector();
const pattern = detector.detectPattern(yourData);

console.log(`Suggested widget: ${pattern.suggestedWidgetType}`);
console.log(`Confidence: ${pattern.confidence * 100}%`);

🎯 MCP Integration

With MCP Data Servers

import { McpClientAdapter } from 'supermodel-client';

const adapter = new McpClientAdapter({
  templateServer: { url: 'http://localhost:3001' },
  autoDetect: true
});

// Process MCP resources
const superModelResource = await adapter.processResource(mcpResource);

// Render with SuperModel
<SuperModelResourceRenderer resource={superModelResource} />

Example MCP Server Integration

// Your MCP server returns raw data
server.registerTool("get_users", {}, async () => {
  return {
    content: [{
      type: "text", 
      text: JSON.stringify({ users: [...] }) // Raw data
    }]
  };
});

// SuperModel Client SDK handles the rest locally

🔒 Privacy Guarantees

What Gets Sent to Template Server

✅ Template requests (widget type only)
✅ Generic template code
✅ Public metadata

What Stays Local

🔒 Your actual data
🔒 Business information
🔒 User details
🔒 All data processing
🔒 Widget rendering

Privacy Verification

# Monitor network traffic to see only template requests
npm run test:privacy

📖 API Reference

Components

`SuperModelResourceRenderer`

interface SuperModelResourceRendererProps {
  data: any;                           // Your data (stays local)
  widgetType?: SuperModelWidgetType;   // Override auto-detection  
  config?: TemplateConfig;             // Widget configuration
  templateServer?: TemplateServerConfig; // Template server settings
  onAction?: (result: SuperModelActionResult) => Promise<void>;
  onError?: (error: Error) => void;
  onLoading?: (isLoading: boolean) => void;
}

`SuperModelTemplateRenderer`

interface SuperModelTemplateRendererProps {
  templateId: string;     // Specific template to use
  data: any;             // Data to render
  config?: TemplateConfig;
  // ... other props
}

Hooks

`useSuperModelRenderer()`

const {
  renderWidget,    // Function to render widgets
  detectPattern,   // Function to detect data patterns  
  loading,         // Loading state
  error           // Error state
} = useSuperModelRenderer(templateServerConfig);

`useSuperModelTemplate()`

const {
  template,       // Loaded template definition
  loading,        // Loading state
  error,          // Error state  
  refetch        // Refetch function
} = useSuperModelTemplate(templateId, templateServerConfig);

Utilities

`DataPatternDetector`

const detector = new DataPatternDetector();
const pattern = detector.detectPattern(data);

interface DataPattern {
  type: 'object' | 'array' | 'primitive';
  subtype?: string;
  confidence: number; // 0-1
  suggestedWidgetType: SuperModelWidgetType;
  metadata?: object;
}

`McpClientAdapter`

const adapter = new McpClientAdapter({
  templateServer: { url: 'http://localhost:3001' },
  autoDetect: true,
  defaultWidgetType: 'card'
});

// Process MCP resources
const processed = await adapter.processResource(mcpResource);

// Create resources from raw data
const resource = adapter.createResourceFromData(data, 'table');

`RenderingEngine`

const engine = new RenderingEngine({
  templateServer: { url: 'http://localhost:3001' },
  enableCaching: true,
  errorHandler: (error) => console.error(error)
});

const element = await engine.render(superModelResource, containerElement);

🛠️ Development

Setup

git clone https://github.com/your-org/supermodel-mcp-ui
cd supermodel-mcp-ui/supermodel-client
npm install
npm run build

Running Examples

React Example:

cd examples/react-example
npm install
npm run dev

Web Components Example:

cd examples/web-components-example
python -m http.server 8000
# Open http://localhost:8000

Integration Test:

cd examples/integration-test
npm install
npm test

Project Structure

supermodel-client/
├── src/
│   ├── components/          # React components
│   ├── hooks/              # React hooks  
│   ├── utils/              # Core utilities
│   ├── web-components/     # Web component registration
│   ├── types.ts            # Type definitions
│   ├── constants.ts        # Configuration constants
│   └── index.ts            # Main exports
├── examples/               # Usage examples
├── dist/                   # Built package
└── README.md

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Workflow

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Start development mode
npm run dev

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

MCP (Model Context Protocol) - For the foundational protocol
mcp-ui - For client architecture inspiration
Web Components standards community

📞 Support

🐛 Bug Reports: GitHub Issues
💡 Feature Requests: GitHub Discussions
📧 Email: [email protected]
💬 Discord: SuperModel Community

🚀 Ready to build privacy-first UI experiences?

Check out our examples to see SuperModel in action!