内容
# MCP 101 — 模型上下文协议简介
Mirantis 网络研讨会的材料介绍了 **模型上下文协议（MCP）** —— 一个开放的标准，允许 AI 代理安全地访问现实世界的工具和数据。
本仓库包含幻灯片和一个小的、可运行的 **天气 MCP 服务器**，您可以克隆、运行并用作构建自己的模板。
- 📑 **[`Mirantis_MCP_Webinar_2026.pdf`](Mirantis_MCP_Webinar_2026.pdf)** — 完整的幻灯片
- 🛠️ **[`mcp-demo/`](mcp-demo/)** — 实时演示代码（参见其 [README](mcp-demo/README.md)）
---
## 什么是 MCP？
MCP 是一个开放的标准，它通过 **一个共同的接口** 将基于 LLM 的代理连接到外部工具和数据，而不是为每个工具进行定制的集成。
没有 MCP，*N* 个代理和 *M* 个工具意味着 *N × M* 个脆弱的、定制的集成。有了 MCP，每个代理都使用一种协议，因此您可以添加或交换工具而无需修改代理代码，共享跨代理的服务器，并保持访问发现和范围限定。
一个有用的思维模型：
```
代理（主机） ──MCP / JSON-RPC 2.0──► MCP 服务器 ──► 工具和数据
例如：Claude Code， 您的代码 API，数据库，文件
GitHub Copilot
```
**MCP 是** 一个标准化的 LLM 与工具通信协议，具有内置的发现和能力协商功能，以及一个可插拔的、多代理友好的架构。
**MCP 不是** 一个代理框架，一个托管服务（您运行服务器），一个后端替代品，限制在一个模型供应商，或一种暴露 **无限** 工具的方式 —— 上下文仍然很重要。
> **工具 vs. 技能：** MCP **工具** 给代理新的 *能力*（执行操作的能力）。代理 **技能** 给它 *知识*（基于文件的操作说明）。技能告诉代理 *做什么*；MCP 工具让它实际 *做*。
---
## 六个基本元素
| | 基本元素 | 它是什么 | 示例 |
|---|---|---|---|
| **服务器端** | **工具** | 可调用的函数 / 操作 | `get_weather(city, units)` |
| | **资源** | 可读数据（只读） | `weather://api-guide` |
| | **提示** | 带有变量的可重用模板 | `weather_advisor(destination)` |
| **客户端** | **采样** | 服务器可以通过客户端请求 LLM 补全 | （无需服务器 API 密钥） |
| | **根目录** | 客户端告诉服务器其文件系统边界 | 将服务器范围限定在工作区 |
| | **诱导** | 服务器暂停以请求用户提供结构化输入 | 请求缺少的参数 |
网络研讨会重点介绍了前两个：**工具** 和 **资源**。
---
## 演示：一个天气 MCP 服务器
[`mcp-demo/`](mcp-demo/) 是一个约 250 行的 Python 服务器，它封装了 [OpenWeatherMap](https://openweathermap.org/) API，并暴露：
- 一个 **工具** —— `get_weather(city, units)` 用于实时天气状况
- 一个 **资源** —— `weather://api-guide` 包含 API 文档
- 通过 **stdio** 传输（简单、本地，推荐用于桌面使用）
天气只是一个熟悉的、安全示例 —— 相同的模式适用于 *任何* 后端：工单系统、数据库、Kubernetes、监控、内部业务 API。
### 快速开始
```bash
cd mcp-demo
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# 从 https://openweathermap.org/appid 获取免费密钥
export OPENWEATHER_API_KEY="your_api_key_here"
python test_server.py # 健全性检查
```
API 密钥始终从 **环境** 中读取，而不是硬编码或提交。演示附带一个 `.mcp.json` 文件，因此 Claude Code 在从 `mcp-demo/` 运行后会自动拾取服务器。您也可以使用 **MCP Inspector** 在没有代理的情况下探索它：
```bash
npx @modelcontextprotocol/inspector ./.venv/bin/python weather_server.py
```
完整的设置、Claude Desktop / Claude Code 配置以及原始 JSON-RPC 消息的 Inspector 演练都在 **[演示 README](mcp-demo/README.md)** 中。
---
## 主要收获
- 一个 MCP 服务器可以封装 **任何** 外部服务或 API 在一个协议后面。
- **配置** 而不是代码，将服务器连接到客户端 —— 通过编辑配置添加功能。
- **用户同意** 是客户端的功能（例如 Claude Desktop），而不是协议要求。
- 倾向于 **多个小而具体的工具** 而不是一个巨大的通用工具 —— 更好的工具选择，更少的上下文膨胀，更容易的权限范围限定。经验法则：每个服务器约 5-10 个设计良好的工具。
- **工具组合** 是 MCP 的亮点：一个请求 → 多个协调的工具调用。
- 实践 **最小权限** 和 **日志记录工具调用** 以实现审计。
---
## 下一步骤和资源
1. 克隆此仓库并运行天气服务器（约 30 分钟）。
2. 在连接代理之前使用 **MCP Inspector** 进行测试。
3. 浏览注册表以查找预构建的服务器，然后构建自己的服务器。
- MCP 文档和入门指南 — <https://modelcontextprotocol.io/>
- 规范 — <https://spec.modelcontextprotocol.io/>
- 服务器注册表 — <https://github.com/modelcontextprotocol/servers>
- MCP Inspector — <https://github.com/modelcontextprotocol/inspector>
- Python SDK — <https://github.com/modelcontextprotocol/python-sdk>
- TypeScript SDK — <https://github.com/modelcontextprotocol/typescript-sdk>
---
*由 Mirantis 呈现。幻灯片和演示共享用于教育目的 —— 天气服务器是一个教学模式，而不是生产代码。*
