MCP 智能聊天助手示例项目_mcp example-优快云博客

MCP 智能聊天助手示例项目

原文: https://github.com/elrondwong/mcp-example

基于Model Context Protocol的智能对话系统示例

项目简介

本项目是基于MCP (Model Context Protocol)框架的智能聊天助手示例，展示了如何使用大语言模型(LLM)与外部数据源和工具进行集成，实现跨模态、多能力的智能对话系统。

MCP框架介绍

MCP (Model Context Protocol)是由Anthropic开源的开放协议，为LLM应用和外部数据源及工具之间的无缝集成提供标准化方式。可以将MCP理解为AI应用的"USB-C接口"，就像USB-C为设备提供了与各种外设和配件连接的标准方式一样，MCP为AI模型提供了与不同数据源和工具连接的标准方式。

MCP核心价值：连接用户、大模型与专业服务

MCP本质上是一个标准化的连接协议，它作为关键的桥梁，将三个核心组件优雅地连接在一起：

用户 - 通过自然语言表达需求的人或者其他的输入者
大模型 - 处理理解和生成的AI系统
专业服务 - 提供特定领域能力的工具和数据源

作为连接器，MCP实现了以下关键价值：

降低用户门槛：允许用户用自然语言表达复杂需求，无需了解底层技术细节
扩展模型能力：让大模型能够访问实时外部数据和专业功能，克服了模型知识局限和"幻觉"问题
激活专业服务：使现有专业服务能够被大模型智能调用，无需彻底重构现有系统
标准化交互：通过统一协议减少集成复杂性，降低开发和维护成本

这种标准协议的设计使得整个AI应用生态系统更加模块化和可扩展，各组件可以专注于自己的强项，同时通过标准接口协同工作，为用户提供集成化的智能体验。

为什么选择MCP?

MCP帮助你在LLM之上构建智能代理和复杂工作流。大语言模型经常需要与数据和工具集成，而MCP提供：

预构建集成列表，可直接连接到你的LLM
在不同LLM提供商和供应商之间切换的灵活性
在你的基础设施内保护数据的最佳实践

MCP架构

在核心上，MCP遵循客户端-服务器架构，其中主机应用程序可以连接到多个服务器：

MCP主机：如Claude Desktop、IDE或AI工具等希望通过MCP访问数据的程序
MCP客户端：维护与服务器1:1连接的协议客户端
MCP服务器：通过标准化的Model Context Protocol暴露特定功能的轻量级程序
本地数据源：MCP服务器可以安全访问的计算机文件、数据库和服务
远程服务：通过互联网可用的外部系统（例如API），MCP服务器可以连接到这些系统

MCP工作流程

MCP的实际工作流程遵循以下步骤：

服务准备：首先，你需要一个或多个遵循MCP标准的MCP服务器，每个服务器为特定领域暴露一个功能接口（工具）和数据资源。这些服务器可以是本地的或远程的。
用户应用：用户通过集成了MCP客户端的应用程序（如聊天界面、IDE插件等）发送请求，MCP客户端负责与MCP服务器通信。
请求处理：
- 用户发送自然语言请求（例如"查询明天北京的天气"）
- 应用程序收集所有已注册的MCP服务器及其工具信息
- 应用程序调用大语言模型分析用户意图，并将其映射到适当的MCP服务和工具
- 模型返回结构化调用信息（服务名称、工具名称、参数等）
服务调用：
- 应用程序根据模型的决定，调用指定MCP服务器的相关工具
- MCP服务器处理请求并返回结构化数据
结果处理：
- 应用程序从服务器接收专业数据
- 再次调用模型将专业数据转换为用户友好的自然语言回复
- 向用户呈现最终回复

下图展示了MCP的工作流程：

┌───────────────┐        ┌───────────────┐        ┌───────────────┐
│               │        │               │        │               │
│     用户      │───────▶│  应用程序     │◀──────▶│   大语言模型  │
│               │        │ (MCP客户端)   │        │               │
└───────────────┘        └───────▲───────┘        └───────────────┘
                                 │
                                 │
                         ┌───────▼───────┐
                         │  MCP服务注册  │
                         │    和发现     │
                         └───────┬───────┘
                                 │
                 ┌───────────────┼───────────────┐
                 │               │               │
         ┌───────▼───────┐┌──────▼────────┐┌─────▼─────────┐
         │               ││               ││                │
         │ MCP服务器 A   ││  MCP服务器 B  ││  MCP服务器 C   │
         │ (天气服务)    ││  (知识库)     ││  (数据分析)    │
         │               ││               ││                │
         └───────────────┘└───────────────┘└────────────────┘

这个工作流程展示了MCP的核心价值：允许大语言模型通过标准化协议无缝利用各种专业服务，同时保持一致的用户体验。用户只需通过自然语言表达需求，无需了解底层技术细节或服务架构。

MCP多服务器协调机制

MCP框架能够优雅地协调多个服务器，实现复杂功能集成。具体协调机制包括：

服务发现和注册：
- MCP主机在启动时扫描并发现本地或网络中的MCP服务器
- 每个服务器在启动时向主机注册其能力（工具、资源类型等）
- 主机维护服务器能力映射表，用于路由请求
能力描述和工具列表：
- 每个MCP服务器发布其支持的工具列表、参数规范和资源类型
- 主机可以通过list_tools和list_resources等API获取每个服务器的能力
- 模型根据这些能力决定调用哪个服务器的哪个工具
上下文管理：
- MCP维护请求上下文，以确保多服务器调用之间的信息一致性
- 上下文可以包括会话信息、用户偏好、身份验证令牌等
- 服务器可以读取上下文以提供个性化响应
请求路由：
- 当应用程序或模型需要特定服务时，MCP客户端负责：
  - 识别哪个服务器可以处理请求
  - 将请求格式化为标准的MCP协议消息
  - 与目标服务器建立连接
  - 传输请求并等待响应
并行处理：
- MCP支持同时向多个服务器发送请求
- 可以并行获取不同数据源的信息
- 可以将多个服务器的结果聚合到一个响应中
错误处理和回退：
- 当特定服务器不可用时，MCP可以自动尝试备用服务器
- 错误报告机制帮助应用程序诊断问题
- 支持为服务中断定义回退策略
版本兼容性：
- MCP协议设计支持不同版本的服务器共存
- 客户端可以处理版本差异，以确保向后兼容性
- 新服务器可以提供增强功能，而无需更新整个环境

在实践中，例如，当用户问"分析上个月的销售数据并与天气比较"时，MCP将：

识别需要销售数据分析和天气查询服务
调用数据分析MCP服务器获取销售统计信息
调用天气MCP服务器获取历史天气数据
将两种数据组合并返回给模型
模型根据完整上下文生成综合分析

这种协调机制使MCP能够无缝结合多个专业服务器的能力，提供集成化的体验，而每个服务器只专注于自己的专业领域，大大提高了系统的模块化和可扩展性。

MCP框架的核心思想是为大语言模型应用提供结构化的上下文信息，包括：

资源：提供给模型的数据，如文件内容、API响应等
工具：模型可以调用的函数，用于执行操作和获取信息
提示：可重用的交互模板，用于引导模型响应

MCP实际应用场景

让我们通过几个生动的例子来看看MCP如何解决实际问题：

例1: 智能代码助手

问题：传统代码助手缺乏对代码仓库的深入理解，无法访问本地代码结构和版本控制信息。

MCP解决方案：

开发者安装支持MCP的IDE插件
IDE创建MCP服务器，暴露本地文件系统、Git历史记录和代码索引
当开发者通过MCP向AI提问"这个bug可能的原因是什么？"时，AI可以：
- 读取当前打开文件的内容
- 查询错误日志
- 检索相关代码模块
- 分析Git提交历史以找到最近的更改
- 提供具体的、基于上下文的解决方案

效果：开发者获得基于项目实际情况的具体建议，而不是泛泛而谈的答案。

例2: 私密知识库问答

问题：企业希望员工能够询问内部文档和数据，但担心隐私泄露。

MCP解决方案：

企业在自己的基础设施上部署MCP服务器，连接内部知识库
员工在聊天界面中问"2023年第三季度我们的销售策略是什么？"
MCP服务器在本地：
- 检索相关内部文档
- 提取所需信息
- 将内容发送给模型进行总结
- 员工收到基于内部数据的答案

效果：敏感数据留在企业内部，但员工仍然获得智能问答体验。

例3: 个人数据助手

问题：用户希望AI帮助管理个人数据，但担心隐私问题。

MCP解决方案：

用户在自己的设备上安装MCP应用程序
应用程序创建本地服务器，连接个人照片库、日历和文件
用户问"帮我找到去年夏天在海滩拍的照片，并创建一个相册"
MCP服务器在本地处理：
- 在照片库中搜索相关图像
- 仅将照片缩略图发送给模型进行分析
- 根据模型建议在本地设备上创建相册

效果：用户获得AI辅助的个人数据管理能力。

例4: 多源研究助手

问题：研究人员需要处理多种不同格式的数据并切换工具耗时。

MCP解决方案：

研究人员部署多个MCP服务器，分别连接：
- 科学文献数据库
- 数据可视化工具
- 统计分析软件
- 笔记和引用管理系统
研究员可以问"分析这组基因数据与近期论文中的发现有何关联"
MCP协调多个服务器：
- 检索并分析实验数据
- 搜索最新相关论文
- 运行统计比较
- 生成可视化图表
- 整合为一份综合报告

效果：研究人员通过一个统一界面完成跨数据源、跨工具的复杂工作流。

这些例子说明了MCP如何解决数据集成、隐私保护和工具互操作性等关键挑战，使AI应用能够安全地访问和处理各种数据源，同时提供丰富的上下文，让大语言模型发挥最大价值。

项目架构

本项目采用了模块化设计，主要包含以下组件：

聊天服务(Chat App)：核心服务组件，负责
- 用户请求处理
- 大模型API调用
- 用户意图解析
- MCP服务调用协调
- 响应格式化
MCP管理器：负责
- MCP服务发现和注册
- 工具列表管理
- 服务调用路由
天气MCP服务：提供天气信息查询功能
- 天气数据获取
- 温度范围查询
- 降水预测
- 天气图表生成
大语言模型服务(vLLM)：提供大模型推理能力
- 模型托管和优化推理
- 用户意图解析和服务选择
- 结构化数据转自然语言描述
- OpenAI兼容API接口

架构图示：

┌─────────────────────────┐           ┌──────────────────────┐
│                         │           │                      │
│      用户/客户端        │◀─HTTP────▶│    mcp_chat_app/     │
│                         │           │    chat_app.py       │
└─────────────────────────┘           │    (Flask应用)       │
                                      └──────────┬───────────┘
                                                 │
                                                 │
                  ┌──────────────────────────────┼──────────────────────────────┐
                  │                              │                              │
     ┌────────────▼─────────────┐   ┌────────────▼─────────────┐   ┌────────────▼─────────────┐
     │  mcp_chat_app/           │   │   mcp_chat_app/          │   │     vllm_server/         │
     │  mcp_manager.py          │   │   mock_mcp_manager.py    │   │     run.py               │
     │  (MCP服务发现与管理)     │   │   (测试用模拟MCP管理器)  │   │   (大模型推理服务        │
     └────────────┬─────────────┘   └──────────────────────────┘   │    可替换为远程API)      │
                  │                                                 └──────────┬───────────────┘
                  │ MCP协议                                                    │
                  │                                                            │
     ┌────────────▼─────────────┐                                  ┌───────────▼───────────────┐
     │  weather_mcp_server/     │◀─────────────────────────────────┤ 1. 意图解析              │
     │  weather_server.py       │                                  │ 2. 参数提取和验证         │
     │  (天气服务MCP实现)       │─────────────────────────────────▶│ 3. 结果格式化和润色      │
     │                          │                                  └───────────────────────────┘
     └──────────────────────────┘                                             ▲
             │        │                                                       │
             │        │                                                       │
┌────────────▼──┐ ┌───▼────────────┐           ┌───────────────────────────┐ │
│ utils.py      │ │ chart_generator.│           │       双向交互流程        │ │
│ (数据处理)    │ │ py (图表生成)   │           │                           │ │
└───────────────┘ └────────────────┘           │ 1. 用户查询意图理解        │ │
                                               │ 2. MCP工具选择             │ │
                                               │ 3. 参数解析和转换          │ │
                                               │ 4. 结果数据自然语言化      │ │
                                               │ 5. 多模态内容处理          │ │
                                               └───────────────────────────┘ │
                                                                             │
                                                       chat_app.py ──────────┘

大模型服务关键交互

大语言模型服务(vLLM)在整个系统中扮演着"大脑"角色，与其他组件有三个关键交互点：

与聊天服务(chat_app.py)的交互：
- 接收用户原始查询，分析用户意图
- 从可用工具列表中选择最合适的MCP服务和工具
- 提取和格式化调用参数
- 将MCP服务返回的结构化数据转化为自然语言回复
- 处理错误情况并提供友好响应
与MCP服务的间接交互：
- 通过聊天服务作为中介，大模型决定调用哪个MCP服务
- 根据MCP服务的工具文档信息，正确构造调用参数
- 理解MCP服务返回的数据结构，进行信息提取和整合
模型能力应用：
- 语义理解：将自然语言转化为结构化意图
- 上下文记忆：维持多轮对话的连贯性
- 格式转换：在自然语言和结构化数据间互相转换
- 多模态处理：支持文本、图表、结构化数据等混合内容

大模型服务采用vLLM加速推理，提供OpenAI兼容的API接口，使系统能够轻松替换底层模型，同时保持接口一致性。该服务不仅提供基础推理能力，还承担着整个系统的决策和协调角色，是连接用户需求与专业服务的关键桥梁。

值得注意的是，本架构中的vLLM服务器组件采用了模块化设计，可以灵活替换为：

本地部署模式：如当前的vllm_server部署，适合开发测试或对数据安全有较高要求的场景
云端API模式：可直接替换为OpenAI、Anthropic Claude、QianWen千问等商业API服务
自托管远程模式：可部署在专用GPU服务器或云端GPU实例上，通过API连接
混合模式：不同功能使用不同来源的模型服务，如意图理解使用轻量模型，内容生成使用更强大的模型

系统设计确保了无论使用哪种模型服务部署方式，聊天应用的核心功能和与MCP服务的交互方式都保持一致，只需修改配置即可切换，无需更改应用代码架构。这种灵活性使开发者可以根据实际需求、预算和计算资源选择最适合的部署策略。

系统工作流程：

用户发送HTTP请求到聊天服务(chat_app.py)
聊天服务使用vLLM大模型服务分析用户意图
根据分析结果，通过mcp_manager调用天气MCP服务的相关工具
天气服务处理请求，可能使用chart_generator生成图表
聊天服务接收MCP服务返回的专业数据
再次调用大模型服务将数据转化为自然语言回复
将最终回复返回给用户

用户使用方式

通过调用api，在api中用户可以通过自然语言查询天气信息：

“北京今天天气怎么样？”
“上海未来三天的温度变化趋势”
“广州今天会下雨吗？”
“给我看看杭州的降水量图表”

系统会调用天气服务获取相关数据，并通过大模型将数据转化为易于理解的回复。

如何用cursor开发自己的MCP服务(以当前项目，天气查询服务为例)

创建一个新的文件夹
拷贝mcp的readme以及python sdk readme到当前的项目根目录以告诉cursor，mcp是什么以及怎么用

生成mcpserver

使用cursor agent开始第一个项目生成

请根据REAME中的MCP框架创建一个项目，这个项目是一个mcpserver，实现了mcpserver的所有功能，作天气查询

这样就会生成 weather_mcp_server 项目

运行mcp

为整个项目创建一个 venv

# 回到项目根目录
uv venv -p python3.12 .venv
source .venv/bin/activate
# 安装mcp
pip install mcp 'mcp[cli]'
# 安装依赖
pip install -r weather_mcp_server/requirements.txt
# 运行mcpserver
python weather_mcp_server/run.py --dev
# 或者使用mcp命令
mcp dev weather_mcp_server/weather_server.py
# 输出如下
Starting MCP inspector...
Proxy server listening on port 3000

🔍 MCP Inspector is up and running at http://localhost:5173 🚀

这样我们就可以在http://localhost:5173 这个mcp代理中访问mcpserver了

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

在claude和cursor中都可以使用，例如在cursor中使用

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

进行添加会帮我们创建一个文件，文件内容需要根据刚才创建的mcpserver来填写

{
 "mcpServers": {
   "server-name": {
  "command": "python",
  "args": ["/yourpath/weather_mcp_server/weather_server.py"]
 }
  }
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

注册上来之后在cursor agent中可以通过cursor使用mcpserver

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

生成用户程序

现在mcpserver使用依赖于cursor，mcp设计本身事为了作为大模型与应用的连接器的，所以我们能不能写个应用来连接大模型和应用呢，现在应用已经有了，需要

有一个大模型(本地启动的无论是deepseek还是、llama、qianwen都表现比较差，用阿里云百联的qwen-plus)
- 可以使用项目中的vllm代码本地启动一个
- 使用在线大模型
有一个面向用户的程序，用户发送请求，例如"北京天气如何"，此程序通过大模型分析用户语义并和mcpserver暴露的服务做匹配，在调用对应服务获取返回，大模型加工之后返回给用户,可参考mcp_simple_chatbot
- 需要有mcpserver注册功能
- 解决上述业务流程

将上面这段话发送给cursor agent，便能生成项目 mcp_chat_app，经过调试基本可用

curl -X POST "http://localhost:8081/chat/test_user" -H "Content-Type: application/json" -d '{"message":  "明天29以上，30以下的城市有哪些？", "use_tools": true}'
{"response":"根据天气预报，明天温度在29°C到30°C之间的城市有以下两个：\n\n1. **广州**：预计最高温度为30°C，天气以高温为主。\n2. **深圳**：预计温度为29.5°C，天气多云。\n\n如果你计划去这两个城市之一，记得根据天气情况做好准备哦！ 😊"}%

curl -X POST "http://localhost:8081/chat/test_user" -H "Content-Type: application/json" -d '{"message":  "西安今天天气如何？", "use_tools": true}'
{"response":"您好！关于西安今天的天气，目前MCP服务没有直接提供具体信息，但它给出了未来7天内部分城市的天气概况。从这些数据中，我们可以看到：\n\n- **最热的城市**是广州和深圳，分别达到30.0°C（高温）和29.5°C（多云）。  \n- **有降雨的城市**是成都，预报为小雨。\n\n虽然西安的天气未在上述列表中提及，但通常情况下，西安的天气以干燥和晴朗为主，建议您参考本地天气应用或稍后再查询以获取更准确的信息哦！如果需要进一步帮助，请告诉我！ 😊"}%

项目扩展

本项目可以通过以下方式进行扩展:

添加更多MCP服务: 开发新的专业服务，如文档处理、代码生成等
增强聊天体验: 添加上下文管理、多轮对话支持
提升大模型能力: 接入更强大的模型、优化提示词工程
开发Web/移动前端: 构建用户友好的界面
添加身份验证: 实现用户管理和权限控制

MCP当前生态

MCP作为一项相对新兴的技术标准，其生态系统目前仍处于发展初期：

成熟应用:
- Claude桌面应用是目前集成MCP最完善的应用，提供了完整的MCP服务发现、管理和调用功能
- Cursor IDE已实现基础的MCP支持，允许开发者在编码过程中利用本地上下文
生态状况:
- 当前支持MCP的应用和工具相对有限，主要集中在开发工具和专业领域
- 官方SDK支持主流编程语言(Python、TypeScript、Java、Kotlin)，但社区贡献的MCP服务库尚在起步阶段
- 大多数MCP服务需要开发者自行构建和部署
发展趋势:
- 随着Anthropic持续推动标准发展和生态建设，更多应用预计将添加MCP支持
- 厂商中立的特性使得MCP有潜力成为连接LLM和专业服务的通用标准
- 开发者社区对私有部署和数据安全的需求正在推动MCP在企业环境中的应用