MCPChatbot Example

MCPChatbot 示例

本项目演示了如何将模型上下文协议 (MCP) 与自定义大模型（如 Qwen）集成，创建一个功能强大的聊天机器人，能够通过 MCP 服务与各种工具进行交互。该实现通过使大模型能够无缝使用外部工具来展示 MCP 的灵活性。

提示

中文版本请参考 README_ZH.md。

概览

聊天机器人 Streamlit 示例

工作流追踪器示例

• 🚩 更新（2025-04-11）：
  • 添加了聊天机器人 streamlit 示例。
• 🚩 更新（2025-04-10）：
  • 更复杂的大模型响应解析，支持多个 MCP 工具调用和多次聊天迭代。
  • 添加了单个提示词示例，支持常规和流式两种模式。
  • 添加了交互式终端聊天机器人示例。

该项目包括：

• 简单/复杂的命令行聊天机器人界面
• 与内置 MCP 服务的集成（如 Markdown 处理工具）
• 支持自定义大模型（如 Qwen）和 Ollama
• 常规和流式两种模式的单个提示词处理示例脚本
• 具有常规和流式响应模式的交互式终端聊天机器人

要求

• Python 3.10+
• 依赖项（通过 requirements 自动安装）：
  • python-dotenv
  • mcp[cli]
  • openai
  • colorama

安装

1. 克隆仓库：

   git clone [email protected]:keli-wen/mcp_chatbot.git
   cd mcp_chatbot
   

2. 设置虚拟环境（推荐）：

   cd folder
   
   # Install uv if you don't have it already
   pip install uv
   
   # Create a virtual environment and install dependencies
   uv venv .venv --python=3.10
   
   # Activate the virtual environment
   # For macOS/Linux
   source .venv/bin/activate
   # For Windows
   .venv\Scripts\activate
   
   # Deactivate the virtual environment
   deactivate
   

3. 安装依赖项：

   pip install -r requirements.txt
   # or use uv for faster installation
   uv pip install -r requirements.txt
   

4. 配置您的环境：

   • 将 .env.example 文件复制到 .env：

     cp .env.example .env
     

   • 编辑 .env 文件以添加您的 Qwen API 密钥（仅用于演示，您可以使用任何大模型 API 密钥，记得在 .env 文件中设置 base_url 和 api_key）和设置路径：

     LLM_MODEL_NAME=your_llm_model_name_here
     LLM_BASE_URL=your_llm_base_url_here
     LLM_API_KEY=your_llm_api_key_here
     OLLAMA_MODEL_NAME=your_ollama_model_name_here
     OLLAMA_BASE_URL=your_ollama_base_url_here
     MARKDOWN_FOLDER_PATH=/path/to/your/markdown/folder
     RESULT_FOLDER_PATH=/path/to/your/result/folder
     

重要配置说明 ⚠️

运行应用程序前，您需要修改以下内容：

1. MCP 服务配置： 编辑 mcp_servers/servers_config.json 以匹配您的本地设置：

   {
       "mcpServers": {
           "markdown_processor": {
               "command": "/path/to/your/uv",
               "args": [
                   "--directory",
                   "/path/to/your/project/mcp_servers",
                   "run",
                   "markdown_processor.py"
               ]
           }
       }
   }
   

   将 /path/to/your/uv 替换为 uv 可执行文件的实际路径。您可以使用 which uv 获取路径。 将 /path/to/your/project/mcp_servers 替换为项目中 mcp_servers 目录的绝对路径。（对于 Windows 用户，您可以查看故障排除部分中的示例）

2. 环境变量： 确保在 .env 文件中设置了正确的路径：

   MARKDOWN_FOLDER_PATH="/path/to/your/markdown/folder"
   RESULT_FOLDER_PATH="/path/to/your/result/folder"
   

   应用程序将验证这些路径，如果它们包含占位符值，将抛出错误。

您可以运行以下命令来检查您的配置：

bash scripts/check.sh

使用

单元测试

您可以运行以下命令来运行单元测试：

bash scripts/unittest.sh

示例

单个提示词示例

该项目包括两个单个提示词示例：

1. 常规模式：处理单个提示词并显示完整响应

   python example/single_prompt/single_prompt.py
   

2. 流式模式：处理单个提示词并实时流式输出

   python example/single_prompt/single_prompt_stream.py
   

两个示例都接受一个可选的 --llm 参数来指定要使用的大模型提供商：

python example/single_prompt/single_prompt.py --llm=ollama

说明

有关更多详情，请参阅单个提示词示例 README。

终端聊天机器人示例

该项目包括两个交互式终端聊天机器人示例：

1. 常规模式：具有完整响应的交互式终端聊天

   python example/chatbot_terminal/chatbot_terminal.py
   

2. 流式模式：具有流式响应的交互式终端聊天

   python example/chatbot_terminal/chatbot_terminal_stream.py
   

两个示例都接受可选的 --llm 参数来指定要使用的大模型提供商：

python example/chatbot_terminal/chatbot_terminal.py --llm=ollama

说明

有关更多详情，请参阅终端聊天机器人示例 README。

Streamlit 网页聊天机器人示例

该项目包括一个使用 Streamlit 的交互式网页聊天机器人示例：

streamlit run example/chatbot_streamlit/app.py

此示例具有以下特点：

• 交互式聊天界面。
• 实时流式响应。
• 详细的 MCP 工具工作流可视化。
• 可配置的大模型设置（OpenAI/Ollama）和通过侧边栏进行的 MCP 工具显示。

说明

有关更多详情，请参阅Streamlit 聊天机器人示例 README。

项目结构

• mcp_chatbot/：核心库代码
  • chat/：聊天会话管理
  • config/：配置处理
  • llm/：大模型客户端实现
  • mcp/：MCP 客户端和工具集成
  • utils/：实用函数（例如 WorkflowTrace 和 StreamPrinter）
• mcp_servers/：自定义 MCP 服务实现
  • markdown_processor.py：用于处理 Markdown 文件的服务
  • servers_config.json：MCP 服务的配置
• data-example/：用于测试的示例 Markdown 文件
• example/：不同用例的示例脚本
  • single_prompt/：单个提示词处理示例（常规和流式）
  • chatbot_terminal/：交互式终端聊天机器人示例（常规和流式）
  • chatbot_streamlit/：使用 Streamlit 的交互式网页聊天机器人示例

扩展项目

您可以通过以下方式扩展此项目：

1. 在 mcp_servers/ 目录中添加新的 MCP 服务
2. 更新 servers_config.json 以包含您的新服务
3. 在现有服务中实现新功能
4. 基于提供的模板创建新示例

故障排除

对于 Windows 用户，您可以使用以下 servers_config.json 作为示例：

{
    "mcpServers": {
        "markdown_processor": {
            "command": "C:\\Users\\13430\\.local\\bin\\uv.exe",
            "args": [
                "--directory",
                "C:\\Users\\13430\\mcp_chatbot\\mcp_servers",
                "run", 
                "markdown_processor.py"
            ]
        }
    }
}

• 路径问题：确保配置文件中的所有路径都是适合您系统的绝对路径
• MCP 服务错误：确保工具已正确安装和配置
• API 密钥错误：验证您的 API 密钥已正确设置在 .env 文件中