From 59e05ba59e4e3fc3ce8d1deeef09b4a0f1832495 Mon Sep 17 00:00:00 2001 From: olaservo Date: Thu, 25 Dec 2025 12:00:13 -0700 Subject: [PATCH] spec: Add client features UX patterns (sampling/elicitation) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates UX specs for better integration of client-initiated features: v2_ux_features.md: - Tools Screen: Inline client request queue during tool execution - History Screen: Hierarchical request trace showing parent-child relationships - Logging Screen: Request correlation with correlation IDs and chain filtering v2_ux_handlers.md: - Sampling Panel: Inline expansion pattern + tool calling flow (2025-11-25 spec) - Elicitation Handler: Inline expansion pattern with schema constraints - Sampling Providers & Testing Profiles: Extensible architecture for response handlers Key design decisions: - Request Trace Model shows causal chains between requests - Client requests appear inline with triggering tool calls - Auto-response profiles enable efficient testing workflows - Extensible provider architecture supports future LLM plugins 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- specification/v2_ux.md | 1410 ++++++++++++++++++++++--------- specification/v2_ux_features.md | 164 +++- specification/v2_ux_handlers.md | 379 ++++++++- 3 files changed, 1492 insertions(+), 461 deletions(-) diff --git a/specification/v2_ux.md b/specification/v2_ux.md index 0fe193c0..7a5263b6 100644 --- a/specification/v2_ux.md +++ b/specification/v2_ux.md @@ -1,9 +1,6 @@ # Inspector V2 UX Specification -### [Brief](README.md) | [V1 Problems](v1_problems.md) | [V2 Scope](v2_scope.md) | [V2 Tech Stack](v2_tech_stack.md) -### UX: Overview | [Features](v2_ux_features.md) | [Handlers](v2_ux_handlers.md) | [Screenshots](v2_screenshots.md) - ---- +### [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) @@ -11,17 +8,24 @@ * [Screen Flows](#screen-flows) * [Server List (Home)](#server-list-home) * [Server Connection Card](#server-connection-card) - * [Server Settings Modal](#server-settings-modal) * [Import server.json Modal](#import-serverjson-modal) * [Server Info (Connected)](#server-info-connected) - * [OAuth Debugger](#oauth-debugger) + * [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) -**Additional UX Documentation:** -- [Feature Screens](v2_ux_features.md) - Tools, Resources, Prompts, Logging, Tasks, History -- [Handlers & Patterns](v2_ux_handlers.md) - Sampling, Elicitation, Roots, Form Generation, Error Handling -- [Visual Reference](v2_screenshots.md) - Screenshots from the Shadcn prototype - ## Design Principles - **Single server connection** - No multiple concurrent connections (defer to plugins) @@ -34,13 +38,13 @@ ## Navigation Model ``` -+-------------------------------------------------------------------------------------+ -| [Server Name v] (*) Connected (23ms) [Tools] [Resources] [Prompts] [Logs] [Tasks] [History] [Disconnect] | -+-------------------------------------------------------------------------------------+ -| | -| Full-width content | -| | -+-------------------------------------------------------------------------------------+ +┌─────────────────────────────────────────────────────────────────────────────────────────┐ +│ [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 @@ -55,21 +59,21 @@ Initial screen shown when no server is connected. Displays server cards in a responsive grid (1-2 columns). ``` -+---------------------------------------------------------+ -| MCP Inspector | -| [+ Add Server v] | -+---------------------------------------------------------+ -| | -| +-------------------------+ +-------------------------+ -| | Server Card 1 | | Server Card 2 | -| | (see below) | | (see below) | -| +-------------------------+ +-------------------------+ -| | -| +-------------------------+ | -| | Server Card 3 | | -| +-------------------------+ | -| | -+---------------------------------------------------------+ +┌─────────────────────────────────────────────────────────┐ +│ MCP Inspector │ +│ [+ Add Server ▼] │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────┐ ┌─────────────────────────┐ +│ │ Server Card 1 │ │ Server Card 2 │ +│ │ (see below) │ │ (see below) │ +│ └─────────────────────────┘ └─────────────────────────┘ +│ │ +│ ┌─────────────────────────┐ │ +│ │ Server Card 3 │ │ +│ └─────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────┘ ``` **Add Server Options:** @@ -87,47 +91,29 @@ Initial screen shown when no server is connected. Displays server cards in a res Each server in the list is displayed as a card with connection controls and status. ``` -+-----------------------------------------------------------------+ -| [Icon] Server Name v1.0.0 | -| STDIO [Via Proxy v] (*) Connected [Toggle] | -+-----------------------------------------------------------------+ -| npx -y @modelcontextprotocol/server-everything [Copy] | -+-----------------------------------------------------------------+ -| [Server Info] [Settings] [Clone] [Edit] [Remove] | -+-----------------------------------------------------------------+ -``` - -**Connection Mode Dropdown:** -- Quick access to switch between Direct and Via Proxy modes without opening Settings -- STDIO servers default to "Via Proxy" (required - cannot connect directly from browser) -- HTTP/SSE servers default to "Direct" (assumes CORS enabled) -- Shows warning text if STDIO + Direct selected: "(STDIO requires proxy)" - -**With OAuth (shows OAuth Debug button):** -``` -+-----------------------------------------------------------------+ -| [Icon] Server Name v1.0.0 | -| HTTP [Direct v] (*) Connected [Toggle] | -+-----------------------------------------------------------------+ -| https://api.example.com/mcp [Copy] | -+-----------------------------------------------------------------+ -| [Server Info] [Settings] [OAuth Debug] [Clone] [Edit] [Remove] | -+-----------------------------------------------------------------+ +┌─────────────────────────────────────────────────────────┐ +│ [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 [Direct v] (!) Failed (3) [Toggle] | -+-----------------------------------------------------------------+ -| https://api.example.com/mcp [Copy] | -+-----------------------------------------------------------------+ -| [Server Info] [Settings] [Clone] [Edit] [Remove] | -+-----------------------------------------------------------------+ -| [!] Connection timeout after 20s | -| [Show more] [View Troubleshooting Guide] | -+-----------------------------------------------------------------+ +┌─────────────────────────────────────────────────────────┐ +│ [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:** @@ -142,181 +128,78 @@ Each server in the list is displayed as a card with connection controls and stat - **Toggle switch** - Connect/disconnect the server - **Copy** - Copy command/URL to clipboard - **Server Info** - Opens server info modal -- **Settings** - Opens server settings modal (see below) -- **OAuth Debug** - Opens OAuth debugger modal (visible when server uses OAuth) -- **Clone** - Duplicates server config for creating variants - **Edit** - Opens edit server modal - **Remove** - Deletes server (with confirmation) -### Server Settings Modal - -Per-server configuration for connection behavior, headers, metadata, timeouts, and OAuth credentials. - -``` -+---------------------------------------------------------------------------+ -| Server Settings: my-server [x] | -+---------------------------------------------------------------------------+ -| | -| Connection Mode | -| +-----------------------------------------------------------------------+ | -| | Via Proxy v | | -| +-----------------------------------------------------------------------+ | -| Direct - Connect directly to server (requires CORS support) | -| Via Proxy - Route through inspector proxy (required for STDIO) | -| | -| --------------------------------------------------------------------------- -| | -| Custom Headers | -| +-----------------------------------------------------------------------+ | -| | Authorization | Bearer sk-... [Remove]| | -| | X-Custom-Header | custom-value [Remove]| | -| +-----------------------------------------------------------------------+ | -| [+ Add Header] | -| | -| --------------------------------------------------------------------------- -| | -| Request Metadata | -| Metadata sent with every MCP request to this server. | -| +-----------------------------------------------------------------------+ | -| | session_id | abc123 [Remove]| | -| +-----------------------------------------------------------------------+ | -| [+ Add Metadata] | -| | -| --------------------------------------------------------------------------- -| | -| Timeouts | -| +-----------------------------------+-----------------------------------+ | -| | Connection Timeout | Request Timeout | | -| | +-----------------------------+ | +-----------------------------+ | | -| | | 30000 ms| | | 60000 ms| | | -| | +-----------------------------+ | +-----------------------------+ | | -| +-----------------------------------+-----------------------------------+ | -| | -| --------------------------------------------------------------------------- -| | -| OAuth Settings (for servers requiring authentication) | -| +-----------------------------------------------------------------------+ | -| | Client ID | | -| | +-------------------------------------------------------------------+ | | -| | | my-client-id | | | -| | +-------------------------------------------------------------------+ | | -| | | | -| | Client Secret | | -| | +-------------------------------------------------------------------+ | | -| | | ******** [Show/Hide] | | | -| | +-------------------------------------------------------------------+ | | -| | | | -| | Scopes | | -| | +-------------------------------------------------------------------+ | | -| | | read write profile | | | -| | +-------------------------------------------------------------------+ | | -| +-----------------------------------------------------------------------+ | -| | -| [Cancel] [Save Settings] | -+---------------------------------------------------------------------------+ -``` - -**Connection Mode:** -- **Direct** - Browser connects directly to server (requires server to have CORS headers) -- **Via Proxy** - Route through inspector proxy (required for STDIO transport, useful for CORS-restricted servers) - -**Custom Headers:** -- Key-value pairs sent with every HTTP request to this server -- Useful for API keys, authorization tokens, custom routing - -**Request Metadata:** -- Data included in `_meta` field of every MCP request -- Per-server isolation (previously stored globally in localStorage) - -**Timeouts:** -- **Connection Timeout** - Max time to establish connection (ms) -- **Request Timeout** - Max time for individual requests (ms) - -**OAuth Settings:** -- Pre-configure OAuth credentials for servers requiring authentication -- Client ID and Client Secret for OAuth 2.0 flows -- Scopes to request during authorization - -**Clone Functionality:** -The [Clone] button on the server card creates a duplicate configuration, enabling: -- Testing same server with different headers/metadata -- Comparing behavior with different timeout settings -- Maintaining separate OAuth credentials for different environments - ### Import server.json Modal Support for importing MCP Registry `server.json` format for testing servers before publishing. ``` -+-----------------------------------------------------------------------------+ -| Import MCP Registry server.json [x] | -+-----------------------------------------------------------------------------+ -| | -| 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: | -| +-------------------------------------------------------------------------+ | -| | [check] Schema validation passed | | -| | [check] Package found: my-mcp-server (npm) | | -| | [warn] Environment variable API_KEY not set | | -| | [info] Runtime hint: npx | | -| | [info] 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] | -+-----------------------------------------------------------------------------+ -``` - -**Browse Button:** -- Opens native file picker to select a local `server.json` file -- Supports `.json` file filter -- Note: Registry browser may be added as future enhancement or plugin +┌─────────────────────────────────────────────────────────────────────────────┐ +│ 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 @@ -366,36 +249,36 @@ Support for importing MCP Registry `server.json` format for testing servers befo Shown as a modal or dedicated screen after successful connection. ``` -+---------------------------------------------------------+ -| Server Information [x] | -+---------------------------------------------------------+ -| | -| Name: everything-server | -| Version: 1.0.0 | -| Protocol: 2025-11-25 | -| Transport: stdio | -| | -| Server Capabilities Client Capabilities | -| --------------------- --------------------- | -| [check] Tools (4) [check] Sampling | -| [check] Resources (12) [check] Elicitation | -| [check] Prompts (2) [check] Roots (3) | -| [check] Logging [check] Tasks | -| [check] Completions | -| [check] Tasks | -| [x] 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 v] | -| | -+---------------------------------------------------------+ +┌─────────────────────────────────────────────────────────┐ +│ 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:** @@ -406,109 +289,808 @@ Shown as a modal or dedicated screen after successful connection. - Display server instructions if provided - Show OAuth tokens with copy and JWT decode options -### OAuth Debugger - -Accessed via [OAuth Debug] button on the server card (visible when server uses OAuth). - -``` -+---------------------------------------------------------------------------+ -| OAuth Debugger: my-server [x] | -+---------------------------------------------------------------------------+ -| | -| OAuth Flow Status | -| +-----------------------------------------------------------------------+ | -| | Step 1: Authorization Request [Completed] | | -| | +-------------------------------------------------------------------+ | | -| | | GET https://auth.example.com/authorize | | | -| | | ?client_id=my-client-id | | | -| | | &redirect_uri=http://localhost:5173/callback | | | -| | | &response_type=code | | | -| | | &scope=read%20write | | | -| | | &state=abc123 | | | -| | +-------------------------------------------------------------------+ | | -| | [Copy URL] | | -| +-----------------------------------------------------------------------+ | -| | -| +-----------------------------------------------------------------------+ | -| | Step 2: Authorization Code [Completed] | | -| | +-------------------------------------------------------------------+ | | -| | | code: xyz789... | | | -| | | state: abc123 (verified) | | | -| | +-------------------------------------------------------------------+ | | -| +-----------------------------------------------------------------------+ | -| | -| +-----------------------------------------------------------------------+ | -| | Step 3: Token Exchange [Completed] | | -| | +-------------------------------------------------------------------+ | | -| | | POST https://auth.example.com/token | | | -| | | grant_type=authorization_code&code=xyz789... | | | -| | +-------------------------------------------------------------------+ | | -| +-----------------------------------------------------------------------+ | -| | -| +-----------------------------------------------------------------------+ | -| | Step 4: Access Token [Active] | | -| | +-------------------------------------------------------------------+ | | -| | | access_token: eyJhbG... [Copy] [Decode] | | | -| | | token_type: Bearer | | | -| | | expires_in: 3600 (expires at 15:32:00) | | | -| | | scope: read write | | | -| | +-------------------------------------------------------------------+ | | -| +-----------------------------------------------------------------------+ | -| | -| +-----------------------------------------------------------------------+ | -| | Refresh Token | | -| | +-------------------------------------------------------------------+ | | -| | | refresh_token: def456... [Copy] | | | -| | +-------------------------------------------------------------------+ | | -| | [Test Refresh Now] | | -| +-----------------------------------------------------------------------+ | -| | -| --------------------------------------------------------------------------- -| | -| Decoded Access Token (JWT) | -| +-----------------------------------------------------------------------+ | -| | Header: | | -| | { "alg": "RS256", "typ": "JWT" } | | -| | | | -| | Payload: | | -| | { | | -| | "sub": "user123", | | -| | "aud": "my-client-id", | | -| | "scope": "read write", | | -| | "exp": 1732990800, | | -| | "iat": 1732987200 | | -| | } | | -| +-----------------------------------------------------------------------+ | -| | -| [Revoke Token] [Start New Flow] | -+---------------------------------------------------------------------------+ +### 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] │ │ +└─────────────────┴──────────────────────────────────────┴────────────────────────┘ +``` + +**With Pending Client Requests (inline expansion):** + +When a tool execution triggers sampling or elicitation requests, they appear inline: + +``` +┌─────────────────┬────────────────────────────────────────────────────────────────┐ +│ Tools (4) │ Tool: query_database [Executing...] │ +│ ├────────────────────────────────────────────────────────────────┤ +│ [Search...] │ Parameters: { "table": "users", "limit": 10 } │ +│ ├────────────────────────────────────────────────────────────────┤ +│ ● query_db │ [!] Pending Client Requests (2) │ +│ ○ echo │ │ +│ ○ add │ ┌──────────────────────────────────────────────────────────┐ │ +│ ○ longOp │ │ sampling/createMessage [1 of 2] │ │ +│ │ │ Model hints: claude-3-sonnet │ │ +│ │ │ Messages: "Analyze this database schema..." │ │ +│ │ │ │ │ +│ │ │ Response: [Testing Profile: Quick Mock] │ │ +│ │ │ ┌───────────────────────────────────────────────────────┐ │ │ +│ │ │ │ This is a mock LLM response for testing purposes. │ │ │ +│ │ │ └───────────────────────────────────────────────────────┘ │ │ +│ │ │ │ │ +│ │ │ [Auto-respond] [Edit & Send] [Reject] │ │ +│ │ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ ┌──────────────────────────────────────────────────────────┐ │ +│ │ │ elicitation/create (form) [2 of 2] │ │ +│ │ │ Message: "Please confirm the query parameters" │ │ +│ │ │ │ │ +│ │ │ table: [users ] limit: [10] [x] include_deleted │ │ +│ │ │ │ │ +│ │ │ [Cancel] [Submit] │ │ +│ │ └──────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ [Cancel Tool] │ +└─────────────────┴────────────────────────────────────────────────────────────────┘ ``` **Features:** -- **Flow Visualization** - Step-by-step view of OAuth 2.0 flow - - Authorization request URL with all parameters - - Authorization code received - - Token exchange request/response - - Access token details -- **Token Display:** - - Access token with copy and decode options - - Token type and expiration time - - Refresh token (if available) - - Decoded JWT payload and header -- **Actions:** - - [Test Refresh Now] - Manually trigger token refresh - - [Revoke Token] - Revoke current access token - - [Start New Flow] - Begin fresh OAuth flow - - [Copy] - Copy tokens/URLs to clipboard - - [Decode] - Show JWT contents +- **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` +- **Inline Client Request Queue** - When tool triggers sampling/elicitation: + - Pending requests shown inline (not as separate modal) + - Queue counter shows total pending requests + - Each request shows type, summary, and response options + - **Auto-respond** button uses active Testing Profile + - **Edit & Send** allows modifying response before sending + - Requests processed in order, tool execution resumes after all resolved + - Visible connection between tool call and its triggered requests +- **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 -**Use Cases:** -1. Debugging OAuth configuration issues -2. Verifying token claims and scopes -3. Testing token refresh behavior -4. Understanding the full OAuth handshake +``` +┌─────────────────────────┬─────────────────────────────────────────────────┐ +│ 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 │ │ +│ │ │ +│ Request Filter: │ │ +│ ┌────────────────┐ │ │ +│ │ All requests ▼ │ │ │ +│ └────────────────┘ │ │ +│ │ │ +│ [Clear] [Export] │ [Auto-scroll ✓] [Copy All] │ +└──────────────────────┴──────────────────────────────────────────────────┘ +``` + +**With Request Correlation:** + +Logs can be filtered by the request that triggered them: + +``` +┌──────────────────────┬──────────────────────────────────────────────────┐ +│ Log Controls (25%) │ Log Stream (filtered by request) │ +├──────────────────────┼──────────────────────────────────────────────────┤ +│ │ │ +│ Request Filter: │ Showing logs for: tools/call (query_database) │ +│ ┌────────────────┐ │ [View in History] │ +│ │ query_database │ │ ───────────────────────────────────────────── │ +│ │ 14:32:10 ▼ │ │ 14:32:10 [DEBUG] Starting query execution │ +│ └────────────────┘ │ 14:32:11 [INFO] Requesting LLM analysis │ +│ │ 14:32:12 [DEBUG] Sampling response received │ +│ Recent Requests: │ 14:32:13 [WARN] Query taking longer than usual │ +│ ○ query_database │ 14:32:15 [INFO] Query completed, 42 rows │ +│ ○ analyze_data │ │ +│ ○ prompts/get │ │ +│ │ │ +│ [Show All Logs] │ [Auto-scroll ✓] [Copy Filtered] │ +└──────────────────────┴──────────────────────────────────────────────────┘ +``` + +**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 +- **Request Correlation**: + - Filter logs by request (shows logs emitted during a specific tool/resource/prompt call) + - Recent requests dropdown shows last N requests + - [View in History] link navigates to the request in History screen + - Logs include correlation ID linking them to their parent request + - Click any log entry to see which request chain it belongs to + +#### 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 **hierarchical request trace** capability. Shows parent-child relationships when tool calls trigger sampling or elicitation requests. + +``` +┌─────────────────────────────────────────────────────────────────────────────────────┐ +│ History [Search...] [Filter ▼] [Clear All] │ +├─────────────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ [>] 14:35:22 tools/call query_database [success] 450ms [Replay] [Pin] │ +│ +-- 14:35:23 sampling/createMessage claude-3-sonnet [+45ms] │ +│ | Model: claude-3-sonnet-20241022 │ +│ | Response: "Based on the schema, I recommend..." [Expand] │ +│ +-- 14:35:24 sampling/createMessage gpt-4 [+120ms] │ +│ | Model: gpt-4-turbo │ +│ | Response: "The query should use an index..." [Expand] │ +│ +-- 14:35:25 elicitation/create (form: confirm_action) [+200ms] │ +│ User provided: { confirmed: true } │ +│ │ +│ [>] 14:34:15 resources/read file:///config.json [success] 120ms [Replay] [Pin] │ +│ (no client requests) │ +│ │ +│ [>] 14:33:45 prompts/get greeting_prompt [success] 30ms [Replay] [Pin] │ +│ Arguments: { "name": "John", "interests": "cats" } │ +│ │ +│ [>] 14:32:10 tools/call analyze_data [success] 800ms [Replay] [Pin] │ +│ +-- 14:32:11 sampling/createMessage claude-3-opus [+350ms] │ +│ | Messages: "Analyze this dataset and identify..." │ +│ | Response: "I've identified 3 key patterns..." [Expand] │ +│ +-- 14:32:12 elicitation/create (url: oauth) [+400ms] │ +│ Status: User completed OAuth flow │ +│ │ +│ Pinned Requests (2) │ +│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ +│ │ * "Test query" tools/call query_database 14:35:22 [Replay] [Unpin] │ │ +│ │ * "Get config" resources/read config.json 14:34:15 [Replay] [Unpin] │ │ +│ └─────────────────────────────────────────────────────────────────────────────────┘ │ +│ │ +│ Showing 50 of 127 entries │ +│ [Load More] │ +└─────────────────────────────────────────────────────────────────────────────────────┘ +``` + +**Features:** + +- **Request Trace** - Hierarchical view showing causal relationships: + - Top-level requests (tools/call, resources/read, prompts/get) shown as parent nodes + - Client requests (sampling, elicitation) shown as nested children with timing offset + - Expandable/collapsible tree structure + - Visual connector lines showing the chain + - **Correlation ID** links related requests together + +- **Automatic Capture** - All MCP requests/responses logged automatically: + - `tools/call` - Tool invocations (parent) + - `resources/read` - Resource reads (parent) + - `prompts/get` - Prompt retrievals (parent) + - `sampling/createMessage` - Sampling requests (child, nested under triggering request) + - `elicitation/create` - Elicitation requests (child, nested under triggering request) + +- **Request Details** displayed: + - Timestamp (absolute for parents, relative offset for children) + - Method name + - Target (tool name, resource URI, prompt name, model hint) + - Parameters/arguments + - Result status (success/error) + - Total response time (for parents), offset time (for children) + - 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 + - Replaying a parent re-executes the full chain + +- **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 + - Show/hide child requests (flatten view) + +- **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 (with any triggered client requests nested) + +### Client Feature Handlers + +Client feature handlers manage server-initiated requests (sampling, elicitation). They appear in two contexts: + +1. **Inline** - When triggered during tool execution, shown within the Tools screen (see [Inline Client Request Queue](#tools-screen)) +2. **Modal** - For standalone testing or detailed view + +For detailed documentation including Testing Profiles and Sampling Providers, see [v2_ux_handlers.md](v2_ux_handlers.md). + +#### Sampling Panel + +When server sends `sampling/createMessage` request (modal view shown, inline view in Tools Screen above): + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ 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 +- **Testing Profile** selector for quick response strategy switching +- **[Auto-respond]** button generates response from active Testing Profile +- **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 +- Extensible via Sampling Providers (see [v2_ux_handlers.md](v2_ux_handlers.md#sampling-providers--testing-profiles)) + +#### Elicitation Handler + +When server sends `elicitation/create` request (modal views shown, inline views in Tools Screen above): + +**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 @@ -520,75 +1102,75 @@ This UX specification covers **100% of the MCP 2025-11-25 protocol specification |--------|-------------| | `initialize` | Connection flow (implicit) | | `ping` | Navigation bar latency display | -| `tools/list` | [Tools Screen](v2_ux_features.md#tools-screen) | -| `tools/call` | [Tools Screen](v2_ux_features.md#tools-screen) | -| `resources/list` | [Resources Screen](v2_ux_features.md#resources-screen) | -| `resources/templates/list` | [Resources Screen](v2_ux_features.md#resources-screen) (templates section) | -| `resources/read` | [Resources Screen](v2_ux_features.md#resources-screen) | -| `resources/subscribe` | [Resources Screen](v2_ux_features.md#resources-screen) | -| `resources/unsubscribe` | [Resources Screen](v2_ux_features.md#resources-screen) | -| `prompts/list` | [Prompts Screen](v2_ux_features.md#prompts-screen) | -| `prompts/get` | [Prompts Screen](v2_ux_features.md#prompts-screen) | -| `sampling/createMessage` | [Sampling Panel](v2_ux_handlers.md#sampling-panel) | -| `elicitation/create` | [Elicitation Handler](v2_ux_handlers.md#elicitation-handler) | -| `completion/complete` | [Tools](v2_ux_features.md#tools-screen)/[Prompts](v2_ux_features.md#prompts-screen) autocomplete | -| `logging/setLevel` | [Logging Screen](v2_ux_features.md#logging-screen) | -| `roots/list` | [Roots Configuration](v2_ux_handlers.md#roots-configuration) | -| `tasks/list` | [Tasks Screen](v2_ux_features.md#tasks-screen) | -| `tasks/get` | [Tasks Screen](v2_ux_features.md#tasks-screen) | -| `tasks/result` | [Tasks Screen](v2_ux_features.md#tasks-screen) | -| `tasks/cancel` | [Tasks Screen](v2_ux_features.md#tasks-screen) | +| `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](v2_ux_features.md#tools-screen) progress bar, [Tasks Screen](v2_ux_features.md#tasks-screen) | -| `notifications/cancelled` | [Tools Screen](v2_ux_features.md#tools-screen) cancel button | -| `notifications/message` | [Logging Screen](v2_ux_features.md#logging-screen) | -| `notifications/tools/list_changed` | [Tools Screen](v2_ux_features.md#tools-screen) indicator | -| `notifications/resources/list_changed` | [Resources Screen](v2_ux_features.md#resources-screen) indicator | -| `notifications/prompts/list_changed` | [Prompts Screen](v2_ux_features.md#prompts-screen) indicator | -| `notifications/resources/updated` | [Resources Screen](v2_ux_features.md#resources-screen) subscriptions | -| `notifications/roots/listChanged` | [Roots Configuration](v2_ux_handlers.md#roots-configuration) | -| `notifications/task/statusChanged` | [Tasks Screen](v2_ux_features.md#tasks-screen) | -| `notifications/elicitation/complete` | [Elicitation Handler](v2_ux_handlers.md#elicitation-handler) (URL mode) | +| `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](v2_ux_features.md#tools-screen), Server Info | -| `resources` | Server | [Resources Screen](v2_ux_features.md#resources-screen), Server Info | -| `prompts` | Server | [Prompts Screen](v2_ux_features.md#prompts-screen), Server Info | -| `logging` | Server | [Logging Screen](v2_ux_features.md#logging-screen), Server Info | +| `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](v2_ux_features.md#tasks-screen), Server Info | -| `experimental` | Server | [Experimental Features Panel](v2_ux_handlers.md#experimental-features-panel), Server Info | -| `sampling` | Client | [Sampling Panel](v2_ux_handlers.md#sampling-panel), Server Info | -| `elicitation` | Client | [Elicitation Handler](v2_ux_handlers.md#elicitation-handler), Server Info | -| `roots` | Client | [Roots Configuration](v2_ux_handlers.md#roots-configuration), Server Info | -| `tasks` | Client | [Tasks Screen](v2_ux_features.md#tasks-screen), Server Info | -| `experimental` | Client | [Experimental Features Panel](v2_ux_handlers.md#experimental-features-panel), 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](v2_ux_features.md#tools-screen) results, [Prompts](v2_ux_features.md#prompts-screen) messages, [Resources](v2_ux_features.md#resources-screen) | -| Audio (base64) | [Tools](v2_ux_features.md#tools-screen) results, [Prompts](v2_ux_features.md#prompts-screen) messages, [Resources](v2_ux_features.md#resources-screen) | -| Resource links | [Tools](v2_ux_features.md#tools-screen) results, embedded display | -| Embedded resources | [Prompts](v2_ux_features.md#prompts-screen) messages | +| 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](v2_ux_features.md#tools-screen) badges | -| Tool hints | [Tools Screen](v2_ux_features.md#tools-screen) description | -| Tool readOnly | [Tools Screen](v2_ux_features.md#tools-screen) indicator | -| Tool destructive | [Tools Screen](v2_ux_features.md#tools-screen) warning | -| Resource audience | [Resources Screen](v2_ux_features.md#resources-screen) badges | -| Resource priority | [Resources Screen](v2_ux_features.md#resources-screen) indicator | +| 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 | diff --git a/specification/v2_ux_features.md b/specification/v2_ux_features.md index fc2c8105..d8cfde76 100644 --- a/specification/v2_ux_features.md +++ b/specification/v2_ux_features.md @@ -49,6 +49,44 @@ Each feature screen uses a **resizable panel layout** for flexibility. +---------------------+--------------------------------------+------------------------+ ``` +**With Pending Client Requests (inline expansion):** + +When a tool execution triggers sampling or elicitation requests, they appear inline: + +``` ++---------------------+--------------------------------------------------------------+ +| Tools (4) | Tool: query_database [Executing...] | +| +--------------------------------------------------------------+ +| [Search...] | Parameters: { "table": "users", "limit": 10 } | +| +--------------------------------------------------------------+ +| (*) query_db | [!] Pending Client Requests (2) | +| ( ) echo | | +| ( ) add | +----------------------------------------------------------+ | +| ( ) longOp | | sampling/createMessage [1 of 2] | | +| | | Model hints: claude-3-sonnet | | +| | | Messages: "Analyze this database schema..." | | +| | | | | +| | | Response: [Testing Profile: Quick Mock] | | +| | | +------------------------------------------------------+ | | +| | | | This is a mock LLM response for testing purposes. | | | +| | | +------------------------------------------------------+ | | +| | | | | +| | | [Auto-respond] [Edit & Send] [Reject] | | +| | +----------------------------------------------------------+ | +| | | +| | +----------------------------------------------------------+ | +| | | elicitation/create (form) [2 of 2] | | +| | | Message: "Please confirm the query parameters" | | +| | | | | +| | | table: [users ] limit: [10] [x] include_deleted | | +| | | | | +| | | [Cancel] [Submit] | | +| | +----------------------------------------------------------+ | +| | | +| | [Cancel Tool] | ++---------------------+--------------------------------------------------------------+ +``` + **Features:** - **List Changed Indicator** - Shows when `notifications/tools/list_changed` received, with refresh button - Searchable/filterable tool list @@ -72,6 +110,14 @@ Each feature screen uses a **resizable panel layout** for flexibility. - Elapsed time display - Execute button with loading state - **Cancel button** sends `notifications/cancelled` +- **Inline Client Request Queue** - When tool triggers sampling/elicitation: + - Pending requests shown inline (not as separate modal) + - Queue counter shows total pending requests + - Each request shows type, summary, and response options + - **Auto-respond** button uses active Testing Profile + - **Edit & Send** allows modifying response before sending + - Requests processed in order, tool execution resumes after all resolved + - Visible connection between tool call and its triggered requests - **Rich Result Display**: - JSON/text with syntax highlighting - Image preview for image content (base64) @@ -233,10 +279,39 @@ Uses an **accordion layout** for the left panel to organize Resources, Templates | [x] ALERT | | | [x] EMERGENCY | | | | | +| Request Filter: | | +| +-----------------+ | | +| | All requests v | | | +| +-----------------+ | | +| | | | [Clear] [Export] | [Auto-scroll] [Copy All] | +-----------------------+-----------------------------------------------------+ ``` +**With Request Correlation:** + +Logs can be filtered by the request that triggered them: + +``` ++-----------------------+-----------------------------------------------------+ +| Log Controls (25%) | Log Stream (filtered by request) | ++-----------------------+-----------------------------------------------------+ +| | | +| Request Filter: | Showing logs for: tools/call (query_database) | +| +-----------------+ | [View in History] | +| | query_database | | ------------------------------------------------- | +| | 14:32:10 v | | 14:32:10 [DEBUG] Starting query execution | +| +-----------------+ | 14:32:11 [INFO] Requesting LLM analysis | +| | 14:32:12 [DEBUG] Sampling response received | +| Recent Requests: | 14:32:13 [WARNING] Query taking longer than usual | +| ( ) query_database | 14:32:15 [INFO] Query completed, 42 rows | +| ( ) analyze_data | | +| ( ) prompts/get | | +| | | +| [Show All Logs] | [Auto-scroll] [Copy Filtered] | ++-----------------------+-----------------------------------------------------+ +``` + **Features:** - **Set Log Level** via `logging/setLevel` request - Options: debug, info, notice, warning, error, critical, alert, emergency @@ -261,6 +336,12 @@ Uses an **accordion layout** for the left panel to organize Resources, Templates - Auto-scroll toggle - Export logs to file - Copy all logs to clipboard +- **Request Correlation**: + - Filter logs by request (shows logs emitted during a specific tool/resource/prompt call) + - Recent requests dropdown shows last N requests + - [View in History] link navigates to the request in History screen + - Logs include correlation ID linking them to their parent request + - Click any log entry to see which request chain it belongs to ## Tasks Screen @@ -314,46 +395,40 @@ Uses an **accordion layout** for the left panel to organize Resources, Templates ## History Screen -A unified history of all MCP requests with replay capability. +A unified history of all MCP requests with **hierarchical request trace** capability. Shows parent-child relationships when tool calls trigger sampling or elicitation requests. ``` +-------------------------------------------------------------------------------------+ | History [Search...] [Filter v] [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:35:22 tools/call query_database [success] 450ms [Replay] [Pin] | +| +-- 14:35:23 sampling/createMessage claude-3-sonnet [+45ms] | +| | Model: claude-3-sonnet-20241022 | +| | Response: "Based on the schema, I recommend..." [Expand] | +| +-- 14:35:24 sampling/createMessage gpt-4 [+120ms] | +| | Model: gpt-4-turbo | +| | Response: "The query should use an index..." [Expand] | +| +-- 14:35:25 elicitation/create (form: confirm_action) [+200ms] | +| User provided: { confirmed: true } | | | -| +---------------------------------------------------------------------------------+ | -| | 14:34:15 resources/read file:///config.json [Replay] [Pin] | | -| | Result: Success (120ms) | | -| | ------------------------------------------------------------------ | | -| | Content: { "name": "my-app", "version": "1.0.0" } (collapsed) [Expand] | | -| +---------------------------------------------------------------------------------+ | +| [>] 14:34:15 resources/read file:///config.json [success] 120ms [Replay] [Pin] | +| (no client requests) | | | -| +---------------------------------------------------------------------------------+ | -| | 14:33:45 prompts/get greeting_prompt [Replay] [Pin] | | -| | Arguments: { "name": "John", "interests": "cats" } | | -| | Result: Success (30ms) | | -| +---------------------------------------------------------------------------------+ | +| [>] 14:33:45 prompts/get greeting_prompt [success] 30ms [Replay] [Pin] | +| Arguments: { "name": "John", "interests": "cats" } | | | -| +---------------------------------------------------------------------------------+ | -| | 14:32:10 tools/call query_database [Replay] [Pin] | | -| | Parameters: { "table": "users", "limit": 10 } | | -| | Result: [X] Error (200ms) | | -| | ------------------------------------------------------------------ | | -| | Error: "Table 'users' not found" | | -| +---------------------------------------------------------------------------------+ | +| [>] 14:32:10 tools/call analyze_data [success] 800ms [Replay] [Pin] | +| +-- 14:32:11 sampling/createMessage claude-3-opus [+350ms] | +| | Messages: "Analyze this dataset and identify..." | +| | Response: "I've identified 3 key patterns..." [Expand] | +| +-- 14:32:12 elicitation/create (url: oauth) [+400ms] | +| Status: User completed OAuth flow | | | | 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] | +| | * "Test query" tools/call query_database 14:35:22 [Replay] [Unpin] | | +| | * "Get config" resources/read config.json 14:34:15 [Replay] [Unpin] | | | +---------------------------------------------------------------------------------+ | | | | Showing 50 of 127 entries | @@ -362,31 +437,46 @@ A unified history of all MCP requests with replay capability. ``` **Features:** + +- **Request Trace** - Hierarchical view showing causal relationships: + - Top-level requests (tools/call, resources/read, prompts/get) shown as parent nodes + - Client requests (sampling, elicitation) shown as nested children with timing offset + - Expandable/collapsible tree structure + - Visual connector lines showing the chain + - **Correlation ID** links related requests together + - **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 + - `tools/call` - Tool invocations (parent) + - `resources/read` - Resource reads (parent) + - `prompts/get` - Prompt retrievals (parent) + - `sampling/createMessage` - Sampling requests (child, nested under triggering request) + - `elicitation/create` - Elicitation requests (child, nested under triggering request) + - **Request Details** displayed: - - Timestamp + - Timestamp (absolute for parents, relative offset for children) - Method name - - Target (tool name, resource URI, prompt name) + - Target (tool name, resource URI, prompt name, model hint) - Parameters/arguments - Result status (success/error) - - Response time + - Total response time (for parents), offset time (for children) - 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 + - Replaying a parent re-executes the full chain + - **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 + - Show/hide child requests (flatten view) + - **Search** across method names, parameters, and responses - **Pagination** - Load more for large histories - **Clear** - Clear history (with confirmation) @@ -397,4 +487,4 @@ A unified history of all MCP requests with replay capability. 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 +5. New request is added to history (with any triggered client requests nested) diff --git a/specification/v2_ux_handlers.md b/specification/v2_ux_handlers.md index 0092a58e..80f21a44 100644 --- a/specification/v2_ux_handlers.md +++ b/specification/v2_ux_handlers.md @@ -11,6 +11,7 @@ * [Elicitation Handler](#elicitation-handler) * [Roots Configuration](#roots-configuration) * [Experimental Features Panel](#experimental-features-panel) + * [Sampling Providers & Testing Profiles](#sampling-providers--testing-profiles) * [Form Generation](#form-generation) * [Error Handling UX](#error-handling-ux) @@ -20,7 +21,53 @@ These are modals/panels that appear when the server invokes client capabilities. ### Sampling Panel -When server sends `sampling/createMessage` request: +Sampling requests appear in two contexts: + +1. **Inline** - When triggered during tool execution (shown in Tools screen) +2. **Modal** - For standalone testing or when triggered outside tool context + +#### Inline Expansion (Primary) + +When a tool call triggers a sampling request, it appears inline within the tool execution flow: + +``` ++-------------------------------------------------------------------------+ +| Tool: query_database [Executing...] | ++-------------------------------------------------------------------------+ +| Parameters: { "table": "users", "limit": 10 } | ++-------------------------------------------------------------------------+ +| [!] Sampling Request [Profile: Quick Mock v] | +| | +| +---------------------------------------------------------------------+ | +| | Model hints: claude-3-sonnet, gpt-4 | | +| | Messages: "Analyze this database schema and recommend an index..." | | +| | [View Details] | | +| +---------------------------------------------------------------------+ | +| | +| Response: | +| +---------------------------------------------------------------------+ | +| | Based on the query patterns, I recommend creating a composite | | +| | index on (user_id, created_at) for optimal performance... | | +| +---------------------------------------------------------------------+ | +| | +| Model Used: [mock-model-1.0] Stop Reason: [end_turn v] | +| | +| [Auto-respond] [Edit & Send] [Reject] | ++-------------------------------------------------------------------------+ +``` + +**Inline Features:** +- Compact view showing essential info (model hints, message preview) +- [View Details] expands to show full request (like modal view) +- **Testing Profile** dropdown to quickly switch response behavior +- **[Auto-respond]** uses active Testing Profile to generate response +- **[Edit & Send]** allows modifying response before sending +- **[Reject]** declines the sampling request +- Response field pre-filled based on active Testing Profile + +#### Modal View (Standalone Testing) + +For testing sampling outside of tool execution, or when [View Details] is clicked: ``` +-------------------------------------------------------------------------+ @@ -55,7 +102,9 @@ When server sends `sampling/createMessage` request: | | | ----------------------------------------------------------------------- | | | -| Response (enter mock response or connect to LLM): | +| Testing Profile: [Quick Mock v] [Edit Profiles] | +| | +| Response: | | +---------------------------------------------------------------------+ | | | Based on the data chart, I can see several key trends: | | | | | | @@ -64,29 +113,210 @@ When server sends `sampling/createMessage` request: | | | | | +---------------------------------------------------------------------+ | | | -| Model Used: ________________ Stop Reason: [end_turn v] | +| Model Used: [mock-model-1.0] Stop Reason: [end_turn v] | | | -| [Reject Request] [Send Response] | +| [Auto-respond] [Reject Request] [Send Response] | +-------------------------------------------------------------------------+ ``` -**Features:** +**Modal Features:** - Display full sampling request details: - Messages with text, image, and audio content - - Model hints and preferences + - Model hints and preferences (cost, speed, intelligence priorities) - Max tokens, stop sequences, temperature - Context inclusion settings + - **Tools** and **toolChoice** (if provided) for tool-enabled sampling +- **Testing Profile** selector with [Edit Profiles] link +- **[Auto-respond]** generates response from active profile - **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) +- Integration with Testing Profiles (see below) + +#### Sampling with Tool Calling (2025-11-25) + +Sampling requests can include `tools` and `toolChoice` parameters, enabling multi-turn agentic loops where the LLM can request tool execution. + +**Request with Tools:** + +``` ++-------------------------------------------------------------------------+ +| Sampling Request (with tools) [x] | ++-------------------------------------------------------------------------+ +| | +| Messages: | +| +---------------------------------------------------------------------+ | +| | [0] role: user | | +| | "What's the weather in Paris and London?" | | +| +---------------------------------------------------------------------+ | +| | +| Available Tools (2): | +| +---------------------------------------------------------------------+ | +| | get_weather | | +| | Get current weather for a city | | +| | Parameters: { city: string } | | +| +---------------------------------------------------------------------+ | +| | get_forecast | | +| | Get 5-day forecast for a city | | +| | Parameters: { city: string, days: number } | | +| +---------------------------------------------------------------------+ | +| | +| Tool Choice: [auto v] (auto | none | required | specific tool) | +| | ++-------------------------------------------------------------------------+ +``` + +**Response with Tool Use:** + +When the LLM wants to call tools, the response includes `stopReason: "toolUse"`: + +``` ++-------------------------------------------------------------------------+ +| Sampling Response | ++-------------------------------------------------------------------------+ +| | +| Response Content: | +| +---------------------------------------------------------------------+ | +| | I'll check the weather for both cities. | | +| +---------------------------------------------------------------------+ | +| | +| Tool Calls Requested: | +| +---------------------------------------------------------------------+ | +| | [1] get_weather({ "city": "Paris" }) | | +| | [2] get_weather({ "city": "London" }) | | +| +---------------------------------------------------------------------+ | +| | +| Model Used: [claude-3-sonnet] Stop Reason: [toolUse] | +| | +| [!] Server must execute tools and send follow-up sampling request | +| | +| [Reject Request] [Send Response] | ++-------------------------------------------------------------------------+ +``` + +**Multi-Turn Tool Loop Flow:** + +``` +Server Client (Inspector) + | | + | sampling/createMessage (with tools) | + |--------------------------------------->| + | | [User reviews request] + | | [User approves/provides response] + | Response (stopReason: toolUse) | + |<---------------------------------------| + | | + | [Server executes requested tools] | + | | + | sampling/createMessage | + | (history + tool_results + tools) | + |--------------------------------------->| + | | [User reviews continuation] + | Response (stopReason: endTurn) | + |<---------------------------------------| + | | + | [Server processes final response] | +``` + +**Tool Results in Follow-up Request:** + +The server sends tool results back in a continuation request: + +``` ++-------------------------------------------------------------------------+ +| Sampling Request (continuation with tool results) [x] | ++-------------------------------------------------------------------------+ +| | +| Messages: | +| +---------------------------------------------------------------------+ | +| | [0] role: user | | +| | "What's the weather in Paris and London?" | | +| | | | +| | [1] role: assistant | | +| | "I'll check the weather for both cities." | | +| | Tool calls: get_weather(Paris), get_weather(London) | | +| | | | +| | [2] role: user (tool_result) | | +| | get_weather(Paris): { "temp": 18, "conditions": "Sunny" } | | +| | get_weather(London): { "temp": 14, "conditions": "Cloudy" } | | +| +---------------------------------------------------------------------+ | +| | +| Available Tools (2): [same as before] | +| | ++-------------------------------------------------------------------------+ +``` + +**History View:** + +The History screen shows the complete tool loop as a nested chain: + +``` +[>] 14:35:22 tools/call weather_report [success] 2.5s [Replay] + +-- 14:35:23 sampling/createMessage (with tools) [+100ms] + | Response: toolUse - get_weather(Paris), get_weather(London) + +-- 14:35:24 [tool execution: get_weather x2] [+500ms] + +-- 14:35:25 sampling/createMessage (continuation) [+1.2s] + | Response: "Paris is 18C and sunny, London is 14C and cloudy" +``` ### Elicitation Handler -When server sends `elicitation/create` request: +Elicitation requests appear in two contexts: + +1. **Inline** - When triggered during tool execution (shown in Tools screen) +2. **Modal** - For standalone testing or when triggered outside tool context + +#### Inline Expansion (Form Mode) + +When a tool call triggers a form elicitation, it appears inline: + +``` ++-------------------------------------------------------------------------+ +| Tool: process_data [Executing...] | ++-------------------------------------------------------------------------+ +| Parameters: { "dataset": "quarterly_sales" } | ++-------------------------------------------------------------------------+ +| [!] Elicitation Request (form) | +| | +| "Please confirm the data processing parameters." | +| | +| +---------------------------------------------------------------------+ | +| | include_deleted: [ ] No output_format: [CSV v] | | +| | date_range: [2024-01-01] to [2024-12-31] | | +| +---------------------------------------------------------------------+ | +| | +| WARNING: Server "data-processor" is requesting this data. | +| | +| [Cancel] [Submit] | ++-------------------------------------------------------------------------+ +``` + +#### Inline Expansion (URL Mode) + +When a tool call triggers a URL elicitation: -**Form Mode:** +``` ++-------------------------------------------------------------------------+ +| Tool: connect_oauth [Executing...] | ++-------------------------------------------------------------------------+ +| Parameters: { "provider": "github" } | ++-------------------------------------------------------------------------+ +| [!] Elicitation Request (external URL) | +| | +| "Please complete OAuth authorization." | +| | +| URL: https://github.com/login/oauth/authorize?... [Copy] [Open] | +| | +| Status: Waiting for completion... (spinning) | +| | +| [Cancel] | ++-------------------------------------------------------------------------+ +``` + +#### Modal View - Form Mode + +For standalone testing or expanded view: ``` +-------------------------------------------------------------------------+ @@ -124,7 +354,7 @@ When server sends `elicitation/create` request: +-------------------------------------------------------------------------+ ``` -**URL Mode:** +#### Modal View - URL Mode ``` +-------------------------------------------------------------------------+ @@ -158,12 +388,22 @@ When server sends `elicitation/create` request: ``` **Features:** + +- **Inline Display:** + - Compact form showing essential fields + - Integrated with tool execution flow + - Clear connection between tool call and elicitation + - Same submit/cancel behavior as modal + - **Form Mode:** - Generate form from JSON Schema in request + - **Schema restriction:** Flat objects with primitive properties only (string, number, boolean, enum) - no nested objects or arrays - Validate input before submission - Required field indicators - Security warning with server name - Submit returns response to server + - Response `action`: "accept" | "decline" | "cancel" + - **URL Mode:** - Display URL for user to visit - Copy URL button @@ -171,6 +411,7 @@ When server sends `elicitation/create` request: - Waiting indicator until `notifications/elicitation/complete` received - Elicitation ID display - Domain verification warning + - **Cancel** sends declined response ### Roots Configuration @@ -324,6 +565,124 @@ Accessed via Settings or dedicated nav item: - Testing experimental methods before SDK support - Comparing behavior across different servers +## Sampling Providers & Testing Profiles + +Testing Profiles allow quick switching between different sampling response strategies. + +### Architecture + +``` +Sampling Providers (built-in for V2): ++-- Manual - User types each response ++-- Mock/Template - Auto-respond with preconfigured templates + +Testing Profiles (saved configurations): ++-- Profile selects a provider ++-- Profile configures that provider's settings ++-- Quick switch between profiles for different testing scenarios +``` + +### Testing Profiles Settings + +``` ++-------------------------------------------------------------------------+ +| Sampling Settings | ++-------------------------------------------------------------------------+ +| | +| Active Profile: [Quick Mock v] [+ New Profile] | +| | +| Saved Profiles: | +| +---------------------------------------------------------------------+ | +| | (*) Quick Mock | Mock, auto-respond, simple template | | +| | ( ) Detailed Mock | Mock, model-specific templates | | +| | ( ) Manual Review | Manual, no auto-respond | | +| +---------------------------------------------------------------------+ | +| [Edit Selected] [Delete] | +| | ++-------------------------------------------------------------------------+ +| Profile: Quick Mock [Editing] | ++-------------------------------------------------------------------------+ +| | +| Profile Name: [Quick Mock ] | +| | +| Provider: [Mock/Template v] | +| | +| [x] Auto-respond to sampling requests | +| | +| Default Response Template: | +| +---------------------------------------------------------------------+ | +| | This is a mock LLM response for testing purposes. | | +| +---------------------------------------------------------------------+ | +| | +| Default Model: [mock-model-1.0 ] | +| Default Stop Reason: [end_turn v] | +| | +| Model-Specific Overrides: [+ Add] | +| +---------------------------------------------------------------------+ | +| | Pattern | Response Template | Actions | | +| +---------------------------------------------------------------------+ | +| | claude-* | "I'll analyze this as Claude would..." | [Edit] | | +| | gpt-* | "As an AI assistant, I can help..." | [Edit] | | +| +---------------------------------------------------------------------+ | +| | +| [Save Profile] [Cancel] | ++-------------------------------------------------------------------------+ +``` + +### Provider: Manual + +User manually enters each sampling response: + +- No auto-respond +- Response field starts empty +- User must type or paste response +- Best for careful testing of specific responses + +### Provider: Mock/Template + +Automatically generates responses based on templates: + +- **Auto-respond** enabled by default +- Default template used for all requests (unless overridden) +- **Model-specific overrides** match model hints with patterns: + - `claude-*` matches any Claude model hint + - `gpt-*` matches any GPT model hint + - First matching pattern wins +- Response pre-filled in UI (user can still edit before sending) + +### Profile Switching + +Profiles can be switched from: + +1. **Sampling Settings** panel (global) +2. **Inline sampling request** dropdown (per-request override) +3. **Modal sampling view** dropdown + +### Extension Points (Future) + +The provider interface is designed for future plugin extensions: + +```typescript +interface SamplingProvider { + name: string; + description: string; + configure(): ProviderConfig; // Returns config UI schema + respond(request: SamplingRequest, config: ProviderConfig): Promise; +} +``` + +**Built-in providers (V2):** +- Manual +- Mock/Template + +**Future plugin examples:** +- OpenAI Provider (forwards to OpenAI API) +- Anthropic Provider (forwards to Claude API) +- Ollama Provider (local LLM) +- Custom Provider (user-defined handler) + +When plugins are installed, they appear as additional provider options in the profile configuration. + ## Form Generation Forms are dynamically generated from JSON Schema for tool inputs, prompt arguments, and resource template variables.