知识教练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 |
进一步阅读
