mcp-inspector 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d4704c72568b86082e74cc0c70052fec7e4a4d6e31b0f8fad00e42e76af5b63
-  data.tar.gz: fcb8bba16641850e3af1720ff8d9111a7c94ad325e5f063afc9685760bec8590
+  metadata.gz: 66bc1141435b3fef45e1bb3536ee65703a804499644fe91fe433520d9f3064d4
+  data.tar.gz: 07db01d952c3e50a20ea7dacd942c27390351d1a3669c10e5816af1d8bfef49d
 SHA512:
-  metadata.gz: 896468351dee78dc3402113c403b80c92dcfa9388c90bce33b27835e31cd95a544efc36c1e70d0496390bb2009a085438ff92e6dcd85975e4b80e1a212cd58d4
-  data.tar.gz: 3ae68d16805d58016150e1fdfc02cf48cf80a7b2080fbc73bcf8c038539759ea52146782503168e33fbbdbda454bfc0d7cda9ae8a1f84100aa3bd14d6ad1c179
+  metadata.gz: 0b08184300a2822dfe7127e6fd988cca938b41ed1d7793e0a74a7f7c931276c5347bf5e52b861598b3a349ca69a646c222fc74f24e5ed794feedf719d2c9e7ce
+  data.tar.gz: 573f2babc2f3a59650f11a0f448239981a31a26fd309e199b3a8181c28342c284aa35789b293a7a2c0a1047886a990a1acb58865bda1f79e882aa69f09054b0b

data/NAMING_CONVENTION.md

@@ -0,0 +1,145 @@
+# Naming Convention Change
+
+## Summary
+
+The gem has been renamed from `MCPInspector` to `McpInspector` to follow Ruby naming conventions and avoid complex inflection configuration.
+
+## Why the Change?
+
+Ruby/Rails conventions dictate that:
+- Acronyms should only stay fully uppercase when standalone (e.g., `MCP`) or at the end of a constant name (e.g., `ServerMCP`)
+- In compound names, only the first letter of each word should be capitalized (e.g., `HttpClient`, not `HTTPClient`)
+- `McpInspector` follows this convention, treating "Mcp" as a word rather than requiring special inflection rules
+
+This change:
+✅ Simplifies autoloading (no custom Zeitwerk inflections needed)
+✅ Follows Rails conventions
+✅ Avoids conflicts between gem and Rails autoloaders
+✅ Makes the codebase more maintainable
+
+## What Changed
+
+### Module Names
+- `MCPInspector` → `McpInspector`
+- `MCPInspector::Web` → `McpInspector::Web`
+- All nested modules updated accordingly
+
+### File Changes
+
+**Core Library:**
+- `lib/mcp_inspector.rb` - Removed inflection config
+- `lib/mcp_inspector/version.rb` - Updated module name
+- `lib/mcp_inspector/cli.rb` - Updated all class references
+- All files in `lib/mcp_inspector/transport/` - Updated module names
+- All files in `lib/mcp_inspector/data/` - Updated module names
+- All files in `lib/mcp_inspector/presentation/` - Updated module names
+
+**Web Engine:**
+- `lib/mcp_inspector_web.rb` - Updated module name
+- `lib/mcp_inspector/web/engine.rb` - Removed inflection initializer
+- `lib/mcp_inspector/web/config/routes.rb` - Updated engine reference
+- All controllers - Updated module names
+- All views - Updated references (if any)
+
+**Demo Application:**
+- `inspector/config/routes.rb` - Updated mount statement
+- `inspector/config/initializers/inflections.rb` - Removed MCP acronym
+- `inspector/config/application.rb` - No changes needed (require still works)
+
+**Documentation:**
+- `README.md` - Updated all code examples
+- `WEB_README.md` - Removed inflection step, updated examples
+- `inspector/README.md` - Removed inflection section
+- `QUICKSTART.md` - Removed inflection step
+- `mcp-inspector.gemspec` - Updated version constant reference
+
+## Usage Examples
+
+### Before (with inflections)
+
+```ruby
+# Needed inflection configuration
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym "MCP"
+end
+
+# Module reference
+module MCPInspector
+  module Web
+    # ...
+  end
+end
+
+# Mount statement
+mount MCPInspector::Web::Engine, at: '/mcp_inspector'
+```
+
+### After (no inflections needed)
+
+```ruby
+# No inflection configuration needed!
+
+# Module reference
+module McpInspector
+  module Web
+    # ...
+  end
+end
+
+# Mount statement
+mount McpInspector::Web::Engine, at: '/mcp_inspector'
+```
+
+## Migration Guide
+
+If you have an existing installation:
+
+1. **Update your routes** (`config/routes.rb`):
+   ```ruby
+   # Old
+   mount MCPInspector::Web::Engine, at: '/mcp_inspector'
+
+   # New
+   mount McpInspector::Web::Engine, at: '/mcp_inspector'
+   ```
+
+2. **Remove inflection configuration** (`config/initializers/inflections.rb`):
+   ```ruby
+   # Remove this:
+   ActiveSupport::Inflector.inflections(:en) do |inflect|
+     inflect.acronym "MCP"
+   end
+   ```
+
+3. **Update any custom code** that references the modules:
+   ```ruby
+   # Old
+   MCPInspector::Data::ConfigManager
+
+   # New
+   McpInspector::Data::ConfigManager
+   ```
+
+4. **Restart your server**
+
+That's it! No changes needed to configuration files or other aspects of the gem.
+
+## Benefits
+
+- ✅ **Simpler setup** - No inflection configuration required
+- ✅ **Standard Rails** - Follows Rails autoloading conventions
+- ✅ **Less magic** - No custom Zeitwerk configuration
+- ✅ **More maintainable** - Easier for other developers to understand
+- ✅ **Fewer conflicts** - Avoids autoloader conflicts
+
+## Technical Details
+
+The change affects:
+- **14 Ruby files** in `lib/mcp_inspector/`
+- **4 controller files** in the web engine
+- **1 routes file** in the web engine
+- **1 engine file**
+- **4 documentation files**
+- **Demo app configuration**
+
+All references to `MCPInspector` have been systematically replaced with `McpInspector` throughout the codebase.

data/QUICKSTART.md

@@ -0,0 +1,166 @@
+# MCP Inspector - Quick Start Guide
+
+Get the MCP Inspector web interface running in under 5 minutes!
+
+## For the Web Interface (Demo App)
+
+### Prerequisites
+- Ruby 2.7+ installed
+- Node.js and npm installed (for MCP servers)
+- Bundler installed (`gem install bundler`)
+
+### Quick Start (3 commands)
+
+```bash
+# 1. Navigate to the demo app
+cd inspector
+
+# 2. Run the start script (installs dependencies and starts server)
+bin/start
+
+# 3. Open your browser to http://localhost:3000
+```
+
+That's it! You should now see the MCP Inspector web interface.
+
+### What's Included
+
+The demo comes pre-configured with two MCP servers:
+
+1. **filesystem-server** - Interact with files in `/tmp` directory
+2. **github-server** - Interact with GitHub (requires GITHUB_TOKEN)
+
+### Your First Test
+
+1. **Create a test file**:
+   ```bash
+   echo "Hello MCP Inspector!" > /tmp/test.txt
+   ```
+
+2. **In the browser**:
+   - Select "filesystem-server" from the dropdown
+   - Click "List Tools"
+   - Find "read_file" tool and click "Execute"
+   - Enter: `{"path": "/tmp/test.txt"}`
+   - Click "Execute Tool"
+   - See your file contents appear!
+
+### Optional: GitHub Server Setup
+
+To use the GitHub server:
+
+```bash
+export GITHUB_TOKEN=your_github_token_here
+```
+
+Get a token at: https://github.com/settings/tokens
+
+Then restart the server and select "github-server" from the dropdown.
+
+## Integrating Into Your Own Rails App
+
+To add MCP Inspector to your existing Rails application:
+
+1. **Mount the engine** in `config/routes.rb`:
+   ```ruby
+   mount McpInspector::Web::Engine, at: '/mcp_inspector'
+   ```
+
+2. **Require the engine** in `config/application.rb`:
+   ```ruby
+   require 'mcp_inspector_web'
+   ```
+
+3. **Restart your server** and visit `/mcp_inspector`
+
+See [WEB_README.md](WEB_README.md) for complete documentation.
+
+## For the CLI Tool
+
+If you prefer the command-line interface:
+
+```bash
+# Install the gem
+gem install mcp-inspector
+
+# Create configuration
+mcp-inspector config init
+
+# List available tools
+mcp-inspector list tools --server filesystem-server
+
+# Execute a tool
+mcp-inspector execute read_file --server filesystem-server --args '{"path": "/tmp/test.txt"}'
+```
+
+## What's Next?
+
+- **Web Interface Documentation**: See [WEB_README.md](WEB_README.md)
+- **CLI Documentation**: See [README.md](README.md)
+- **Demo App Details**: See [inspector/README.md](inspector/README.md)
+- **Add Your Own MCP Servers**: Edit `.mcp-inspector.json`
+
+## Troubleshooting
+
+### "Command not found: npx"
+Install Node.js from https://nodejs.org/
+
+### "Bundle not found"
+```bash
+gem install bundler
+```
+
+### "Connection failed"
+Make sure the MCP server is installed:
+```bash
+npx -y @modelcontextprotocol/server-filesystem /tmp
+```
+
+### Need Help?
+- Check the comprehensive [WEB_README.md](WEB_README.md)
+- Check the demo app [README](inspector/README.md)
+- Open an issue on GitHub
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────┐
+│   Browser (Web Interface)           │
+│   http://localhost:3000              │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────┐
+│   Rails Engine (MCP Inspector Web)  │
+│   - Controllers                      │
+│   - Views (Tailwind CSS)             │
+│   - Turbo Streams                    │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────┐
+│   MCP Inspector Core                │
+│   - Transport Layer                  │
+│   - Data Layer                       │
+│   - Configuration Management         │
+└──────────────┬──────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────┐
+│   MCP Servers                        │
+│   - filesystem-server                │
+│   - github-server                    │
+│   - your-custom-server               │
+└─────────────────────────────────────┘
+```
+
+## Key Features
+
+✅ **Zero Configuration** - Pre-configured demo app ready to run
+✅ **Interactive UI** - Click, type, execute - no command-line needed
+✅ **Real-time Updates** - Turbo Streams for seamless interactions
+✅ **Multiple Transports** - stdio, SSE, WebSocket support
+✅ **Secure** - CSRF protection, input validation, timeouts
+✅ **Extensible** - Add your own MCP servers easily
+
+Happy inspecting! 🔍

data/README.md

@@ -6,9 +6,10 @@ A Ruby gem that provides a command-line tool for connecting to and inspecting MC
 
 - **Multi-transport support**: Connect to MCP servers via stdio, SSE, or WebSocket
 - **Command-based CLI**: Execute operations without persistent sessions
+- **Web Interface**: Rails Engine for browser-based MCP server inspection
 - **JSON configuration**: Configure multiple servers in a single JSON file
 - **Structured output**: All output in JSON format for easy parsing and automation
-- **Three-layer architecture**: Designed for future web adaptation
+- **Three-layer architecture**: Designed for both CLI and web interfaces
 
 ## Installation
 
@@ -224,15 +225,54 @@ mcp-inspector list resources --server github-server
 mcp-inspector execute search_repositories --server github-server --args '{"query": "ruby mcp"}'
 ```
 
+## Web Interface
+
+MCP Inspector includes a Rails Engine for browser-based inspection of MCP servers. The web interface provides:
+
+- Interactive server selection and operation execution
+- Real-time updates using Hotwire/Turbo Streams
+- Modern UI with Tailwind CSS
+- Easy mounting in existing Rails applications
+
+### Quick Setup
+
+1. Add to your Rails app's `config/routes.rb`:
+
+```ruby
+mount McpInspector::Web::Engine, at: '/mcp_inspector'
+```
+
+2. Require the web engine in `config/application.rb`:
+
+```ruby
+require 'mcp_inspector_web'
+```
+
+3. Start your Rails server and visit `/mcp_inspector`
+
+### Demo Application
+
+A complete working demo is available in the `inspector/` directory:
+
+```bash
+cd inspector
+bin/start
+# Visit http://localhost:3000
+```
+
+For detailed documentation:
+- Web interface: [WEB_README.md](WEB_README.md)
+- Demo application: [inspector/README.md](inspector/README.md)
+
 ## Architecture
 
 The gem uses a three-layer architecture:
 
 1. **Transport Layer**: Handles connections to MCP servers
-2. **Data Layer**: Manages configuration and input/output processing  
-3. **Presentation Layer**: Formats output for display
+2. **Data Layer**: Manages configuration and input/output processing
+3. **Presentation Layer**: Formats output for display (CLI and Web)
 
-This design makes it easy to add new output formats or adapt for web interfaces in the future.
+This design makes it easy to add new output formats and provides both CLI and web interfaces using the same core functionality.
 
 ## Development