Mcp 智能聊天助手示例项目

Posted by elrond on March 19, 2025

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_toolslist_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协议进行包装,以便与大模型应用集成。

相关资源

贡献指南

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

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

许可证

Apache-2.0 License