AI导哈

MCP客户端检查工具

一个用于测试和验证MCP（模型上下文协议）客户端实现的交互式Web控制台平台。

  • by Beyond-Better
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Beyond-Better/bb-mcp-client-inspector

使用说明

超越MCP客户端检查器

针对MCP（模型上下文协议）客户端的综合测试平台 实施（方案/版本）

概述

MCP服务器客户端检查器提供了一个交互式网页控制台用于测试 并验证MCP客户端实现。同时 MCP 检查器 存在为一种 用于测试服务器的MCP客户端，此项目满足了相反的需求——即一个MCP（管理控制协议/客户端）用于（此处根据上下文，可能指“用于管理或监控服务器”，但原文未明确，因此保持“MCP”以涵盖多种可能性） 用于测试客户端的服务器。

主要特点

  • 🔍 看起来像是一个放大镜的符号，常用于表示搜索或查看细节。在中文里，可以简单地翻译为“🔍（放大镜）”或者根据上下文意译为“🔍（查找/查看细节）”。由于这是一个图形符号，直接翻译可能无法完全传达其在特定语境中的含义，因此需要结合具体使用场景来理解。 协议消息检查查看所有MCP JSON-RPC消息 实时
  • 🧠 这个表情符号通常被用来表示大脑、思考、智慧或智力。所以，可以翻译为“🧠（表示大脑/思考/智慧）”。不过，在实际应用中，我们往往直接用“🧠”这个符号来传达这些含义，而不需要具体翻译出文字。 抽样测试测试客户端的大型语言模型（LLM）完成功能
  • ❓ **诱发测试（或引出测试）**测试客户端用户输入请求处理
  • 🔔（铃铛或提醒的符号，具体含义根据上下文而定） 通知测试触发并验证列表变更通知
  • 🛠️（工具或修理的象征，可具体翻译为“工具”或根据上下文译为“修理工具”等） 检查员工具六个用于测试场景的实用工具
  • 📊 表格/数据图表 多客户端支持同时测试多个客户端（HTTP模式）
  • 🌐（表示互联网或网络的符号，可翻译为“网络”或“互联网”） Web 控制台用于测试的交互式清新用户界面

安装

快速入门（推荐）

直接从JSR运行 - 无需安装！

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

这将启动两个服务器：

  • MCP服务器 on http://localhost:3000
  • 网页用户界面 开启/打开 http://localhost:8000

打开你的浏览器到 http://localhost:8000 访问检查器控制台。

自定义端口

如果默认端口已被使用，请指定自定义端口：

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

可用选项：

  • --mcp-port <port> - MCP服务器端口（默认：3000）
  • --ui-port <port> - Fresh UI 的端口（默认：8000）
  • --mcp-host <host> - MCP服务器的主机（默认：localhost）
  • --ui-host <host> - Fresh UI 的主机（默认：localhost）

开发环境设置

对于开发或定制，请从源代码运行：

先决条件：

  • Deno 2.5及以上版本 - 安装Deno
  • Git - 用于克隆仓库

快速设置：

# 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

这将启动两个服务器并启用热重载。打开 http://localhost:8000 在您的浏览器中。

📖 详细说明： 如需配置选项、故障排除和高级设置，请参阅 INSTALLATION.md 翻译为中文是：“安装指南.md” 或 “安装说明文件.md”

建筑学

双服务器设计

┌─────────────────────────────────────┐
│  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                   │
└─────────────────────────────────────┘

技术栈

MCP服务器:

  • 运行时：Deno 2.5+
  • 框架：bb-mcp-server 库
  • MCP SDK：@modelcontextprotocol/sdk 版本 1.18.2
  • 存储：Deno KV
  • 语言：TypeScript

全新的用户界面:

  • 框架：Deno Fresh
  • UI: Preact Islands（用户界面：Preact 岛屿模式）
  • 样式：Tailwind CSS + DaisyUI
  • 语言：TypeScript + JSX

项目结构

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/

文档

对于实施者（大型语言模型）

按照以下顺序阅读设计文档：

  1. PROJECT_OVERVIEW.md 翻译为中文是：“项目概述.md” - 从这里开始 背景和目标
  2. ARCHITECTURE.md 翻译为中文是：“架构.md”（文件名，表示这是一个关于架构的Markdown文档） - 理解系统 建筑学
  3. MCP_SERVER_DESIGN.md 翻译为中文是：“MCP服务器设计.md” - MCP服务器 实施细节
  4. FRESH_UI_DESIGN.md 翻译为中文是：“新鲜的UI设计.md”（注：这里的“.md”通常表示Markdown文件格式，但在中文语境下，我们通常不会特别翻译文件扩展名，除非需要说明其具体含义或用途。在此处，为了保持原文的完整性，我保留了“.md”的形式。） - 新鲜的用户界面 实施细节
  5. DATA_MODELS.md（数据模型说明文件） - 类型定义和 接口
  6. WEBSOCKET_PROTOCOL.md 翻译为中文是：“WEBSOCKET 协议说明文件” 或 “WEBSOCKET 协议文档” - 控制台 通信协议
  7. `TESTING_STRATEGY.md` 翻译为中文是：`测试策略.md` - 测试方法和 示例
  8. IMPLEMENTATION_PHASES.md 翻译为中文是：《实施阶段.md》（注：这里的“.md”通常表示Markdown文件格式，但在中文语境下，我们通常不会特别指出文件扩展名，除非它对理解内容有特殊意义，因此也可以简单翻译为《实施阶段》） - 分阶段的 发展计划

快速入门指南

每份文件内容全面且独立成篇。关于实施：

  • 第一阶段专注于MCP_SERVER_DESIGN.md文件和基本基础设施
  • 第二阶段参考 WEBSOCKET_PROTOCOL.md 和 FRESH_UI_DESIGN.md
  • 第三阶段使用 DATA_MODELS.md 文件来共享类型
  • 第四阶段请遵循 TESTING_STRATEGY.md 文件进行测试实现

检查员工具

该服务器包含六个用于测试的实用工具：

  1. echo（回声） - 回显消息，可选延迟和转换
  2. 转换日期 - 日期/时区转换和格式化
  3. 计算 - 基本算术运算
  4. 延迟响应 - 可配置的延迟（用于超时测试）
  5. 随机数据 - 生成随机测试数据
  6. `trigger_error` 翻译成中文是“触发错误” - 故意触发错误（用于错误处理测试）

测试能力

采样

测试客户端的大型语言模型（LLM）补全能力：

  • 简单的文本提示
  • 模型偏好
  • 温度（参数）和最大标记数
  • 响应处理

引出（或诱发）

测试客户端用户输入请求：

  • 简单的文本输入
  • 结构化数据（带有JSON模式）
  • 接受/拒绝/取消回复
  • 模式验证

通知

触发并验证通知：

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

发展路线图

版本1.0（初始发布）

第一阶段：基础 （第一天）

  • ✅ 使用 bb-mcp-server 的 MCP 服务器
  • ✅ 基本检查工具
  • ✅ 消息存储（Deno KV）
  • ✅ 新的用户界面基础

第二阶段：核心功能 （第二天）

  • ✅ WebSocket通信
  • ✅ 采样请求/响应
  • ✅ 引导性请求/响应
  • ✅ 通知触发
  • ✅ 消息查看器

第三阶段：润色 （第三天）

  • ✅ 支持多客户端
  • ✅ 用户界面优化
  • ✅ 错误处理
  • ✅ 性能优化

阶段4：发布 （第四天）

  • ✅ 完整的文件记录
  • ✅ 用户界面中的消息过滤
  • ✅ 全面测试
  • ✅ 示例场景
  • ✅ 部署准备

路线图（未来版本）

  • 🔄 多轮采样对话
  • 🔄 完整的MCP功能套件（提示/根资源/资源）
  • 🔄 支持流式响应
  • 🔄 预配置的测试场景
  • 🔄 会话导出/导入
  • 🔄 客户指标与分析
  • 🔄 WebSocket 认证

设计原则

关注点分离（或职责分离）

  • MCP服务器处理MCP协议、工具执行、消息追踪
  • 全新的用户界面处理用户界面、可视化、用户交互
  • WebSocket服务器与用户界面之间的实时通信桥梁

简约至上

  • 版本1.0 特性仅提供基本测试功能
  • 路线图项目未来版本的高级功能
  • 明确的界限每个组件都有单一职责

生产质量

  • 综合测试>80%的代码覆盖率
  • 错误处理优雅降级与恢复
  • 文档实施所需的完整规格说明
  • 类型安全全程严格使用TypeScript

实施指南

对于参与此项目的大型语言模型（LLM）实施者：

先决条件

# Deno 2.5+
deno --version

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

开发环境设置

# 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

测试

# MCP Server tests
cd mcp-server
deno task test

# UI tests
cd fresh-ui
deno task test

关键设计决策

1. 分离进程

为什么清晰的职责分离，独立开发，即时热重载 自然运作

考虑的备选方案在MCP服务器中嵌入Fresh应用程序（过于复杂）

2. WebSocket通信

为什么实时更新，低延迟，双向通信

考虑的备选方案HTTP轮询（延迟较高，开销较大）

3. bb-mcp-server 库

为什么经过验证的基础设施、插件系统、内置会话管理

考虑的备选方案原始MCP SDK（更多样板代码，重复造轮子） （基础设施）

4. Deno KV 存储

为什么内置、快速、简单的API，非常适合会话数据

考虑过的备选方案外部数据库（v1.0版本中无需如此复杂）

5. 新鲜群岛

为什么极简JavaScript，快速渲染，易于理解

已考虑的备选方案SPA框架（复杂度更高，包体积更大）

成功指标

功能

  • ✅ 成功测试了采样请求和响应
  • ✅ 成功测试了触发流程（接受/拒绝/取消）
  • ✅ 成功触发并验证通知
  • ✅ 清晰显示所有MCP协议消息
  • ✅ 支持多个连接的客户端（HTTP模式）

可用性

  • ✅ 简单设置（从克隆到运行少于5分钟）
  • ✅ 直观的用户界面（学习曲线极小）
  • ✅ 清晰的错误信息和反馈
  • ✅ 响应式实时更新

质量

  • ✅ 全面的测试覆盖率（>80%）
  • ✅ 为大型语言模型（LLM）使用提供清晰的文档说明
  • ✅ 包含示例测试场景
  • ✅ 准生产就绪的错误处理

贡献

这个项目旨在由大型语言模型（LLMs）按照全面的（规划/指南/步骤）来实施 设计文档。在贡献时：

  1. 先阅读相关的设计文档
  2. 遵循实施阶段
  3. 在实现的同时编写测试
  4. 根据需要更新文档
  5. 确保全程类型安全

许可证

麻省理工学院许可证（推荐以促进最大范围的采用）

项目状态

当前设计完成 - 准备实施

  • ✅ 完整的设计文档
  • ✅ 架构确定
  • ✅ 已指定类型定义
  • ✅ 已确定测试策略
  • ✅ 已规划实施阶段
  • 🔨 实施状态：尚未开始

下一步行动

对于实施者：

  1. 请查阅 PROJECT_OVERVIEW.md 以了解背景信息
  2. 阅读 ARCHITECTURE.md 文件以了解系统架构
  3. 按照IMPLEMENTATION_PHASES.md开始实施第一阶段
  4. 根据需要引用特定的设计文件
  5. 按照 TESTING_STRATEGY.md 编写测试

仓库（或存储库）

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

JSR 包： @beyondbetter/bb-mcp-client-inspector

项目版本0.1.0（设计阶段） 文档版本1.0 最后 已更新2025年10月22日 状态设计完成 - 准备实施

为MCP社区倾心打造

相关 MCP