知识教练MCP演示
全栈演示 模型上下文协议（MCP） 具有流式Python服务器和React web客户端，通过 流式HTTP 运输。专为演示、研讨会和培训MCP概念的新学习者而设计。
架构概述
┌───────────────────────────┐ JSON-RPC 2.0 ┌──────────────────────────────┐
│ React Web Client │ ◄──── Streamable HTTP ────► │ Python MCP Server │
│ (Vite + TypeScript) │ POST /mcp/ │ (FastAPI + FastMCP) │
│ │ │ │
│ ┌─────────────────────┐ │ │ ┌────────────────────────┐ │
│ │ McpStreamClient │──┼──────── initialize ─────────►│ │ StreamableHTTP ASGI │ │
│ │ (services/) │ │ mcp-session-id │ │ Session Manager │ │
│ │ │◄─┼──────── session header ──────│ │ │ │
│ │ │──┼──────── tools/call ──────────►│ │ ┌──────────────────┐ │ │
│ │ │◄─┼──────── structuredContent ───│ │ │ InMemoryEventStore│ │ │
│ └─────────────────────┘ │ │ │ └──────────────────┘ │ │
│ │ │ └────────────────────────┘ │
│ ┌─────────────────────┐ │ │ │
│ │ useChatSession │ │ │ ┌────────────────────────┐ │
│ │ (hooks/) │ │ │ │ MCP Capabilities │ │
│ └─────────────────────┘ │ │ │ ├─ Resources (2) │ │
│ │ │ │ ├─ Tools (1) │ │
│ ┌─────────────────────┐ │ │ │ └─ Prompts (1) │ │
│ │ ChatWindow │ │ │ └────────────────────────┘ │
│ │ (components/chat/) │ │ │ │
│ └─────────────────────┘ │ │ ┌────────────────────────┐ │
│ │ │ │ KnowledgeBase │ │
│ │ │ │ (knowledge_base.yaml) │ │
└───────────────────────────┘ └──────────────────────────────┘
localhost:5173 127.0.0.1:8000
技术栈
| 层 | 技术 | 目的 |
|---|
| 后端运行时 | Python 3.11+ | 服务器语言 |
| MCP框架 | FastMCP (mcp 包） | MCP协议抽象（资源、工具、提示） |
| Web框架 | FastAPI 0.115+ | HTTP路由、CORS、生命周期挂钩 |
| ASGI服务器 | Uvicorn 0.30+ | 生产级异步服务器 |
| 上海证券交易所 | sse starlette 1.8+ | 服务器发送流媒体事件 |
| 验证 | Pydantic 2.8+ | 数据模型和设置 |
| 程序包管理器 | 紫外线 >=0.9 | 快速Python依赖管理 |
| 前端框架 | React 19.2 | UI组件 |
| 语言 | TypeScript 5.9 | 类型安全的前端代码 |
| 构建工具 | Vite 7.2 | 开发服务器和捆绑器 |
| 样式 | CSS（自定义属性） | 无框架，轻量级主题 |
| 协议 | MCP流式HTTP | 基于HTTP的JSON-RPC 2.0，具有会话管理功能 |
| 测试 | pytest+pytest-asyncio | 服务器单元和集成测试 |
| 代码检查 | ESLint 9 | 前端代码质量 |
项目布局
.
├── server/ # Python MCP server
│ ├── pyproject.toml # Dependencies and CLI entry points
│ ├── src/knowledge_coach/
│ │ ├── main.py # FastAPI app + FastMCP wiring
│ │ ├── config.py # Environment-based settings (KC_ prefix)
│ │ ├── models.py # Pydantic response models
│ │ ├── knowledge_base.py # In-memory resource search engine
│ │ ├── knowledge_base.yaml # 12+ training resource fixtures
│ │ ├── event_store.py # Session event replay store
│ │ ├── resources.py # MCP resource registrations
│ │ ├── tools.py # MCP tool registrations
│ │ ├── prompts.py # MCP prompt template registrations
│ │ └── cli.py # Dev CLI (inspector, config export)
│ └── tests/ # pytest suite
│ ├── test_knowledge_base.py # Knowledge base unit tests
│ └── test_streamable_http.py # MCP protocol integration test
│
└── web/ # React + Vite chat client
├── package.json # NPM dependencies and scripts
└── src/
├── config.ts # MCP endpoint configuration
├── types/mcp.ts # TypeScript interfaces matching server models
├── services/mcpClient.ts # Low-level MCP Streamable HTTP client
├── hooks/useChatSession.ts # Chat session state management hook
└── components/
├── AppShell.tsx # Layout wrapper with header
└── chat/
├── ChatWindow.tsx # Main chat UI (messages, composer, status)
└── ChatPlaceholder.tsx # Welcome screen with setup steps
MCP能力暴露
资源（只读数据）
| URI | 描述 |
|---|
resource://knowledge-coach/resources | 所有培训资源的Markdown目录 |
resource://knowledge-coach/{resource_id} | 单个资源的详细视图 |
工具（可执行操作）
| 工具 | 参数 | 返回 |
|---|
coach_resources | question, experience_level, max_results | CoachingResponse 标题、评分建议和下一步行动 |
提示（LLM模板）
| 提示 | 参数 | 说明 |
|---|
demo_run_of_show | audience, focus_topic | 使用动态匹配的资源生成演示脚本 |
先决条件
- Python 3.11+
uv >= 0.9- Node.js 20+
快速开始
1.MCP服务器
cd server
uv sync --extra dev # install dependencies (runtime + pytest)
uv run knowledge-coach-server
服务器正在监听 http://127.0.0.1:8000 MCP端点位于 http://127.0.0.1:8000/mcp/.
其他服务器命令：
| 命令 | 目的 |
|---|
uv run knowledge-coach-dev | 具有热重新加载功能的开发服务器 |
uv run knowledge-coach-inspector | 启动MCP检查器UI |
uv run knowledge-coach-inspector-config | 出口 inspector.config.json |
2.React Web客户端
cd web
npm install
npm run dev
开放时间： http://localhost:5173。要覆盖MCP端点，请创建 web/.env.local:
VITE_MCP_BASE_URL=http://127.0.0.1:8001/mcp/
运行测试和检查
# Server tests (from server/)
uv run pytest
# Frontend lint + type check (from web/)
npm run lint
npm run build
演示流程
- 启动MCP服务器：
uv run knowledge-coach-server - （可选）启动MCP检查器：
uv run knowledge-coach-inspector --交互式浏览资源、工具和提示 - 启动React应用程序：
npm run dev 并打开 http://localhost:5173 - 输入提示（例如。 *“为采用MCP的销售工程师设计培训计划”*)，选择一个体验级别，然后单击 生成推荐
- 客户端执行MCP握手，调用
coach_resources，并呈现具有匹配分数和下一步的结构化推荐
环境变量
服务器(KC_ 前缀，或 .env 归档 server/)
| 变量 | 默认值 | 描述 |
|---|
KC_HOST | 127.0.0.1 | 服务器绑定地址 |
KC_PORT | 8000 | 服务器端口 |
KC_RELOAD | false | 启用热重新加载 |
KC_ALLOWED_ORIGINS | http://localhost:5173 | CORS允许的来源（逗号分隔） |
KC_SERVER_NAME | Knowledge Coach MCP | MCP握手中的服务器名称 |
Web（Vite环境变量，或 .env.local 在 web/)
| 变量 | 默认值 | 描述 |
|---|
VITE_MCP_BASE_URL | http://127.0.0.1:8000/mcp/ | MCP服务器端点 |
故障排除
| 问题 | 解决方案 |
|---|
客户留下 idle 或显示 error | 在打开React应用程序之前，确保服务器正在运行 |
| CORS错误 | 将您的客户端源添加到 KC_ALLOWED_ORIGINS |
| 检查器无法连接 | 验证服务器是否正在运行 http://127.0.0.1:8000/mcp/ |
| 端口已在使用中 | 终止现有进程或更改 KC_PORT |
进一步阅读
