diff --git a/specification/README.md b/specification/README.md index 4f24c5b7..0610ff21 100644 --- a/specification/README.md +++ b/specification/README.md @@ -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) diff --git a/specification/v1_problems.md b/specification/v1_problems.md index e40ab6e7..8f2fb7bb 100644 --- a/specification/v1_problems.md +++ b/specification/v1_problems.md @@ -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) diff --git a/specification/v2_scope.md b/specification/v2_scope.md index 1b0ceeec..06fb9721 100644 --- a/specification/v2_scope.md +++ b/specification/v2_scope.md @@ -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) diff --git a/specification/v2_tech_stack.md b/specification/v2_tech_stack.md index d60f5f5f..486d9522 100644 --- a/specification/v2_tech_stack.md +++ b/specification/v2_tech_stack.md @@ -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) @@ -29,13 +29,76 @@ Let's choose a feature-rich component set with easy theming control ### Transport Operation Let's consider how to operate the server transports. -* -[ ] [Express](https://expressjs.com/) +* -[x] [Express](https://expressjs.com/) * -[ ] Node:[http](https://nodejs.org/docs/v22.18.0/api/http.html) ### Logging Let's step up our logging capability with an advanced logger: * -[ ] [Winston](https://github.com/winstonjs/winston?tab=readme-ov-file#winston) -* -[ ] [Pino](https://github.com/pinojs/pino?tab=readme-ov-file#pino) +* -[x] [Pino](https://github.com/pinojs/pino?tab=readme-ov-file#pino) * -[ ] [Morgan](https://github.com/expressjs/morgan?tab=readme-ov-file#morgan) * -[ ] [Log4js](https://github.com/stritti/log4js?tab=readme-ov-file#log4js) * -[ ] [Bunyan](https://github.com/trentm/node-bunyan) + +#### Pino Rationale + +Pino is selected for synergy with the **History Screen** feature. The log file serves dual purposes: +1. **Server diagnostics** - Standard application logging +2. **History persistence** - Request/response replay source + +**Why Pino over Winston:** + +| Requirement | Pino | Winston | +|-------------|------|---------| +| Default JSON format | Yes - NDJSON | No - Text (needs config) | +| Line-by-line parsing | Yes - Native | No - Extra work | +| High-throughput logging | Yes - Very fast | Partial - Slower | +| Log rotation | Yes - pino-roll | Yes - winston-daily-rotate | +| Dev-friendly output | Yes - pino-pretty | Yes - Built-in | + +**Architecture:** + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Proxy Server │ +│ │ +│ MCP Request ──▶ Pino Logger ──┬──▶ history.ndjson (file) │ +│ │ │ +│ └──▶ Console (pino-pretty) │ +│ │ +│ History API: GET /api/history?method=tools/call&limit=50 │ +│ (parses history.ndjson, returns filtered JSON) │ +└─────────────────────────────────────────────────────────────────┘ +``` + +**Log Entry Schema:** + +Each MCP operation logs a request/response pair: + +```json +{"ts":1732987200000,"level":"info","type":"mcp_request","method":"tools/call","target":"echo","params":{"message":"hello"},"requestId":"abc123","serverId":"my-server"} +{"ts":1732987200045,"level":"info","type":"mcp_response","requestId":"abc123","result":{"content":[{"type":"text","text":"hello"}]},"duration":45,"success":true} +``` + +**Schema fields:** + +| Field | Description | +|-------|-------------| +| `ts` | Unix timestamp (ms) | +| `level` | Log level (info, error) | +| `type` | `mcp_request` or `mcp_response` | +| `method` | MCP method (tools/call, resources/read, prompts/get, etc.) | +| `target` | Tool name, resource URI, or prompt name | +| `params` | Request parameters | +| `requestId` | Correlation ID linking request to response | +| `serverId` | Server identifier | +| `result` | Response data (for mcp_response) | +| `error` | Error message (for failed requests) | +| `duration` | Response time in ms | +| `success` | Boolean success indicator | + +**Dependencies:** +- `pino` - Core logger +- `pino-pretty` - Dev console formatting +- `pino-roll` - Log rotation (optional) +- `pino-http` - Express integration diff --git a/specification/v2_ux.md b/specification/v2_ux.md new file mode 100644 index 00000000..15867aa0 --- /dev/null +++ b/specification/v2_ux.md @@ -0,0 +1,1079 @@ +# 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) + * [Import server.json Modal](#import-serverjson-modal) + * [Server Info (Connected)](#server-info-connected) + * [Feature Screens](#feature-screens) + * [Tools Screen](#tools-screen) + * [Resources Screen](#resources-screen) + * [Prompts Screen](#prompts-screen) + * [Logging Screen](#logging-screen) + * [Tasks Screen](#tasks-screen) + * [History Screen](#history-screen) + * [Client Feature Handlers](#client-feature-handlers) + * [Sampling Panel](#sampling-panel) + * [Elicitation Handler](#elicitation-handler) + * [Roots Configuration](#roots-configuration) + * [Experimental Features Panel](#experimental-features-panel) + * [Form Generation](#form-generation) + * [Error Handling UX](#error-handling-ux) + * [MCP Protocol Coverage](#mcp-protocol-coverage) + +## 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 ▼] ● Connected (23ms) [Tools] [Resources] [Prompts] [Logs] [Tasks] [History] [Disconnect] │ +├─────────────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Full-width content │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────────────┘ +``` + +- **Menu bar** displays server name, connection status with latency, and disconnect button when connected +- **Top navigation** links to Tools, Resources, Prompts, Logs, Tasks, and History sections +- **Connection indicator** shows latency from periodic `ping` requests +- **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 for manual configuration +- **Import config** - Paste/upload internal `mcp.json` config +- **Import server.json** - Import MCP Registry format ([Issue #922](https://github.com/modelcontextprotocol/inspector/issues/922)) + +**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) + +### Import server.json Modal + +Support for importing MCP Registry `server.json` format for testing servers before publishing. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ Import MCP Registry server.json [×] │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Paste server.json content or drag and drop a file: │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ { │ │ +│ │ "$schema": "https://static.modelcontextprotocol.io/schemas/...", │ │ +│ │ "name": "io.github.user/my-server", │ │ +│ │ "description": "A sample MCP server", │ │ +│ │ "version": "1.0.0", │ │ +│ │ "packages": [{ │ │ +│ │ "registryType": "npm", │ │ +│ │ "identifier": "my-mcp-server", │ │ +│ │ "runtimeHint": "npx", │ │ +│ │ "transport": { "type": "stdio" }, │ │ +│ │ "environmentVariables": [ │ │ +│ │ { "name": "API_KEY", "description": "API key", "required": true } │ │ +│ │ ] │ │ +│ │ }] │ │ +│ │ } │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ [Browse...] [Clear]│ +│ │ +│ ─────────────────────────────────────────────────────────────────────────── │ +│ │ +│ Validation Results: │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ ✓ Schema validation passed │ │ +│ │ ✓ Package found: my-mcp-server (npm) │ │ +│ │ ⚠ Environment variable API_KEY not set │ │ +│ │ ℹ Runtime hint: npx │ │ +│ │ ℹ Transport: stdio │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ─────────────────────────────────────────────────────────────────────────── │ +│ │ +│ Package Selection (if multiple packages): │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ ● npm: my-mcp-server (npx) │ │ +│ │ ○ pypi: my-mcp-server (uvx) │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Environment Variables: │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ API_KEY * Description: API key │ │ +│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ sk-... │ │ │ +│ │ └─────────────────────────────────────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ OPTIONAL_VAR Description: Optional setting │ │ +│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ +│ │ │ │ │ │ +│ │ └─────────────────────────────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Server Name (optional override): │ +│ ┌─────────────────────────────────────────────────────────────────────────┐ │ +│ │ my-server │ │ +│ └─────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ [Validate Again] [Cancel] [Add Server] │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +**Schema Validation:** +- Validate against official MCP Registry schema +- Show validation errors inline with line numbers +- Highlight issues in the JSON editor + +**Package Selection:** +- If server.json contains multiple packages (npm + pypi), let user choose which to use +- Display registry type, identifier, and runtime hint for each option + +**Environment Variables:** +- Parse `environmentVariables` array from selected package +- Generate form fields for each variable +- Mark required variables with asterisk (*) +- Show description as helper text +- Validate required variables are filled before enabling "Add Server" + +**Value Verification:** +- Check if package exists in registry (npm, pypi) +- Verify environment variables are set (or prompt user) +- For HTTP transport: optionally verify URL is reachable +- For STDIO: verify command is available (e.g., `npx` installed) + +**Server Generation:** +- Convert server.json to internal config format +- Construct command from runtime hint + package identifier (e.g., `npx -y my-mcp-server`) +- Apply environment variables +- Set transport type from package.transport + +**server.json to Internal Config Mapping:** +| server.json Field | Internal Config Field | +|-------------------|----------------------| +| `name` | `name` (display name) | +| `packages[n].registryType` | Determines command prefix | +| `packages[n].identifier` | Package name in command | +| `packages[n].runtimeHint` | Command prefix (npx, uvx, etc.) | +| `packages[n].transport.type` | `transportType` | +| `packages[n].environmentVariables` | `env` object | + +**Use Cases:** +1. MCP authors testing server.json before publishing to registry +2. Developers importing servers from registry without manual setup +3. Configuration troubleshooting with detailed validation feedback + +### Server Info (Connected) + +Shown as a modal or dedicated screen after successful connection. + +``` +┌─────────────────────────────────────────────────────────┐ +│ Server Information [×] │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ Name: everything-server │ +│ Version: 1.0.0 │ +│ Protocol: 2025-11-25 │ +│ Transport: stdio │ +│ │ +│ Server Capabilities Client Capabilities │ +│ ───────────────────── ───────────────────── │ +│ ✓ Tools (4) ✓ Sampling │ +│ ✓ Resources (12) ✓ Elicitation │ +│ ✓ Prompts (2) ✓ Roots (3) │ +│ ✓ Logging ✓ Tasks │ +│ ✓ Completions │ +│ ✓ Tasks │ +│ ✗ Experimental │ +│ │ +│ 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, version, and negotiated protocol version +- Show both **server** and **client** capabilities with counts +- Server capabilities: Tools, Resources, Prompts, Logging, Completions, Tasks, Experimental +- Client capabilities: Sampling, Elicitation, Roots, Tasks, Experimental +- 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 + +``` +┌─────────────────┬──────────────────────────────────────┬────────────────────────┐ +│ Tools (4) │ Parameters │ Results │ +│ ● List updated │ (40%) │ (30%) │ +│ [Refresh Now] │ ↔ resize │ │ +├─────────────────┼──────────────────────────────────────┼────────────────────────┤ +│ │ │ │ +│ [Search...] │ Tool: query_database │ Output: │ +│ │ ─────────────────── │ │ +│ ● query_db │ Annotations: │ ┌──────────────────┐ │ +│ [user] │ Audience: user │ │ │ │ +│ [read-only] │ Read-only: true │ │ [Image] │ │ +│ │ Hints: "Useful for data queries" │ │ │ │ +│ ○ echo │ │ └──────────────────┘ │ +│ ○ add │ table * │ │ +│ ○ longOp │ ┌────────────────────────────────┐ │ { │ +│ [long-run] │ │ users ▼ │ │ "rows": 42, │ +│ ○ dangerOp │ └────────────────────────────────┘ │ "data": [...] │ +│ [destructive]│ Suggestions: users, orders, items │ } │ +│ │ │ │ +│ │ limit │ [Play Audio] │ +│ │ ┌────────────────────────────────┐ │ │ +│ │ │ 100 │ │ [Copy] [Clear] │ +│ │ └────────────────────────────────┘ │ │ +│ │ │ │ +│ │ ████████████░░░░░░░░ 60% │ │ +│ │ Processing step 3 of 5... │ │ +│ │ │ │ +│ │ [Execute Tool] [Cancel] │ │ +└─────────────────┴──────────────────────────────────────┴────────────────────────┘ +``` + +**Features:** +- **List Changed Indicator** - Shows when `notifications/tools/list_changed` received, with refresh button +- Searchable/filterable tool list +- **Tool Annotations** displayed: + - Audience badge ([user], [assistant]) + - Read-only indicator ([read-only]) + - Destructive warning ([destructive]) + - Long-running indicator ([long-run]) + - Custom hints from server +- **Autocomplete** for arguments via `completion/complete`: + - Dropdown suggestions as user types + - Supports enum and dynamic completion +- Form generated from tool input schema +- **Progress Indicator** from `notifications/progress`: + - Progress bar with percentage + - Step description if provided + - Elapsed time display +- Execute button with loading state +- **Cancel button** sends `notifications/cancelled` +- **Rich Result Display**: + - JSON/text with syntax highlighting + - Image preview for image content (base64) + - Audio player for audio content (base64) + - Resource links displayed as clickable references + +#### Resources Screen + +``` +┌─────────────────────────┬─────────────────────────────────────────────────┐ +│ Resources (12) │ Content Preview (65%) │ +│ ● List updated │ │ +│ [Refresh Now] │ │ +├─────────────────────────┼─────────────────────────────────────────────────┤ +│ │ │ +│ [Search...] │ URI: file:///config.json │ +│ │ MIME: application/json │ +│ ● config.json │ ───────────────────────────── │ +│ [application] │ │ +│ [priority: 0.9] │ Annotations: │ +│ │ Audience: application │ +│ ○ readme.md │ Priority: 0.9 (high) │ +│ [user] │ │ +│ │ { │ +│ ○ data.csv │ "name": "my-app", │ +│ │ "version": "1.0.0" │ +│ Templates: │ } │ +│ ○ user/{id} │ │ +│ [id: ________ ] [Go] │ [Copy] [Subscribe] [Unsubscribe] │ +│ │ │ +│ Subscriptions: │ Last updated: 14:32:05 │ +│ ● config.json (active) │ │ +│ │ │ +└─────────────────────────┴─────────────────────────────────────────────────┘ +``` + +**Features:** +- **List Changed Indicator** - Shows when `notifications/resources/list_changed` received +- List resources with pagination +- **Resource Annotations** displayed: + - Audience badge ([user], [application/assistant]) + - Priority indicator ([high], [medium], [low]) +- Resource templates with inline variable input +- Subscribe/unsubscribe to resource updates +- **Subscriptions Panel** shows active subscriptions with last update time +- Content viewer (JSON, text, binary preview) +- Image preview for image resources +- Audio player for audio resources + +#### Prompts Screen + +``` +┌──────────────────────────────┬──────────────────────────────────────────┐ +│ Prompts (2) │ Result (65%) │ +│ ● List updated [Refresh Now] │ │ +├──────────────────────────────┼──────────────────────────────────────────┤ +│ │ │ +│ Select Prompt: │ Messages: │ +│ ┌──────────────────────────┐ │ │ +│ │ greeting_prompt ▼ │ │ [0] role: user │ +│ └──────────────────────────┘ │ Content: │ +│ │ "Hello, my name is John and I │ +│ Description: │ like cats" │ +│ "Generates a friendly │ │ +│ greeting message" │ [Image: profile.png] │ +│ │ │ +│ Arguments: │ [1] role: assistant │ +│ ───────────── │ "Nice to meet you, John! I see │ +│ │ you're a cat lover..." │ +│ name * │ │ +│ ┌──────────────────────────┐ │ │ +│ │ John ▼ │ │ │ +│ └──────────────────────────┘ │ │ +│ Suggestions: John, Jane │ │ +│ │ │ +│ interests │ │ +│ ┌──────────────────────────┐ │ │ +│ │ cats │ │ │ +│ └──────────────────────────┘ │ │ +│ │ │ +│ [Get Prompt] │ [Copy JSON] [Copy Messages] │ +└──────────────────────────────┴──────────────────────────────────────────┘ +``` + +**Features:** +- **List Changed Indicator** - Shows when `notifications/prompts/list_changed` received +- Dropdown to select from available prompts +- Prompt description displayed +- **Autocomplete** for arguments via `completion/complete` +- Form generated from prompt arguments +- Display prompt messages result with: + - Role labels + - Text content + - Image content preview + - Audio content player + - Embedded resource display +- Copy functionality (JSON or plain messages) + +#### Logging Screen + +``` +┌──────────────────────┬──────────────────────────────────────────────────┐ +│ Log Controls (25%) │ Log Stream (75%) │ +│ ↔ resize │ │ +├──────────────────────┼──────────────────────────────────────────────────┤ +│ │ │ +│ Log Level: │ 14:32:01 [INFO] Server initialized │ +│ ┌────────────────┐ │ 14:32:02 [DEBUG] Loading tool: echo │ +│ │ debug ▼ │ │ 14:32:02 [DEBUG] Loading tool: add │ +│ └────────────────┘ │ 14:32:05 [WARN] Rate limit approaching │ +│ │ 14:32:10 [ERROR] Failed to fetch resource: 404 │ +│ [Set Level] │ │ +│ │ ───────────────────────────────────────────── │ +│ Filter: │ │ +│ ┌────────────────┐ │ │ +│ │ │ │ │ +│ └────────────────┘ │ │ +│ │ │ +│ Show Levels: │ │ +│ ☑ DEBUG │ │ +│ ☑ INFO │ │ +│ ☑ WARNING │ │ +│ ☑ ERROR │ │ +│ │ │ +│ [Clear] [Export] │ [Auto-scroll ✓] [Copy All] │ +└──────────────────────┴──────────────────────────────────────────────────┘ +``` + +**Features:** +- **Set Log Level** via `logging/setLevel` request + - Options: debug, info, notice, warning, error, critical, alert, emergency +- **Real-time Log Stream** from `notifications/message` +- Filter by text search +- Filter by log level checkboxes +- Color-coded by severity: + - DEBUG: gray + - INFO: blue + - WARNING: yellow + - ERROR: red +- Timestamp display +- Logger name display (if provided) +- Auto-scroll toggle +- Export logs to file +- Copy all logs to clipboard + +#### Tasks Screen + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Tasks [Refresh] │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Active Tasks (2) │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Task: abc-123 Status: running ████████░░ 80% │ │ +│ │ Method: tools/call │ │ +│ │ Tool: longRunningOperation │ │ +│ │ Started: 14:32:05 Elapsed: 45s │ │ +│ │ Progress: Processing batch 4 of 5... │ │ +│ │ [View Details] [Cancel] │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Task: def-456 Status: waiting ░░░░░░░░░░ 0% │ │ +│ │ Method: resources/read │ │ +│ │ Resource: large-dataset │ │ +│ │ Started: 14:33:00 Elapsed: 10s │ │ +│ │ [View Details] [Cancel] │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Completed Tasks (3) [Clear History] │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Task: ghi-789 Status: completed ██████████ 100% │ │ +│ │ Method: tools/call (processData) │ │ +│ │ Completed: 14:31:30 Duration: 1m 30s │ │ +│ │ [View Result] [Dismiss] │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Features:** +- **Task List** via `tasks/list` request +- **Real-time Status Updates** via `notifications/task/statusChanged` +- **Progress Display** from `notifications/progress`: + - Progress bar with percentage + - Current step description + - Total/current progress numbers +- Task states: waiting, running, completed, failed, cancelled +- **Cancel Tasks** via `tasks/cancel` +- **View Results** via `tasks/result` +- **View Task Details** via `tasks/get` +- Task history with dismissal +- Elapsed time / duration display + +#### History Screen + +A unified history of all MCP requests with replay capability. + +``` +┌─────────────────────────────────────────────────────────────────────────────────────┐ +│ History [Search...] [Filter ▼] [Clear All] │ +├─────────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ +│ │ * 14:35:22 tools/call echo [Replay] [Pin] │ │ +│ │ Parameters: { "message": "Hello world" } │ │ +│ │ Result: ✓ Success (45ms) │ │ +│ │ ──────────────────────────────────────────────────────────────────────────── │ │ +│ │ Response: { "content": [{ "type": "text", "text": "Hello world" }] } │ │ +│ └─────────────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ +│ │ 14:34:15 resources/read file:///config.json [Replay] [Pin] │ │ +│ │ Result: ✓ Success (120ms) │ │ +│ │ ──────────────────────────────────────────────────────────────────────────── │ │ +│ │ Content: { "name": "my-app", "version": "1.0.0" } (collapsed) [Expand] │ │ +│ └─────────────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ +│ │ 14:33:45 prompts/get greeting_prompt [Replay] [Pin] │ │ +│ │ Arguments: { "name": "John", "interests": "cats" } │ │ +│ │ Result: ✓ Success (30ms) │ │ +│ └─────────────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ +│ │ 14:32:10 tools/call query_database [Replay] [Pin] │ │ +│ │ Parameters: { "table": "users", "limit": 10 } │ │ +│ │ Result: ✗ Error (200ms) │ │ +│ │ ──────────────────────────────────────────────────────────────────────────── │ │ +│ │ Error: "Table 'users' not found" │ │ +│ └─────────────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Pinned Requests (2) │ +│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ +│ │ * "Test echo" tools/call echo 14:35:22 [Replay] [Unpin] │ +│ │ * "Get config" resources/read file:///config.json 14:34:15 [Replay] [Unpin] │ +│ └─────────────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Showing 50 of 127 entries │ +│ [Load More] │ +└─────────────────────────────────────────────────────────────────────────────────────┘ +``` + +**Features:** +- **Automatic Capture** - All MCP requests/responses logged automatically: + - `tools/call` - Tool invocations + - `resources/read` - Resource reads + - `prompts/get` - Prompt retrievals + - `sampling/createMessage` - Sampling requests/responses + - `elicitation/create` - Elicitation requests/responses +- **Request Details** displayed: + - Timestamp + - Method name + - Target (tool name, resource URI, prompt name) + - Parameters/arguments + - Result status (success/error) + - Response time + - Response data (collapsible) +- **Replay** - Re-execute any request with original parameters: + - Opens relevant screen (Tools, Resources, Prompts) pre-filled + - Option to modify parameters before replay +- **Pin/Save** - Pin important requests for quick access: + - Pinned requests persist across sessions + - Optional custom label for pinned items + - Pinned section at bottom for easy access +- **Filter** by: + - Method type (tools, resources, prompts, sampling, elicitation) + - Status (success, error) + - Time range +- **Search** across method names, parameters, and responses +- **Pagination** - Load more for large histories +- **Clear** - Clear history (with confirmation) +- **Export** - Export history as JSON for sharing/debugging + +**Replay Workflow:** +1. Click [Replay] on any history entry +2. Inspector navigates to the appropriate screen (Tools, Resources, Prompts) +3. Form is pre-filled with the original parameters +4. User can modify parameters or execute immediately +5. New request is added to history + +### Client Feature Handlers + +These are modals/panels that appear when the server invokes client capabilities. + +#### Sampling Panel + +When server sends `sampling/createMessage` request: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Sampling Request [x] │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ The server is requesting an LLM completion. │ +│ │ +│ Messages: │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ [0] role: user │ │ +│ │ "Analyze this data and provide insights about the trends..." │ │ +│ │ │ │ +│ │ [1] role: user │ │ +│ │ [Image: data_chart.png - Click to preview] │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Model Preferences: │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Hints: ["claude-3-sonnet", "gpt-4"] │ │ +│ │ Cost Priority: low (0.2) │ │ +│ │ Speed Priority: medium (0.5) │ │ +│ │ Intelligence Priority: high (0.8) │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Parameters: │ +│ Max Tokens: 1000 │ +│ Stop Sequences: ["\n\n", "END"] │ +│ Temperature: (not specified) │ +│ │ +│ Include Context: ☑ thisServer │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Response (enter mock response or connect to LLM): │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Based on the data chart, I can see several key trends: │ │ +│ │ │ │ +│ │ 1. Revenue has increased 25% quarter-over-quarter │ │ +│ │ 2. User engagement peaks on Tuesdays... │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Model Used: ________________ Stop Reason: [end_turn ▼] │ +│ │ +│ [Reject Request] [Send Response] │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Features:** +- Display full sampling request details: + - Messages with text, image, and audio content + - Model hints and preferences + - Max tokens, stop sequences, temperature + - Context inclusion settings +- **Editable response field** for mock LLM testing +- Model and stop reason fields for response +- **Approve/Reject** with human-in-the-loop +- Image/audio preview in messages +- Option to integrate with real LLM (deferred to plugins) + +#### Elicitation Handler + +When server sends `elicitation/create` request: + +**Form Mode:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Server Request: User Input Required [x] │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ "Please provide your database connection details to proceed." │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Host * │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ localhost │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Port * │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ 5432 │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Database │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ myapp_production │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ SSL Mode │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ require ▼ │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ WARNING: Only provide information you trust this server with. │ +│ The server "{server_name}" is requesting this data. │ +│ │ +│ [Cancel] [Submit] │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**URL Mode:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Server Request: External Action Required [x] │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ "Please complete the OAuth authorization in your browser." │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ The server is requesting you visit: │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ https://auth.example.com/oauth/authorize?client_id=abc&state=xyz │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ [Copy URL] │ +│ │ +│ [Open in Browser] │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Status: Waiting for completion... ◌ (spinning) │ +│ │ +│ Elicitation ID: abc123-def456 │ +│ │ +│ WARNING: This will open an external URL. Verify the domain before proceeding. +│ │ +│ [Cancel] │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Features:** +- **Form Mode:** + - Generate form from JSON Schema in request + - Validate input before submission + - Required field indicators + - Security warning with server name + - Submit returns response to server +- **URL Mode:** + - Display URL for user to visit + - Copy URL button + - Open in browser button + - Waiting indicator until `notifications/elicitation/complete` received + - Elicitation ID display + - Domain verification warning +- **Cancel** sends declined response + +#### Roots Configuration + +Accessed via Settings or Server Info panel: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Roots Configuration │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Filesystem roots exposed to the connected server: │ +│ │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Name URI Actions │ │ +│ ├─────────────────────────────────────────────────────────────────────┤ │ +│ │ Project file:///home/user/myproject [Remove] │ │ +│ ├─────────────────────────────────────────────────────────────────────┤ │ +│ │ Documents file:///home/user/Documents [Remove] │ │ +│ ├─────────────────────────────────────────────────────────────────────┤ │ +│ │ Config file:///etc/myapp [Remove] │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ [+ Add Root] │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Add New Root: │ +│ │ +│ Name: │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ Downloads │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Path: │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ /home/user/Downloads │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ [Browse] [Add] │ +│ │ +│ WARNING: Roots give the server access to these directories. │ +│ Only add directories you trust the server to access. │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Features:** +- List configured roots with name and URI +- Add new roots: + - Name field + - Path field with browse button +- Remove roots +- **Sends `notifications/roots/listChanged`** when roots are modified +- Responds to `roots/list` requests from server +- Security warning about filesystem access + +#### Experimental Features Panel + +Accessed via Settings or dedicated nav item: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ Experimental Features │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ WARNING: These features are non-standard and may change or be removed. │ +│ │ +│ Server Experimental Capabilities: │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ custom_analytics │ │ +│ │ Description: Custom analytics tracking │ │ +│ │ Methods: analytics/track, analytics/query │ │ +│ │ [Test →] │ │ +│ ├─────────────────────────────────────────────────────────────────────┤ │ +│ │ streaming_v2 │ │ +│ │ Description: Enhanced streaming support │ │ +│ │ Methods: stream/start, stream/stop, stream/data │ │ +│ │ [Test →] │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Client Experimental Capabilities (advertised to server): │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ ☐ custom_analytics │ │ +│ │ ☐ streaming_v2 │ │ +│ │ ☐ Add custom capability... │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ ───────────────────────────────────────────────────────────────────── │ +│ │ +│ Raw JSON-RPC Tester: │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ { │ │ +│ │ "jsonrpc": "2.0", │ │ +│ │ "id": 1, │ │ +│ │ "method": "experimental/myMethod", │ │ +│ │ "params": { │ │ +│ │ "key": "value" │ │ +│ │ } │ │ +│ │ } │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ [Send Request] │ +│ │ +│ Response: │ +│ ┌─────────────────────────────────────────────────────────────────────┐ │ +│ │ { │ │ +│ │ "jsonrpc": "2.0", │ │ +│ │ "id": 1, │ │ +│ │ "result": { │ │ +│ │ "status": "success" │ │ +│ │ } │ │ +│ │ } │ │ +│ └─────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Request History: │ +│ 14:32:05 - experimental/myMethod (success) │ +│ 14:31:22 - analytics/track (success) │ +│ 14:30:01 - stream/start (error) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Features:** +- Display server's experimental capabilities from initialization +- Toggle client experimental capabilities to advertise +- Add custom client experimental capabilities +- **Raw JSON-RPC Tester:** + - JSON editor for arbitrary requests + - Send button + - Response display + - Syntax highlighting + - Request history with timestamps and status +- Test experimental methods directly +- View raw request/response for debugging + +## 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 [x] │ +│ [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 | + +## MCP Protocol Coverage + +This UX specification covers **100% of the MCP 2025-11-25 protocol specification**. + +### Request Methods + +| Method | UX Location | +|--------|-------------| +| `initialize` | Connection flow (implicit) | +| `ping` | Navigation bar latency display | +| `tools/list` | Tools Screen | +| `tools/call` | Tools Screen | +| `resources/list` | Resources Screen | +| `resources/templates/list` | Resources Screen (templates section) | +| `resources/read` | Resources Screen | +| `resources/subscribe` | Resources Screen | +| `resources/unsubscribe` | Resources Screen | +| `prompts/list` | Prompts Screen | +| `prompts/get` | Prompts Screen | +| `sampling/createMessage` | Sampling Panel | +| `elicitation/create` | Elicitation Handler | +| `completion/complete` | Tools/Prompts autocomplete | +| `logging/setLevel` | Logging Screen | +| `roots/list` | Roots Configuration | +| `tasks/list` | Tasks Screen | +| `tasks/get` | Tasks Screen | +| `tasks/result` | Tasks Screen | +| `tasks/cancel` | Tasks Screen | + +### Notification Methods + +| Notification | UX Location | +|--------------|-------------| +| `notifications/initialized` | Connection flow (implicit) | +| `notifications/progress` | Tools Screen progress bar, Tasks Screen | +| `notifications/cancelled` | Tools Screen cancel button | +| `notifications/message` | Logging Screen | +| `notifications/tools/list_changed` | Tools Screen indicator | +| `notifications/resources/list_changed` | Resources Screen indicator | +| `notifications/prompts/list_changed` | Prompts Screen indicator | +| `notifications/resources/updated` | Resources Screen subscriptions | +| `notifications/roots/listChanged` | Roots Configuration | +| `notifications/task/statusChanged` | Tasks Screen | +| `notifications/elicitation/complete` | Elicitation Handler (URL mode) | + +### Capabilities + +| Capability | Type | UX Location | +|------------|------|-------------| +| `tools` | Server | Tools Screen, Server Info | +| `resources` | Server | Resources Screen, Server Info | +| `prompts` | Server | Prompts Screen, Server Info | +| `logging` | Server | Logging Screen, Server Info | +| `completions` | Server | Forms autocomplete, Server Info | +| `tasks` | Server | Tasks Screen, Server Info | +| `experimental` | Server | Experimental Features Panel, Server Info | +| `sampling` | Client | Sampling Panel, Server Info | +| `elicitation` | Client | Elicitation Handler, Server Info | +| `roots` | Client | Roots Configuration, Server Info | +| `tasks` | Client | Tasks Screen, Server Info | +| `experimental` | Client | Experimental Features Panel, Server Info | + +### Content Types + +| Content Type | UX Location | +|--------------|-------------| +| Text | All screens (default) | +| Image (base64) | Tools results, Prompts messages, Resources | +| Audio (base64) | Tools results, Prompts messages, Resources | +| Resource links | Tools results, embedded display | +| Embedded resources | Prompts messages | + +### Annotations + +| Annotation | UX Location | +|------------|-------------| +| Tool audience | Tools Screen badges | +| Tool hints | Tools Screen description | +| Tool readOnly | Tools Screen indicator | +| Tool destructive | Tools Screen warning | +| Resource audience | Resources Screen badges | +| Resource priority | Resources Screen indicator |