使用说明
MCP演示UI和服务器套件
一个全面的交互式UI和演示服务器套件，用于学习和实验 模型上下文协议（MCP）.本项目包括：
- 🖥️ 交互式Web用户界面 -可视化MCP架构浏览器和服务器管理器
- 🔧 4台演示MCP服务器 -计算器、数据库、API集成和文件系统服务器
- 📚 教育内容 -通过动手示例学习MCP概念
- 🛠️ 工具测试界面 -实时执行MCP工具
- 📡 协议检查器 -监控MCP通信消息
- 🎯 生产就绪代码 -具有适当错误处理的异步/等待模式
🚀 快速开始
1.安装依赖项
uv sync
2.启动演示UI
uv run python ui_backend.py
3.在浏览器中打开
导航到： http://localhost:8000
4.探索与学习
- 查看MCP架构图
- 启动/停止演示服务器
- 交互式测试工具
- 监控协议消息
- 学习MCP概念
📖 什么是MCP？
模型上下文协议（MCP） 是一种开放协议，使人工智能助手和应用程序能够安全地访问外部数据源和工具。它为AI模型提供了一种标准化的方法：
- 🔌 连接到外部API -天气、新闻、数据库等。
- 💾 访问文件系统 -读/写文件和目录
- 🛠️ 执行自定义函数 -特定领域的业务逻辑
- 📊 查询数据库 -SQL操作和数据检索
- 🤖 扩展AI功能 -超越训练数据限制
MCP充当 桥 在人工智能应用程序和外部资源之间，允许模型通过以下方式扩展其功能 安全、标准化的接口.
🎯 为什么MCP很重要
MCP解决了人工智能应用程序开发中的关键挑战：
🔒 安全与控制
- 问题：人工智能模型对API的直接访问引发了安全问题
- 解决方案：MCP服务器充当具有适当身份验证的受控网关
📊 实时数据访问
- 问题：人工智能模型具有训练截止值，无法访问实时数据
- 解决方案：MCP服务器提供对实时API、数据库和服务的访问
🏗️ 标准化
- 问题：每个AI应用程序都需要自定义集成代码
- 解决方案：标准化的MCP协议适用于不同的AI应用程序
🛠️ 自定义业务逻辑
- 问题：通用AI模型不知道您的特定业务流程
- 解决方案：MCP服务器公开特定于域的工具和工作流
⚡ 动作执行
- 问题：AI模型只能生成文本，不能执行操作
- 解决方案：MCP服务器代表AI模型执行工具
🏛️ MCP架构
MCP遵循具有多种传输选项的客户端-服务器架构：
视觉架构
┌─────────────┐ MCP Protocol ┌─────────────┐
│ │ ◄──────────────────────────► │ │
│ MCP Client │ (JSON-RPC over stdio) │ MCP Server │
│ (AI App) │ │ (This App) │
│ │ │ │
└─────────────┘ └─────────────┘
│
│
┌───────┴───────┐
│ │
External APIs Databases
File Systems Services
关键组件
| 组件 | 描述 | 示例 |
|---|---|---|
| MCP客户端 | AI应用程序发出请求 | 克劳德桌面，定制AI应用程序 |
| MCP服务器 | 您的应用程序公开工具 | 此演示服务器 |
| 传输层 | JSON-RPC协议 | stdio或HTTP |
| 工具 | 客户端可以调用的函数 | add(), list_expenses() |
| 资源 | 访问的数据源 | 文件内容，API数据 |
| 提示 | 预定义提示模板 | 自定义指令集 |
传输机制
1.标准（标准I/O）
- 用例：本地开发，Claude Desktop集成
- 沟通：直接进程stdin/stdout
- 优点：低延迟、简单、安全
- 缺点：单客户端，仅限本地
2.HTTP
- 用例：生产、多客户端、远程访问
- 沟通：HTTP请求/响应
- 优点：基于网络、可扩展、多个客户端
- 缺点：延迟更高，需要网络配置
沟通流程
- 客户端 发送JSON-RPC请求
- 服务器 处理请求（调用工具/获取资源）
- 服务器 发送JSON-RPC响应
- 客户端 在AI环境中使用响应
🔄 MCP服务器生命周期
1.初始化
- 服务器启动并侦听传输（stdio/HTTP）
- 服务器注册可用的工具、资源和提示
- 服务器向客户端发送初始化消息
2.握手
- 客户端和服务器交换功能
- 客户端请求服务器信息（名称、版本、可用工具）
- 服务器以其功能进行响应
3.操作
- 客户端发送工具执行请求
- 服务器处理请求并执行工具
- 服务器将结果返回给客户端
- 每次交互都会重复这个循环
4.关机
- 客户端发送关机信号
- 服务器清理资源
- 服务器正常终止
Start Server → Initialize FastMCP → Register Tools → Listen on stdio/HTTP
│
▼
Client Connects → Handshake → Request Tool → Execute Tool → Return Result
│
▼
Continue Listening...
🛠️ 演示MCP服务器
套房包括 4台综合演示服务器 展示不同的MCP用例：
1.🧮 计算器服务器 （端口8081）
具有异步/等待模式的基本算术运算
add(a, b)-补充subtract(a, b)-减法multiply(a, b)-乘法divide(a, b)-分部power(base, exponent)-指数化square_root(number)-平方根计算
2.💾 数据库服务器 （端口8082）
使用SQLite进行费用跟踪和正确的错误处理
add_expense(description, amount, category, ...)-增加费用list_expenses(limit)-列出费用get_expense(expense_id)-获取具体费用delete_expense(expense_id)-删除费用get_expense_summary()-获取费用统计信息
3.🌐 API集成服务器 （端口8083）
外部API集成（模拟实现）
get_weather(city)-天气数据get_news(category, limit)-新闻文章search_github(query, limit)-GitHub存储库搜索get_crypto_price(symbol)-加密货币价格translate_text(text, target_language)-文本翻译
4.📁 文件系统服务器 （端口8084）
项目目录中的安全文件系统操作
list_directory(path)-列出目录内容read_file(path, max_lines)-读取文本文件write_file(path, content, append)-写入文件search_files(query, path, file_types)-搜索文件内容get_file_info(path)-获取文件/目录元数据
🎮 使用演示UI
先决条件
- Python 3.12或更高版本
uv包管理器（推荐）
安装
# Clone or navigate to project directory
cd fastmcp-demo-server
# Install dependencies
uv sync
启动交互式用户界面
# Start the demo UI server
uv run python ui_backend.py
访问UI： http://localhost:8000
UI功能
🏗️ 架构选项卡
- 交互式MCP架构图
- 关键部件说明
- 运输机制比较
- 通信流可视化
🖥️ 服务器选项卡
- 服务器管理：启动/停止单个演示服务器
- 实时状态：查看正在运行的服务器及其端口
- 自动刷新：服务器状态自动更新
🔧 工具选项卡
- 工具选择：从跨服务器的可用工具中进行选择
- 参数输入：刀具参数的动态表单生成
- 现场执行：执行工具并实时查看结果
- 执行历史：跟踪以前的工具调用和响应
📡 协议选项卡
- 消息检查器：监视JSON-RPC通信
- 协议查看器：请参阅原始MCP协议消息
- 调试工具：清除日志并刷新监控
📚 学习选项卡
- 教育内容：MCP概念和最佳实践
- 代码示例：带解释的工作实施
- 用例：MCP的实际应用
- 进一步阅读：文件和资源链接
测试单个服务器
您还可以单独测试服务器：
# Test Calculator Server
uv run python demo_servers/calculator_server.py
# Test Database Server
uv run python demo_servers/database_server.py
# Test API Server
uv run python demo_servers/api_server.py
# Test File System Server
uv run python demo_servers/filesystem_server.py
与Claude Desktop一起使用
- 配置MCP服务器:
uv run fastmcp install claude-desktop main.py
-
重新启动克劳德桌面 加载新服务器
-
在聊天中使用工具 -Claude现在可以访问您的MCP工具
✨ 主要功能和优点
🎓 教育价值
- 互动学习：MCP概念的实践经验
- 视觉架构：了解MCP组件如何协同工作
- 协议检查：了解JSON-RPC通信
- 最佳实践：学习生产就绪模式
🛠️ 发展特征
- 异步/等待模式：现代Python并发
- 错误处理：全面的尝试/排除块
- 类型安全：正确的参数验证
- 资源管理：安全的数据库和文件操作
🔧 实际应用
- 数据库集成：支持异步的SQLite操作
- API编排：多种外部服务集成
- 文件系统操作：在项目范围内安全操作文件
- 数学计算：具有高级操作的计算器
🌐 生产就绪
- 可扩展体系结构：多个客户端的HTTP传输
- 安全考虑：受控文件访问、输入验证
- 监控：日志记录和错误报告
- 文档：全面的代码注释和文档字符串
📁 项目结构
fastmcp-demo-server/
├── ui_backend.py # FastAPI backend for the demo UI
├── main.py # Original expense tracker server
├── local-guide.md # Development and deployment guide
├── pyproject.toml # Project dependencies and metadata
├── uv.lock # Dependency lock file
├── expenses.db # SQLite database (auto-created)
├── .gitignore # Git ignore rules
└── demo_servers/ # Individual demo MCP servers
├── calculator_server.py # Arithmetic operations server
├── database_server.py # Expense tracking server
├── api_server.py # External API integrations
└── filesystem_server.py # File system operations server
🏗️ 架构概述
UI后端（FastAPI）
- 目的：提供交互式web UI并管理演示服务器
- 特性：服务器生命周期管理、工具测试、协议检查
- 端点：用于服务器控制和工具执行的REST API
- 前端：基于Bootstrap的响应式web界面
演示服务器（FastMCP）
- 框架：FastMCP用于简化MCP服务器开发
- 运输：用于网络访问和多个客户端的HTTP
- 异步支持：带有错误处理的完整async/await实现
- 安全：受控访问边界（特别是文件操作）
关键实施细节
异步/等待模式
@mcp.tool
async def add_expense(description: str, amount: float, category: str) -> dict:
try:
async with aiosqlite.connect(DB_PATH) as conn:
# Async database operations
await conn.execute(...)
await conn.commit()
return {"status": "success"}
except Exception as e:
return {"status": "error", "message": str(e)}
错误处理策略
- 数据库错误:
aiosqlite.Error用于连接/查询问题 - 验证错误：使用描述性消息进行自定义验证
- 系统错误：概述
Exception处理日志 - 故障弱化：返回结构化错误响应
安全措施
- 文件操作：仅限于项目目录
- 输入验证：类型检查和参数验证
- 资源限制：连接池、超时处理
- 访问控制：路径遍历预防
🚀 高级用法
开发工作流程
1.使用uv包管理器
# Initialize new MCP project
mkdir my-mcp-server
cd my-mcp-server
uv init .
uv add fastmcp aiosqlite aiofiles aiohttp
# Create server
# ... add your server code ...
# Run in development mode
uv run fastmcp dev main.py
# Run production server
uv run fastmcp run main.py
# Install to Claude Desktop
uv run fastmcp install claude-desktop main.py
2.MCP调试检查员
# Start inspector (usually at http://localhost:8000)
uv run fastmcp dev main.py
# Test tools and inspect protocol messages
# Monitor server behavior in real-time
生产部署
环境配置
# Set environment variables
export MCP_SERVER_PORT=8080
export MCP_SERVER_HOST=0.0.0.0
export DATABASE_URL=sqlite:///production.db
# Run with production settings
uv run python main.py
Docker部署
FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install uv && uv sync --no-dev
EXPOSE 8080
CMD ["uv", "run", "python", "main.py"]
📚 学习路径
初级水平
- 启动演示UI -探索交互式界面
- 运行单个服务器 -分别测试每个演示服务器
- 检查代码 -通读实现
- 修改工具 -添加您自己的简单工具
中级
- 添加新工具 -用新功能扩展现有服务器
- 创建资源 -实施MCP资源（不仅仅是工具）
- 添加提示 -创建可重用的提示模板
- 错误处理 -改进错误处理和验证
高级水平
- 海关运输 -实施自定义传输机制
- 认证 -添加身份验证和授权
- 监控 -添加指标和日志记录
- 扩展 -处理多个并发客户端
- 生产部署 -部署到云平台
🔗 资源
官方文件
社区资源
开发工具
- MCP检查员：用于调试MCP服务器的内置工具
- 紫外线：快速Python包管理器和项目管理器
- 快速API：现代异步web框架（用于UI后端）
🤝 贡献
贡献方式
- 添加新的演示服务器 -为不同的用例创建服务器
- 改进UI功能 -增强交互界面
- 添加教育内容 -创建更多学习材料
- 修复Bug -报告并解决问题
- 文档 -改进指南和示例
开发设置
# Fork and clone
git clone https://github.com/yourusername/fastmcp-demo-server.git
cd fastmcp-demo-server
# Install dependencies
uv sync
# Start development
uv run python ui_backend.py
📄 许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
🙏 致谢
- Anthropic 用于创建模型上下文协议
- FastMCP 优秀框架团队
- 紫外线 团队为惊人的包管理器
- 独自创立 UI框架团队
MCP开发快乐！ 🎉
使用模型上下文协议学习、实验和构建令人惊叹的AI驱动应用程序。
