Beyond MCP Client Inspector

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

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:

Deno 2.5+ - Install Deno
Git - For cloning the repository

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 INSTALLATION.md

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:

PROJECT_OVERVIEW.md - Start here for context and goals
ARCHITECTURE.md - Understand the system architecture
MCP_SERVER_DESIGN.md - MCP server implementation details
FRESH_UI_DESIGN.md - Fresh UI implementation details
DATA_MODELS.md - Type definitions and interfaces
WEBSOCKET_PROTOCOL.md - Console communication protocol
TESTING_STRATEGY.md - Testing approach and examples
IMPLEMENTATION_PHASES.md - 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:

echo - Echo messages with optional delay and transformation
convert_date - Date/timezone conversion and formatting
calculate - Basic arithmetic operations
delay_response - Configurable delays (for timeout testing)
random_data - Generate random test data
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:

Read the relevant design documents first
Follow the implementation phases
Write tests alongside implementation
Update documentation as needed
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:

Review PROJECT_OVERVIEW.md for context
Study ARCHITECTURE.md for system understanding
Begin Phase 1 implementation following IMPLEMENTATION_PHASES.md
Reference specific design documents as needed
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

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github/workflows		.github/workflows
docs		docs
fresh-ui		fresh-ui
mcp-server		mcp-server
scripts		scripts
shared		shared
tests		tests
.gitignore		.gitignore
GUIDELINES.md		GUIDELINES.md
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
README.md		README.md
deno.jsonc		deno.jsonc
deno.lock		deno.lock
import_map.dev.json		import_map.dev.json
import_map.json		import_map.json
main.ts		main.ts
screenshot-large.png		screenshot-large.png
screenshot-medium.png		screenshot-medium.png
screenshot.png		screenshot.png

License

Beyond-Better/bb-mcp-client-inspector

Folders and files

Latest commit

History

Repository files navigation

Beyond MCP Client Inspector

Overview

Key Features

Installation

Quick Start (Recommended)

Custom Ports

Development Setup

Architecture

Dual-Server Design

Technology Stack

Project Structure

Documentation

For Implementers (LLMs)

Quick Start Guide

Inspector Tools

Testing Capabilities

Sampling

Elicitation

Notifications

Development Roadmap

Version 1.0 (Initial Release)

Roadmap (Future Versions)

Design Principles

Separation of Concerns

Simplicity First

Production Quality

Implementation Guidelines

Prerequisites

Development Setup

Testing

Key Design Decisions

1. Separate Processes

2. WebSocket Communication

3. bb-mcp-server Library

4. Deno KV Storage

5. Fresh Islands

Success Metrics

Functionality

Usability

Quality

Contributing

License

Project Status

Next Steps

Repository

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Packages 0

Languages

Packages