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
|
||||
|
||||
### 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
|
||||
* [Motivation and Context](#motivation-and-context)
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# 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
|
||||
* [Monolithic components](#monolithic-components)
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# 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
|
||||
* [Protocol Features](#protocol-features)
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# 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
|
||||
* [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