MCP示例：采样、通知和根
此存储库是一套动手操作的 模型上下文协议（MCP） 构建示例以展示MCP客户端和MCP服务器如何在实际工作流程中协同工作。
它侧重于三个实际场景：
- 采样：服务器通过客户端请求模型生成
- 日志记录和进度通知：服务器在工具运行时流式传输状态更新
- 基于根的文件访问：服务器仅限于批准的文件系统路径
这个项目是做什么的，为什么建造它？
本项目演示了如何使用Python和.NET构建基于MCP的系统 mcp[cli]，使用 stdio 交通促进地方发展。
它的建立是为了使核心MCP概念有形化：
- 如何从MCP服务器公开工具
- MCP客户端如何调用这些工具
- 如何通过MCP采样委派模型调用
- 如何使用root强制执行安全的文件访问
- 如何通过日志记录/进度通知来提高用户体验
简而言之：它是MCP模式的学习和参考仓库，而不是一个单一的生产应用程序。
建筑是什么样子的？
在较高层次上，每个示例都遵循以下流程：
User/CLI -> MCP Client -> MCP Server -> Tool logic
对于采样，服务器要求客户端调用一个模型：
MCP Server -> ctx.session.create_message(...) -> MCP Client sampling callback -> LLM provider (Gemini/Claude)
项目结构
sampling_example/
- server.py：暴露a rephrase 工具并通过MCP上下文触发采样 - client.py / client_anthropic.py：启动MCP会话并实现对模型SDK的采样回调
notifications_example/
- server.py：暴露 add 工具与 ctx.info(...) 和 ctx.report_progress(...) - client.py：接收日志记录/进度回调并打印更新
roots_example/
- mcp_server.py：工具 list_roots, read_dir, convert_video 通过路径检查 - main.py：使用提供的根目录启动CLI聊天+MCP客户端 - core/：聊天循环、模型适配器、实用程序、视频转换助手
如何在本地运行此程序？
先决条件
- Python 3.10+
uv已安装(pip install uv)- API密钥，具体取决于示例：
- GOOGLE_API_KEY 双子座 - ANTHROPIC_API_KEY 对于克劳德
- FFmpeg（仅需要
roots_example视频转换）
1） 采样示例
cd sampling_example
uv sync
uv run client.py笔记：
client.py使用Gemini(GOOGLE_API_KEY).- 如果使用Anthropic，请切换到
client_anthropic.py正如该文件夹中记录的那样。
2） 通知示例
cd notifications_example
uv sync
uv run client.py3） 根示例
cd roots_example
cp .env.example .env
# set GOOGLE_API_KEY or ANTHROPIC_API_KEY in .env
uv sync
uv run main.py [root2] [root3]例子：
uv run main.py .我该如何部署它？
此回购目前是为 基于本地stdio的执行。尚未包括生产部署管道。
如果要部署：
- 将每个示例打包为服务/容器
- 替换
stdio网络传输（用于远程客户端） - 通过平台中的环境变量注入机密
- 为生产流量添加可观察性、身份验证和访问控制
做出了哪些决定，为什么？
- 分为三个重点示例 隔离MCP概念并保持每个学习路径的简单性。
- 使用Python+
mcp[cli]以减少样板并保持与MCP原语的紧密联系。 - 使用
stdio运输 因为它最容易进行本地开发和调试。 - 通过客户端采样生成委托模型 因此，服务器工具逻辑可以在协议边界保持模型无关性。
- 强制文件操作的根 演示默认情况下安全的文件系统访问。
- 包括进度/日志回调 展示长时间运行的工具的用户友好行为。
接下来需要改进什么？
- 添加统一的根级别
Makefile/用于一个命令设置和执行的任务运行器。 - 对所有示例的文档和命名进行标准化（目前一些README标题/描述不同）。
- 为工具处理程序和路径权限检查添加测试（单元+集成）。
- 为远程部署场景添加可选的HTTP传输示例。
- 为linting、格式化和自动烟雾测试添加CI。
附加说明：
模型上下文协议（MCP） MCP服务器允许我们访问外部（第三方）服务的数据和功能。将MCP视为LLM与数据库、文件、API和内部工具通信的标准方式。
为什么需要MCP 没有MCP，LLM集成看起来像这样： user -> app -> custom tool logic -> LLM
每个工具集成都是定制的：
- 自定义身份验证
- 自定义api包装器
- 自定义架构
- 自定义错误处理
使用MCP： user -> LLM -> MCP Client -> MCP Server -> Tools 您无需编写自定义工具定义，而是通过MCP公开工具，任何与MCP兼容的模型都可以采用此方法。