Terminal-based Chat Client with MCP Server Integration

基于终端的聊天客户端与 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  # On Unix/macOS
# or
.venv\Scripts\activate  # On 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. 创建 .env 文件并填入你的 OpenAI API 密钥：

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 密钥的环境变量

贡献

欢迎提交问题和功能改进请求！