AI导哈

MCP协议测试工具

一款基于浏览器的JavaScript工具，用于测试和调试MCP（Model Context Protocol）服务器，支持完整的协议验证和实时错误检测。

  • by didierphmartin
  • HTML
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 didierphmartin/mcPeek

使用说明

MCPeek🔍

了解MCP协议合规性

由Didier PH Martin和Claude Code（人类学）创建

一个基于浏览器的JavaScript工具，用于测试和调试具有完整协议验证的MCP（模型上下文协议）服务器。

“一次偷看胜过一千次失误”

MCPeek的直观界面显示了服务器管理、协议验证、可用工具和实时活动记录

👥 项目团队

  • 迪迪埃·马丁 -项目负责人、愿景、测试和验证
  • 克劳德密码（来自Anthropic） -技术实施和文件

MCPeek诞生于现实世界的调试挑战。当传统的MCP测试工具无法捕捉到微妙的协议违规时，我们合作构建了更好的东西。

特性

🎨 现代用户界面

  • 自定义服务器管理：使用干净的界面添加、编辑和删除多个MCP服务器
  • 可折叠截面：有组织的UI，具有可扩展的部分，用于服务器和身份验证、服务器信息、协议验证、可用工具和活动日志
  • 视觉状态指示器：实时连接状态，带有颜色编码的成功/错误消息
  • 活动日志：显示详细连接步骤和服务器交互的带时间戳的日志
  • 许可证管理：为经过身份验证的连接内置OAuth令牌刷新控件

✅ 完全支持MCP协议

  • 完成握手实施:
    1. initialize 具有适当参数的请求
    2. notifications/initialized 通知
    3. tools/list 请求
  • 正确的标题：发送 mcp-protocol-version: 2024-11-05
  • JSON-RPC 2.0合规性：所有消息均遵循JSON-RPC 2.0规范

🔍 协议验证与调试

  • 实时验证 带有视觉指示器的服务器响应
  • 详细的错误消息 解释到底出了什么问题
  • 协议合规性检查器 这验证了：
    • capabilities.tools 是一个物体 {}，不是数组 []
    • inputSchema.properties 是对象，不是数组
    • JSON-RPC 2.0消息格式
    • 必填字段存在
    • 正确的数据类型

🛠️ 交互式工具测试

  • 工具卡：显示每个可用工具的名称、描述和参数
  • 参数详细信息：显示所有输入参数及其类型和描述
  • 一键测试：“调用工具”按钮，用于立即执行工具
  • 参数表单：从工具模式生成的动态表单

🎯 是什么让这与众不同

此客户端捕获了我们在备忘录MCP服务器中解决的确切问题：

  1. 空数组与空对象检测

    • ❌ 检测： "capabilities": { "tools": [] }
    • ✅ 预期： "capabilities": { "tools": {} }

  2. 工具模式验证

    • ❌ 检测： "inputSchema": { "properties": [] }
    • ✅ 预期： "inputSchema": { "properties": {} }

  3. 缺少通知/已初始化

    • 初始化后正确发送通知
    • 帮助服务器实现正确的MCP握手

  4. 清除错误报告

    • 你得到的不是“连接失败”，而是：
    • "❌ 关键：capabilities.tools必须是对象｛｝，而不是数组[]“
    • “修复：将”工具“：[]更改为”工具“:｛｝或”工具“（对象）[]”

🤖 LLM辅助调试（突破性功能！）

MCPeek的错误消息旨在直接输入LLM以进行自动修复！

工作流程：

1. MCPeek detects protocol violation
2. Copy the detailed error message
3. Paste into Claude/ChatGPT/any LLM with prompt:
   "Fix this MCP protocol violation in my code: [paste error]"
4. LLM generates the exact fix
5. Apply the fix
6. Re-test with MCPeek
7. ✅ Validation passes!

例子：

MCPeek错误：

❌ CRITICAL: capabilities.tools must be an object {}, not an array []
   Fix: Change "tools": [] to "tools": (object)[]
   Location: mcp.php, handleInitialize function

粘贴到LLM：

I got this error from MCPeek. Please fix my PHP code:

❌ CRITICAL: capabilities.tools must be an object {}, not an array []
   Fix: Change "tools": [] to "tools": (object)[]

My current code:
[paste your code]

LLM回复：

// Change this:
'capabilities' => [
    'tools' => []
]

// To this:
'capabilities' => [
    'tools' => (object)[]
]

为什么有效：

  • ✅ MCPeek提供准确的错误位置
  • ✅ 清楚地解释出了什么问题
  • ✅ 具体修复建议
  • ✅ LLM具有所需的所有上下文
  • ✅ 几分钟内自动修复代码！

这创建了一个反馈循环：MCPeek→ LLM → Fix → MCPeek→ ✅

用法

1.访问客户端

在浏览器中打开应用程序：

# Make sure your web server is running
open http://localhost/mcPeek/

2.添加您的MCP服务器

  1. 展开 🔒 服务器和身份验证 章节
  2. 点击 ➕ 添加自定义MCP服务器
  3. 填写表格：
    • 服务器名称例如。， Memo Server
    • 服务器URL例如。， http://localhost/memo/mcp.php
    • 描述 （可选）：服务器的简要说明
  4. 点击 添加服务器
  5. 您的服务器出现在“自定义服务器”列表中 编辑 和 移除 按钮

3.连接和测试

  1. 从中选择您的服务器 选择MCP服务器 下拉菜单
  2. 点击 连接 -查看活动日志以了解连接进度
  3. 在中查看协议验证结果 🔍 协议验证 章节
  4. 浏览中的可用工具 🔧 可用工具 章节
  5. 点击 呼叫工具 在任何工具上使用参数进行测试

4.管理连接

  • 刷新令牌：刷新经过身份验证的服务器的OAuth令牌
  • 断开：关闭当前连接
  • 重置：清除所有数据并重新开始
  • 编辑/删除：管理您的自定义服务器列表

方案验证小组

连接后，您将看到：

✅ 符合协议的服务器

✅ Initialize Response - Protocol Compliant
✅ Tools List Response - Protocol Compliant

❌ 不符合要求的服务器

❌ Initialize Response - Protocol Violations Found

Errors (2):
• ❌ CRITICAL: capabilities.tools must be an object {}, not an array []
  Fix: Change "tools": [] to "tools": {} or "tools": (object)[]
• Missing "protocolVersion" in initialize result

Warnings (1):
• Missing "serverInfo.version" (recommended)

文件

  • index.html -主客户端界面
  • MCPProtoColValidator.js -协议验证逻辑
  • SSEMCPClient.js -苏格兰和南方能源公司运输支持
  • MCPOAuthClient.js -OAuth 2.1授权客户端
  • oauth-callback.html -OAuth回调处理程序
  • OAUTH_SPEC.md -完整的OAuth实现规范

支持的功能

🔐 OAuth 2.1授权（新增！）

  • 完全支持OAuth 2.1 用于受保护的MCP服务器
  • 自动发现 授权服务器（RFC 9728）
  • PKCE与S256 安全性（RFC 7636）
  • 资源指标 防止令牌滥用（RFC 8707）
  • 令牌刷新 以及自动过期处理
  • 加强授权 对于其他范围
  • 动态客户端注册 （RFC 7591）

OAuth流程：

  1. 客户端尝试连接→ 接收401
  2. 从受保护的资源元数据中发现授权服务器
  3. 打开带有PKCE挑战的OAuth弹出窗口
  4. 用户授权范围
  5. 交换访问令牌的授权码
  6. 使用Bearer令牌恢复MCP连接
  7. 过期时自动刷新令牌

看 OAUTH_SPEC.md 了解完整的实施细节。

支持的交通工具

HTTP（基于HTTP的JSON-RPC）

  • 直接POST请求
  • OAuth 2.1授权支持
  • 完整方案验证
  • 令牌管理

SSE（服务器发送事件）

  • 实时双向通信
  • 支持流式响应
  • OAuth令牌注入

MCP协议参考

初始化握手

// 1. Client sends initialize
POST /mcp.php
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "clientInfo": { "name": "...", "version": "..." }
  }
}

// 2. Server responds
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },  // MUST be object!
    "serverInfo": { "name": "...", "version": "..." }
  }
}

// 3. Client sends notification (no 'id', no response expected)
POST /mcp.php
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized",
  "params": {}
}

// 4. Client requests tools
POST /mcp.php
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

检测到的常见问题

问题1：数组而不是对象

问题：

'capabilities' => [
    'tools' => []  // ❌ Wrong!
]

修复：

'capabilities' => [
    'tools' => (object)[]  // ✅ Correct!
]

问题2：缺少通知处理程序

问题： 服务器无法处理 notifications/initialized

修复：

case 'notifications/initialized':
    // Acknowledge, no response needed
    if (!isset($request['id'])) {
        http_response_code(200);
        exit;
    }
    break;

问题3：缺少CORS标头

问题： 浏览器无法发送自定义标头

修复：

header('Access-Control-Allow-Headers: Content-Type, Accept, mcp-protocol-version');

测试您的MCP服务器

  1. 启动服务器 （例如，用于PHP服务器的XAMPP）
  2. 打开客户端: http://localhost/quantis/backend/mcp_client2/
  3. 添加您的服务器 使用自定义服务器窗体
  4. 单击连接 并审查验证小组
  5. 修复任何协议违规 报道
  6. 测试工具 使用工具卡

贡献

此客户端旨在帮助MCP社区构建更好、更合规的服务器。请随意：

  • 报告问题
  • 提出改进建议
  • 添加对新传输的支持
  • 增强验证规则

许可证

MIT许可证

致谢

由...创建 克劳德代码 （Anthropic）帮助调试和验证MCP协议实现。

特别感谢MCP社区和致力于使协议更加健壮和可互操作的开发人员。

安全与合规

OAuth 2.1安全特性

  • ✅ PKCE（S256） -防止授权码被拦截
  • ✅ 资源指标 -防止混淆的副攻击
  • ✅ 状态验证 -CSRF保护
  • ✅ 令牌存储 -sessionStorage用于访问令牌，localStorage用于刷新令牌
  • ✅ HTTPS强制 -所有授权端点都需要
  • ✅ 令牌刷新 -自动轮换和过期处理

MCP协议合规性

  • ✅ JSON-RPC 2.0 -所有消息均符合JSON-RPC 2.0
  • ✅ 协议版本 -用途 mcp-protocol-version: 2024-11-05 头球
  • ✅ 完整握手 -初始化→ 通知/已初始化→ 工具/列表
  • ✅ 验证 -实时协议合规性检查

协议版本： 2024-11-05（2025年6月OAuth更新） 客户端版本： 2.1.0 OAuth版本： OAuth 2.1 最后更新时间： 2025-12-10

最近更新（v2.1.0）

UI/UX改进

  • ✨ 具有编辑/删除功能的增强服务器管理
  • 📊 可折叠部分，便于更好地组织
  • 🎨 视觉状态指示器和颜色编码信息
  • 📝 带有时间戳的实时活动日志
  • 🔄 主界面中的令牌刷新控件
  • 🎯 带有详细参数显示的交互式工具卡

用户体验

  • 通过可扩展部分改进导航
  • 更好的连接状态视觉反馈
  • 简化服务器配置工作流程
  • 通过详细的活动日志记录增强调试

相关 MCP