MCP 工具测试器

一个功能完善的 MCP (Model Context Protocol) 工具测试应用，支持连接 MCP 服务器、列出工具、配置参数并执行工具调用。

功能特性

✨ 完整的 MCP 支持

支持新版 Streamable HTTP 协议（2025-06-18）
支持旧版 HTTP+SSE 协议（2024-11-05）
自动协议检测和切换
保持 SSE 连接的后台监听

🎨 现代化界面

三栏布局：工具列表 | 参数配置 | 结果+日志
动态参数表单自动生成
支持所有 MCP 参数类型
可拖动调整的日志区域
实时彩色日志输出
智能日志自动滚动
鼠标悬停显示工具详细信息
自定义标题栏（可拖动窗口）

🔧 强大的工具支持

自动列出所有可用工具
根据工具定义动态生成表单
支持 string、number、boolean、enum、object、array 类型
必需参数自动验证
JSON 自动格式化显示

🎨 现代化窗口

自定义标题栏设计
拖动标题栏移动窗口
双击标题栏最大化/还原
优雅的窗口控制按钮
悬停高亮效果

快速开始

1. 安装依赖

cd mcp-ui
flutter pub get

2. 运行应用

flutter run -d macos

或者选择其他平台：

flutter run -d windows
flutter run -d linux

3. 连接到 MCP 服务器

在顶部输入框输入 MCP 服务器地址，例如：
```
http://127.0.0.1:18080/sse
```
点击 [连接] 按钮
等待连接成功，工具列表会自动加载

4. 使用工具

选择工具 - 在左侧列表中点击任意工具
填写参数 - 根据参数类型填写表单
执行工具 - 点击绿色的"执行工具"按钮
查看结果 - 结果显示在右上方，日志显示在右下方

界面布局

┌────────────────────────────────────────────────────────┐
│  🔗 MCP 服务器地址  [连接/断开]  ● 状态                  │
├──────────┬───────────────────┬──────────────────────┤
│          │                   │  📋 执行结果           │
│  工具    │  ⚙️ 参数配置       │  ┌──────────────────┐ │
│  列表    │                   │  │ JSON 结果显示     │ │
│  ┌────┐  │  参数1: _______   │  │                  │ │
│  │工具1│  │  参数2: _______   │  └──────────────────┘ │
│  │工具2│  │  参数3: _______   │  ═══ 拖动调整 ═══   │
│  │工具3│  │                   │  🖥️ 调试日志          │
│  └────┘  │  [▶ 执行工具]      │  ┌──────────────────┐ │
│          │                   │  │ 📡 🔧 ✅ ❌       │ │
└──────────┴───────────────────┴──────────────────────┘

参数类型支持

文本 (string)

名称: [文本输入框]

数字 (number/integer)

数量: [数字输入框]  (自动验证)

布尔 (boolean)

启用: ○ True  ○ False

枚举 (enum)

选项: [下拉选择框]

对象 (object)

配置: [多行 JSON 输入]
{"key": "value"}

数组 (array)

列表: [多行 JSON 输入]
["item1", "item2"]

工具列表悬停提示

鼠标悬停在左侧工具列表的任意工具上，会显示详细的工具信息：

🔧 工具名称

📝 描述：
工具的详细描述信息

⚙️ 参数：
  • 参数1 (必需) - string
    参数描述
    
  • 参数2 (可选) - number
    参数描述
    默认值: 10

💡 点击选择该工具

提示特性：

延迟 0.5 秒显示，避免误触
深色背景，白色文字，易于阅读
显示完整的参数列表和类型
标注必需参数和默认值
列出枚举类型的可选值

智能日志滚动

调试日志区域支持智能自动滚动，确保始终显示最新日志：

┌──────────────────────────────────────────┐
│ 🖥️ 调试日志              [▶ 自动] 🟢   │
├──────────────────────────────────────────┤
│ 12:34:56 🔄 开始连接...                  │
│ 12:34:57 📡 连接成功                     │
│ 12:34:58 🔧 获取工具列表...              │
│ 12:34:59 ✅ 找到 3 个工具                │
│ 12:35:00 ✅ 调用成功 ← 自动滚动到这里    │
│                         ┌──────────────┐ │
│                         │ ⬇ 跳到最新   │ │ (暂停时显示)
│                         └──────────────┘ │
└──────────────────────────────────────────┘

功能特性：

🔄 自动滚动 - 新日志产生时自动滚动到底部
⏸️ 智能暂停 - 向上滚动查看历史时自动暂停
⬇️ 快速返回 - 点击"跳到最新"按钮立即回到最新日志
🟢 状态指示 - 实时显示滚动模式（自动/暂停）
✨ 平滑动画 - 优雅的滚动过渡效果

使用方法：

默认模式：自动跟踪最新日志
向上滚动：自动切换到暂停模式
滚到底部：自动恢复自动滚动
点击按钮：快速跳到最新日志

自定义标题栏

应用使用自定义标题栏，提供更好的用户体验：

┌────────────────────────────────────────────────────────┐
│ 🔵 MCP 工具测试器          [刷新] [复制]  [_] [□] [×]  │
│ ← 可拖动区域 →                         ← 窗口控制 →   │
├────────────────────────────────────────────────────────┤
│  主内容区域...                                          │
└────────────────────────────────────────────────────────┘

功能特性：

🎯 拖动移动 - 点击标题栏任意位置拖动窗口
🔄 双击切换 - 双击标题栏最大化/还原窗口
🎨 悬停效果 - 按钮悬停显示高亮效果
❌ 关闭高亮 - 关闭按钮悬停显示红色
🔧 自定义按钮 - 支持添加自定义操作按钮

窗口控制：

[_] - 最小化窗口
[□] - 最大化/还原窗口
[×] - 关闭窗口（悬停时显示红色）

MCP 协议支持

新版 Streamable HTTP (推荐)

协议版本：2025-06-18
单一端点：/mcp
支持 POST 和 GET
会话管理：Mcp-Session-Id

旧版 HTTP+SSE (兼容)

协议版本：2024-11-05
SSE 端点：/sse（GET）
消息端点：/message（POST）
响应通过 SSE 流返回

应用会自动检测服务器协议版本并使用正确的通信方式。

调试功能

实时日志

右下角的日志区域显示所有操作的详细信息：

🔄 连接过程
📡 SSE 通信
📤 请求发送
📥 响应接收
🔧 工具操作
✅ 成功（绿色）
❌ 失败（红色）

可调整布局

拖动分隔线可调整日志区域高度（100px-600px）

复制功能

点击顶部 📋 图标复制所有日志
点击结果区 📋 图标复制执行结果

示例

连接到本地 MCP 服务器

# 启动示例 MCP 服务器
npx @modelcontextprotocol/server-example

# 或者使用 Playwright MCP
npx @playwright/mcp@latest --port 18080

然后在应用中输入地址并连接：

http://127.0.0.1:18080/sse

调用工具示例

假设有一个 search 工具：

参数：

query (string, 必需) - 搜索关键词
limit (number) - 结果数量限制

填写：

query: "Hello World"
limit: 10

执行结果：

{
  "results": [
    {"title": "...", "url": "..."},
    {"title": "...", "url": "..."}
  ],
  "total": 10
}

故障排查

问题 1: 连接失败

检查：

MCP 服务器是否正在运行？
地址和端口是否正确？
防火墙是否阻止连接？

解决：

# 测试 SSE 端点
curl -N -H "Accept: text/event-stream" http://127.0.0.1:18080/sse

问题 2: 工具列表为空

检查日志：

是否看到 "✅ Successfully connected"？
是否看到 "✅ Found X tools"？

可能原因：

服务器没有注册工具
SSE 连接断开
响应格式不正确

问题 3: 参数验证失败

原因： 必需参数未填写

解决： 填写所有带 [必需] 标记的参数

问题 4: JSON 格式错误

常见错误：

// ❌ 错误
{name: 'John'}

// ✅ 正确
{"name": "John"}

使用在线 JSON 验证器检查格式。

项目结构

mcp-ui/
├── lib/
│   ├── main.dart                    # 应用入口
│   ├── models/
│   │   └── mcp_tool.dart           # MCP 工具模型
│   ├── services/
│   │   ├── mcp_service.dart        # MCP 通信服务
│   │   └── app_state.dart          # 应用状态管理
│   └── screens/
│       ├── simple_test_screen.dart # 主测试界面
│       ├── home_screen.dart        # 原首页
│       └── mcp_debug_screen.dart   # 调试页面
├── test_mcp.py                     # Python 测试脚本
├── NEW_UI_GUIDE.md                 # 界面使用指南
├── QUICK_TEST.md                   # 快速测试指南
├── MCP_PROTOCOL_NOTES.md           # 协议说明
└── LEGACY_SSE_TROUBLESHOOTING.md   # 故障排查指南

技术栈

Flutter - 跨平台 UI 框架
Dart - 编程语言
Provider - 状态管理
HTTP - 网络请求
macos_ui - macOS 原生组件
window_manager - 窗口管理和自定义标题栏

开发

运行测试

flutter test

代码分析

flutter analyze

格式化代码

flutter format lib/

文档

NEW_UI_GUIDE.md - 详细的界面使用指南
QUICK_TEST.md - 快速测试指南
MCP_PROTOCOL_NOTES.md - MCP 协议详解
LEGACY_SSE_TROUBLESHOOTING.md - SSE 故障排查
CUSTOM_TITLE_BAR.md - 自定义标题栏详解
AUTO_SCROLL_LOG.md - 日志自动滚动功能详解

MCP 相关资源

更新日志

v2.3 (当前版本)

✅ 智能日志自动滚动
✅ 用户滚动时自动暂停
✅ "跳到最新"悬浮按钮
✅ 滚动状态实时指示
✅ 平滑滚动动画

v2.2

✅ 自定义标题栏（window_manager）
✅ 可拖动窗口位置
✅ 双击标题栏最大化/还原
✅ 优雅的窗口控制按钮
✅ 悬停高亮效果

v2.1

✅ 工具列表鼠标悬停提示
✅ 显示完整的工具信息和使用说明
✅ 美化的提示样式和动画

v2.0

✅ 全新的三栏界面布局
✅ 动态参数表单生成
✅ 支持所有 MCP 参数类型
✅ 可拖动调整的日志区域
✅ 旧版 SSE 协议完整支持
✅ 实时彩色日志输出
✅ 参数验证和类型转换
✅ JSON 自动格式化

v1.0

✅ 基础 MCP 连接
✅ 工具列表显示
✅ 简单的工具调用

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

联系

如有问题或建议，欢迎反馈。