From 79b5e9fdd3499bb4d10f2a5cb1334d83e38a1aa8 Mon Sep 17 00:00:00 2001 From: olaservo Date: Sun, 30 Nov 2025 06:39:24 -0700 Subject: [PATCH] Add full MCP 2025-11-25 protocol coverage to v2_ux.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add server.json import support (Issue #922) for MCP Registry format - Add History Screen with automatic capture and replay functionality - Add Pino logging rationale with log-as-history architecture - Remove emojis from markdown files, use text alternatives New UX sections added: - Logging Screen (notifications/message, logging/setLevel) - Tasks Screen (tasks/*, notifications/task/statusChanged) - Sampling Panel (sampling/createMessage) - Elicitation Handler (form + URL modes) - Roots Configuration (roots/list) - Experimental Features Panel (raw JSON-RPC tester) Enhanced existing screens: - Tools: annotations, autocomplete, progress indicators, image/audio - Resources: annotations, subscriptions - Prompts: autocomplete - Navigation: ping latency, listChanged indicators 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- specification/v2_tech_stack.md | 63 +++ specification/v2_ux.md | 924 +++++++++++++++++++++++++++++---- 2 files changed, 898 insertions(+), 89 deletions(-) diff --git a/specification/v2_tech_stack.md b/specification/v2_tech_stack.md index a8d4d0b9..486d9522 100644 --- a/specification/v2_tech_stack.md +++ b/specification/v2_tech_stack.md @@ -39,3 +39,66 @@ Let's step up our logging capability with an advanced logger: * -[ ] [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 index e53aacaa..15867aa0 100644 --- a/specification/v2_ux.md +++ b/specification/v2_ux.md @@ -8,10 +8,23 @@ * [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 @@ -25,17 +38,18 @@ ## Navigation Model ``` -┌─────────────────────────────────────────────────────────┐ -│ [Server Name ▼] [Tools] [Resources] [Prompts] [Disconnect] │ -├─────────────────────────────────────────────────────────┤ -│ │ -│ Full-width content │ -│ │ -└─────────────────────────────────────────────────────────┘ +┌─────────────────────────────────────────────────────────────────────────────────────────┐ +│ [Server Name ▼] ● Connected (23ms) [Tools] [Resources] [Prompts] [Logs] [Tasks] [History] [Disconnect] │ +├─────────────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Full-width content │ +│ │ +└─────────────────────────────────────────────────────────────────────────────────────────┘ ``` -- **Menu bar** displays server name and disconnect button when connected -- **Top navigation** links to Tools, Resources, Prompts sections +- **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 @@ -63,8 +77,9 @@ Initial screen shown when no server is connected. Displays server cards in a res ``` **Add Server Options:** -- Add manually (opens form modal) -- Import from JSON (paste/upload config) +- **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 @@ -96,7 +111,7 @@ Each server in the list is displayed as a card with connection controls and stat ├─────────────────────────────────────────────────────────┤ │ [Server Info] [Edit] [Remove] │ ├─────────────────────────────────────────────────────────┤ -│ ⚠️ Connection timeout after 20s │ +│ [!] Connection timeout after 20s │ │ [Show more] [View Troubleshooting Guide →] │ └─────────────────────────────────────────────────────────┘ ``` @@ -116,6 +131,119 @@ Each server in the list is displayed as a card with connection controls and stat - **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. @@ -127,15 +255,18 @@ Shown as a modal or dedicated screen after successful connection. │ │ │ Name: everything-server │ │ Version: 1.0.0 │ +│ Protocol: 2025-11-25 │ │ Transport: stdio │ │ │ -│ Capabilities │ -│ ───────────── │ -│ ✓ Tools (4) │ -│ ✓ Resources (12) │ -│ ✓ Prompts (2) │ -│ ✓ Logging │ -│ ✗ Sampling │ +│ Server Capabilities Client Capabilities │ +│ ───────────────────── ───────────────────── │ +│ ✓ Tools (4) ✓ Sampling │ +│ ✓ Resources (12) ✓ Elicitation │ +│ ✓ Prompts (2) ✓ Roots (3) │ +│ ✓ Logging ✓ Tasks │ +│ ✓ Completions │ +│ ✓ Tasks │ +│ ✗ Experimental │ │ │ │ Server Instructions │ │ ─────────────────── │ @@ -151,8 +282,10 @@ Shown as a modal or dedicated screen after successful connection. ``` **Functionality:** -- Display server metadata and version -- Show capability summary with counts +- 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 @@ -163,97 +296,627 @@ 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] │ -└─────────────┴────────────────────┴──────────────────┘ +┌─────────────────┬──────────────────────────────────────┬────────────────────────┐ +│ 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 -- JSON/text result display -- Support for cancellation of in-progress requests +- **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 (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] │ -│ │ │ -└──────────────────┴──────────────────────────────────────┘ +┌─────────────────────────┬─────────────────────────────────────────────────┐ +│ 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 templates with variable input +- **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 ``` -┌─────────────────────────┬───────────────────────────────┐ -│ 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] │ -└─────────────────────────┴───────────────────────────────┘ +┌──────────────────────────────┬──────────────────────────────────────────┐ +│ 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 -- Copy functionality +- 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 @@ -294,7 +957,7 @@ Transient errors and success messages shown as toasts: └─────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────┐ -│ ⚠️ Tool execution failed: Invalid parameters [×] │ +│ [!] Tool execution failed: Invalid parameters [x] │ │ [View Documentation →] │ └─────────────────────────────────────────────────────────┘ ``` @@ -305,7 +968,7 @@ Persistent errors shown inline in context (e.g., server cards): ``` ┌─────────────────────────────────────────────────────────┐ -│ ⚠️ Connection Error │ +│ [!] Connection Error │ │ │ │ Failed to connect: ECONNREFUSED │ │ Retry attempt 3 of 5 │ @@ -331,3 +994,86 @@ Clear visual feedback for connection lifecycle: | 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 |