使用说明

项目简介

本项目 'mcp-demo' 是一个用于演示 Model Context Protocol (MCP) 的简单示例，包含 MCP 客户端 ('mcp-client') 和两个 MCP 服务器示例 ('mcp-server' 目录下的 'weather.py')。客户端可以连接到本地文件服务器、命令服务器或在线 HTTP/SSE 服务器，并调用服务器提供的工具。本示例主要展示了如何通过 MCP 框架构建能够提供天气预报和警报功能的 AI 助手。

主要功能点

MCP 客户端:
- 支持命令行交互，方便用户输入查询和命令。
- 可以连接到不同类型的 MCP 服务器 (Stdio, SSE)。
- 能够列出和调用 MCP 服务器提供的工具。
- 支持根据用户查询内容建议合适的服务器。
- 内置 OpenAI API 调用功能，可以与 LLM 模型进行对话。
- 提供调试模式，方便开发者查看工具调用细节。
天气服务 MCP 服务器 (weather.py):
- 使用 'FastMCP' 框架快速搭建。
- 提供两个工具：
  - 'get_forecast': 获取指定经纬度的天气预报。
  - 'get_alerts': 获取指定美国州的天气警报。
- 通过标准输入/输出 (Stdio) 协议与客户端通信。

安装步骤

克隆仓库

git clone https://github.com/syuchua/mcp-demo.git
cd mcp-demo

安装依赖 推荐使用 'uv' 包管理器，或者使用 'pip'：

# 使用 uv (推荐)
uv pip install -e .
# 或者使用 pip
pip install -e .

配置 API_KEY
- 方式一：创建 '.env' 文件 (可选) 在项目根目录下创建 '.env' 文件，并添加你的 OpenAI API Key：
```
OPENAI_API_KEY="your-api-key"
```
- 方式二：编辑 'mcp-client/config.yaml' 文件 打开 'mcp-client/config.yaml' 文件，修改 'api.openai_api_key' 的值为你的 OpenAI API Key。

服务器配置

本示例客户端默认配置了可以连接到本地 'weather.py' 天气服务，无需额外配置即可运行。如果需要修改或添加其他 MCP 服务器，可以编辑 'mcp-client/config.yaml' 文件中的 'servers.instances' 字段。

以下是 'config.yaml' 中关于 'weather' 服务器的配置示例，类型为 'stdio'，表示通过标准输入输出流连接到本地脚本：

servers:
  directory: ../mcp-server # 指定服务器脚本所在的目录，相对于 mcp-client 目录
  default: weather      # 默认连接的服务器名称

  instances:
    weather: # 服务器名称，客户端使用此名称连接
      name: weather
      type: stdio  # 服务器类型，stdio 表示标准输入输出流
      script: weather.py # 服务器脚本路径，相对于 servers.directory 指定的目录
      description: 本地天气服务示例 (Stdio) # 服务器描述信息

配置参数说明:

'name': 服务器的名称，客户端通过此名称来连接服务器。
'type': 服务器的连接类型，本示例中使用了 'stdio' 类型，表示通过标准输入输出流与服务器通信。其他可选类型包括 'sse' (Server-Sent Events) 等。
'script': 当 'type' 为 'stdio' 或 'command' 时，指定服务器脚本的路径。路径是相对于 'servers.directory' 配置的目录。
'description': 服务器的描述信息，用于在客户端显示服务器列表时提供说明。

基本使用方法

启动 MCP 客户端 在项目根目录下，运行以下命令启动客户端：

python mcp-client/mcp_client.py
# 或者使用 uv 运行
uv run mcp-client/mcp_client.py

命令行交互 客户端启动后，即可在命令行中输入查询或使用命令：
- '!help': 显示帮助信息。
- '!servers': 列出可用的服务器。
- '!connect <server>': 连接到指定的服务器，例如 '!connect weather'。
- '!models': 列出可用的 LLM 模型。
- '!model <name>': 切换使用的模型，例如 '!model gpt-4o'。
- '!debug <on/off>': 开启/关闭调试模式。
- '!quit' 或 '!exit': 退出程序。
查询示例
- 连接到天气服务并查询天气
```
!connect weather
查询旧金山天气预报
```
- 直接查询，客户端自动选择服务器 (如果配置了服务器建议功能)
```
北京明天的天气怎么样？
```
客户端会根据你的查询，尝试连接到合适的服务器并调用相应的工具来获取结果。

注意: 本示例中的 'weather.py' 服务器依赖美国国家气象局 (NWS) 的 API，可能仅适用于查询美国地区的天气信息。

关键词