@mcp-use/inspector 0.4.5 → 0.4.6-canary.1

package/README.md

@@ -21,12 +21,29 @@
         <img src="https://dcbadge.limes.pink/api/server/XkNkSkMz3V?style=flat" /></a>
 </p>
 
-🔍 **MCP Inspector** is a powerful web-based debugging and inspection tool for MCP (Model Context Protocol) servers. It provides a beautiful, intuitive interface for testing tools, exploring resources, managing prompts, and monitoring server connections - all from your browser. Think of it as Swagger UI for MCP servers, but better!
+🔍 **MCP Inspector by mcp-use** is an open-source, interactive developer tool for testing and debugging MCP servers with support for MCP-UI and OpenAI Apps SDK widgets. It provides a beautiful, intuitive interface for testing tools, exploring resources, managing prompts, and monitoring server connections - all from your browser.
+
+## 🚀 Try it:
+
+- **Online**: [inspector.mcp-use.com](https://inspector.mcp-use.com/inspector)
+- **Locally**: Run `npx @mcp-use/inspector`
+- **Repository**: [github.com/mcp-use/mcp-use](https://github.com/mcp-use/mcp-use/tree/main/libraries/typescript/packages/inspector)
+
+## 🎥 Demo
+
+[![mcp-use inspector demo video](https://github.com/user-attachments/assets/4ef1643b-6f28-473e-8e7b-40c0c454d69d)](https://www.youtube.com/watch?v=DvsNSABz1GM)
+
+
+### 📖 Documentation
+
+For detailed usage instructions and guides, visit [docs.mcp-use.com/inspector](https://docs.mcp-use.com/inspector)
+
+---
 
 ## 📦 Related Packages
 
-| Package                                                                                           | Description             | Version                                                                                                         |
-| ------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Package                                                                                        | Description             | Version                                                                                                         |
+| ---------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
 | [mcp-use](https://github.com/mcp-use/mcp-use/tree/main/packages/mcp-use)                       | Core MCP framework      | [![npm](https://img.shields.io/npm/v/mcp-use.svg)](https://www.npmjs.com/package/mcp-use)                       |
 | [@mcp-use/cli](https://github.com/mcp-use/mcp-use/tree/main/packages/cli)                      | Build tool for MCP apps | [![npm](https://img.shields.io/npm/v/@mcp-use/cli.svg)](https://www.npmjs.com/package/@mcp-use/cli)             |
 | [create-mcp-use-app](https://github.com/mcp-use/mcp-use/tree/main/packages/create-mcp-use-app) | Create MCP apps         | [![npm](https://img.shields.io/npm/v/create-mcp-use-app.svg)](https://www.npmjs.com/package/create-mcp-use-app) |
@@ -48,495 +65,325 @@
 | **📁 Resource Browser**    | View and copy resource URIs with syntax highlighting            |
 | **💬 Prompt Manager**      | Test and manage prompts with argument templates                 |
 | **🌐 Universal Support**   | Works with HTTP/SSE and WebSocket connections                   |
+| **🎨 Widget Support**      | Full support for MCP-UI and OpenAI Apps SDK widgets             |
+| **🔑 BYOK Chat**           | Bring Your Own Key chat interface for testing conversational flows |
+| **💾 Saved Tool Calls**    | Save and replay tool executions for repeated testing            |
+| **⌨️ Quick Actions**       | Cmd + K keyboard shortcuts for rapid navigation                 |
+| **🐳 Docker Ready**        | Self-host with a single Docker container for production use     |
 
 ---
 
 ## 🚀 Quick Start
 
-### Method 1: Automatic with mcp-use Server (Recommended)
-
-When you create an MCP server with `mcp-use`, the inspector is automatically available:
-
-```typescript
-import { createMCPServer } from 'mcp-use/server'
-
-const server = createMCPServer('my-server', {
-  version: '1.0.0',
-})
-
-// Add your tools, resources, prompts...
-
-server.listen(3000)
-// 🎉 Inspector automatically available at http://localhost:3000/inspector
-// 🚀 Auto-connects to your local server at http://localhost:3000/mcp
-```
+### Access the Inspector
 
-**That's it!** No additional configuration needed. The inspector:
+There are three ways to use the MCP Inspector:
 
-- Automatically mounts at `/inspector`
-- Auto-connects to your local MCP server
-- Provides instant debugging capabilities
-- Opens automatically in dev mode with `@mcp-use/cli`
+#### 1. Online Version (Recommended for Testing)
 
-### Method 2: Standalone CLI Tool
+Visit [inspector.mcp-use.com](https://inspector.mcp-use.com/inspector) - no installation required!
 
-Use the inspector with any MCP server (local or remote):
+#### 2. Run Locally
 
 ```bash
-# Inspect a remote server
-npx mcp-inspect --url https://mcp.linear.app/sse
-
-# Custom port
-npx mcp-inspect --url http://localhost:3000/mcp --port 8080
-
-# Open inspector without auto-connect
-npx mcp-inspect
+npx @mcp-use/inspector
 ```
 
-### Method 3: Custom Integration
+Opens the inspector in your browser at `http://localhost:8080`
 
-Mount the inspector in your Express app at a custom path:
+#### 3. Auto-mounted with mcp-use Servers
+
+When you create an MCP server with `mcp-use`, the inspector is automatically available at `/inspector`:
 
 ```typescript
-import { mountInspector } from '@mcp-use/inspector'
-import express from 'express'
+import { createMCPServer } from 'mcp-use/server'
 
-const app = express()
+const server = createMCPServer('my-server', {
+  version: '1.0.0',
+})
 
-// Mount at custom path
-mountInspector(app, '/debug/inspector')
+// Add your tools, resources, prompts...
 
-app.listen(3000)
-// Inspector available at http://localhost:3000/debug/inspector
+server.listen(3000)
+// 🎉 Inspector automatically available at http://localhost:3000/inspector
 ```
 
 ---
 
 ## 📖 Usage Guide
 
-### Dashboard Overview
+### Dashboard
 
-The main dashboard shows:
+The main dashboard is your central hub for managing MCP server connections:
 
-- **Connection Overview**: Total servers, active connections, available tools
-- **Server List**: All configured servers with their current status
-- **Quick Actions**: Add new server, refresh all, clear sessions
+- **Connected Servers Panel** (left): View all your connected servers
+- **Connect Panel** (right): Add new server connections with transport, URL, auth, and headers configuration
+- **Quick Actions**: Access settings and clear sessions from the top bar
 
-### Adding Servers
+### Adding an MCP Server
 
-Click "Add New MCP Server" and provide:
+To connect to an MCP server:
 
-- **Server Name** (optional): Friendly name for identification
-- **Server URL**: The MCP endpoint URL
+1. **Open Connect Panel**: Click the Connect panel on the right side of the dashboard
+2. **Configure Transport**: 
+   - Select "Streamable HTTP" for SSE connections
+   - Select "WebSocket" for WS connections
+   - Configure "stdin/stdio" for local process connections
+3. **Enter Server URL**: Input the MCP server endpoint (e.g., `https://mcp.linear.app/mcp`)
+4. **Configure Authentication** (if needed): Add OAuth credentials or API headers
+5. **Click Connect**: Establish the connection
 
 Example URLs:
-
+- Linear: `https://mcp.linear.app/mcp`
 - Local: `http://localhost:3000/mcp`
-- Linear: `https://mcp.linear.app/sse`
-- WebSocket: `ws://localhost:8080`
-
-### Connection States
-
-The inspector displays real-time connection states:
-
-| State                 | Description                | Action             |
-| --------------------- | -------------------------- | ------------------ |
-| 🔍 **discovering**    | Finding the server         | Wait               |
-| 🔄 **connecting**     | Establishing connection    | Wait               |
-| 🔐 **authenticating** | OAuth flow in progress     | Complete auth      |
-| 📥 **loading**        | Loading tools & resources  | Wait               |
-| ✅ **ready**          | Connected and operational  | Use tools          |
-| ❌ **failed**         | Connection failed          | Retry              |
-| ⏳ **pending_auth**   | Waiting for authentication | Click Authenticate |
-
-### Testing Tools
-
-1. Click **"Inspect"** on a connected server
-2. Navigate to the **Tools** tab
-3. Select a tool to view its schema
-4. Click **"Execute"** to open the test panel
-5. Enter JSON parameters
-6. Click **"Run"** to execute
-7. View results in real-time
-
-Example tool execution:
-
-```json
-// Input for 'search_database' tool
-{
-  "query": "user analytics",
-  "limit": 10,
-  "sortBy": "date"
-}
-
-// Result
-{
-  "results": [...],
-  "total": 42,
-  "executionTime": "23ms"
-}
-```
 
 ### OAuth Authentication
 
 For servers requiring OAuth (like Linear):
 
-1. Connection shows "pending_auth" status
-2. Click **"Authenticate"** button
-3. Complete OAuth in the popup window
-4. Connection automatically completes
-
-If popup is blocked:
-
-- Click "open auth page" link
-- Complete authentication manually
-- Return to inspector
-
-### Resource Management
-
-Browse available resources:
-
-- View resource descriptions
-- Copy resource URIs
-- Check MIME types
-- Preview resource metadata
+1. After clicking **Connect**, you'll see the authorization page
+2. Click **"Approve"** to grant access
+3. The inspector handles the redirect automatically
+4. Server appears in Connected Servers list with a green indicator
 
-### Prompt Testing
+> **Privacy Note**: All authentication tokens and credentials are stored securely in your browser's local storage. Nothing is sent to our servers - everything stays on your device.
 
-Test prompts with the inspector:
+### Connected Servers
 
-1. Navigate to **Prompts** tab
-2. Select a prompt
-3. Fill in required arguments
-4. Click **"Render"** to see output
-5. Copy rendered prompt for use
-
----
-
-## 🎨 UI Components
-
-### Server Card
-
-Each server displays:
-
-- Connection status indicator
+Once connected, each server shows:
+- Connection status indicator (green = connected)
 - Server name and URL
 - Available tools count
-- Last connection time
-- Action buttons (Connect/Disconnect/Inspect/Remove)
-
-### Tool Explorer
+- Action buttons: **Inspect**, **Disconnect**, **Remove**
 
-The tool explorer shows:
+Click **"Inspect"** to open the detailed server view.
 
-- Tool name and description
-- Input schema with types
-- Output schema
-- Execution panel
-- Response viewer with syntax highlighting
+---
 
-### Chat Interface
+## 🔍 Server Detail View
 
-Interactive chat for testing conversational flows:
+After clicking **"Inspect"** on a connected server, you'll see four main tabs:
 
-- Send messages to test prompts
-- View tool calls in real-time
-- See formatted responses
-- Copy conversation history
+### Tools Tab
 
----
+The Tools tab displays all available tools from the MCP server.
 
-## 🔧 Advanced Features
+**Features:**
+- Browse all available tools with their names and descriptions
+- Select a tool to view its detailed schema
+- Click **"Execute"** to test the tool
+- Enter JSON parameters in the input panel
+- View real-time results with syntax highlighting
+- Support for MCP-UI and OpenAI Apps SDK widgets
 
-### Bulk Operations
+**Example**: When connected to Linear MCP server, you'll see 23+ tools for managing issues, projects, and teams.
 
-Manage multiple servers efficiently:
+### Resources Tab
 
-```javascript
-// Select multiple servers
-// Click "Bulk Actions"
-// Choose: Connect All, Disconnect All, Remove Selected
-```
+Browse available resources from the MCP server:
 
-### Session Management
+- View resource descriptions and metadata
+- Copy resource URIs for use in your applications
+- Check MIME types and resource properties
+- Preview resource content
 
-Sessions are automatically saved to localStorage:
+> **Note**: Some servers (like Linear) may not expose resources, in which case you'll see "No resources available".
 
-- Preserves server configurations
-- Maintains connection preferences
-- Restores on page reload
-- Clear with "Clear All Sessions"
+### Prompts Tab
 
-### Custom Themes
+Test and manage pre-configured prompts:
 
-The inspector respects system theme preferences:
+- View all available prompts with descriptions
+- Select a prompt to see its schema
+- Fill in required arguments in the form
+- Click **"Render"** to execute the prompt
+- Copy the rendered output for use
 
-- Light mode for better readability
-- Dark mode for reduced eye strain
-- Automatic switching based on OS settings
+> **Note**: Not all servers provide prompts. If none are available, you'll see "No prompts available".
 
-### Keyboard Shortcuts
+### Chat Tab
 
-| Shortcut       | Action                  |
-| -------------- | ----------------------- |
-| `Cmd/Ctrl + K` | Quick server search     |
-| `Cmd/Ctrl + N` | Add new server          |
-| `Cmd/Ctrl + R` | Refresh all connections |
-| `Esc`          | Close modals            |
+The Chat tab provides an interactive interface to test the MCP server with an LLM using **BYOK (Bring Your Own Key)**.
 
----
+> **Privacy**: Your API key is stored locally in your browser and never sent to our servers. All requests are made directly from your device to your LLM provider.
 
-## 🛠️ Configuration Examples
+**Setup:**
 
-### Local Development Server
+1. Click **"Configure API Key"** to open the configuration modal
+2. Select your **Provider** (OpenAI, Anthropic, etc.)
+3. Choose the **Model** (gpt-4o, claude-3-5-sonnet, etc.)
+4. Enter your **API Key** (stored locally in browser)
+5. Click **"Save Configuration"**
 
-```javascript
-// Your MCP server
-import { createMCPServer } from 'mcp-use/server'
+**Using Chat:**
 
-const server = createMCPServer('dev-server', {
-  version: '1.0.0',
-  description: 'Development MCP Server',
-})
-
-server.tool('debug_tool', {
-  description: 'Debug tool for testing',
-  parameters: z.object({
-    message: z.string(),
-  }),
-  execute: async ({ message }) => {
-    console.log('Debug:', message)
-    return { received: message, timestamp: Date.now() }
-  },
-})
+- Type natural language queries to test the MCP server
+- View tool calls in real-time with visual indicators
+- See detailed JSON output for arguments and results
+- Watch the assistant's response based on tool results
+- Track exactly how the MCP server processes requests
 
-server.listen(3000)
-// Inspector at http://localhost:3000/inspector
-```
+---
 
-### Production Server with Auth
+## ⌨️ Keyboard Shortcuts
 
-```javascript
-const server = createMCPServer('production-server', {
-  version: '1.0.0',
-  oauth: {
-    clientId: process.env.OAUTH_CLIENT_ID,
-    clientSecret: process.env.OAUTH_CLIENT_SECRET,
-    authorizationUrl: 'https://api.example.com/oauth/authorize',
-    tokenUrl: 'https://api.example.com/oauth/token',
-  },
-})
+| Shortcut       | Action                     |
+| -------------- | -------------------------- |
+| `Cmd/Ctrl + K` | Quick search and navigation |
+| `Esc`          | Close modals and overlays  |
 
-// Inspector handles OAuth flow automatically
-```
+**Quick Search (Cmd/Ctrl + K)** allows you to:
+- Quickly connect to a new server
+- Access documentation and tutorials
+- Jump to recently used servers
+- Search and execute tools directly
+- Navigate to different tabs
 
-### Multiple Server Management
+---
 
-In the inspector, manage multiple servers:
+## 💾 Persistency
 
-```javascript
-// Add servers via UI
-// Server 1: Local Development
-URL: http://localhost:3000/mcp
+The inspector automatically saves your configurations:
 
-// Server 2: Staging
-URL: https://staging.example.com/mcp
+- **Server connections** persist across page reloads
+- **Credentials** are stored securely in your browser's localStorage
+- **Session preferences** are maintained automatically
+- Clear all sessions anytime with the **"Clear All"** button
 
-// Server 3: Production
-URL: https://api.example.com/mcp
-```
+Your data never leaves your browser - everything is stored locally for privacy and security.
 
 ---
 
-## 🏗️ Architecture
+## 🐳 Self-Hosting
 
-The inspector is built with modern web technologies:
+Deploy the MCP Inspector to your own infrastructure with a single Docker container. Perfect for enterprise environments, air-gapped networks, or when you need full control over your debugging environment.
 
-### Frontend Stack
+### Docker Image
 
-- **React 19**: UI framework
-- **React Router**: Navigation
-- **Tailwind CSS**: Styling
-- **shadcn/ui**: Component library
-- **Framer Motion**: Animations
-- **React Syntax Highlighter**: Code display
+The official Docker image is available on [Docker Hub](https://hub.docker.com/r/mcpuse/inspector).
 
-### Core Components
+**Quick Start:**
 
-```
-src/client/
-├── components/
-│   ├── InspectorDashboard.tsx  # Main dashboard view
-│   ├── ServerList.tsx          # Server management
-│   ├── ServerDetail.tsx        # Individual server view
-│   ├── ToolExecutor.tsx        # Tool testing interface
-│   ├── ResourceBrowser.tsx    # Resource explorer
-│   └── ChatInterface.tsx      # Interactive chat
-├── context/
-│   └── McpContext.tsx         # Connection state management
-└── hooks/
-    └── useMcp.ts              # MCP connection hook
+```bash
+docker run -d -p 8080:8080 --name mcp-inspector mcpuse/inspector:latest
 ```
 
-### Connection Management
+Then visit `http://localhost:8080` to access your self-hosted inspector.
 
-The `useMcp` hook handles:
+### Docker Deployment Options
 
-- WebSocket/SSE connections
-- Automatic reconnection
-- OAuth flow management
-- Error recovery
-- State synchronization
-
----
-
-## 🐛 Troubleshooting
-
-### Common Issues and Solutions
-
-**Inspector not loading:**
+**Using Docker Run:**
 
 ```bash
-# Check server is running
-curl http://localhost:3000/inspector
-
-# Verify no conflicting routes
-# Ensure inspector is mounted correctly
+docker run -d \
+  --name mcp-inspector \
+  -p 8080:8080 \
+  -e NODE_ENV=production \
+  mcpuse/inspector:latest
 ```
 
-**Connection fails immediately:**
+**Using Docker Compose:**
+
+```yaml
+version: '3.8'
+services:
+  mcp-inspector:
+    image: mcpuse/inspector:latest
+    ports:
+      - "8080:8080"
+    environment:
+      - NODE_ENV=production
+      - PORT=8080
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
 
-- Check CORS configuration
-- Verify server URL is correct
-- Ensure server supports SSE/WebSocket
-- Check network/firewall settings
+### Environment Variables
 
-**OAuth popup blocked:**
+All configuration is optional. The inspector works out of the box with sensible defaults.
 
-- Allow popups for the inspector domain
-- Use the manual auth link provided
-- Check browser console for errors
+| Variable    | Default    | Description                  |
+| ----------- | ---------- | ---------------------------- |
+| `NODE_ENV`  | production | Node.js environment          |
+| `PORT`      | 8080       | Port to run the inspector on |
+| `HOST`      | 0.0.0.0    | Host to bind to              |
 
-**Tools not executing:**
+### Deploy to Railway
 
-- Verify tool schemas are valid
-- Check server logs for errors
-- Ensure proper authentication
-- Validate input parameters
+Deploy instantly to Railway with automatic HTTPS and custom domains:
 
-**Session not persisting:**
+[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template)
 
-- Check localStorage is enabled
-- Clear browser cache
-- Try incognito/private mode
-- Check for browser extensions blocking storage
+For more deployment options and support, visit the [self-hosting documentation](https://docs.mcp-use.com/inspector/self-hosting).
 
 ---
 
-## 🚀 Performance Tips
+## 📊 Telemetry & Privacy
 
-### Optimize for Large Tool Sets
+The MCP Inspector collects anonymized usage data to help us improve the tool.
 
-```javascript
-// Use pagination for many tools
-server.configurePagination({
-  toolsPerPage: 50,
-  enableSearch: true,
-})
-```
+### What Data is Collected?
 
-### Reduce Connection Overhead
+We collect:
 
-```javascript
-// Configure connection pooling
-const inspector = {
-  maxConnections: 5,
-  connectionTimeout: 30000,
-  keepAlive: true,
-}
-```
+- **Usage events**: When you connect to servers, execute tools, read resources, or call prompts
+- **Anonymous user ID**: A randomly generated UUID stored in your browser's localStorage
+- **Technical information**: Package version, browser type, and connection types
+- **Performance data**: Tool execution duration and success/failure rates
 
-### Enable Caching
+We **DO NOT** collect:
 
-```javascript
-// Cache tool results
-server.enableCache({
-  ttl: 300, // 5 minutes
-  maxSize: 100, // MB
-})
-```
+- Personal information (names, emails, etc.)
+- Actual tool arguments or results
+- Server credentials or API keys
+- Resource content or data
 
----
+### How to Opt Out
 
-## 🔒 Security Considerations
+You can disable telemetry in several ways:
 
-### CORS Configuration
+**Option 1: Environment Variable**
 
-```javascript
-// Configure CORS for inspector access
-server.configureCORS({
-  origin: ['http://localhost:3000'],
-  credentials: true,
-})
+```bash
+# Set before starting the inspector
+export MCP_USE_ANONYMIZED_TELEMETRY=false
 ```
 
-### Authentication
+**Option 2: localStorage (Browser)**
 
 ```javascript
-// Add authentication middleware
-server.use(authMiddleware)
+// In browser console
+localStorage.setItem('mcp_inspector_telemetry_disabled', 'true')
 ```
 
-### Rate Limiting
+**Option 3: Package-level**
 
-```javascript
-// Prevent abuse
-server.configureRateLimit({
-  windowMs: 60000, // 1 minute
-  max: 100, // requests
-})
+```json
+// Add to your package.json
+{
+  "scarfSettings": {
+    "enabled": false
+  }
+}
 ```
 
----
-
-## 📚 API Reference
-
-### Inspector Methods
+### Telemetry Providers
 
-```typescript
-// Mount inspector
-mountInspector(app: Express, path?: string): void
+We use:
 
-// Standalone server
-startInspectorServer(port: number): void
-
-// Configuration
-configureInspector(options: InspectorOptions): void
-```
-
-### Connection Options
-
-```typescript
-interface InspectorOptions {
-  autoConnect?: boolean // Auto-connect to local server
-  theme?: 'light' | 'dark' | 'auto'
-  persistence?: boolean // Save sessions
-  maxConnections?: number
-  connectionTimeout?: number
-}
-```
+- **PostHog**: For product analytics and feature usage tracking
+- **Scarf**: For package download analytics and company insights
 
+Both providers respect your privacy and follow GDPR compliance.
 ---
 
 ## 🤝 Contributing
 
-We welcome contributions! Areas for improvement:
-
-- Additional UI themes
-- More keyboard shortcuts
-- Enhanced tool testing features
-- Performance optimizations
-- Localization support
+We welcome contributions! 
 
 See our [contributing guide](https://github.com/mcp-use/mcp-use/blob/main/CONTRIBUTING.md) for details.
 
@@ -544,11 +391,11 @@ See our [contributing guide](https://github.com/mcp-use/mcp-use/blob/main/CONTRI
 
 ## 📚 Learn More
 
-- [mcp-use Documentation](https://github.com/mcp-use/mcp-use)
-- [Model Context Protocol](https://modelcontextprotocol.io)
-- [Creating MCP Servers](https://github.com/mcp-use/mcp-use/tree/main/packages/mcp-use#-mcp-server-framework)
-- [Building with React](https://react.dev)
-- [Tailwind CSS](https://tailwindcss.com)
+- [Inspector Documentation](https://docs.mcp-use.com/inspector) - Complete usage guide and tutorials
+- [Self-Hosting Guide](https://docs.mcp-use.com/inspector/self-hosting) - Deploy your own instance
+- [mcp-use Documentation](https://docs.mcp-use.com) - Full framework documentation
+- [Model Context Protocol](https://modelcontextprotocol.io) - Official MCP specification
+- [GitHub Repository](https://github.com/mcp-use/mcp-use) - Source code and examples
 
 ---