Add v2_ux.md specification with detailed UX patterns
Based on MCPJam Inspector analysis: - Server connection card with status indicators - Resizable panel layouts for Tools/Resources/Prompts screens - Form generation from JSON Schema - Error handling patterns (inline errors, retry count, doc links) Also updates nav links in all spec files to include v2_ux.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
olaservo
parent
dfb0f1436a
commit
8fec93fa5a
5 changed files with 337 additions and 4 deletions
|
|
@ -1,6 +1,6 @@
|
||||||
# Inspector V2 Brief
|
# Inspector V2 Brief
|
||||||
|
|
||||||
### Brief | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md)
|
### Brief | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md) | [V2 UX](v2_ux.md)
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
* [Motivation and Context](#motivation-and-context)
|
* [Motivation and Context](#motivation-and-context)
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
# Inspector V1 Problems
|
# Inspector V1 Problems
|
||||||
|
|
||||||
### [Brief](README.md) | V1 Problems | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md)
|
### [Brief](README.md) | V1 Problems | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md) | [V2 UX](v2_ux.md)
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
* [Monolithic components](#monolithic-components)
|
* [Monolithic components](#monolithic-components)
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
# Inspector V2 Scope
|
# Inspector V2 Scope
|
||||||
|
|
||||||
### [Brief](README.md) | [V1 Problems](v1_problems.md) | V2 Scope | [V2 Tech Stack](v2_tech_stack.md)
|
### [Brief](README.md) | [V1 Problems](v1_problems.md) | V2 Scope | [V2 Tech Stack](v2_tech_stack.md) | [V2 UX](v2_ux.md)
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
* [Protocol Features](#protocol-features)
|
* [Protocol Features](#protocol-features)
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
# Inspector V2 Tech Stack
|
# Inspector V2 Tech Stack
|
||||||
|
|
||||||
### [Brief](README.md) | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | V2 Tech Stack
|
### [Brief](README.md) | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | V2 Tech Stack | [V2 UX](v2_ux.md)
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
* [Web Client](#web-client)
|
* [Web Client](#web-client)
|
||||||
|
|
|
||||||
333
specification/v2_ux.md
Normal file
333
specification/v2_ux.md
Normal file
|
|
@ -0,0 +1,333 @@
|
||||||
|
# Inspector V2 UX Specification
|
||||||
|
|
||||||
|
### [Brief](README.md) | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md) | V2 UX
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
* [Design Principles](#design-principles)
|
||||||
|
* [Navigation Model](#navigation-model)
|
||||||
|
* [Screen Flows](#screen-flows)
|
||||||
|
* [Server List (Home)](#server-list-home)
|
||||||
|
* [Server Connection Card](#server-connection-card)
|
||||||
|
* [Server Info (Connected)](#server-info-connected)
|
||||||
|
* [Feature Screens](#feature-screens)
|
||||||
|
* [Form Generation](#form-generation)
|
||||||
|
* [Error Handling UX](#error-handling-ux)
|
||||||
|
|
||||||
|
## Design Principles
|
||||||
|
|
||||||
|
- **Single server connection** - No multiple concurrent connections (defer to plugins)
|
||||||
|
- **MCPJam-inspired** - Use MCPJam Inspector as UX reference model
|
||||||
|
- **Full-width content** - Maximize screen real estate for each section
|
||||||
|
- **No sidebar** - Deferred until menu becomes cumbersome or extensions multiply
|
||||||
|
- **Progressive disclosure** - Show relevant information at each connection stage
|
||||||
|
- **Resizable panels** - Allow users to adjust panel sizes on feature screens
|
||||||
|
|
||||||
|
## Navigation Model
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ [Server Name ▼] [Tools] [Resources] [Prompts] [Disconnect] │
|
||||||
|
├─────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ Full-width content │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
- **Menu bar** displays server name and disconnect button when connected
|
||||||
|
- **Top navigation** links to Tools, Resources, Prompts sections
|
||||||
|
- **No sidebar** - content areas use full width
|
||||||
|
|
||||||
|
## Screen Flows
|
||||||
|
|
||||||
|
### Server List (Home)
|
||||||
|
|
||||||
|
Initial screen shown when no server is connected. Displays server cards in a responsive grid (1-2 columns).
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ MCP Inspector │
|
||||||
|
│ [+ Add Server ▼] │
|
||||||
|
├─────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────┐ ┌─────────────────────────┐
|
||||||
|
│ │ Server Card 1 │ │ Server Card 2 │
|
||||||
|
│ │ (see below) │ │ (see below) │
|
||||||
|
│ └─────────────────────────┘ └─────────────────────────┘
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────┐ │
|
||||||
|
│ │ Server Card 3 │ │
|
||||||
|
│ └─────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Add Server Options:**
|
||||||
|
- Add manually (opens form modal)
|
||||||
|
- Import from JSON (paste/upload config)
|
||||||
|
|
||||||
|
**Functionality:**
|
||||||
|
- List servers from `mcp.json` config file
|
||||||
|
- Add/edit/delete servers via CRUD endpoints on proxy
|
||||||
|
- Responsive grid layout (1 column mobile, 2 columns desktop)
|
||||||
|
|
||||||
|
### Server Connection Card
|
||||||
|
|
||||||
|
Each server in the list is displayed as a card with connection controls and status.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ [Icon] Server Name v1.0.0 │
|
||||||
|
│ STDIO [●] Connected [Toggle] │
|
||||||
|
├─────────────────────────────────────────────────────────┤
|
||||||
|
│ npx -y @modelcontextprotocol/server-everything [Copy]│
|
||||||
|
├─────────────────────────────────────────────────────────┤
|
||||||
|
│ [Server Info] [Edit] [Remove] │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**With Error State:**
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ [Icon] Server Name v1.0.0 │
|
||||||
|
│ HTTP [●] Failed (3) [Toggle] │
|
||||||
|
├─────────────────────────────────────────────────────────┤
|
||||||
|
│ https://api.example.com/mcp [Copy]│
|
||||||
|
├─────────────────────────────────────────────────────────┤
|
||||||
|
│ [Server Info] [Edit] [Remove] │
|
||||||
|
├─────────────────────────────────────────────────────────┤
|
||||||
|
│ ⚠️ Connection timeout after 20s │
|
||||||
|
│ [Show more] [View Troubleshooting Guide →] │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Status Indicators:**
|
||||||
|
| Status | Indicator | Display |
|
||||||
|
|--------|-----------|---------|
|
||||||
|
| Connected | Green dot | "Connected" |
|
||||||
|
| Connecting | Yellow pulsing dot | "Connecting..." |
|
||||||
|
| Failed | Red dot | "Failed (N)" with retry count |
|
||||||
|
| Disconnected | Gray dot | "Disconnected" |
|
||||||
|
|
||||||
|
**Card Actions:**
|
||||||
|
- **Toggle switch** - Connect/disconnect the server
|
||||||
|
- **Copy** - Copy command/URL to clipboard
|
||||||
|
- **Server Info** - Opens server info modal
|
||||||
|
- **Edit** - Opens edit server modal
|
||||||
|
- **Remove** - Deletes server (with confirmation)
|
||||||
|
|
||||||
|
### Server Info (Connected)
|
||||||
|
|
||||||
|
Shown as a modal or dedicated screen after successful connection.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ Server Information [×] │
|
||||||
|
├─────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ Name: everything-server │
|
||||||
|
│ Version: 1.0.0 │
|
||||||
|
│ Transport: stdio │
|
||||||
|
│ │
|
||||||
|
│ Capabilities │
|
||||||
|
│ ───────────── │
|
||||||
|
│ ✓ Tools (4) │
|
||||||
|
│ ✓ Resources (12) │
|
||||||
|
│ ✓ Prompts (2) │
|
||||||
|
│ ✓ Logging │
|
||||||
|
│ ✗ Sampling │
|
||||||
|
│ │
|
||||||
|
│ Server Instructions │
|
||||||
|
│ ─────────────────── │
|
||||||
|
│ "This server provides testing tools for MCP..." │
|
||||||
|
│ │
|
||||||
|
│ OAuth Details (if applicable) │
|
||||||
|
│ ───────────── │
|
||||||
|
│ Auth URL: https://auth.example.com │
|
||||||
|
│ Scopes: read, write │
|
||||||
|
│ Access Token: eyJhbG... [Copy] [Decode JWT ▼] │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Functionality:**
|
||||||
|
- Display server metadata and version
|
||||||
|
- Show capability summary with counts
|
||||||
|
- Display server instructions if provided
|
||||||
|
- Show OAuth tokens with copy and JWT decode options
|
||||||
|
|
||||||
|
### Feature Screens
|
||||||
|
|
||||||
|
Each feature screen uses a **resizable panel layout** for flexibility.
|
||||||
|
|
||||||
|
#### Tools Screen
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────┬────────────────────┬──────────────────┐
|
||||||
|
│ Tool List │ Parameters │ Results │
|
||||||
|
│ (30%) │ (40%) │ (30%) │
|
||||||
|
│ ↔ resize │ ↔ resize │ │
|
||||||
|
├─────────────┼────────────────────┼──────────────────┤
|
||||||
|
│ │ │ │
|
||||||
|
│ [Search...] │ Tool: echo │ Output: │
|
||||||
|
│ │ ─────────────── │ │
|
||||||
|
│ ● echo │ │ { │
|
||||||
|
│ ○ add │ message * │ "content": [ │
|
||||||
|
│ ○ longOp │ ┌───────────────┐ │ { │
|
||||||
|
│ ○ sampleLLM │ │ Hello world │ │ "type": │
|
||||||
|
│ │ └───────────────┘ │ "text" │
|
||||||
|
│ │ │ } │
|
||||||
|
│ │ [Execute Tool] │ ] │
|
||||||
|
│ │ │ } │
|
||||||
|
│ │ │ │
|
||||||
|
│ │ │ [Copy] [Clear] │
|
||||||
|
└─────────────┴────────────────────┴──────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- Searchable/filterable tool list
|
||||||
|
- Form generated from tool input schema
|
||||||
|
- Execute button with loading state
|
||||||
|
- JSON/text result display
|
||||||
|
- Support for cancellation of in-progress requests
|
||||||
|
|
||||||
|
#### Resources Screen
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────────┬──────────────────────────────────────┐
|
||||||
|
│ Resources (35%) │ Content Preview (65%) │
|
||||||
|
│ ↔ resize │ │
|
||||||
|
├──────────────────┼──────────────────────────────────────┤
|
||||||
|
│ │ │
|
||||||
|
│ [Search...] │ URI: file:///config.json │
|
||||||
|
│ [Refresh] │ MIME: application/json │
|
||||||
|
│ │ ───────────────────────────── │
|
||||||
|
│ ● config.json │ │
|
||||||
|
│ ○ readme.md │ { │
|
||||||
|
│ ○ data.csv │ "name": "my-app", │
|
||||||
|
│ │ "version": "1.0.0" │
|
||||||
|
│ Templates: │ } │
|
||||||
|
│ ○ user/{id} │ │
|
||||||
|
│ │ [Copy] [Subscribe] │
|
||||||
|
│ │ │
|
||||||
|
└──────────────────┴──────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- List resources with pagination
|
||||||
|
- Resource templates with variable input
|
||||||
|
- Subscribe/unsubscribe to resource updates
|
||||||
|
- Content viewer (JSON, text, binary preview)
|
||||||
|
|
||||||
|
#### Prompts Screen
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────┬───────────────────────────────┐
|
||||||
|
│ Prompt Selection (35%) │ Result (65%) │
|
||||||
|
│ ↔ resize │ │
|
||||||
|
├─────────────────────────┼───────────────────────────────┤
|
||||||
|
│ │ │
|
||||||
|
│ Select Prompt: │ Messages: │
|
||||||
|
│ ┌─────────────────────┐ │ │
|
||||||
|
│ │ greeting_prompt ▼ │ │ [0] role: user │
|
||||||
|
│ └─────────────────────┘ │ "Hello, my name is │
|
||||||
|
│ │ John and I like cats" │
|
||||||
|
│ Arguments: │ │
|
||||||
|
│ ───────────── │ [1] role: assistant │
|
||||||
|
│ │ "Nice to meet you..." │
|
||||||
|
│ name * │ │
|
||||||
|
│ ┌─────────────────────┐ │ │
|
||||||
|
│ │ John │ │ │
|
||||||
|
│ └─────────────────────┘ │ │
|
||||||
|
│ │ │
|
||||||
|
│ interests │ │
|
||||||
|
│ ┌─────────────────────┐ │ │
|
||||||
|
│ │ cats │ │ │
|
||||||
|
│ └─────────────────────┘ │ │
|
||||||
|
│ │ │
|
||||||
|
│ [Get Prompt] │ [Copy] │
|
||||||
|
└─────────────────────────┴───────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Features:**
|
||||||
|
- Dropdown to select from available prompts
|
||||||
|
- Form generated from prompt arguments
|
||||||
|
- Display prompt messages result
|
||||||
|
- Copy functionality
|
||||||
|
|
||||||
|
## Form Generation
|
||||||
|
|
||||||
|
Forms are dynamically generated from JSON Schema for tool inputs, prompt arguments, and resource template variables.
|
||||||
|
|
||||||
|
**Supported Field Types:**
|
||||||
|
| JSON Schema Type | Form Control |
|
||||||
|
|------------------|--------------|
|
||||||
|
| `string` | Text input |
|
||||||
|
| `string` (enum) | Select dropdown |
|
||||||
|
| `string` (format: uri) | URL input with validation |
|
||||||
|
| `number` / `integer` | Number input |
|
||||||
|
| `boolean` | Checkbox or toggle |
|
||||||
|
| `array` | Dynamic list with add/remove |
|
||||||
|
| `object` | Nested fieldset |
|
||||||
|
|
||||||
|
**Schema Features:**
|
||||||
|
- `required` - Mark fields as required (*)
|
||||||
|
- `default` - Pre-fill with default value
|
||||||
|
- `description` - Show as helper text
|
||||||
|
- `enum` - Render as select dropdown
|
||||||
|
- `minimum` / `maximum` - Validation for numbers
|
||||||
|
- `minLength` / `maxLength` - Validation for strings
|
||||||
|
|
||||||
|
**Fallback:**
|
||||||
|
- For complex schemas (`anyOf`, `oneOf`, `$ref`), show JSON editor as fallback
|
||||||
|
- Toggle between form view and JSON editor
|
||||||
|
|
||||||
|
## Error Handling UX
|
||||||
|
|
||||||
|
### Toast Notifications
|
||||||
|
|
||||||
|
Transient errors and success messages shown as toasts:
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ ✓ Connected to everything-server [×] │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ ⚠️ Tool execution failed: Invalid parameters [×] │
|
||||||
|
│ [View Documentation →] │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Inline Error Display
|
||||||
|
|
||||||
|
Persistent errors shown inline in context (e.g., server cards):
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ ⚠️ Connection Error │
|
||||||
|
│ │
|
||||||
|
│ Failed to connect: ECONNREFUSED │
|
||||||
|
│ Retry attempt 3 of 5 │
|
||||||
|
│ │
|
||||||
|
│ [Show full error] [Troubleshooting Guide →] │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Error Display Patterns:**
|
||||||
|
- **Truncation** - Long errors truncated to ~100 chars with "Show more"
|
||||||
|
- **Retry count** - Display retry attempts for connection errors
|
||||||
|
- **Doc links** - Contextual links to troubleshooting documentation
|
||||||
|
- **Expandable** - Click to show full error message/stack trace
|
||||||
|
|
||||||
|
### Connection States
|
||||||
|
|
||||||
|
Clear visual feedback for connection lifecycle:
|
||||||
|
|
||||||
|
| State | Visual | User Action |
|
||||||
|
|-------|--------|-------------|
|
||||||
|
| Disconnected | Gray status, toggle off | Click toggle to connect |
|
||||||
|
| Connecting | Yellow pulsing, spinner | Wait or cancel |
|
||||||
|
| Connected | Green status, toggle on | Click toggle to disconnect |
|
||||||
|
| Failed | Red status, error shown | Retry or edit config |
|
||||||
|
| OAuth Flow | Redirect indicator | Complete OAuth in browser |
|
||||||
Loading…
Reference in a new issue