| Name | par-mcp-inspector-tui JSON |
| Version |
0.4.0
JSON |
| download |
| home_page | None |
| Summary | PAR MCP Inspector TUI |
| upload_time | 2025-07-27 20:43:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2025 Paul Robello
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
mcp
terminal
tui
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PAR MCP Inspector TUI
[](https://python.org)
A comprehensive Terminal User Interface (TUI) application for inspecting and interacting with Model Context Protocol (MCP) servers. This tool provides an intuitive interface to connect to MCP servers, explore their capabilities, and execute tools, prompts, and resources in real-time.
[](https://buymeacoffee.com/probello3)
## Screenshots
*The MCP Inspector TUI showing a connected "Everything" server with available tools (echo, add, printEnv), tool parameter forms, and real-time interaction logs. The interface displays server management on the left, tabbed content areas in the center, and notifications on the right.*
## Features
- **Multiple Transport Support**: Connect to MCP servers via STDIO and HTTP+SSE
- **MCP Roots Support**: Full implementation of MCP filesystem roots protocol with TUI and CLI management
- **CLI Debugging Tools**: Connect to arbitrary servers and inspect interactions without configuration
- **Resource Download CLI**: Download resources by name with automatic file type detection
- **Real-time Introspection**: Discover tools, prompts, and resources from connected servers
- **Dynamic Forms**: Automatically generated forms based on server-provided schemas with real-time validation
- **Form Validation**: Smart execute button control - disabled until all required fields are filled
- **Magic Number Detection**: Automatic file type detection using magic numbers for binary resources
- **Syntax Highlighting**: Rich response formatting with support for JSON, Markdown, and code
- **File Management**: Save and open resources with proper file extensions and MIME type handling
- **Server Management**: Persistent configuration storage for multiple server connections
- **Non-blocking Operations**: Async communication ensuring responsive UI
- **Server Notifications**: Real-time notifications from MCP servers with auto-refresh capabilities
- **Application Notifications**: Real-time status updates and error handling
- **Tab Auto-clearing**: Automatically clears all tabs when disconnecting from servers
- **Capability-aware**: Gracefully handles servers with partial MCP implementation
## Technology Stack
- **Python 3.11+** - Modern Python with latest features
- **FastMCP** - High-performance Model Context Protocol implementation with robust transport layer
- **Textual** - Beautiful, responsive terminal user interfaces
- **Pydantic** - Data validation and serialization
- **Rich** - Terminal output formatting and syntax highlighting
- **filetype** - Magic number file type detection
- **YAML** - Configuration file format
- **Asyncio** - Asynchronous programming for responsive interfaces
## Prerequisites
To install PAR MCP Inspector TUI, make sure you have Python 3.11+.
### [uv](https://pypi.org/project/uv/) is recommended
#### Linux and Mac
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
#### Windows
```bash
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
## Installation
### Installation from PyPI (Recommended)
Install the latest stable version using uv:
```bash
uv tool install par-mcp-inspector-tui
```
Or using pip:
```bash
pip install par-mcp-inspector-tui
```
After installation, you can run the tool directly:
```bash
# Launch the TUI application
pmit tui
# Show all available commands
pmit --help
```
### Installation From Source
For development or to get the latest features:
1. Clone the repository:
```bash
git clone https://github.com/paulrobello/par-mcp-inspector-tui.git
cd par-mcp-inspector-tui
```
2. Install the package dependencies using uv:
```bash
uv sync
```
3. Run using uv:
```bash
uv run pmit tui
```
## Usage
### CLI Commands Overview
If installed from PyPI:
```shell
# Show all available commands
pmit --help
# Show version information
pmit --version
# Launch the TUI application
pmit tui
# Launch TUI with debug mode
pmit tui --debug
# List configured servers
pmit servers
# Debug a configured server
pmit debug <server-id> --verbose
# Connect to arbitrary STDIO server
pmit connect npx --arg "-y" --arg "@modelcontextprotocol/server-filesystem" --arg "/tmp"
# Connect to arbitrary TCP server
pmit connect-tcp localhost 3333
# Download resources from servers
pmit download-resource <server-id> <resource-name>
# Manage filesystem roots for servers
pmit roots-list [server-id]
pmit roots-add <server-id> <path>
pmit roots-remove <server-id> <path>
```
If running from source:
```shell
# Show all available commands
uv run pmit --help
# Show version information
uv run pmit --version
# Launch the TUI application
uv run pmit tui
# Launch TUI with debug mode
uv run pmit tui --debug
# List configured servers
uv run pmit servers
# Debug a configured server
uv run pmit debug <server-id> --verbose
# Connect to arbitrary STDIO server
uv run pmit connect npx --arg "-y" --arg "@modelcontextprotocol/server-filesystem" --arg "/tmp"
# Connect to arbitrary TCP server
uv run pmit connect-tcp localhost 3333
# Download resources from servers
uv run pmit download-resource <server-id> <resource-name>
# Manage filesystem roots for servers
uv run pmit roots-list [server-id]
uv run pmit roots-add <server-id> <path>
uv run pmit roots-remove <server-id> <path>
```
### TUI Application
```shell
# Start the MCP Inspector TUI (if installed from PyPI)
pmit tui
# Enable debug mode for troubleshooting
pmit tui --debug
# If running from source
uv run pmit tui
uv run pmit tui --debug
```
**Options:**
- `--debug -d`: Enable debug mode for detailed logging and troubleshooting
### First Time Setup
1. **Launch the application**: `pmit tui` (or `uv run pmit tui` if running from source)
2. **Default servers**: The application comes with working example server configurations:
- **Example STDIO Server**: Filesystem server for `/tmp` directory
- **Everything**: Comprehensive test server with tools, resources, and notifications
3. **Add your servers**: Use the "Add Server" button to configure your MCP servers
4. **Connect**: Select a server from the list and click "Connect"
5. **Explore**: Browse resources, prompts, and tools in the tabbed interface
### Quick Testing without Configuration
Test any MCP server instantly without adding it to configuration:
```shell
# Test a filesystem server
uv run pmit connect npx \
--arg "-y" \
--arg "@modelcontextprotocol/server-filesystem" \
--arg "/tmp" \
--name "My Test Server" \
--verbose
# Test with environment variables
uv run pmit connect python \
--arg "my_server.py" \
--env "DEBUG=1" \
--env "DATABASE_URL=sqlite:///test.db"
# Test TCP server
uv run pmit connect-tcp myhost.com 8080 --verbose
```
## CLI Commands Reference
### Global Options
- `--version -v`: Show version and exit
- `--help`: Show help message and exit
### `tui` - Launch TUI Application
```shell
# If installed from PyPI
pmit tui [OPTIONS]
# If running from source
uv run pmit tui [OPTIONS]
```
**Options:**
- `--debug -d`: Enable debug mode for detailed logging and troubleshooting
### `servers` - List Configured Servers
```shell
# If installed from PyPI
pmit servers
# If running from source
uv run pmit servers
```
Shows a formatted table of all configured MCP servers with their connection details and status.
### `debug` - Debug Configured Server
```shell
# If installed from PyPI
pmit debug <server-id-or-name> [OPTIONS]
# If running from source
uv run pmit debug <server-id-or-name> [OPTIONS]
```
**Arguments:**
- `server-id-or-name`: Server ID or name to debug (required)
**Options:**
- `--verbose -v`: Verbose output with raw JSON
- `--debug`: Enable debug logging of MCP messages
Connect to a pre-configured server and test all MCP endpoints:
- Shows server information and capabilities
- Tests resources, tools, and prompts endpoints with enhanced display
- **Enhanced Resource Display**: Color-coded labels and ready-to-use download commands
- Displays detailed error information
- Use `--verbose` for raw JSON responses
- Use `--debug` for detailed MCP message logging
**Enhanced Resource Display Features:**
- **Resource Names**: Clearly highlighted for use with `download-resource` command
- **Download Instructions**: Exact command syntax for configured servers
- **Color-Coded Output**: Green names, cyan URIs, yellow descriptions, magenta MIME types
- **Smart Guidance**: Different messages for configured vs temporary servers
### `connect` - Connect to Arbitrary STDIO Server
```shell
# If installed from PyPI
pmit connect <command> [OPTIONS]
# If running from source
uv run pmit connect <command> [OPTIONS]
```
**Arguments:**
- `command`: Command to execute for STDIO transport (required)
**Options:**
- `--arg -a`: Command arguments (can be specified multiple times)
- `--env -e`: Environment variables in KEY=VALUE format (can be specified multiple times)
- `--verbose -v`: Verbose output with raw JSON
- `--debug`: Enable debug logging of MCP messages
- `--name -n`: Server name for display (default: Ad-hoc Server)
Connect to an arbitrary STDIO server without adding it to configuration. Uses the same enhanced debug output as the `debug` command, including:
- **Color-coded resource display** with download guidance
- **Smart messaging**: Informs users to add server to configuration before downloading resources
- **Full MCP testing**: Resources, tools, and prompts endpoints
**Examples:**
```shell
# Basic usage (PyPI installation)
pmit connect npx -a "-y" -a "@modelcontextprotocol/server-filesystem" -a "/tmp"
# With environment variables and custom name
pmit connect python -a "server.py" -e "DEBUG=1" -e "PORT=8080" -n "My Server"
# Verbose output with debug logging
pmit connect node -a "server.js" --verbose --debug
# From source
uv run pmit connect npx -a "-y" -a "@modelcontextprotocol/server-filesystem" -a "/tmp"
```
### `connect-tcp` - Connect to Arbitrary TCP Server
```shell
# If installed from PyPI
pmit connect-tcp [HOST] [PORT] [OPTIONS]
# If running from source
uv run pmit connect-tcp [HOST] [PORT] [OPTIONS]
```
**Arguments:**
- `host`: Host to connect to (default: localhost)
- `port`: Port to connect to (default: 3333)
**Options:**
- `--verbose -v`: Verbose output with raw JSON
- `--debug`: Enable debug logging of MCP messages
- `--name -n`: Server name for display (default: TCP Server)
Connect to an arbitrary TCP server without adding it to configuration. Uses the same enhanced debug output as other debug commands, including:
- **Enhanced resource listing** with color-coded display
- **Download guidance**: Instructions to add server to configuration first
- **Complete testing**: All MCP endpoints (resources, tools, prompts)
**Examples:**
```shell
# Default host and port (PyPI installation)
pmit connect-tcp
# Custom host and port with verbose and debug output
pmit connect-tcp example.com 8080 -n "Remote Server" --verbose --debug
# From source
uv run pmit connect-tcp
uv run pmit connect-tcp example.com 8080 -n "Remote Server" --verbose --debug
```
### `download-resource` - Download Resources by Name
```shell
# If installed from PyPI
pmit download-resource <server-id-or-name> <resource-name> [OPTIONS]
# If running from source
uv run pmit download-resource <server-id-or-name> <resource-name> [OPTIONS]
```
**Arguments:**
- `server-id-or-name`: Server ID or name to download from (required)
- `resource-name`: Resource name to download (required)
**Options:**
- `--output -o`: Output directory (default: current directory)
- `--filename -f`: Custom filename (default: auto-detect from resource)
- `--verbose -v`: Verbose output with detailed information
- `--debug`: Enable debug logging of MCP messages
**Features:**
- **Smart Resource Finding**: Exact name match, case-insensitive fallback, and partial matching
- **Automatic File Type Detection**: Uses MIME types and magic number detection for proper extensions
- **Custom Output**: Specify output directory and custom filenames
- **Error Handling**: Clear error messages for missing servers/resources
**Examples:**
```shell
# Download resource with auto-detection (PyPI installation)
pmit download-resource Everything "Resource 1"
# Custom output directory
pmit download-resource filesystem-server "config.json" --output ~/Downloads
# Custom filename with verbose output
pmit download-resource Everything "Resource 2" --filename my-file.txt --verbose
# Download binary resource (automatic type detection)
pmit download-resource image-server "logo.png" --output ./assets
# From source
uv run pmit download-resource Everything "Resource 1"
```
### `roots-list` - List Filesystem Roots
```shell
# If installed from PyPI
pmit roots-list [SERVER_ID] [OPTIONS]
# If running from source
uv run pmit roots-list [SERVER_ID] [OPTIONS]
```
**Arguments:**
- `server-id`: Server ID (optional - uses current connected server if not specified)
**Options:**
- `--verbose -v`: Show detailed root information including path validation and type
**Features:**
- **Automatic Server Detection**: If no server ID provided, uses the currently connected server
- **Path Validation**: Shows ✓ for existing paths, ✗ for missing paths
- **Type Detection**: Displays whether paths are directories or files (with `--verbose`)
- **URI Support**: Handles both local paths and `file://` URIs
- **Clear Display**: Numbered list with status indicators
**Examples:**
```shell
# List roots for connected server (PyPI installation)
pmit roots-list
# List roots for specific server with details
pmit roots-list my-server-id --verbose
# From source
uv run pmit roots-list
uv run pmit roots-list my-server-id --verbose
```
### `roots-add` - Add Filesystem Root
```shell
# If installed from PyPI
pmit roots-add <server-id> <path> [OPTIONS]
# If running from source
uv run pmit roots-add <server-id> <path> [OPTIONS]
```
**Arguments:**
- `server-id`: Server ID (required)
- `path`: Filesystem path or `file://` URI to add as root (required)
**Options:**
- `--name -n`: Display name for the root (used in TUI interface)
**Features:**
- **Automatic URI Conversion**: Converts local paths to proper `file://` URIs
- **Duplicate Prevention**: Prevents adding the same root path multiple times
- **Path Resolution**: Automatically resolves relative paths to absolute paths
- **Persistent Storage**: Saves roots to server configuration immediately
- **Display Name Support**: Optional display names for better TUI presentation
**Examples:**
```shell
# Add current directory as root (PyPI installation)
pmit roots-add my-server-id . --name "Project Root"
# Add absolute path
pmit roots-add my-server-id /home/user/documents
# Add with file:// URI
pmit roots-add my-server-id file:///tmp/workspace --name "Workspace"
# From source
uv run pmit roots-add my-server-id . --name "Project Root"
uv run pmit roots-add my-server-id /home/user/documents
```
### `roots-remove` - Remove Filesystem Root
```shell
# If installed from PyPI
pmit roots-remove <server-id> <path>
# If running from source
uv run pmit roots-remove <server-id> <path>
```
**Arguments:**
- `server-id`: Server ID (required)
- `path`: Filesystem path or `file://` URI to remove (required)
**Features:**
- **Flexible Path Matching**: Accepts both local paths and `file://` URIs
- **Automatic URI Conversion**: Converts local paths to URIs for matching
- **Path Resolution**: Resolves relative paths to match stored absolute paths
- **Not Found Handling**: Shows available roots if specified path not found
- **Immediate Persistence**: Updates server configuration immediately
**Examples:**
```shell
# Remove by local path (PyPI installation)
pmit roots-remove my-server-id /tmp/workspace
# Remove by file:// URI
pmit roots-remove my-server-id file:///home/user/documents
# Remove relative path (resolved automatically)
pmit roots-remove my-server-id ../parent-dir
# From source
uv run pmit roots-remove my-server-id /tmp/workspace
uv run pmit roots-remove my-server-id file:///home/user/documents
```
## Server Configuration
The TUI application stores server configurations in `~/.config/mcp-inspector/servers.yaml`. Example configuration:
```yaml
servers:
filesystem-server:
name: "Filesystem Server"
transport: "stdio"
command: "npx"
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
- "/tmp"
env:
NODE_ENV: "production"
toast_notifications: true # Show toast notifications (default: true)
roots: # MCP filesystem roots (optional)
- "file:///tmp"
- "file:///home/user/documents"
- "file:///var/log"
http-mcp-server:
name: "HTTP MCP Server"
transport: "http"
url: "https://api.example.com/mcp"
toast_notifications: true # Show toast notifications for this server
roots: # Roots can be specified for any transport type
- "file:///workspace/project"
- "file:///shared/resources"
```
#### Configuration Options
- **toast_notifications** (boolean, default: true): Controls whether to show toast popup notifications when the server sends notifications. When `false`, notifications are still added to the notifications tab but won't show as toast popups. Note: Toasts are automatically suppressed when viewing the notifications tab regardless of this setting.
- **roots** (array of strings, optional): List of filesystem roots that define the boundaries of filesystem access for MCP servers. Each root should be a `file://` URI pointing to a directory or file. These roots are sent to the server during connection to establish filesystem boundaries according to the MCP roots protocol. Roots can be managed through the TUI interface (Roots tab) or via CLI commands (`roots-add`, `roots-remove`, `roots-list`).
#### UI Configuration
You can configure toast notifications through the TUI interface:
1. **Add Server Dialog**: When adding a new server, check/uncheck "Show toast notifications from this server"
2. **Edit Server Dialog**: Select any server and click "Edit Server" to modify the toast notification setting
3. **Per-Server Control**: Each server has different notification settings
4. **Real-time Updates**: Changes take effect immediately after saving
### Supported Transport Types
#### STDIO Transport (Recommended)
For servers that communicate via standard input/output (most common):
```yaml
servers:
my-stdio-server:
name: "My STDIO Server"
transport: "stdio"
command: "python"
args:
- "server.py"
env:
DEBUG: "1"
```
#### HTTP Transport
For HTTP-based MCP servers with SSE (Server-Sent Events) support:
```yaml
servers:
my-http-server:
name: "My HTTP MCP Server"
transport: "http"
url: "https://api.example.com/mcp"
```
#### TCP Transport (Legacy HTTP+SSE)
For backward compatibility with HTTP-based MCP servers:
```yaml
servers:
my-tcp-server:
name: "My TCP Server"
transport: "tcp"
host: "localhost"
port: 8080
```
**Important Notes**:
- **STDIO transport** is recommended for most MCP servers (filesystem, everything, etc.)
- **HTTP transport** is for servers with full HTTP URLs
- **TCP transport** actually uses HTTP+SSE protocol, not raw TCP sockets
- Use HTTP/TCP transports only for servers that explicitly support HTTP+SSE protocol
## User Interface
### Main Layout
- **Left Panel**: Server list and connection status
- **Center Panel**: Tabbed interface with:
- **Resources**: Browse and read available resources
- **Prompts**: Execute prompts with dynamic argument forms and validation
- **Tools**: Call tools with smart parameter validation and form controls
- **Roots**: Manage filesystem roots for MCP server access boundaries
- **Notifications**: Real-time server notifications with auto-refresh capabilities
- **Right Panel**: Response viewer with formatted output and syntax highlighting
### Form Validation Features
- **Required Field Indicators**: Red asterisks (*) mark required parameters
- **Smart Execute Button**: Automatically disabled when required fields are empty
- **Real-time Validation**: Button state updates as you type in form fields
- **Array Field Support**: Add/remove dynamic list items with validation
- **Multiple Field Types**: Text, number, checkbox, select, and array inputs
### Server Notifications Features
- **Real-time Updates**: Receive notifications from MCP servers as they happen
- **Auto-refresh**: Automatically refresh tools, resources, and prompts when server lists change
- **Server Context**: Each notification shows which server sent it
- **Message Types**: Supports different notification types:
- `notifications/tools/list_changed` - Tools list has changed
- `notifications/resources/list_changed` - Resources list has changed
- `notifications/prompts/list_changed` - Prompts list has changed
- `notifications/message` - General server messages with level indicators
- **Visual Distinction**: Server notifications have unique styling and icons (🔔)
- **Chronological Order**: Newest notifications appear at the top
- **Notification History**: View complete history of server communications
- **Toast Control**: Per-server configuration for toast popup notifications
- Enable/disable through Add/Edit Server dialogs
- Automatic suppression when viewing notifications tab
- Real-time configuration updates without restart
### Filesystem Roots Management
The **Roots** tab provides comprehensive management of filesystem boundaries for MCP servers:
**Root Management Features:**
- **Add New Roots**: Click "Add Root" to add filesystem paths or `file://` URIs
- **Remove Roots**: Select roots and click "Remove Root" to delete them
- **Path Validation**: Real-time status indicators show if root paths exist (✓/✗)
- **Type Display**: Shows whether roots are directories, files, or URIs
- **Server Integration**: Roots are automatically sent to servers during connection
- **Persistent Storage**: Root configurations are saved with server settings
**Root Display Format:**
- **Status Indicator**: ✓ (exists), ✗ (missing), or ? (unknown)
- **Path Information**: Shows the full `file://` URI or local path
- **Type Information**: (directory), (file), or (URI) designations
- **Organized List**: Clean, numbered display of all configured roots
**MCP Protocol Integration:**
- **Automatic Transmission**: Roots are sent to servers during connection establishment
- **Protocol Compliance**: Implements MCP `roots/list` protocol specification
- **Boundary Enforcement**: Servers use roots to restrict filesystem access
- **Notification Support**: Responds to `notifications/roots/list_changed` from servers
### Server Management
#### Add/Edit Server Dialog
The server configuration dialog provides comprehensive settings for MCP servers:
**Basic Configuration:**
- **Server Name**: Descriptive name for identification
- **Transport Type**: Choose between STDIO or TCP communication
**STDIO Transport Settings:**
- **Command**: Executable command (e.g., `python`, `npx`, `node`)
- **Arguments**: Command-line arguments (one per line)
- **Environment Variables**: KEY=value pairs (one per line)
**HTTP Transport Settings:**
- **URL**: Complete HTTP/HTTPS URL to the MCP server endpoint
**TCP Transport Settings (Legacy):**
- **Host**: Server hostname or IP address
- **Port**: Network port number (1-65535)
**Notification Settings:**
- **Toast Notifications Checkbox**: Control popup notifications for this server
- ✅ **Checked (default)**: Display toast popups + notifications tab
- ❌ **Unchecked**: Notifications tab only (quiet mode)
- 🎯 **Smart Behavior**: Toasts auto-suppressed when viewing notifications tab
**Dialog Features:**
- Real-time form validation with helpful error messages
- Dynamic sections based on transport type selection
- Persistent settings with immediate effect after save
- Maintains UI selection state after edits
### Keyboard Shortcuts
- `q` - Quit application
- `d` - Toggle dark/light mode
- `s` - Focus server panel
- `r` - Refresh server data
- `Ctrl+O` - Open last saved resource file (when viewing resources)
## Testing with MCP Servers
### Example Servers for Testing
Test these official MCP servers using the CLI commands:
1. **Filesystem Server**:
```shell
# Using CLI connect (PyPI installation)
pmit connect npx \
-a "-y" -a "@modelcontextprotocol/server-filesystem" -a "/tmp" \
--verbose
# From source
uv run pmit connect npx \
-a "-y" -a "@modelcontextprotocol/server-filesystem" -a "/tmp" \
--verbose
# Direct command for reference
npx -y @modelcontextprotocol/server-filesystem /tmp
```
2. **SQLite Server**:
```shell
# Using CLI connect (PyPI installation)
pmit connect npx \
-a "-y" -a "@modelcontextprotocol/server-sqlite" \
-a "--db-path" -a "test.db" \
--verbose
# From source
uv run pmit connect npx \
-a "-y" -a "@modelcontextprotocol/server-sqlite" \
-a "--db-path" -a "test.db" \
--verbose
# Direct command for reference
npx -y @modelcontextprotocol/server-sqlite --db-path test.db
```
3. **Custom Python Server**:
```shell
# Test your custom server (PyPI installation)
pmit connect python \
-a "my_mcp_server.py" \
-e "DATABASE_URL=sqlite:///data.db" \
-n "My Custom Server" \
--verbose
# From source
uv run pmit connect python \
-a "my_mcp_server.py" \
-e "DATABASE_URL=sqlite:///data.db" \
-n "My Custom Server" \
--verbose
```
4. **GitHub MCP Server**:
```shell
# Test GitHub integration server (PyPI installation)
pmit connect npx \
-a "-y" -a "@modelcontextprotocol/server-github" \
-e "GITHUB_PERSONAL_ACCESS_TOKEN=your_token" \
--verbose
# From source
uv run pmit connect npx \
-a "-y" -a "@modelcontextprotocol/server-github" \
-e "GITHUB_PERSONAL_ACCESS_TOKEN=your_token" \
--verbose
```
5. **Everything Server (for testing notifications)**:
```shell
# Test server that sends regular notifications (PyPI installation)
pmit connect npx \
-a "-y" -a "@modelcontextprotocol/server-everything" \
--verbose
# From source
uv run pmit connect npx \
-a "-y" -a "@modelcontextprotocol/server-everything" \
--verbose
```
This server sends `notifications/message` every 20 seconds, perfect for testing the notification system.
### Server Capability Testing
The CLI commands automatically test server capabilities with enhanced display formatting:
#### Enhanced Resource Display
- **Color-Coded Labels**: Green names, cyan URIs, yellow descriptions, magenta MIME types
- **Download Ready**: Shows exact `download-resource` commands for configured servers
- **Smart Guidance**: Different messages for configured vs temporary servers
Example output for configured servers:
```
Testing Resources:
Found 3 resources:
Use 'download-resource my-server-id "<resource-name>"' to download any resource
1. Name: config.json
URI: file:///path/to/config.json
Description: Application configuration file
MIME Type: application/json
2. Name: logo.png
URI: file:///path/to/logo.png
MIME Type: image/png
```
#### Standard Testing Features
- **Server Info**: Name, version, protocol version
- **Tools**: Available tools with parameter schemas
- **Prompts**: Available prompts with argument definitions
- **Error Handling**: Timeouts and capability-based filtering
Use `--verbose` flag to see raw JSON responses and detailed debugging information.
## Changelog
### v0.4.0 - MCP Roots Protocol & Enhanced Filesystem Support
- **🌿 MCP Roots Protocol Implementation**: Full support for MCP filesystem roots protocol
- **📁 Comprehensive Roots Management**: Complete TUI and CLI interface for managing filesystem boundaries
- **🎛️ Roots Tab in TUI**: Dedicated interface for visual root management with real-time validation
- **⚡ CLI Root Commands**: Three new commands for root management:
- `pmit roots-list [server-id] [--verbose]` - List and validate filesystem roots
- `pmit roots-add <server-id> <path> [--name]` - Add roots with display names
- `pmit roots-remove <server-id> <path>` - Remove roots with flexible path matching
- **🔒 Automatic Root Transmission**: Roots are automatically sent to servers during connection
- **✅ Path Validation**: Real-time validation with status indicators (✓/✗) for root paths
- **🔄 Protocol Compliance**: Implements `roots/list` and `notifications/roots/list_changed` protocols
- **📊 Enhanced Server Configuration**: Persistent root storage in server configurations
- **🛠️ Developer Features**: URI conversion, path resolution, and comprehensive testing support
- **🐛 Bug Fixes**:
- Fixed server panel widget error with #server-list query during state changes
- Enhanced error handling for widget lifecycle management
- Improved stderr output suppression for cleaner TUI display
### v0.3.0 - FastMCP Integration & Major Improvements
- **🔥 Major Architecture Overhaul**: Migrated to FastMCP for robust, high-performance MCP protocol handling
- **✨ Enhanced Transport Support**: Added HTTP+SSE transport alongside improved STDIO transport
- **🧹 Tab Auto-clearing**: Automatically clears all tabs when disconnecting from servers for clean state management
- **🔧 Improved Error Handling**: Enhanced connection error reporting and recovery with FastMCP integration
- **📋 Real-time Notifications**: Fixed and enhanced MCP server notifications with FastMCP's MessageHandler system
- **🎯 Configuration Cleanup**: Removed problematic TCP server examples from default setup
- **📚 Comprehensive Documentation**: Updated all documentation and architecture diagrams to reflect FastMCP integration
- **🐛 Bug Fixes**:
- Fixed resource reading errors with FastMCP's object-based responses
- Fixed prompt and tool execution compatibility issues
- Fixed app shutdown callback errors
- Resolved all type checking errors across transport implementations
- **⚡ Performance**: Connection reuse enabled by default for better performance
- **🔒 Stability**: Enhanced subprocess management and cleanup for STDIO transport
**🔄 Migration Note**: Existing users may have legacy server configurations. Use the [Clean Installation](#clean-installation) steps if you encounter connection issues with old TCP server examples.
### v0.2.0 - Previous Release
- Initial stable release with custom MCP implementation
- Basic STDIO and TCP transport support
- TUI interface with resource, tool, and prompt management
## Development
### Setup Development Environment
```shell
# Clone repository
git clone https://github.com/paulrobello/par-mcp-inspector-tui.git
cd par-mcp-inspector-tui
# Install dependencies
uv sync
# Run formatting, linting, and type checking
make checkall
# Run the application
uv run pmit tui
```
### Development Commands
```shell
# Format, lint, and type check
make checkall
# Individual tools
make format # Format with ruff
make lint # Lint with ruff
make typecheck # Type check with pyright
# Update dependencies
uv sync -U
# Build package
uv build
```
### Clean Installation
To start with a completely clean configuration (removes any problematic legacy servers):
```shell
# Remove existing configuration
rm ~/.config/par-mcp-inspector-tui/servers.yaml
# Launch app - will create new default configuration
pmit tui
```
## Architecture Overview
The application is built on a modern, layered architecture leveraging **FastMCP** as the core Model Context Protocol implementation. This provides robust transport handling, automatic serialization, and real-time notification support.
### Key Architectural Components
#### FastMCP Integration
- **StdioTransport**: Handles subprocess communication with automatic process lifecycle management
- **WSTransport**: Manages WebSocket connections for TCP-based MCP servers
- **NotificationBridge**: Custom bridge that adapts FastMCP's `MessageHandler` system to our notification architecture
- **Automatic Protocol Handling**: JSON-RPC 2.0 serialization, error handling, and capability negotiation
#### Transport Layer Architecture
- **STDIO Transport**: Uses FastMCP's `StdioTransport` with a `NotificationBridge` to convert FastMCP notifications to our `MCPNotification` format
- **TCP Transport**: Uses FastMCP's `WSTransport` with direct `MessageHandler` integration
- **Connection Management**: Robust connection handling with automatic cleanup and error recovery
#### Notification System
- **Real-time Notifications**: FastMCP's native notification support enables instant server-to-client communication
- **Protocol Bridge**: `NotificationBridge` class seamlessly converts FastMCP notifications to application-level events
- **Auto-refresh Logic**: List change notifications automatically refresh relevant UI views
- **Toast Control**: Per-server notification preferences with intelligent suppression
### Detailed Diagrams
For comprehensive architectural diagrams showing the FastMCP integration, component structure, protocol communication, and data flow, see the [Architecture Diagrams](docs/diagrams.md) document.
The diagrams include:
- **Application Flow Diagram** - CLI command routing and component interactions including download-resource command
- **TUI Component Architecture** - UI layout and widget organization
- **MCP Protocol Flow** - FastMCP-based communication sequence with notification bridge
- **Client Transport Architecture** - FastMCP transport implementations with notification bridge architecture
- **Server Notifications Architecture** - FastMCP notification system with protocol adaptation
- **Data Flow Through Layers** - Information flow across system layers
- **Form Validation Flow** - Real-time validation system for execute button control
- **Dynamic Form Architecture** - Form widget structure and validation relationships
- **File Type Detection Flow** - Magic number detection and MIME type handling for resource downloads
## Project Structure
```
src/par-mcp-inspector-tui/
├── __init__.py # Package metadata
├── __main__.py # CLI entry point
├── models/ # Data models
│ ├── base.py # MCP protocol base types
│ ├── server.py # Server configuration
│ ├── tool.py # Tool definitions
│ ├── resource.py # Resource definitions
│ └── prompt.py # Prompt definitions
├── client/ # FastMCP-based client implementations
│ ├── base.py # Abstract client interface
│ ├── stdio.py # STDIO transport client with FastMCP StdioTransport
│ └── tcp.py # TCP transport client with FastMCP WSTransport
├── services/ # Service layer
│ ├── mcp_service.py # MCP connection service
│ └── server_manager.py # Server configuration management
└── tui/ # Terminal UI components
├── app.py # Main TUI application
├── app.tcss # Textual CSS styling
└── widgets/ # Custom UI widgets
├── server_panel.py # Server list and connection
├── connection_status.py # Connection status display
├── resources_view.py # Resources browser
├── prompts_view.py # Prompts interface
├── tools_view.py # Tools interface
├── response_viewer.py # Response display
├── dynamic_form.py # Dynamic form builder with validation
└── notification_panel.py # Notifications
```
## Troubleshooting
### Common Issues
1. **Server won't connect**:
- Check the command/path for STDIO servers
- Verify host/port for TCP servers
- Use CLI debug commands for detailed connection testing
- Enable debug mode for detailed error messages
- FastMCP provides enhanced error reporting for connection issues
2. **No tools/resources showing**:
- Use `--verbose` flag to see server capabilities
- Check if server supports the requested endpoints (resources/tools/prompts)
- Verify server implements MCP protocol correctly
- Some servers may only implement partial MCP functionality
3. **Request timeouts**:
- Server may not support the requested endpoint
- Check server capabilities with `debug` command
- Verify server is responsive and not hanging
4. **Form validation errors**:
- Check parameter types and requirements
- Ensure all required fields are filled
- Review server documentation for parameter formats
5. **Resource download issues**:
- Use `debug` command to see available resource names with color-coded display
- Ensure resource name matches exactly (case-sensitive)
- Check if server is configured (temporary servers need to be added to configuration)
- Verify resource actually contains downloadable content
- Use `--verbose` flag with download command for detailed error information
### Debugging Tools
#### CLI Debugging
```shell
# Test any STDIO server without configuration (PyPI installation)
pmit connect <command> --verbose --debug
# Test any TCP server without configuration
pmit connect-tcp <host> <port> --verbose --debug
# Debug configured servers
pmit debug <server-id-or-name> --verbose --debug
# List all configured servers
pmit servers
# Download resources from configured servers
pmit download-resource <server-id> "<resource-name>" --verbose
# From source (prefix all commands with 'uv run')
uv run pmit connect <command> --verbose --debug
uv run pmit connect-tcp <host> <port> --verbose --debug
# etc...
```
#### TUI Debug Mode
```shell
# Enable debug logging in TUI (PyPI installation)
pmit tui --debug
# From source
uv run pmit tui --debug
```
#### Enhanced Debug Features
The debug commands provide enhanced resource display:
- **Color-coded output**: Green names, cyan URIs, yellow descriptions, magenta MIME types
- **Download instructions**: Ready-to-use `download-resource` commands for configured servers
- **Smart guidance**: Different messages for configured vs temporary servers
#### Capability Checking
The application automatically checks server capabilities to avoid timeouts:
- If a server reports `null` for resources/tools/prompts capabilities, those endpoints are skipped
- Use `--verbose` to see raw server capability information
- Servers with `{}` (empty object) capabilities will still be tested
## Contributing
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
### How to Contribute
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run `make checkall` to ensure code quality
5. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
Paul Robello - probello@gmail.com
## Related Projects
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [MCP Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations
- [Textual](https://textual.textualize.io/) - The TUI framework used by this application
Raw data
{
"_id": null,
"home_page": null,
"name": "par-mcp-inspector-tui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Paul Robello <probello@gmail.com>",
"keywords": "mcp, terminal, tui",
"author": null,
"author_email": "Paul Robello <probello@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2b/cb/09c8889109cd30ce10e2996acbe6966c6ae80f1d1ddb8ab9baf3de64300c/par_mcp_inspector_tui-0.4.0.tar.gz",
"platform": null,
"description": "# PAR MCP Inspector TUI\n\n[](https://python.org)\n\n\n\n\n\n\n\nA comprehensive Terminal User Interface (TUI) application for inspecting and interacting with Model Context Protocol (MCP) servers. This tool provides an intuitive interface to connect to MCP servers, explore their capabilities, and execute tools, prompts, and resources in real-time.\n\n[](https://buymeacoffee.com/probello3)\n\n## Screenshots\n\n\n\n*The MCP Inspector TUI showing a connected \"Everything\" server with available tools (echo, add, printEnv), tool parameter forms, and real-time interaction logs. The interface displays server management on the left, tabbed content areas in the center, and notifications on the right.*\n\n## Features\n\n- **Multiple Transport Support**: Connect to MCP servers via STDIO and HTTP+SSE\n- **MCP Roots Support**: Full implementation of MCP filesystem roots protocol with TUI and CLI management\n- **CLI Debugging Tools**: Connect to arbitrary servers and inspect interactions without configuration\n- **Resource Download CLI**: Download resources by name with automatic file type detection\n- **Real-time Introspection**: Discover tools, prompts, and resources from connected servers\n- **Dynamic Forms**: Automatically generated forms based on server-provided schemas with real-time validation\n- **Form Validation**: Smart execute button control - disabled until all required fields are filled\n- **Magic Number Detection**: Automatic file type detection using magic numbers for binary resources\n- **Syntax Highlighting**: Rich response formatting with support for JSON, Markdown, and code\n- **File Management**: Save and open resources with proper file extensions and MIME type handling\n- **Server Management**: Persistent configuration storage for multiple server connections\n- **Non-blocking Operations**: Async communication ensuring responsive UI\n- **Server Notifications**: Real-time notifications from MCP servers with auto-refresh capabilities\n- **Application Notifications**: Real-time status updates and error handling\n- **Tab Auto-clearing**: Automatically clears all tabs when disconnecting from servers\n- **Capability-aware**: Gracefully handles servers with partial MCP implementation\n\n## Technology Stack\n- **Python 3.11+** - Modern Python with latest features\n- **FastMCP** - High-performance Model Context Protocol implementation with robust transport layer\n- **Textual** - Beautiful, responsive terminal user interfaces\n- **Pydantic** - Data validation and serialization\n- **Rich** - Terminal output formatting and syntax highlighting\n- **filetype** - Magic number file type detection\n- **YAML** - Configuration file format\n- **Asyncio** - Asynchronous programming for responsive interfaces\n\n## Prerequisites\n\nTo install PAR MCP Inspector TUI, make sure you have Python 3.11+.\n\n### [uv](https://pypi.org/project/uv/) is recommended\n\n#### Linux and Mac\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n#### Windows\n```bash\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\n## Installation\n\n### Installation from PyPI (Recommended)\n\nInstall the latest stable version using uv:\n\n```bash\nuv tool install par-mcp-inspector-tui\n```\n\nOr using pip:\n\n```bash\npip install par-mcp-inspector-tui\n```\n\nAfter installation, you can run the tool directly:\n\n```bash\n# Launch the TUI application\npmit tui\n\n# Show all available commands\npmit --help\n```\n\n### Installation From Source\n\nFor development or to get the latest features:\n\n1. Clone the repository:\n ```bash\n git clone https://github.com/paulrobello/par-mcp-inspector-tui.git\n cd par-mcp-inspector-tui\n ```\n\n2. Install the package dependencies using uv:\n ```bash\n uv sync\n ```\n\n3. Run using uv:\n ```bash\n uv run pmit tui\n ```\n\n## Usage\n\n### CLI Commands Overview\n\nIf installed from PyPI:\n```shell\n# Show all available commands\npmit --help\n\n# Show version information\npmit --version\n\n# Launch the TUI application\npmit tui\n\n# Launch TUI with debug mode\npmit tui --debug\n\n# List configured servers\npmit servers\n\n# Debug a configured server\npmit debug <server-id> --verbose\n\n# Connect to arbitrary STDIO server\npmit connect npx --arg \"-y\" --arg \"@modelcontextprotocol/server-filesystem\" --arg \"/tmp\"\n\n# Connect to arbitrary TCP server\npmit connect-tcp localhost 3333\n\n# Download resources from servers\npmit download-resource <server-id> <resource-name>\n\n# Manage filesystem roots for servers\npmit roots-list [server-id]\npmit roots-add <server-id> <path>\npmit roots-remove <server-id> <path>\n```\n\nIf running from source:\n```shell\n# Show all available commands\nuv run pmit --help\n\n# Show version information\nuv run pmit --version\n\n# Launch the TUI application\nuv run pmit tui\n\n# Launch TUI with debug mode\nuv run pmit tui --debug\n\n# List configured servers\nuv run pmit servers\n\n# Debug a configured server\nuv run pmit debug <server-id> --verbose\n\n# Connect to arbitrary STDIO server\nuv run pmit connect npx --arg \"-y\" --arg \"@modelcontextprotocol/server-filesystem\" --arg \"/tmp\"\n\n# Connect to arbitrary TCP server\nuv run pmit connect-tcp localhost 3333\n\n# Download resources from servers\nuv run pmit download-resource <server-id> <resource-name>\n\n# Manage filesystem roots for servers\nuv run pmit roots-list [server-id]\nuv run pmit roots-add <server-id> <path>\nuv run pmit roots-remove <server-id> <path>\n```\n\n### TUI Application\n\n```shell\n# Start the MCP Inspector TUI (if installed from PyPI)\npmit tui\n\n# Enable debug mode for troubleshooting\npmit tui --debug\n\n# If running from source\nuv run pmit tui\nuv run pmit tui --debug\n```\n\n**Options:**\n- `--debug -d`: Enable debug mode for detailed logging and troubleshooting\n\n### First Time Setup\n\n1. **Launch the application**: `pmit tui` (or `uv run pmit tui` if running from source)\n2. **Default servers**: The application comes with working example server configurations:\n - **Example STDIO Server**: Filesystem server for `/tmp` directory\n - **Everything**: Comprehensive test server with tools, resources, and notifications\n3. **Add your servers**: Use the \"Add Server\" button to configure your MCP servers\n4. **Connect**: Select a server from the list and click \"Connect\"\n5. **Explore**: Browse resources, prompts, and tools in the tabbed interface\n\n### Quick Testing without Configuration\n\nTest any MCP server instantly without adding it to configuration:\n\n```shell\n# Test a filesystem server\nuv run pmit connect npx \\\n --arg \"-y\" \\\n --arg \"@modelcontextprotocol/server-filesystem\" \\\n --arg \"/tmp\" \\\n --name \"My Test Server\" \\\n --verbose\n\n# Test with environment variables\nuv run pmit connect python \\\n --arg \"my_server.py\" \\\n --env \"DEBUG=1\" \\\n --env \"DATABASE_URL=sqlite:///test.db\"\n\n# Test TCP server\nuv run pmit connect-tcp myhost.com 8080 --verbose\n```\n\n## CLI Commands Reference\n\n### Global Options\n- `--version -v`: Show version and exit\n- `--help`: Show help message and exit\n\n### `tui` - Launch TUI Application\n```shell\n# If installed from PyPI\npmit tui [OPTIONS]\n\n# If running from source\nuv run pmit tui [OPTIONS]\n```\n\n**Options:**\n- `--debug -d`: Enable debug mode for detailed logging and troubleshooting\n\n### `servers` - List Configured Servers\n```shell\n# If installed from PyPI\npmit servers\n\n# If running from source\nuv run pmit servers\n```\nShows a formatted table of all configured MCP servers with their connection details and status.\n\n### `debug` - Debug Configured Server\n```shell\n# If installed from PyPI\npmit debug <server-id-or-name> [OPTIONS]\n\n# If running from source\nuv run pmit debug <server-id-or-name> [OPTIONS]\n```\n\n**Arguments:**\n- `server-id-or-name`: Server ID or name to debug (required)\n\n**Options:**\n- `--verbose -v`: Verbose output with raw JSON\n- `--debug`: Enable debug logging of MCP messages\n\nConnect to a pre-configured server and test all MCP endpoints:\n- Shows server information and capabilities\n- Tests resources, tools, and prompts endpoints with enhanced display\n- **Enhanced Resource Display**: Color-coded labels and ready-to-use download commands\n- Displays detailed error information\n- Use `--verbose` for raw JSON responses\n- Use `--debug` for detailed MCP message logging\n\n**Enhanced Resource Display Features:**\n- **Resource Names**: Clearly highlighted for use with `download-resource` command\n- **Download Instructions**: Exact command syntax for configured servers\n- **Color-Coded Output**: Green names, cyan URIs, yellow descriptions, magenta MIME types\n- **Smart Guidance**: Different messages for configured vs temporary servers\n\n### `connect` - Connect to Arbitrary STDIO Server\n```shell\n# If installed from PyPI\npmit connect <command> [OPTIONS]\n\n# If running from source\nuv run pmit connect <command> [OPTIONS]\n```\n\n**Arguments:**\n- `command`: Command to execute for STDIO transport (required)\n\n**Options:**\n- `--arg -a`: Command arguments (can be specified multiple times)\n- `--env -e`: Environment variables in KEY=VALUE format (can be specified multiple times)\n- `--verbose -v`: Verbose output with raw JSON\n- `--debug`: Enable debug logging of MCP messages\n- `--name -n`: Server name for display (default: Ad-hoc Server)\n\nConnect to an arbitrary STDIO server without adding it to configuration. Uses the same enhanced debug output as the `debug` command, including:\n- **Color-coded resource display** with download guidance\n- **Smart messaging**: Informs users to add server to configuration before downloading resources\n- **Full MCP testing**: Resources, tools, and prompts endpoints\n\n**Examples:**\n```shell\n# Basic usage (PyPI installation)\npmit connect npx -a \"-y\" -a \"@modelcontextprotocol/server-filesystem\" -a \"/tmp\"\n\n# With environment variables and custom name\npmit connect python -a \"server.py\" -e \"DEBUG=1\" -e \"PORT=8080\" -n \"My Server\"\n\n# Verbose output with debug logging\npmit connect node -a \"server.js\" --verbose --debug\n\n# From source\nuv run pmit connect npx -a \"-y\" -a \"@modelcontextprotocol/server-filesystem\" -a \"/tmp\"\n```\n\n### `connect-tcp` - Connect to Arbitrary TCP Server\n```shell\n# If installed from PyPI\npmit connect-tcp [HOST] [PORT] [OPTIONS]\n\n# If running from source\nuv run pmit connect-tcp [HOST] [PORT] [OPTIONS]\n```\n\n**Arguments:**\n- `host`: Host to connect to (default: localhost)\n- `port`: Port to connect to (default: 3333)\n\n**Options:**\n- `--verbose -v`: Verbose output with raw JSON\n- `--debug`: Enable debug logging of MCP messages\n- `--name -n`: Server name for display (default: TCP Server)\n\nConnect to an arbitrary TCP server without adding it to configuration. Uses the same enhanced debug output as other debug commands, including:\n- **Enhanced resource listing** with color-coded display\n- **Download guidance**: Instructions to add server to configuration first\n- **Complete testing**: All MCP endpoints (resources, tools, prompts)\n\n**Examples:**\n```shell\n# Default host and port (PyPI installation)\npmit connect-tcp\n\n# Custom host and port with verbose and debug output\npmit connect-tcp example.com 8080 -n \"Remote Server\" --verbose --debug\n\n# From source\nuv run pmit connect-tcp\nuv run pmit connect-tcp example.com 8080 -n \"Remote Server\" --verbose --debug\n```\n\n### `download-resource` - Download Resources by Name\n```shell\n# If installed from PyPI\npmit download-resource <server-id-or-name> <resource-name> [OPTIONS]\n\n# If running from source\nuv run pmit download-resource <server-id-or-name> <resource-name> [OPTIONS]\n```\n\n**Arguments:**\n- `server-id-or-name`: Server ID or name to download from (required)\n- `resource-name`: Resource name to download (required)\n\n**Options:**\n- `--output -o`: Output directory (default: current directory)\n- `--filename -f`: Custom filename (default: auto-detect from resource)\n- `--verbose -v`: Verbose output with detailed information\n- `--debug`: Enable debug logging of MCP messages\n\n**Features:**\n- **Smart Resource Finding**: Exact name match, case-insensitive fallback, and partial matching\n- **Automatic File Type Detection**: Uses MIME types and magic number detection for proper extensions\n- **Custom Output**: Specify output directory and custom filenames\n- **Error Handling**: Clear error messages for missing servers/resources\n\n**Examples:**\n```shell\n# Download resource with auto-detection (PyPI installation)\npmit download-resource Everything \"Resource 1\"\n\n# Custom output directory\npmit download-resource filesystem-server \"config.json\" --output ~/Downloads\n\n# Custom filename with verbose output\npmit download-resource Everything \"Resource 2\" --filename my-file.txt --verbose\n\n# Download binary resource (automatic type detection)\npmit download-resource image-server \"logo.png\" --output ./assets\n\n# From source\nuv run pmit download-resource Everything \"Resource 1\"\n```\n\n### `roots-list` - List Filesystem Roots\n```shell\n# If installed from PyPI\npmit roots-list [SERVER_ID] [OPTIONS]\n\n# If running from source\nuv run pmit roots-list [SERVER_ID] [OPTIONS]\n```\n\n**Arguments:**\n- `server-id`: Server ID (optional - uses current connected server if not specified)\n\n**Options:**\n- `--verbose -v`: Show detailed root information including path validation and type\n\n**Features:**\n- **Automatic Server Detection**: If no server ID provided, uses the currently connected server\n- **Path Validation**: Shows \u2713 for existing paths, \u2717 for missing paths\n- **Type Detection**: Displays whether paths are directories or files (with `--verbose`)\n- **URI Support**: Handles both local paths and `file://` URIs\n- **Clear Display**: Numbered list with status indicators\n\n**Examples:**\n```shell\n# List roots for connected server (PyPI installation)\npmit roots-list\n\n# List roots for specific server with details\npmit roots-list my-server-id --verbose\n\n# From source\nuv run pmit roots-list\nuv run pmit roots-list my-server-id --verbose\n```\n\n### `roots-add` - Add Filesystem Root\n```shell\n# If installed from PyPI\npmit roots-add <server-id> <path> [OPTIONS]\n\n# If running from source\nuv run pmit roots-add <server-id> <path> [OPTIONS]\n```\n\n**Arguments:**\n- `server-id`: Server ID (required)\n- `path`: Filesystem path or `file://` URI to add as root (required)\n\n**Options:**\n- `--name -n`: Display name for the root (used in TUI interface)\n\n**Features:**\n- **Automatic URI Conversion**: Converts local paths to proper `file://` URIs\n- **Duplicate Prevention**: Prevents adding the same root path multiple times\n- **Path Resolution**: Automatically resolves relative paths to absolute paths\n- **Persistent Storage**: Saves roots to server configuration immediately\n- **Display Name Support**: Optional display names for better TUI presentation\n\n**Examples:**\n```shell\n# Add current directory as root (PyPI installation)\npmit roots-add my-server-id . --name \"Project Root\"\n\n# Add absolute path\npmit roots-add my-server-id /home/user/documents\n\n# Add with file:// URI\npmit roots-add my-server-id file:///tmp/workspace --name \"Workspace\"\n\n# From source\nuv run pmit roots-add my-server-id . --name \"Project Root\"\nuv run pmit roots-add my-server-id /home/user/documents\n```\n\n### `roots-remove` - Remove Filesystem Root\n```shell\n# If installed from PyPI\npmit roots-remove <server-id> <path>\n\n# If running from source\nuv run pmit roots-remove <server-id> <path>\n```\n\n**Arguments:**\n- `server-id`: Server ID (required)\n- `path`: Filesystem path or `file://` URI to remove (required)\n\n**Features:**\n- **Flexible Path Matching**: Accepts both local paths and `file://` URIs\n- **Automatic URI Conversion**: Converts local paths to URIs for matching\n- **Path Resolution**: Resolves relative paths to match stored absolute paths\n- **Not Found Handling**: Shows available roots if specified path not found\n- **Immediate Persistence**: Updates server configuration immediately\n\n**Examples:**\n```shell\n# Remove by local path (PyPI installation)\npmit roots-remove my-server-id /tmp/workspace\n\n# Remove by file:// URI\npmit roots-remove my-server-id file:///home/user/documents\n\n# Remove relative path (resolved automatically)\npmit roots-remove my-server-id ../parent-dir\n\n# From source\nuv run pmit roots-remove my-server-id /tmp/workspace\nuv run pmit roots-remove my-server-id file:///home/user/documents\n```\n\n## Server Configuration\n\nThe TUI application stores server configurations in `~/.config/mcp-inspector/servers.yaml`. Example configuration:\n\n```yaml\nservers:\n filesystem-server:\n name: \"Filesystem Server\"\n transport: \"stdio\"\n command: \"npx\"\n args:\n - \"-y\"\n - \"@modelcontextprotocol/server-filesystem\"\n - \"/tmp\"\n env:\n NODE_ENV: \"production\"\n toast_notifications: true # Show toast notifications (default: true)\n roots: # MCP filesystem roots (optional)\n - \"file:///tmp\"\n - \"file:///home/user/documents\"\n - \"file:///var/log\"\n\n http-mcp-server:\n name: \"HTTP MCP Server\"\n transport: \"http\"\n url: \"https://api.example.com/mcp\"\n toast_notifications: true # Show toast notifications for this server\n roots: # Roots can be specified for any transport type\n - \"file:///workspace/project\"\n - \"file:///shared/resources\"\n```\n\n#### Configuration Options\n\n- **toast_notifications** (boolean, default: true): Controls whether to show toast popup notifications when the server sends notifications. When `false`, notifications are still added to the notifications tab but won't show as toast popups. Note: Toasts are automatically suppressed when viewing the notifications tab regardless of this setting.\n\n- **roots** (array of strings, optional): List of filesystem roots that define the boundaries of filesystem access for MCP servers. Each root should be a `file://` URI pointing to a directory or file. These roots are sent to the server during connection to establish filesystem boundaries according to the MCP roots protocol. Roots can be managed through the TUI interface (Roots tab) or via CLI commands (`roots-add`, `roots-remove`, `roots-list`).\n\n#### UI Configuration\n\nYou can configure toast notifications through the TUI interface:\n\n1. **Add Server Dialog**: When adding a new server, check/uncheck \"Show toast notifications from this server\"\n2. **Edit Server Dialog**: Select any server and click \"Edit Server\" to modify the toast notification setting\n3. **Per-Server Control**: Each server has different notification settings\n4. **Real-time Updates**: Changes take effect immediately after saving\n\n### Supported Transport Types\n\n#### STDIO Transport (Recommended)\nFor servers that communicate via standard input/output (most common):\n```yaml\nservers:\n my-stdio-server:\n name: \"My STDIO Server\"\n transport: \"stdio\"\n command: \"python\"\n args:\n - \"server.py\"\n env:\n DEBUG: \"1\"\n```\n\n#### HTTP Transport\nFor HTTP-based MCP servers with SSE (Server-Sent Events) support:\n```yaml\nservers:\n my-http-server:\n name: \"My HTTP MCP Server\"\n transport: \"http\"\n url: \"https://api.example.com/mcp\"\n```\n\n#### TCP Transport (Legacy HTTP+SSE)\nFor backward compatibility with HTTP-based MCP servers:\n```yaml\nservers:\n my-tcp-server:\n name: \"My TCP Server\"\n transport: \"tcp\"\n host: \"localhost\"\n port: 8080\n```\n\n**Important Notes**:\n- **STDIO transport** is recommended for most MCP servers (filesystem, everything, etc.)\n- **HTTP transport** is for servers with full HTTP URLs\n- **TCP transport** actually uses HTTP+SSE protocol, not raw TCP sockets\n- Use HTTP/TCP transports only for servers that explicitly support HTTP+SSE protocol\n\n## User Interface\n\n### Main Layout\n- **Left Panel**: Server list and connection status\n- **Center Panel**: Tabbed interface with:\n - **Resources**: Browse and read available resources\n - **Prompts**: Execute prompts with dynamic argument forms and validation\n - **Tools**: Call tools with smart parameter validation and form controls\n - **Roots**: Manage filesystem roots for MCP server access boundaries\n - **Notifications**: Real-time server notifications with auto-refresh capabilities\n- **Right Panel**: Response viewer with formatted output and syntax highlighting\n\n### Form Validation Features\n- **Required Field Indicators**: Red asterisks (*) mark required parameters\n- **Smart Execute Button**: Automatically disabled when required fields are empty\n- **Real-time Validation**: Button state updates as you type in form fields\n- **Array Field Support**: Add/remove dynamic list items with validation\n- **Multiple Field Types**: Text, number, checkbox, select, and array inputs\n\n### Server Notifications Features\n- **Real-time Updates**: Receive notifications from MCP servers as they happen\n- **Auto-refresh**: Automatically refresh tools, resources, and prompts when server lists change\n- **Server Context**: Each notification shows which server sent it\n- **Message Types**: Supports different notification types:\n - `notifications/tools/list_changed` - Tools list has changed\n - `notifications/resources/list_changed` - Resources list has changed \n - `notifications/prompts/list_changed` - Prompts list has changed\n - `notifications/message` - General server messages with level indicators\n- **Visual Distinction**: Server notifications have unique styling and icons (\ud83d\udd14)\n- **Chronological Order**: Newest notifications appear at the top\n- **Notification History**: View complete history of server communications\n- **Toast Control**: Per-server configuration for toast popup notifications\n - Enable/disable through Add/Edit Server dialogs\n - Automatic suppression when viewing notifications tab\n - Real-time configuration updates without restart\n\n### Filesystem Roots Management\n\nThe **Roots** tab provides comprehensive management of filesystem boundaries for MCP servers:\n\n**Root Management Features:**\n- **Add New Roots**: Click \"Add Root\" to add filesystem paths or `file://` URIs\n- **Remove Roots**: Select roots and click \"Remove Root\" to delete them\n- **Path Validation**: Real-time status indicators show if root paths exist (\u2713/\u2717)\n- **Type Display**: Shows whether roots are directories, files, or URIs\n- **Server Integration**: Roots are automatically sent to servers during connection\n- **Persistent Storage**: Root configurations are saved with server settings\n\n**Root Display Format:**\n- **Status Indicator**: \u2713 (exists), \u2717 (missing), or ? (unknown)\n- **Path Information**: Shows the full `file://` URI or local path\n- **Type Information**: (directory), (file), or (URI) designations\n- **Organized List**: Clean, numbered display of all configured roots\n\n**MCP Protocol Integration:**\n- **Automatic Transmission**: Roots are sent to servers during connection establishment\n- **Protocol Compliance**: Implements MCP `roots/list` protocol specification\n- **Boundary Enforcement**: Servers use roots to restrict filesystem access\n- **Notification Support**: Responds to `notifications/roots/list_changed` from servers\n\n### Server Management\n\n#### Add/Edit Server Dialog\n\nThe server configuration dialog provides comprehensive settings for MCP servers:\n\n**Basic Configuration:**\n- **Server Name**: Descriptive name for identification\n- **Transport Type**: Choose between STDIO or TCP communication\n\n**STDIO Transport Settings:**\n- **Command**: Executable command (e.g., `python`, `npx`, `node`)\n- **Arguments**: Command-line arguments (one per line)\n- **Environment Variables**: KEY=value pairs (one per line)\n\n**HTTP Transport Settings:**\n- **URL**: Complete HTTP/HTTPS URL to the MCP server endpoint\n\n**TCP Transport Settings (Legacy):**\n- **Host**: Server hostname or IP address \n- **Port**: Network port number (1-65535)\n\n**Notification Settings:**\n- **Toast Notifications Checkbox**: Control popup notifications for this server\n - \u2705 **Checked (default)**: Display toast popups + notifications tab\n - \u274c **Unchecked**: Notifications tab only (quiet mode)\n - \ud83c\udfaf **Smart Behavior**: Toasts auto-suppressed when viewing notifications tab\n\n**Dialog Features:**\n- Real-time form validation with helpful error messages\n- Dynamic sections based on transport type selection\n- Persistent settings with immediate effect after save\n- Maintains UI selection state after edits\n\n### Keyboard Shortcuts\n- `q` - Quit application\n- `d` - Toggle dark/light mode\n- `s` - Focus server panel\n- `r` - Refresh server data\n- `Ctrl+O` - Open last saved resource file (when viewing resources)\n\n## Testing with MCP Servers\n\n### Example Servers for Testing\n\nTest these official MCP servers using the CLI commands:\n\n1. **Filesystem Server**:\n ```shell\n # Using CLI connect (PyPI installation)\n pmit connect npx \\\n -a \"-y\" -a \"@modelcontextprotocol/server-filesystem\" -a \"/tmp\" \\\n --verbose\n\n # From source\n uv run pmit connect npx \\\n -a \"-y\" -a \"@modelcontextprotocol/server-filesystem\" -a \"/tmp\" \\\n --verbose\n\n # Direct command for reference\n npx -y @modelcontextprotocol/server-filesystem /tmp\n ```\n\n2. **SQLite Server**:\n ```shell\n # Using CLI connect (PyPI installation)\n pmit connect npx \\\n -a \"-y\" -a \"@modelcontextprotocol/server-sqlite\" \\\n -a \"--db-path\" -a \"test.db\" \\\n --verbose\n\n # From source\n uv run pmit connect npx \\\n -a \"-y\" -a \"@modelcontextprotocol/server-sqlite\" \\\n -a \"--db-path\" -a \"test.db\" \\\n --verbose\n\n # Direct command for reference\n npx -y @modelcontextprotocol/server-sqlite --db-path test.db\n ```\n\n3. **Custom Python Server**:\n ```shell\n # Test your custom server (PyPI installation)\n pmit connect python \\\n -a \"my_mcp_server.py\" \\\n -e \"DATABASE_URL=sqlite:///data.db\" \\\n -n \"My Custom Server\" \\\n --verbose\n\n # From source\n uv run pmit connect python \\\n -a \"my_mcp_server.py\" \\\n -e \"DATABASE_URL=sqlite:///data.db\" \\\n -n \"My Custom Server\" \\\n --verbose\n ```\n\n4. **GitHub MCP Server**:\n ```shell\n # Test GitHub integration server (PyPI installation)\n pmit connect npx \\\n -a \"-y\" -a \"@modelcontextprotocol/server-github\" \\\n -e \"GITHUB_PERSONAL_ACCESS_TOKEN=your_token\" \\\n --verbose\n\n # From source\n uv run pmit connect npx \\\n -a \"-y\" -a \"@modelcontextprotocol/server-github\" \\\n -e \"GITHUB_PERSONAL_ACCESS_TOKEN=your_token\" \\\n --verbose\n ```\n\n5. **Everything Server (for testing notifications)**:\n ```shell\n # Test server that sends regular notifications (PyPI installation)\n pmit connect npx \\\n -a \"-y\" -a \"@modelcontextprotocol/server-everything\" \\\n --verbose\n\n # From source\n uv run pmit connect npx \\\n -a \"-y\" -a \"@modelcontextprotocol/server-everything\" \\\n --verbose\n ```\n This server sends `notifications/message` every 20 seconds, perfect for testing the notification system.\n\n### Server Capability Testing\n\nThe CLI commands automatically test server capabilities with enhanced display formatting:\n\n#### Enhanced Resource Display\n- **Color-Coded Labels**: Green names, cyan URIs, yellow descriptions, magenta MIME types\n- **Download Ready**: Shows exact `download-resource` commands for configured servers\n- **Smart Guidance**: Different messages for configured vs temporary servers\n\nExample output for configured servers:\n```\nTesting Resources:\nFound 3 resources:\nUse 'download-resource my-server-id \"<resource-name>\"' to download any resource\n\n 1. Name: config.json\n URI: file:///path/to/config.json\n Description: Application configuration file\n MIME Type: application/json\n\n 2. Name: logo.png\n URI: file:///path/to/logo.png\n MIME Type: image/png\n```\n\n#### Standard Testing Features\n- **Server Info**: Name, version, protocol version\n- **Tools**: Available tools with parameter schemas \n- **Prompts**: Available prompts with argument definitions\n- **Error Handling**: Timeouts and capability-based filtering\n\nUse `--verbose` flag to see raw JSON responses and detailed debugging information.\n\n## Changelog\n\n### v0.4.0 - MCP Roots Protocol & Enhanced Filesystem Support\n- **\ud83c\udf3f MCP Roots Protocol Implementation**: Full support for MCP filesystem roots protocol\n- **\ud83d\udcc1 Comprehensive Roots Management**: Complete TUI and CLI interface for managing filesystem boundaries\n- **\ud83c\udf9b\ufe0f Roots Tab in TUI**: Dedicated interface for visual root management with real-time validation\n- **\u26a1 CLI Root Commands**: Three new commands for root management:\n - `pmit roots-list [server-id] [--verbose]` - List and validate filesystem roots\n - `pmit roots-add <server-id> <path> [--name]` - Add roots with display names\n - `pmit roots-remove <server-id> <path>` - Remove roots with flexible path matching\n- **\ud83d\udd12 Automatic Root Transmission**: Roots are automatically sent to servers during connection\n- **\u2705 Path Validation**: Real-time validation with status indicators (\u2713/\u2717) for root paths\n- **\ud83d\udd04 Protocol Compliance**: Implements `roots/list` and `notifications/roots/list_changed` protocols\n- **\ud83d\udcca Enhanced Server Configuration**: Persistent root storage in server configurations\n- **\ud83d\udee0\ufe0f Developer Features**: URI conversion, path resolution, and comprehensive testing support\n- **\ud83d\udc1b Bug Fixes**:\n - Fixed server panel widget error with #server-list query during state changes\n - Enhanced error handling for widget lifecycle management\n - Improved stderr output suppression for cleaner TUI display\n\n### v0.3.0 - FastMCP Integration & Major Improvements\n- **\ud83d\udd25 Major Architecture Overhaul**: Migrated to FastMCP for robust, high-performance MCP protocol handling\n- **\u2728 Enhanced Transport Support**: Added HTTP+SSE transport alongside improved STDIO transport \n- **\ud83e\uddf9 Tab Auto-clearing**: Automatically clears all tabs when disconnecting from servers for clean state management\n- **\ud83d\udd27 Improved Error Handling**: Enhanced connection error reporting and recovery with FastMCP integration\n- **\ud83d\udccb Real-time Notifications**: Fixed and enhanced MCP server notifications with FastMCP's MessageHandler system\n- **\ud83c\udfaf Configuration Cleanup**: Removed problematic TCP server examples from default setup\n- **\ud83d\udcda Comprehensive Documentation**: Updated all documentation and architecture diagrams to reflect FastMCP integration\n- **\ud83d\udc1b Bug Fixes**:\n - Fixed resource reading errors with FastMCP's object-based responses\n - Fixed prompt and tool execution compatibility issues\n - Fixed app shutdown callback errors\n - Resolved all type checking errors across transport implementations\n- **\u26a1 Performance**: Connection reuse enabled by default for better performance\n- **\ud83d\udd12 Stability**: Enhanced subprocess management and cleanup for STDIO transport\n\n**\ud83d\udd04 Migration Note**: Existing users may have legacy server configurations. Use the [Clean Installation](#clean-installation) steps if you encounter connection issues with old TCP server examples.\n\n### v0.2.0 - Previous Release\n- Initial stable release with custom MCP implementation\n- Basic STDIO and TCP transport support\n- TUI interface with resource, tool, and prompt management\n\n## Development\n\n### Setup Development Environment\n\n```shell\n# Clone repository\ngit clone https://github.com/paulrobello/par-mcp-inspector-tui.git\ncd par-mcp-inspector-tui\n\n# Install dependencies\nuv sync\n\n# Run formatting, linting, and type checking\nmake checkall\n\n# Run the application\nuv run pmit tui\n```\n\n### Development Commands\n\n```shell\n# Format, lint, and type check\nmake checkall\n\n# Individual tools\nmake format # Format with ruff\nmake lint # Lint with ruff\nmake typecheck # Type check with pyright\n\n# Update dependencies\nuv sync -U\n\n# Build package\nuv build\n```\n\n### Clean Installation\n\nTo start with a completely clean configuration (removes any problematic legacy servers):\n\n```shell\n# Remove existing configuration\nrm ~/.config/par-mcp-inspector-tui/servers.yaml\n\n# Launch app - will create new default configuration\npmit tui\n```\n\n## Architecture Overview\n\nThe application is built on a modern, layered architecture leveraging **FastMCP** as the core Model Context Protocol implementation. This provides robust transport handling, automatic serialization, and real-time notification support.\n\n### Key Architectural Components\n\n#### FastMCP Integration\n- **StdioTransport**: Handles subprocess communication with automatic process lifecycle management\n- **WSTransport**: Manages WebSocket connections for TCP-based MCP servers \n- **NotificationBridge**: Custom bridge that adapts FastMCP's `MessageHandler` system to our notification architecture\n- **Automatic Protocol Handling**: JSON-RPC 2.0 serialization, error handling, and capability negotiation\n\n#### Transport Layer Architecture\n- **STDIO Transport**: Uses FastMCP's `StdioTransport` with a `NotificationBridge` to convert FastMCP notifications to our `MCPNotification` format\n- **TCP Transport**: Uses FastMCP's `WSTransport` with direct `MessageHandler` integration\n- **Connection Management**: Robust connection handling with automatic cleanup and error recovery\n\n#### Notification System\n- **Real-time Notifications**: FastMCP's native notification support enables instant server-to-client communication\n- **Protocol Bridge**: `NotificationBridge` class seamlessly converts FastMCP notifications to application-level events\n- **Auto-refresh Logic**: List change notifications automatically refresh relevant UI views\n- **Toast Control**: Per-server notification preferences with intelligent suppression\n\n### Detailed Diagrams\n\nFor comprehensive architectural diagrams showing the FastMCP integration, component structure, protocol communication, and data flow, see the [Architecture Diagrams](docs/diagrams.md) document.\n\nThe diagrams include:\n- **Application Flow Diagram** - CLI command routing and component interactions including download-resource command\n- **TUI Component Architecture** - UI layout and widget organization \n- **MCP Protocol Flow** - FastMCP-based communication sequence with notification bridge\n- **Client Transport Architecture** - FastMCP transport implementations with notification bridge architecture\n- **Server Notifications Architecture** - FastMCP notification system with protocol adaptation\n- **Data Flow Through Layers** - Information flow across system layers\n- **Form Validation Flow** - Real-time validation system for execute button control\n- **Dynamic Form Architecture** - Form widget structure and validation relationships\n- **File Type Detection Flow** - Magic number detection and MIME type handling for resource downloads\n\n## Project Structure\n\n```\nsrc/par-mcp-inspector-tui/\n\u251c\u2500\u2500 __init__.py # Package metadata\n\u251c\u2500\u2500 __main__.py # CLI entry point\n\u251c\u2500\u2500 models/ # Data models\n\u2502 \u251c\u2500\u2500 base.py # MCP protocol base types\n\u2502 \u251c\u2500\u2500 server.py # Server configuration\n\u2502 \u251c\u2500\u2500 tool.py # Tool definitions\n\u2502 \u251c\u2500\u2500 resource.py # Resource definitions\n\u2502 \u2514\u2500\u2500 prompt.py # Prompt definitions\n\u251c\u2500\u2500 client/ # FastMCP-based client implementations\n\u2502 \u251c\u2500\u2500 base.py # Abstract client interface\n\u2502 \u251c\u2500\u2500 stdio.py # STDIO transport client with FastMCP StdioTransport\n\u2502 \u2514\u2500\u2500 tcp.py # TCP transport client with FastMCP WSTransport\n\u251c\u2500\u2500 services/ # Service layer\n\u2502 \u251c\u2500\u2500 mcp_service.py # MCP connection service\n\u2502 \u2514\u2500\u2500 server_manager.py # Server configuration management\n\u2514\u2500\u2500 tui/ # Terminal UI components\n \u251c\u2500\u2500 app.py # Main TUI application\n \u251c\u2500\u2500 app.tcss # Textual CSS styling\n \u2514\u2500\u2500 widgets/ # Custom UI widgets\n \u251c\u2500\u2500 server_panel.py # Server list and connection\n \u251c\u2500\u2500 connection_status.py # Connection status display\n \u251c\u2500\u2500 resources_view.py # Resources browser\n \u251c\u2500\u2500 prompts_view.py # Prompts interface\n \u251c\u2500\u2500 tools_view.py # Tools interface\n \u251c\u2500\u2500 response_viewer.py # Response display\n \u251c\u2500\u2500 dynamic_form.py # Dynamic form builder with validation\n \u2514\u2500\u2500 notification_panel.py # Notifications\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Server won't connect**:\n - Check the command/path for STDIO servers\n - Verify host/port for TCP servers\n - Use CLI debug commands for detailed connection testing\n - Enable debug mode for detailed error messages\n - FastMCP provides enhanced error reporting for connection issues\n\n2. **No tools/resources showing**:\n - Use `--verbose` flag to see server capabilities\n - Check if server supports the requested endpoints (resources/tools/prompts)\n - Verify server implements MCP protocol correctly\n - Some servers may only implement partial MCP functionality\n\n3. **Request timeouts**:\n - Server may not support the requested endpoint\n - Check server capabilities with `debug` command\n - Verify server is responsive and not hanging\n\n4. **Form validation errors**:\n - Check parameter types and requirements\n - Ensure all required fields are filled\n - Review server documentation for parameter formats\n\n5. **Resource download issues**:\n - Use `debug` command to see available resource names with color-coded display\n - Ensure resource name matches exactly (case-sensitive)\n - Check if server is configured (temporary servers need to be added to configuration)\n - Verify resource actually contains downloadable content\n - Use `--verbose` flag with download command for detailed error information\n\n### Debugging Tools\n\n#### CLI Debugging\n```shell\n# Test any STDIO server without configuration (PyPI installation)\npmit connect <command> --verbose --debug\n\n# Test any TCP server without configuration \npmit connect-tcp <host> <port> --verbose --debug\n\n# Debug configured servers\npmit debug <server-id-or-name> --verbose --debug\n\n# List all configured servers\npmit servers\n\n# Download resources from configured servers\npmit download-resource <server-id> \"<resource-name>\" --verbose\n\n# From source (prefix all commands with 'uv run')\nuv run pmit connect <command> --verbose --debug\nuv run pmit connect-tcp <host> <port> --verbose --debug\n# etc...\n```\n\n#### TUI Debug Mode\n```shell\n# Enable debug logging in TUI (PyPI installation)\npmit tui --debug\n\n# From source\nuv run pmit tui --debug\n```\n\n#### Enhanced Debug Features\nThe debug commands provide enhanced resource display:\n- **Color-coded output**: Green names, cyan URIs, yellow descriptions, magenta MIME types\n- **Download instructions**: Ready-to-use `download-resource` commands for configured servers\n- **Smart guidance**: Different messages for configured vs temporary servers\n\n#### Capability Checking \nThe application automatically checks server capabilities to avoid timeouts:\n- If a server reports `null` for resources/tools/prompts capabilities, those endpoints are skipped\n- Use `--verbose` to see raw server capability information\n- Servers with `{}` (empty object) capabilities will still be tested\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues, feature requests, or pull requests.\n\n### How to Contribute\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run `make checkall` to ensure code quality\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\nPaul Robello - probello@gmail.com\n\n## Related Projects\n\n- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification\n- [MCP Servers](https://github.com/modelcontextprotocol/servers) - Official MCP server implementations\n- [Textual](https://textual.textualize.io/) - The TUI framework used by this application\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Paul Robello\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "PAR MCP Inspector TUI",
"version": "0.4.0",
"project_urls": {
"Discussions": "https://github.com/paulrobello/par-mcp-inspector-tui/discussions",
"Documentation": "https://github.com/paulrobello/par-mcp-inspector-tui/blob/main/README.md",
"Homepage": "https://github.com/paulrobello/par-mcp-inspector-tui",
"Issues": "https://github.com/paulrobello/par-mcp-inspector-tui/issues",
"Repository": "https://github.com/paulrobello/par-mcp-inspector-tui",
"Wiki": "https://github.com/paulrobello/par-mcp-inspector-tui/wiki"
},
"split_keywords": [
"mcp",
" terminal",
" tui"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d427d001883b68fc2e116684469368d137e842662e8786720aa46b377a910bcd",
"md5": "45a678cbcbcf55fe1b95795be47fa251",
"sha256": "627b69a5d083208b138e6c5b7af5c963afd8959c3071bbbc0bab1d84975a083f"
},
"downloads": -1,
"filename": "par_mcp_inspector_tui-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45a678cbcbcf55fe1b95795be47fa251",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 85420,
"upload_time": "2025-07-27T20:43:06",
"upload_time_iso_8601": "2025-07-27T20:43:06.403759Z",
"url": "https://files.pythonhosted.org/packages/d4/27/d001883b68fc2e116684469368d137e842662e8786720aa46b377a910bcd/par_mcp_inspector_tui-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2bcb09c8889109cd30ce10e2996acbe6966c6ae80f1d1ddb8ab9baf3de64300c",
"md5": "70755a658ca6c0f5cf722a83af26dae5",
"sha256": "fb9776c5d27edcc0facd3ee7b17702b5077d8b08cbc039df32d922fbb1d6fa9c"
},
"downloads": -1,
"filename": "par_mcp_inspector_tui-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "70755a658ca6c0f5cf722a83af26dae5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 73851,
"upload_time": "2025-07-27T20:43:07",
"upload_time_iso_8601": "2025-07-27T20:43:07.787235Z",
"url": "https://files.pythonhosted.org/packages/2b/cb/09c8889109cd30ce10e2996acbe6966c6ae80f1d1ddb8ab9baf3de64300c/par_mcp_inspector_tui-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 20:43:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paulrobello",
"github_project": "par-mcp-inspector-tui",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "par-mcp-inspector-tui"
}
