使用说明

MCP检查员教学应用程序

一种实时可视化模型上下文协议（MCP）通信的教育工具

特性 • 快速开始 • 用法 • 建筑 • 文档

概述

这 MCP检查员教学应用程序 是一个基于Next.js的教育工具，旨在通过提供LLM驱动的聊天界面和MCP服务器之间完整通信流的透明、实时可视化来揭开模型上下文协议（MCP）的神秘面纱。

什么是MCP？

这模型上下文协议（MCP）是一种开放协议，使人工智能应用程序能够安全地连接到数据源和工具。将其视为一个通用适配器，允许AI助手访问数据库、API、文件系统等，而无需为每个源进行自定义集成。

为什么是这个应用程序？

理解MCP可能具有挑战性，因为该协议涉及多个参与者（主机应用程序、LLM、MCP服务器）通过复杂的消息序列进行通信。此应用程序通过以下方式使学习MCP变得直观：

可视化5阶段工作流程 从初始化到最终响应
表明LLM从不直接调用MCP服务器 （主机应用程序协调一切）
记录每个协议消息和内部操作 实现完全透明
保持严格的垂直对齐 这样你就可以追踪参与者之间的因果关系

特性

🎯 核心能力

基于演员的时间线可视化 -五列布局，显示主机应用程序、LLM和MCP服务器作为单独的参与者
完整的协议覆盖范围 -MCP工作流程的所有5个阶段（初始化、发现、选择、执行、综合）
实时事件流 -实时时间线更新的服务器发送事件（SSE）
交互式消息卡 -单击以展开/折叠JSON-RPC消息，并突出显示语法
持久MCP连接 -用于有状态服务器连接的全局单例客户端
两相LLM推理 -清楚地显示了计划（工具选择）与综合（最终响应）的分离

🔍 教育特色

预配置的AWS文档MCP服务器 -无需API密钥，可立即工作
建议查询 -三个示例查询展示了不同的交互模式
垂直对齐系统 -处于同一高度的事件之间存在因果关系
控制台日志 -查看所有参与者（主机、LLM、MCP服务器）的内部操作
性能指标 -跟踪每个阶段的处理时间

🛠️ 技术特性

内置 Next.js 15 （应用路由器）和 反应19
TypeScript 始终具有严格的型号安全性
Tailwind CSS 响应式设计
状态用于国家管理
已测试 使用Jest+React测试库（49项测试通过）
优化使用React.memo查看100多个时间线事件

快速开始

先决条件

在开始之前，请确保您已经：

Node.js 20+ （推荐LTS）
npm或pnpm （包管理器）
Python 3.10+ （适用于MCP服务器）
紫外线 （Python包管理器）- 安装uv
无烟煤API密钥 -得到一个在 console.anthropic.com

安装

克隆存储库

git clone <repository-url>
cd mcp-visualizer

cd mcp-inspector-app

重要提示： 所有后续命令都应从 mcp-inspector-app 目录！

安装依赖项

npm install

设置环境变量

创建一个 .env.local 当前目录中的文件(mcp-inspector-app):

# Copy the example file
cp .env.local.example .env.local

# Edit .env.local and add your API key
ANTHROPIC_API_KEY=sk-ant-...your-key-here...

验证AWS文档MCP服务器

该应用程序使用AWS文档MCP服务器，该服务器需要 uvx （部分 uv 包管理器）：

# Test that uvx is installed
uvx --version

# Verify the MCP server package can be installed (this will download it)
uvx awslabs.aws-documentation-mcp-server@latest

注：服务器命令将显示为挂起-这是正常的！它正在等待通过stdin输入JSON-RPC。按 Ctrl+C 退出。只要你看到“已安装的X软件包”没有错误，你就可以开始了！

运行应用程序

# Start the development server
npm run dev

该应用程序将在 http://localhost:3000 （如果使用3000，则使用下一个可用端口）。

用法

首次用户体验

当你第一次打开应用程序时，你会看到：

时间轴查看 -五列代表基于参与者的架构
建议查询 -三个预先配置的示例开始使用
连接状态 -显示MCP服务器何时连接并准备就绪

运行第一个查询

尝试建议的查询： “在AWS文档中搜索S3存储桶命名规则”

点击 “尝试此查询” 按钮或手动输入查询
按发送或按Enter键
实时查看时间线填充情况：
- 第一阶段： 初始化和协商（如果尚未连接）
- 第二阶段： 工具发现（列出可用的MCP工具）
- 第三阶段： 模型驱动选择（LLM计划使用哪些工具）
- 第四阶段： 执行往返（MCP服务器调用AWS API）
- 第五阶段： 综合与最终响应（LLM生成自然语言答案）

理解时间线

列布局

五列布局对于理解MCP至关重要：

列	宽度	用途
主机应用程序	20%	聊天界面、编排逻辑、控制台日志
主机↔ LLM	15%	显示LLM API请求/响应的通信通道
LLM	15%	LLM推理处理和内部操作
主机↔ 主控程序	15%	显示JSON-RPC消息的通信通道
MCP服务器	35%	服务器操作、工具执行、外部API调用

关键见解： 请注意，LLM和MCP服务器列之间没有直接连接。Host App负责协调所有通信！

消息卡类型

通信通道中的信息卡使用颜色编码的边框：

🟢 绿色左边框 -REQUEST（需要响应）
🔵 蓝色右边框 -响应（回复请求）
🟣 紫色左边框 -通知（预期无响应）
🔴 红色边界 -错误

单击任何消息卡以展开并查看带有语法突出显示的完整JSON有效负载。

控制台日志徽章

控制台日志显示了带有颜色编码徽章的内部操作：

用户输入 （灰色）-用户提交了一条消息
系统（蓝色）-系统事件（连接、握手）
内部（灰色）-内部处理（模式转换等）
LLM （indigo）-LLM推理操作
服务器 （绿色）-MCP服务器操作
日志（黄色）-一般信息日志
完成（灰色）-工作流完成标记

建议查询

该应用程序包括三个教学查询：

1.单工具示例

查询： “在AWS文档中搜索S3存储桶命名规则”

通过一个工具调用演示最简单的工作流。非常适合首次使用的用户。

2.多工具示例

查询： “查找S3存储桶命名规则并向我显示相关主题”

显示LLM在阶段4中选择多个工具并顺序执行它们。

3.模型驱动选择

查询： “Lambda函数的安全最佳实践是什么？”

演示LLM根据查询意图自主选择正确的工具。

交互式功能

展开/折叠邮件 -单击任何消息卡以切换JSON有效负载可见性
滚动时间线 -时间线垂直滚动；所有列保持对齐
阶段标题 -粘性标题显示你处于哪个阶段
状态栏 -底部栏显示连接状态和事件计数

建筑

基于演员的设计

该应用程序使用 基于参与者的架构 受序列图的启发：

┌──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
│ Host App     │ Host ↔ LLM   │ LLM          │ Host ↔ MCP   │ MCP Server   │
│ (20%)        │ (15%)        │ (15%)        │ (15%)        │ (35%)        │
├──────────────┼──────────────┼──────────────┼──────────────┼──────────────┤
│ Chat UI      │ LLM Request  │ Processing   │ initialize   │ Handshake    │
│ Console Logs │ Cards        │ Indicators   │ tools/list   │ Tool Exec    │
│ User Input   │              │              │ tools/call   │ External API │
└──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
    ▲                                                              ▲
    │                                                              │
    └──────────  Host orchestrates all communication   ────────────┘

(LLM never talks directly to MCP)

五阶段MCP工作流程

每个查询都遵循此符合协议的工作流程：

初始化和协商 -三条信息握手(initialize → 响应→ initialized)
发现与情境化 - tools/list 请求查找可用工具
模型驱动选择 -首次LLM推理（规划）返回 tool_use 块
执行往返 - tools/call 向MCP服务器发出请求，该服务器委托给外部API
综合与最终回应 -第二LLM推理（合成）生成自然语言答案

关键教学点： 法学硕士有两个要求——一个是规划，一个是综合。这经常被误解！

技术栈

前端： Next.js 15（应用路由器）、React 19、TypeScript 5
造型： 顺风CSS 4
状态管理： 状态 5
MCP集成： @模型上下文协议/sdk v1.20
LLM集成： @人工智能/sdk v0.65
实时事件： 服务器发送事件（SSE）
测试： Jest 30+React测试库16

垂直对齐系统

最重要的UI要求： 所有列均通过以下方式保持严格的垂直对齐 间隔块.

当一个参与者有活动时（例如，MCP服务器记录多条消息），其他列会呈现空的间隔块以保持对齐。这允许用户在时间线上水平追踪因果关系。

看 docs/模块5验证结果.md 作为视觉示例。

文档

主要文件

MVP产品需求文档 -完整的产品规格
技术设计文件 -架构和实施细节
MCP序列图 -符合协议的序列图
事件记录系统图 -事件架构和回放支持

视觉设计

原始交互式HTML模型 -静态HTML原型

发展

项目结构

mcp-visualizer/
├── mcp-inspector-app/          # Next.js application
│   ├── app/                    # Next.js App Router pages
│   │   ├── api/                # API routes (workflow, events, LLM, MCP)
│   │   ├── demo/               # Demo page (removed - see timeline)
│   │   └── timeline/           # Main timeline page
│   ├── components/             # React components
│   │   ├── actors/             # Actor column components
│   │   ├── grid/               # Grid layout components
│   │   ├── lanes/              # Communication lane components
│   │   └── timeline/           # Timeline view components
│   ├── lib/                    # Core libraries
│   │   ├── mcp/                # MCP client integration
│   │   ├── llm/                # Claude API integration
│   │   ├── orchestration/      # 5-phase workflow orchestration
│   │   ├── event-builder.ts    # Event creation helpers
│   │   ├── layout-engine.ts    # Row building & spacer insertion
│   │   └── constants.ts        # Colors, badge types, etc.
│   ├── store/                  # Zustand state management
│   ├── types/                  # TypeScript type definitions
│   └── __tests__/              # Jest unit tests
├── mcp_visualizer/             # Python POC (reference implementation)
│   └── poc/                    # Validated Python proof-of-concept
└── docs/                       # Documentation and validation reports

运行测试

注：从运行以下命令 mcp-inspector-app 目录。

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

当前状态： 49项测试通过（26个事件生成器+23个布局引擎）

生产大楼

注：从运行以下命令 mcp-inspector-app 目录。

# Build optimized production bundle
npm run build

# Start production server
npm start

环境变量

创建 .env.local 在 mcp-inspector-app 目录：

# Required: Anthropic API key for Claude
ANTHROPIC_API_KEY=sk-ant-...your-key-here...

# Optional: Override default MCP server command
# MCP_SERVER_COMMAND=uvx
# MCP_SERVER_ARGS=awslabs.aws-documentation-mcp-server@latest

故障排除

MCP服务器无法连接

如果AWS文档MCP服务器无法连接：

验证是否安装了uvx：
```
uvx --version
```
如果未找到，请安装uv： https://docs.astral.sh/uv/

测试服务器软件包安装：

# This will download and cache the package
uvx awslabs.aws-documentation-mcp-server@latest
# Press Ctrl+C to exit (it's normal for it to wait for input)

检查控制台日志 在浏览器DevTools中查看特定错误消息

查找MCP服务器日志 在你跑步的终点站 npm run dev -您应该看到以下消息：

[MCPGlobalClient] Connecting to: uvx awslabs.aws-documentation-mcp-server@latest
[MCPGlobalClient] Connection established

LLM API错误

如果您看到“找不到API密钥”或身份验证错误：

验证您的 .env.local 文件存在 在 mcp-inspector-app/
检查API密钥格式 （开始于 sk-ant-)
重新启动开发服务器 更新后 .env.local

时间线未更新

如果时间线没有填充事件：

检查浏览器控制台 JavaScript错误
验证SSE连接 已建立（检查DevTools中的“网络”选项卡）
尝试刷新页面 重新启动事件流

性能问题

如果时间线在许多事件中感觉很慢：

该应用程序针对100多个活动进行了优化。如果你看到500+，性能可能会下降。
清除时间线并开始新的会话
检查模块10的性能基准验证结果

贡献

这是一个教育项目，旨在教授模型上下文协议。欢迎投稿！

开发工作流程

分叉存储库
创建要素分支
进行更改
如果适用，添加测试
跑 npm test 和 npm run build 验证
提交拉取请求

代码的风格

TypeScript严格模式已启用
尾风CSS造型
遵循现有的组件模式
用注释记录复杂的逻辑

了解更多

MCP资源

模型上下文协议规范： https://modelcontextprotocol.io/specification
MCP文件： https://modelcontextprotocol.io/docs
MCP TypeScript SDK： https://github.com/modelcontextprotocol/typescript-sdk
AWS文档MCP服务器： https://awslabs.github.io/mcp/servers/aws-documentation-mcp-server

API资源

人类学文献： https://docs.anthropic.com
工具使用指南： https://docs.anthropic.com/en/docs/tool-use
TypeScript SDK： https://github.com/anthropics/anthropic-sdk-typescript

Next.js资源

Next.js文档： https://nextjs.org/docs
应用路由器指南： https://nextjs.org/docs/app

许可证

[在此处添加您的许可证信息]

致谢

模型上下文协议团队 -创建优秀的开放协议
AWS实验室 -对于AWS文档MCP服务器
Anthropic -对于克劳德和工具使用能力
Next.js团队 -强大的React框架

内置❤️ 教授模型上下文协议

报告错误 • 请求功能