内容
# MCP 服务器演示
[](https://github.com/mcp-use/mcp-use)
一个基于模型上下文协议（MCP）的天气信息服务器演示，该服务器使用国家气象服务 API。
## 什么是 MCP？
模型上下文协议（MCP）是一种标准，允许 AI 系统与外部工具和数据源连接。该服务器暴露了与天气相关的工具，可以被 MCP 兼容的客户端使用。
## 功能
该 MCP 服务器提供两个主要工具：
- **`get_alerts`**：检索美国任何州的活跃天气警报
- **`get_forecast`**：获取特定位置（纬度/经度）的详细天气预报
## 先决条件
- Python 3.10+
- `uv` 包管理器
## 安装
1. 克隆或导航到项目目录：
```bash
cd custom_mcp_server
```
2. 安装依赖项：
```bash
uv sync
```
## 本地运行
以开发模式运行 MCP 服务器：
```bash
uv run mcp dev server/weather.py
```
此命令将：
- 启动 MCP 服务器
- 启动 MCP 检查器（一个基于 Web 的测试界面）
- 自动打开浏览器到检查器
## 使用 MCP 检查器测试
**MCP 检查器** 是一个 MCP 主机，允许您与服务器交互并测试其工具。
### MCP 检查器仪表盘
#### 工具
<img src="assets/mcp_inspector_demo.png" width=1000/>
#### 工具响应
<img src="assets/mcp_inspector_tool_success.png" width=1000/>
### 使用检查器
1. 运行上述命令后，检查器将在浏览器中打开
2. 您将在界面中看到服务器的可用工具列表
3. 测试工具：
#### 测试 `get_alerts`：
- 选择 `get_alerts` 工具
- 输入两个字母的美国州代码（例如，`CA` 表示加利福尼亚州，`NY` 表示纽约州）
- 点击“运行”以查看活跃的天气警报
#### 测试 `get_forecast`：
- 选择 `get_forecast` 工具
- 输入纬度值（例如，`39.7456`）
- 输入经度值（例如，`-97.0892`）
- 点击“运行”以查看详细预报
### 示例输出
**get_alerts** 返回格式化的警报，包含：
- 事件类型
- 受影响区域
- 严重程度
- 详细描述
- 安全指示
**get_forecast** 返回 5 个周期的预报，包含：
- 周期名称（例如，“今晚”，“明天”）
- 温度
- 风速和风向
- 详细预报描述
## 与 MCP 主机（Claude Desktop、Antigravity、Cursor 等）一起使用
在您使用 MCP 检查器测试服务器后，您可以将其与生产 MCP 主机一起使用。
### 安装
要在 Claude 桌面应用程序中安装服务器：
```bash
uv run mcp install server/weather.py
```
### 配置
通过将以下内容添加到您的 MCP 工具配置文件中来配置您的 MCP 主机：
**配置文件位置：**
- **Claude Desktop**：文件 -> 设置 -> 开发者
- **Antigravity**：切换代理 -> 附加选项（右上角的 3 个点）-> MCP 服务器 -> 管理 MCP 服务器 -> 查看原始配置
- **Cursor**：文件 -> 首选项 -> 光标设置 -> MCP
**JSON 配置：**
```json
{
"mcpServers": {
"weather": {
"command": "uv",
"args": [
"run",
"--with",
"mcp[cli]",
"mcp",
"run",
".../custom_mcp_server/server/weather.py"
]
}
}
}
```
> **重要**：更新 `args` 数组中的绝对路径以匹配您的本地安装路径。
### 使用 MCP 主机测试
配置完成后，重启您的 MCP 主机应用程序，并使用以下查询进行测试：
- “加利福尼亚州当前的天气警报是什么？”
- “给我旧金山的天气预报。”
#### 示例：使用 Antigravity 与天气 MCP 服务器
<img src="assets/mcpserver_with_mcp_host.png" width=1000/>
## 与聊天机器人 CLI 一起使用
您还可以直接通过 **`mcp-use`** 库将 MCP 服务器工具集成到自定义聊天机器人 CLI 中。这种方法允许您构建可以利用 MCP 工具的对话式界面。
### 运行聊天机器人 CLI
运行交互式聊天机器人：
```bash
uv run server/client.py
```
聊天机器人提供：
- **内存启用对话**：在多个查询中保持上下文
- **交互式命令**：
- 输入 `exit`、`quit` 或 `q` 以退出
- 输入 `clear` 或 `cls` 以清除对话历史
- **工具集成**：在相关时自动使用 MCP 天气工具
### 实现概述
聊天机器人 (`server/client.py`) 展示：
- **MCP 客户端集成**：从 `server/weather.json` 加载服务器配置
- **LangChain 集成**：使用 MCP 代理与 ChatGroq LLM
- **内存管理**：启用对话历史跟踪
- **错误处理**：优雅的错误处理和日志记录
### 示例交互
#### 交互式 CLI 界面
<img src="assets/integrate_mcp_tool_with_chatbot_cli.png" width=800/>
#### 助手响应与工具使用
<img src="assets/integrate_mcp_tool_with_chatbot_cli_Assistant.png" width=800/>
## 传输模式
该 MCP 服务器支持两种传输模式：**STDIO**（默认）和 **SSE**。
### 1. STDIO 模式（默认）
在此模式下，客户端启动服务器进程并通过标准输入/输出进行通信。这是本地运行的最简单方式。
**运行 STDIO 客户端：**
`client-stdio.py` 脚本自动管理服务器生命周期。
```bash
uv run mcpserver/client-stdio.py
```
### 2. SSE 模式（服务器发送事件）
在此模式下，服务器作为独立的 HTTP 服务器运行，客户端连接到它。这对于远程连接或多个客户端非常有用。
**步骤 1：启动服务器**
您必须先启动服务器。使用环境变量将传输设置为 `sse` 或修改 `server.py` 中的默认设置。
```bash
# 以 SSE 模式启动服务器（监听端口 8000）
MCP_TRANSPORT=sse uv run mcpserver/server.py
```
**步骤 2：运行 SSE 客户端**
在另一个终端中运行客户端：
```bash
uv run mcpserver/client-sse.py
```
### 服务器配置
服务器在 `mcpserver/server.py` 中配置：
- **名称**：`weather`
- **主机**：`0.0.0.0`（仅 SSE 传输）
- **端口**：`8000`（仅 SSE 传输）
## 使用 Docker 运行
您可以将 MCP 服务器作为 Docker 容器运行。这对于部署或隔离非常有用。
### 构建和运行
1. **构建 Docker 镜像：**
```bash
docker build -t mcp-server .
```
2. **以分离模式运行容器：**
```bash
docker run -d -p 8000:8000 --name mcp-container mcp-server
```
这将在端口 8000 上以 SSE 模式启动服务器。
### 在 Docker 中运行客户端
在正在运行的容器中运行客户端脚本：
```bash
docker exec -it mcp-container uv run client-sse.py
```
## 传输协议：STDIO
该 MCP 服务器使用 **STDIO（标准输入/输出）传输协议** 进行客户端和服务器之间的通信。
### STDIO 传输的工作原理
在 STDIO 传输模型中：
1. **进程模型**：MCP 客户端启动服务器作为子进程
2. **消息交换**：
- 服务器通过其 **标准输入（stdin）** 接收 JSON-RPC 消息
- 服务器将其响应写入 **标准输出（stdout）**
3. **消息格式**：
- 消息由换行符分隔
- 消息 **不得** 包含嵌入的换行符
4. **日志记录**：
- 服务器 **可能** 为日志目的写入 UTF-8 字符串到 **标准错误（stderr）**
- 客户端可以捕获、转发或忽略这些日志
5. **关键规则**：
- 服务器 **不得** 向 stdout 写入任何不是有效 MCP 消息的内容
- 客户端 **不得** 向服务器的 stdin 写入任何不是有效 MCP 消息的内容
### 为什么使用 STDIO？
STDIO 传输适用于：
- 本地开发和测试
- 直接子进程通信
- 简单的客户端-服务器架构，无网络开销
- 使用 MCP 检查器轻松调试
## 实现细节
- 使用 **FastMCP** 框架构建
- 使用国家气象服务（NWS）API
- 使用 async/await 进行高效的 API 请求
- 正确的错误处理和超时
- 用于客户端-服务器通信的 STDIO 传输
## 项目结构
```
custom_mcp_server/
├── mcpserver/
│ ├── server.py # MCP 服务器实现
│ ├── client-sse.py # SSE 客户端
│ └── client-stdio.py # STDIO 客户端
├── logger.py # 日志记录配置
├── Dockerfile # Docker 配置
├── .dockerignore # Docker 忽略文件
├── README.md # 此文件
├── pyproject.toml # 项目依赖项
└── requirements.txt # Python 需求
```
## 备注
- NWS API 仅提供美国的天气数据
- 预报数据需要有效的美国坐标
- 服务器根据 NWS API 指南包含 User-Agent 头
## 参考
此实现基于 Anthropic 的 [模型上下文协议 Python SDK](https://github.com/modelcontextprotocol/python-sdk)。
