mcp-inspector 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d4704c72568b86082e74cc0c70052fec7e4a4d6e31b0f8fad00e42e76af5b63
+  data.tar.gz: fcb8bba16641850e3af1720ff8d9111a7c94ad325e5f063afc9685760bec8590
+SHA512:
+  metadata.gz: 896468351dee78dc3402113c403b80c92dcfa9388c90bce33b27835e31cd95a544efc36c1e70d0496390bb2009a085438ff92e6dcd85975e4b80e1a212cd58d4
+  data.tar.gz: 3ae68d16805d58016150e1fdfc02cf48cf80a7b2080fbc73bcf8c038539759ea52146782503168e33fbbdbda454bfc0d7cda9ae8a1f84100aa3bd14d6ad1c179

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/README.md

@@ -0,0 +1,261 @@
+# MCP Inspector
+
+A Ruby gem that provides a command-line tool for connecting to and inspecting MCP (Model Context Protocol) servers. The tool allows you to list and execute tools, read resources, and get prompts from MCP servers with JSON output by default.
+
+## Features
+
+- **Multi-transport support**: Connect to MCP servers via stdio, SSE, or WebSocket
+- **Command-based CLI**: Execute operations without persistent sessions
+- **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
+
+## Installation
+
+Install the gem by executing:
+
+```bash
+gem install mcp-inspector
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem 'mcp-inspector'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+1. **Create a configuration file:**
+
+```bash
+mcp-inspector config init
+```
+
+This creates `~/.mcp-inspector.json` with example server configurations.
+
+2. **List available servers:**
+
+```bash
+mcp-inspector config list
+```
+
+3. **List tools from a server:**
+
+```bash
+mcp-inspector list tools --server filesystem-server
+```
+
+4. **Execute a tool:**
+
+```bash
+mcp-inspector execute read_file --server filesystem-server --args '{"path": "/tmp/test.txt"}'
+```
+
+## Configuration
+
+The tool looks for configuration files in this order:
+
+1. Custom path via `--config` flag
+2. `./.mcp-inspector.json` (project config)
+3. `~/.mcp-inspector.json` (user config)
+
+### Configuration Format
+
+```json
+{
+  "servers": [
+    {
+      "name": "filesystem-server",
+      "transport": "stdio",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem"],
+      "args": ["/tmp"],
+      "env": {}
+    },
+    {
+      "name": "github-server",
+      "transport": "stdio",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    {
+      "name": "http-server",
+      "transport": "sse",
+      "url": "http://localhost:8080/sse"
+    }
+  ],
+  "defaults": {
+    "output": "json",
+    "pretty": true
+  }
+}
+```
+
+### Transport Types
+
+- **stdio**: Run a command and communicate via stdin/stdout
+- **sse**: Connect to Server-Sent Events endpoint
+- **websocket**: Connect to WebSocket endpoint
+
+## Usage
+
+### Global Options
+
+- `--config PATH`: Path to config file
+- `--server NAME`: Server name from config (required)
+- `--output FORMAT`: Output format (json)
+- `--pretty`: Pretty print output (default: true)
+- `--no-pretty`: Disable pretty printing
+
+### Commands
+
+#### List Resources
+
+```bash
+# List all tools
+mcp-inspector list tools --server myserver
+
+# List all resources  
+mcp-inspector list resources --server myserver
+
+# List all prompts
+mcp-inspector list prompts --server myserver
+```
+
+#### Execute Operations
+
+```bash
+# Execute a tool
+mcp-inspector execute tool_name --server myserver --args '{"key": "value"}'
+
+# Read a resource
+mcp-inspector read file:///path/to/file --server myserver
+
+# Get a prompt
+mcp-inspector prompt prompt_name --server myserver --args '{"key": "value"}'
+```
+
+#### Server Information
+
+```bash
+# Show server info and capabilities
+mcp-inspector info --server myserver
+```
+
+#### Configuration Management
+
+```bash
+# List configured servers
+mcp-inspector config list
+
+# Show server configuration
+mcp-inspector config show myserver
+
+# Create example config file
+mcp-inspector config init [path]
+```
+
+### Output Format
+
+All commands return JSON with a consistent structure:
+
+```json
+{
+  "status": "success",
+  "data": {
+    "tools": [...],
+    "count": 3
+  },
+  "metadata": {
+    "operation": "list_tools",
+    "server": "filesystem-server",
+    "timestamp": "2024-01-01T12:00:00Z"
+  }
+}
+```
+
+Error responses:
+
+```json
+{
+  "status": "error",
+  "error": {
+    "type": "ConnectionError", 
+    "message": "Failed to connect to server"
+  },
+  "metadata": {
+    "operation": "list_tools",
+    "server": "filesystem-server",
+    "timestamp": "2024-01-01T12:00:00Z"
+  }
+}
+```
+
+## Examples
+
+### Filesystem Server
+
+```bash
+# List files in a directory
+mcp-inspector list tools --server filesystem-server
+
+# Read a file
+mcp-inspector execute read_file --server filesystem-server --args '{"path": "/tmp/example.txt"}'
+
+# Write to a file
+mcp-inspector execute write_file --server filesystem-server --args '{"path": "/tmp/output.txt", "content": "Hello World"}'
+```
+
+### GitHub Server
+
+```bash
+# List repository information
+mcp-inspector list resources --server github-server
+
+# Search repositories
+mcp-inspector execute search_repositories --server github-server --args '{"query": "ruby mcp"}'
+```
+
+## 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
+
+This design makes it easy to add new output formats or adapt for web interfaces in the future.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Building the Gem
+
+```bash
+gem build mcp-inspector.gemspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/anthropics/mcp-inspector.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/mcp-inspector.json

@@ -0,0 +1,28 @@
+{
+  "servers": [
+    {
+      "name": "filesystem-server",
+      "transport": "stdio",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem"],
+      "args": ["/tmp"],
+      "env": {}
+    },
+    {
+      "name": "github-server",
+      "transport": "stdio",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    {
+      "name": "http-server",
+      "transport": "sse",
+      "url": "http://localhost:8080/sse"
+    }
+  ],
+  "defaults": {
+    "output": "json",
+    "pretty": true
+  }
+}

data/exe/mcp-inspector

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/mcp_inspector"
+
+begin
+  MCPInspector::CLI.start(ARGV)
+rescue Interrupt
+  puts "\nInterrupted"
+  exit(130)
+rescue => e
+  warn "Error: #{e.message}"
+  exit(1)
+end

data/lib/mcp_inspector/cli.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "data/config_manager"
+require_relative "data/input_adapter"
+require_relative "data/output_adapter"
+require_relative "transport/base_adapter"
+require_relative "transport/client_adapter"
+require_relative "transport/server_config"
+require_relative "presentation/base_formatter"
+require_relative "presentation/json_formatter"
+
+module MCPInspector
+  class CLI < Thor
+    class << self
+      def exit_on_failure?
+        true
+      end
+    end
+
+    class_option :config, type: :string, desc: "Path to config file"
+    class_option :server, type: :string, desc: "Server name from config"
+    class_option :output, type: :string, default: "json", desc: "Output format (json)"
+    class_option :pretty, type: :boolean, default: true, desc: "Pretty print output"
+    class_option :no_pretty, type: :boolean, desc: "Disable pretty printing"
+
+    def initialize(args = [], local_options = {}, config = {})
+      super
+      setup_global_options
+    end
+
+    desc "list TYPE", "List MCP server resources (tools, resources, prompts)"
+    def list(type)
+      case type
+      when "tools"
+        list_tools
+      when "resources"
+        list_resources
+      when "prompts"
+        list_prompts
+      else
+        warn "Invalid list type '#{type}'. Valid options: tools, resources, prompts"
+        exit(1)
+      end
+    end
+
+    desc "execute TOOL_NAME", "Execute a tool on the MCP server"
+    option :args, type: :string, desc: "JSON arguments for the tool", default: "{}"
+    def execute(tool_name)
+      with_server_connection do |adapter, output_adapter|
+        input_adapter = MCPInspector::Data::InputAdapter.new
+        input_adapter.validate_tool_name!(tool_name)
+        
+        arguments = input_adapter.parse_json_arguments(options[:args])
+        result = adapter.execute_tool(tool_name, arguments)
+        
+        metadata = build_metadata("execute_tool", tool_name)
+        output_adapter.output_tool_result(result, metadata)
+      end
+    rescue => e
+      handle_error(e)
+    end
+
+    desc "read RESOURCE_URI", "Read a resource from the MCP server"
+    def read(resource_uri)
+      with_server_connection do |adapter, output_adapter|
+        input_adapter = MCPInspector::Data::InputAdapter.new
+        input_adapter.validate_resource_uri!(resource_uri)
+        
+        content = adapter.read_resource(resource_uri)
+        
+        metadata = build_metadata("read_resource", resource_uri)
+        output_adapter.output_resource_content(content, metadata)
+      end
+    rescue => e
+      handle_error(e)
+    end
+
+    desc "prompt PROMPT_NAME", "Get a prompt from the MCP server"
+    option :args, type: :string, desc: "JSON arguments for the prompt", default: "{}"
+    def prompt(prompt_name)
+      with_server_connection do |adapter, output_adapter|
+        input_adapter = MCPInspector::Data::InputAdapter.new
+        input_adapter.validate_prompt_name!(prompt_name)
+        
+        arguments = input_adapter.parse_json_arguments(options[:args])
+        result = adapter.get_prompt(prompt_name, arguments)
+        
+        metadata = build_metadata("get_prompt", prompt_name)
+        output_adapter.output_prompt_result(result, metadata)
+      end
+    rescue => e
+      handle_error(e)
+    end
+
+    desc "info", "Show server connection details and capabilities"
+    def info
+      with_server_connection do |adapter, output_adapter|
+        server_info = adapter.server_info
+        
+        metadata = build_metadata("server_info")
+        output_adapter.output_server_info(server_info, metadata)
+      end
+    rescue => e
+      handle_error(e)
+    end
+
+    desc "config ACTION [NAME]", "Manage configuration (list, show SERVER_NAME, init [PATH])"
+    def config(action, name_or_path = nil)
+      case action
+      when "list"
+        config_list
+      when "show"
+        config_show(name_or_path)
+      when "init"
+        config_init(name_or_path)
+      else
+        warn "Invalid config action '#{action}'. Valid options: list, show, init"
+        exit(1)
+      end
+    end
+
+    private
+
+    def setup_global_options
+      # Handle --no-pretty flag
+      if options[:no_pretty]
+        @pretty_print = false
+      else
+        @pretty_print = options.fetch(:pretty, true)
+      end
+    end
+
+    def with_server_connection
+      ensure_server_specified!
+      config_manager = load_config_manager
+      server_config = config_manager.find_server(options[:server])
+      
+      adapter = MCPInspector::Transport::ClientAdapter.new
+      output_adapter = create_output_adapter
+      
+      begin
+        adapter.connect(server_config)
+        yield adapter, output_adapter
+      ensure
+        adapter.disconnect if adapter.connected?
+      end
+    end
+
+    def load_config_manager
+      MCPInspector::Data::ConfigManager.new(config_path: options[:config])
+    rescue MCPInspector::Data::ConfigManager::ConfigError => e
+      if e.message.include?("No configuration file found")
+        suggest_config_creation
+      end
+      raise
+    end
+
+    def suggest_config_creation
+      warn "Tip: Create a configuration file with:"
+      warn "  mcp-inspector config init"
+    end
+
+    def create_output_adapter
+      MCPInspector::Data::OutputAdapter.new(
+        format: options[:output],
+        pretty: @pretty_print
+      )
+    end
+
+    def build_metadata(operation, target = nil)
+      metadata = {
+        operation: operation,
+        server: options[:server]
+      }
+      
+      metadata[:target] = target if target
+      metadata
+    end
+
+    def handle_error(error)
+      output_adapter = create_output_adapter
+      metadata = build_metadata("error")
+      output_adapter.output_error(error, metadata)
+      exit(1)
+    end
+
+    def ensure_server_specified!
+      unless options[:server]
+        warn "Error: --server option is required for this command"
+        exit(1)
+      end
+    end
+
+    def list_tools
+      with_server_connection do |adapter, output_adapter|
+        tools = adapter.list_tools
+        
+        metadata = build_metadata("list_tools")
+        output_adapter.output_tools_list(tools, metadata)
+      end
+    end
+
+    def list_resources
+      with_server_connection do |adapter, output_adapter|
+        resources = adapter.list_resources
+        
+        metadata = build_metadata("list_resources")
+        output_adapter.output_resources_list(resources, metadata)
+      end
+    end
+
+    def list_prompts
+      with_server_connection do |adapter, output_adapter|
+        prompts = adapter.list_prompts
+        
+        metadata = build_metadata("list_prompts")
+        output_adapter.output_prompts_list(prompts, metadata)
+      end
+    end
+
+    def config_list
+      config_manager = load_config_manager
+      output_adapter = create_output_adapter
+      
+      metadata = build_metadata("config_list")
+      output_adapter.output_config_list(config_manager.servers, metadata)
+    end
+
+    def config_show(server_name)
+      unless server_name
+        warn "Server name is required for 'config show'"
+        exit(1)
+      end
+      
+      config_manager = load_config_manager
+      server_config = config_manager.find_server(server_name)
+      output_adapter = create_output_adapter
+      
+      metadata = build_metadata("config_show", server_name)
+      output_adapter.output_config_details(server_config, metadata)
+    end
+
+    def config_init(path = nil)
+      path ||= MCPInspector::Data::ConfigManager::DEFAULT_USER_CONFIG_PATH
+      
+      if File.exist?(path)
+        warn "Configuration file already exists: #{path}"
+        exit(1)
+      end
+      
+      created_path = MCPInspector::Data::ConfigManager.create_example_config(path)
+      puts "Created example configuration file: #{created_path}"
+      puts "Edit this file to configure your MCP servers."
+    end
+  end
+end