bb-mcp-client-inspector

Beyond-Better/bb-mcp-client-inspector

3.2

If you are the rightful owner of bb-mcp-client-inspector and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Beyond MCP Client Inspector is a comprehensive testing platform designed for MCP (Model Context Protocol) client implementations, providing an interactive web console for testing and validating these implementations.

Tools
6
Resources
0
Prompts
0

Beyond MCP Client Inspector

Beyond Better MCP Server MCP Client MCP Server

JSR JSR Score JSR Scope License: MIT

A comprehensive testing platform for MCP (Model Context Protocol) client implementations

Overview

The MCP Server Client Inspector provides an interactive web console for testing and validating MCP client implementations. While the MCP Inspector exists as an MCP client for testing servers, this project fills the inverse need - an MCP server for testing clients.

Key Features

  • 🔍 Protocol Message Inspection: View all MCP JSON-RPC messages in real-time
  • 🧠 Sampling Testing: Test client LLM completion capabilities
  • ❓ Elicitation Testing: Test client user input request handling
  • 🔔 Notification Testing: Trigger and verify list change notifications
  • 🛠️ Inspector Tools: Six utility tools for testing scenarios
  • 📊 Multi-Client Support: Test multiple clients simultaneously (HTTP mode)
  • 🌐 Web Console: Interactive Fresh UI for testing

Inspector Console

Installation

Quick Start (Recommended)

Run directly from JSR - No installation required!

deno run -A jsr:@beyondbetter/bb-mcp-client-inspector

This will start both servers:

  • MCP Server on http://localhost:3000
  • Web UI on http://localhost:8000

Open your browser to http://localhost:8000 to access the inspector console.

Custom Ports

Specify custom ports if the defaults are in use:

deno run -A jsr:@beyondbetter/bb-mcp-client-inspector --mcp-port 3001 --ui-port 8080

Available options:

  • --mcp-port <port> - Port for MCP server (default: 3000)
  • --ui-port <port> - Port for Fresh UI (default: 8000)
  • --mcp-host <host> - Host for MCP server (default: localhost)
  • --ui-host <host> - Host for Fresh UI (default: localhost)

Development Setup

For development or customization, run from source:

Prerequisites:

Quick Setup:

# Clone and navigate
git clone https://github.com/Beyond-Better/bb-mcp-server-client-inspector.git
cd bb-mcp-server-client-inspector

# Run both servers in development mode
deno task dev

This starts both servers with hot reload. Open http://localhost:8000 in your browser.

📖 Detailed Instructions: For configuration options, troubleshooting, and advanced setup, see

Architecture

Dual-Server Design

┌─────────────────────────────────────┐
│  MCP Server (Deno)                  │
│  ├─ STDIO/HTTP transport (MCP)      │
│  ├─ WebSocket endpoint (/ws/console)│
│  ├─ Inspector tools                 │
│  └─ Session management (KV)         │
└──────────────┬──────────────────────┘
               │ WebSocket
               │ (real-time updates)
┌──────────────▼──────────────────────┐
│  Fresh UI Server (Deno Fresh)       │
│  ├─ Console UI routes               │
│  ├─ WebSocket client                │
│  ├─ Hot reload (dev mode)           │
│  └─ Static assets                   │
└─────────────────────────────────────┘

Technology Stack

MCP Server:

  • Runtime: Deno 2.5+
  • Framework: bb-mcp-server library
  • MCP SDK: @modelcontextprotocol/sdk v1.18.2
  • Storage: Deno KV
  • Language: TypeScript

Fresh UI:

  • Framework: Deno Fresh
  • UI: Preact Islands
  • Styling: Tailwind CSS + DaisyUI
  • Language: TypeScript + JSX

Project Structure

bb-mcp-server-client-inspector/
├── docs/                           # Comprehensive design documentation
│   ├── 01-PROJECT_OVERVIEW.md      # Project summary and goals
│   ├── 02-ARCHITECTURE.md          # System architecture
│   ├── 03-MCP_SERVER_DESIGN.md     # MCP server specifications
│   ├── 04-FRESH_UI_DESIGN.md       # Fresh UI specifications
│   ├── 05-DATA_MODELS.md           # Type definitions
│   ├── 06-WEBSOCKET_PROTOCOL.md    # Console communication protocol
│   ├── 07-TESTING_STRATEGY.md      # Testing approach
│   └── 08-IMPLEMENTATION_PHASES.md # Development roadmap
├── mcp-server/                     # MCP Server
│   ├── main.ts
│   ├── src/
│   │   ├── plugins/
│   │   │   └── inspector.plugin/
│   │   ├── console/
│   │   └── dependencyHelper.ts
│   └── tests/
├── fresh-ui/                       # Fresh UI Server
│   ├── main.ts
│   ├── routes/
│   ├── islands/
│   ├── components/
│   └── hooks/
└── shared/                         # Shared types
    └── types/

Documentation

For Implementers (LLMs)

Read the design documents in this order:

  1. - Start here for context and goals
  2. - Understand the system architecture
  3. - MCP server implementation details
  4. - Fresh UI implementation details
  5. - Type definitions and interfaces
  6. - Console communication protocol
  7. - Testing approach and examples
  8. - Phased development plan

Quick Start Guide

Each document is comprehensive and self-contained. For implementation:

  • Phase 1: Focus on MCP_SERVER_DESIGN.md and basic infrastructure
  • Phase 2: Reference WEBSOCKET_PROTOCOL.md and FRESH_UI_DESIGN.md
  • Phase 3: Use DATA_MODELS.md for shared types
  • Phase 4: Follow TESTING_STRATEGY.md for test implementation

Inspector Tools

The server includes six utility tools for testing:

  1. echo - Echo messages with optional delay and transformation
  2. convert_date - Date/timezone conversion and formatting
  3. calculate - Basic arithmetic operations
  4. delay_response - Configurable delays (for timeout testing)
  5. random_data - Generate random test data
  6. trigger_error - Intentionally trigger errors (for error handling tests)

Testing Capabilities

Sampling

Test client LLM completion capabilities:

  • Simple text prompts
  • Model preferences
  • Temperature and max tokens
  • Response handling

Elicitation

Test client user input requests:

  • Simple text input
  • Structured data (with JSON schema)
  • Accept/decline/cancel responses
  • Schema validation

Notifications

Trigger and verify notifications:

  • notifications/tools/list_changed
  • notifications/resources/list_changed
  • notifications/prompts/list_changed

Development Roadmap

Version 1.0 (Initial Release)

Phase 1: Foundation (Day 1)

  • ✅ MCP server with bb-mcp-server
  • ✅ Basic inspector tools
  • ✅ Message storage (Deno KV)
  • ✅ Fresh UI foundation

Phase 2: Core Features (Day 2)

  • ✅ WebSocket communication
  • ✅ Sampling request/response
  • ✅ Elicitation request/response
  • ✅ Notification triggering
  • ✅ Message viewer

Phase 3: Polish (Day 3)

  • ✅ Multi-client support
  • ✅ UI refinement
  • ✅ Error handling
  • ✅ Performance optimization

Phase 4: Release (Day 4)

  • ✅ Complete documentation
  • ✅ Message filtering in UI
  • ✅ Comprehensive testing
  • ✅ Example scenarios
  • ✅ Deployment preparation

Roadmap (Future Versions)

  • 🔄 Multi-turn sampling conversations
  • 🔄 Full suite of MCP features (prompts/roots/resources)
  • 🔄 Streaming response support
  • 🔄 Pre-configured test scenarios
  • 🔄 Session export/import
  • 🔄 Client metrics and analytics
  • 🔄 WebSocket authentication

Design Principles

Separation of Concerns

  • MCP Server: Handles MCP protocol, tool execution, message tracking
  • Fresh UI: Handles user interface, visualization, user interactions
  • WebSocket: Real-time communication bridge between server and UI

Simplicity First

  • v1.0 Features: Essential testing capabilities only
  • Roadmap Items: Advanced features for future versions
  • Clear Boundaries: Each component has a single responsibility

Production Quality

  • Comprehensive Testing: >80% code coverage
  • Error Handling: Graceful degradation and recovery
  • Documentation: Complete specs for implementation
  • Type Safety: Strict TypeScript throughout

Implementation Guidelines

For LLM implementers working on this project:

Prerequisites

# Deno 2.5+
deno --version

# bb-mcp-server library
deno info jsr:@beyondbetter/bb-mcp-server

Development Setup

# Clone the repository
git clone https://github.com/Beyond-Better/bb-mcp-server-client-inspector.git
cd bb-mcp-server-client-inspector

# Terminal 1: MCP Server
cd mcp-server
cp .env.example .env
deno task dev

# Terminal 2: Fresh UI
cd fresh-ui
cp .env.example .env
deno task dev

Testing

# MCP Server tests
cd mcp-server
deno task test

# UI tests
cd fresh-ui
deno task test

Key Design Decisions

1. Separate Processes

Why: Clean separation of concerns, independent development, Fresh hot reload works naturally

Alternative Considered: Embedded Fresh app in MCP server (too complex)

2. WebSocket Communication

Why: Real-time updates, low latency, bidirectional communication

Alternative Considered: HTTP polling (higher latency, more overhead)

3. bb-mcp-server Library

Why: Proven infrastructure, plugin system, built-in session management

Alternative Considered: Raw MCP SDK (more boilerplate, reinventing infrastructure)

4. Deno KV Storage

Why: Built-in, fast, simple API, perfect for session data

Alternative Considered: External database (unnecessary complexity for v1.0)

5. Fresh Islands

Why: Minimal JavaScript, fast rendering, easy to understand

Alternative Considered: SPA framework (more complexity, larger bundle)

Success Metrics

Functionality

  • ✅ Successfully tests sampling requests and responses
  • ✅ Successfully tests elicitation flows (accept/decline/cancel)
  • ✅ Successfully triggers and verifies notifications
  • ✅ Displays all MCP protocol messages clearly
  • ✅ Handles multiple connected clients (HTTP mode)

Usability

  • ✅ Simple setup (< 5 minutes from clone to running)
  • ✅ Intuitive UI (minimal learning curve)
  • ✅ Clear error messages and feedback
  • ✅ Responsive real-time updates

Quality

  • ✅ Comprehensive test coverage (>80%)
  • ✅ Clear documentation for LLM consumption
  • ✅ Example test scenarios included
  • ✅ Production-ready error handling

Contributing

This project is designed for implementation by LLMs following the comprehensive design documentation. When contributing:

  1. Read the relevant design documents first
  2. Follow the implementation phases
  3. Write tests alongside implementation
  4. Update documentation as needed
  5. Ensure type safety throughout

License

MIT License (recommended for maximum adoption)

Project Status

Current: Design Complete - Ready for Implementation

  • ✅ Comprehensive design documentation
  • ✅ Architecture finalized
  • ✅ Type definitions specified
  • ✅ Testing strategy defined
  • ✅ Implementation phases planned
  • 🔨 Implementation: Not started

Next Steps

For implementers:

  1. Review PROJECT_OVERVIEW.md for context
  2. Study ARCHITECTURE.md for system understanding
  3. Begin Phase 1 implementation following IMPLEMENTATION_PHASES.md
  4. Reference specific design documents as needed
  5. Write tests following TESTING_STRATEGY.md

Repository

GitHub: beyond-better/bb-mcp-server-client-inspector

JSR Package: @beyondbetter/bb-mcp-client-inspector

Project Version: 0.1.0 (Design) Documentation Version: 1.0 Last Updated: 2025-10-22 Status: Design Complete - Ready for Implementation

Built with ❤️ for the MCP community