基于终端的聊天客户端，集成 MCP 服务器

本项目演示了如何构建一个基于终端的聊天客户端界面，该界面连接到 MCP 服务器并与 OpenAI 的 API 集成。它包含一个简单的天气服务，作为 MCP 功能的示例。

前提条件

• Python 3.8 或更高版本
• UV 包管理器（一个快速、可靠的 Python 包安装程序和解析器）

安装

1. 安装 UV

UV 是一个现代 Python 包管理器，与传统的 pip 等工具相比，它提供了显著的性能改进。它用 Rust 编写，并提供：

• 更快的包安装
• 可靠的依赖关系解析
• 内置的虚拟环境管理
• 与现有的 Python 工具兼容

要安装 UV，请运行：

curl -LsSf https://astral.sh/uv/install.sh | sh

2. 项目设置

1. 初始化一个新项目：

uv init

2. 创建并激活一个虚拟环境：

uv venv
source .venv/bin/activate  # 在 Unix/macOS 上
# 或
.venv\Scripts\activate  # 在 Windows 上

3. 安装所需的包：

uv pip install httpx mcp[cli] openai python-dotenv

项目结构和实现指南

该项目由两个主要组件组成：一个聊天客户端 (client.py) 和一个天气服务 (weather.py)。 让我们逐步了解每个组件是如何构建的以及每个部分的作用。

构建聊天客户端 (client.py)

聊天客户端构建为一个异步 Python 应用程序，它同时连接到 MCP 服务器和 OpenAI 的 API。 以下是它的构建方式：

1. 导入和设置

   import asyncio
   import os
   import sys
   from typing import Optional
   from contextlib import AsyncExitStack
   from dotenv import load_dotenv
   import openai
   from mcp import ClientSession, StdioServerParameters
   from mcp.client.stdio import stdio_client
   

   • asyncio: 用于异步编程
   • AsyncExitStack: 管理异步资源的清理
   • dotenv: 从 .env 文件加载环境变量
   • mcp: 用于服务器通信的核心 MCP 功能

2. MCPClient 类 主客户端类处理：

   • 连接到 MCP 服务器
   • OpenAI API 集成
   • 消息处理
   • 工具执行

   关键方法：

   • connect_to_server(): 建立与 MCP 服务器的连接
   • process_query(): 处理用户查询和工具执行
   • chat_loop(): 管理交互式聊天会话
   • cleanup(): 确保正确的资源清理

3. 主函数

   async def main():
       client = MCPClient()
       try:
           await client.connect_to_server(sys.argv[1])
           await client.chat_loop()
       finally:
           await client.cleanup()
   

   • 初始化客户端的入口点
   • 连接到指定的服务器
   • 运行聊天循环
   • 确保正确的清理

构建天气服务 (weather.py)

天气服务构建为一个 MCP 服务器，它通过国家气象局 API 提供天气信息：

1. 服务初始化

   from mcp.server.fastmcp import FastMCP
   mcp = FastMCP("weather")
   

   • 创建一个名为 "weather" 的 MCP 服务器实例
   • 设置服务器基础设施

2. API 集成

   NWS_API_BASE = "https://api.weather.gov"
   USER_AGENT = "weather-app/1.0"
   

   • 定义国家气象局 API 的常量
   • 设置正确的用户代理以进行 API 请求

3. 辅助函数

   • make_nws_request(): 处理 API 请求，并进行适当的错误处理
   • format_alert(): 将天气警报格式化为可读文本

4. MCP 工具 实现了两个主要工具：

   a. get_alerts(state):

   • 获取美国州当前的有效天气警报
   • 返回格式化的警报信息

   b. get_forecast(latitude, longitude):

   • 检索某个位置的天气预报
   • 返回详细的预报信息

5. 服务器执行

   if __name__ == "__main__":
       mcp.run(transport="stdio")
   

   • 使用 stdio 传输运行 MCP 服务器
   • 启用与聊天客户端的通信

用法

1. 创建一个包含您的 OpenAI API 密钥的 .env 文件：

OPENAI_API_KEY=your_api_key_here

2. 启动 MCP 服务器：

python weather.py

3. 在单独的终端中，运行聊天客户端：

python client.py weather.py

4. 与聊天界面交互：
   • 提出一般问题以与 AI 聊天
   • 使用与天气相关的查询来获取天气信息
   • 示例：“加利福尼亚的天气怎么样？” 或 “纽约有什么警报吗？”

与 Cursor 的 Agent 模式一起使用

此 MCP 服务器可以直接与 Cursor 的 Agent 模式集成（注意：这与 Cursor 的 Ask 功能不同，仅在 Agent 模式下有效）。 以下是设置方法：

将 MCP 服务器添加到 Cursor

1. 打开 Cursor 设置
2. 导航到 Features > MCP
3. 点击 + Add New MCP Server
4. 填写表格：
   • Type: 选择 stdio
   • Name: "Weather Service"（或您喜欢的任何名称）
   • Command: 输入运行天气服务器的完整路径：

     python /full/path/to/your/weather.py
     

替代方案：项目特定的配置

您还可以通过创建 .cursor/mcp.json 文件来为您的项目配置 MCP 服务器：

1. 在您的项目根目录中创建 .cursor 目录：

mkdir .cursor

2. 创建包含以下内容的 mcp.json：

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": [
        "/full/path/to/your/weather.py"
      ]
    }
  }
}

使用天气工具

1. 打开 Cursor 的 Composer（Agent 模式）
2. Agent 将自动检测何时需要天气信息
3. 示例查询：
   • "旧金山当前的天气怎么样？"
   • "加利福尼亚有什么天气警报吗？"
   • "给我纽约市的预报"

重要提示

• 工具仅在 Cursor 的 Agent 模式（Composer）中可用，而不在 Ask 模式中可用
• 默认情况下，Cursor 会在使用 MCP 工具之前请求批准
• 您可能需要单击 MCP 设置中的刷新按钮才能看到新添加的工具
• 服务器必须在您的本地计算机上运行（远程服务器需要 SSE 传输）

特点

• 具有 OpenAI 集成的实时聊天界面
• 用于可扩展功能的 MCP 服务器集成
• 具有警报和预报的天气服务
• 异步操作以获得更好的性能
• 正确的错误处理和资源清理
• 用于 API 密钥的环境变量配置

贡献

欢迎提交问题和增强请求！