MCP 智能聊天助手示例项目

基于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本质上是一个标准化的连接协议，它作为关键的桥梁，将三个核心组件优雅地连接在一起：

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

作为连接器，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的实际工作流程遵循以下步骤：

1. 服务准备：首先，你需要一个或多个遵循MCP标准的MCP服务器，每个服务器为特定领域暴露一个功能接口（工具）和数据资源。这些服务器可以是本地的或远程的。

2. 用户应用：用户通过集成了MCP客户端的应用程序（如聊天界面、IDE插件等）发送请求，MCP客户端负责与MCP服务器通信。

3. 请求处理：

   • 用户发送自然语言请求（例如"查询明天北京的天气"）
   • 应用程序收集所有已注册的MCP服务器及其工具信息
   • 应用程序调用大语言模型分析用户意图，并将其映射到适当的MCP服务和工具
   • 模型返回结构化调用信息（服务名称、工具名称、参数等）

4. 服务调用：

   • 应用程序根据模型的决定，调用指定MCP服务器的相关工具
   • MCP服务器处理请求并返回结构化数据

5. 结果处理：

   • 应用程序从服务器接收专业数据
   • 再次调用模型将专业数据转换为用户友好的自然语言回复
   • 向用户呈现最终回复

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

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

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

MCP多服务器协调机制

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

1. 服务发现和注册：

   • MCP主机在启动时扫描并发现本地或网络中的MCP服务器
   • 每个服务器在启动时向主机注册其能力（工具、资源类型等）
   • 主机维护服务器能力映射表，用于路由请求

2. 能力描述和工具列表：

   • 每个MCP服务器发布其支持的工具列表、参数规范和资源类型
   • 主机可以通过list_tools和list_resources等API获取每个服务器的能力
   • 模型根据这些能力决定调用哪个服务器的哪个工具

3. 上下文管理：

   • MCP维护请求上下文，以确保多服务器调用之间的信息一致性
   • 上下文可以包括会话信息、用户偏好、身份验证令牌等
   • 服务器可以读取上下文以提供个性化响应

4. 请求路由：

   • 当应用程序或模型需要特定服务时，MCP客户端负责：
     • 识别哪个服务器可以处理请求
     • 将请求格式化为标准的MCP协议消息
     • 与目标服务器建立连接
     • 传输请求并等待响应

5. 并行处理：

   • MCP支持同时向多个服务器发送请求
   • 可以并行获取不同数据源的信息
   • 可以将多个服务器的结果聚合到一个响应中

6. 错误处理和回退：

   • 当特定服务器不可用时，MCP可以自动尝试备用服务器
   • 错误报告机制帮助应用程序诊断问题
   • 支持为服务中断定义回退策略

7. 版本兼容性：

   • MCP协议设计支持不同版本的服务器共存
   • 客户端可以处理版本差异，以确保向后兼容性
   • 新服务器可以提供增强功能，而无需更新整个环境

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

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

这种协调机制使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应用能够安全地访问和处理各种数据源，同时提供丰富的上下文，让大语言模型发挥最大价值。

项目架构

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

1. 聊天服务(Chat App)：核心服务组件，负责
   • 用户请求处理
   • 大模型API调用
   • 用户意图解析
   • MCP服务调用协调
   • 响应格式化
2. MCP管理器：负责
   • MCP服务发现和注册
   • 工具列表管理
   • 服务调用路由
3. 天气MCP服务：提供天气信息查询功能
   • 天气数据获取
   • 温度范围查询
   • 降水预测
   • 天气图表生成
4. 大语言模型服务(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)在整个系统中扮演着"大脑"角色，与其他组件有三个关键交互点：

1. 与聊天服务(chat_app.py)的交互：

   • 接收用户原始查询，分析用户意图
   • 从可用工具列表中选择最合适的MCP服务和工具
   • 提取和格式化调用参数
   • 将MCP服务返回的结构化数据转化为自然语言回复
   • 处理错误情况并提供友好响应

2. 与MCP服务的间接交互：

   • 通过聊天服务作为中介，大模型决定调用哪个MCP服务
   • 根据MCP服务的工具文档信息，正确构造调用参数
   • 理解MCP服务返回的数据结构，进行信息提取和整合

3. 模型能力应用：

   • 语义理解：将自然语言转化为结构化意图
   • 上下文记忆：维持多轮对话的连贯性
   • 格式转换：在自然语言和结构化数据间互相转换
   • 多模态处理：支持文本、图表、结构化数据等混合内容

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

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

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

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

系统工作流程：

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

用户使用方式

通过调用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了

!mcp-inspector

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

!cursor-mcp

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

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

!cursor-mcp-server

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

!cursor-beijing

生成用户程序

现在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虽然西安的天气未在上述列表中提及，但通常情况下，西安的天气以干燥和晴朗为主，建议您参考本地天气应用或稍后再查询以获取更准确的信息哦！如果需要进一步帮助，请告诉我！ 😊"}%      

项目扩展

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

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

MCP当前生态

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

• 成熟应用:

  • Claude桌面应用是目前集成MCP最完善的应用，提供了完整的MCP服务发现、管理和调用功能
  • Cursor IDE已实现基础的MCP支持，允许开发者在编码过程中利用本地上下文

• 生态状况:

  • 当前支持MCP的应用和工具相对有限，主要集中在开发工具和专业领域
  • 官方SDK支持主流编程语言(Python、TypeScript、Java、Kotlin)，但社区贡献的MCP服务库尚在起步阶段
  • 大多数MCP服务需要开发者自行构建和部署

• 发展趋势:

  • 随着Anthropic持续推动标准发展和生态建设，更多应用预计将添加MCP支持
  • 厂商中立的特性使得MCP有潜力成为连接LLM和专业服务的通用标准
  • 开发者社区对私有部署和数据安全的需求正在推动MCP在企业环境中的应用

对于开发者而言，现阶段是参与MCP生态建设的有利时机，可以通过构建专业领域的MCP服务来填补生态空白，也可以将现有工具和服务通过MCP协议进行包装，以便与大模型应用集成。

相关资源

• 📚 阅读 MCP文档
• 🔍 查看 MCP规范
• 💻 使用SDK构建:
  • TypeScript SDK
  • Python SDK
  • Java SDK
  • Kotlin SDK

贡献指南

欢迎为项目做出贡献! 您可以通过以下方式参与:

1. 提交问题和功能请求
2. 提交代码改进
3. 贡献新的MCP服务
4. 改进文档

许可证

Apache-2.0 License