MCP Client With Groq And Streamlit

带有Groq和Streamlit的MCP客户端

使用LangChain、LangGraph和Groq构建的强大的模型上下文协议（MCP）客户端，具有实时执行跟踪、互联网搜索功能和交互式Streamlit界面。

🚀 特性

• MCP服务器集成：具有可定制工具的流式HTTP MCP服务器
• Groq LLM集成：使用Groq的API和LangChain进行快速推理
• 实时执行跟踪：全面详细的日志记录显示：

- Agent推理和决策过程 - 带有输入和输出的工具调用 - LLM思维步骤 - 链执行流程

• 网络搜索：用于网络搜索的Google自定义搜索API集成
• 交互式用户界面：基于Streamlit的web界面，便于交互
• 工具管理：模块化工具系统，易于扩展

📋 先决条件

• Python 3.8或更高版本
• Groq API密钥(在这里买一个)
• Google API密钥和自定义搜索引擎ID（用于网络搜索功能）

- 谷歌云控制台 - 自定义搜索引擎设置

🔧 安装

1. 克隆存储库 （或导航到项目目录）：

   cd MCPclientwithgroq

1. 创建虚拟环境 （推荐）：

   python -m venv venv

   # On Windows
   venv\Scripts\activate

   # On Linux/Mac
   source venv/bin/activate

1. 安装依赖项:

   pip install -r requirements.txt

1. 设置环境变量:

创建一个 .env 项目根目录中的文件：

   # Required: Groq API Key
   GROQ_API_KEY=your_groq_api_key_here

   # Optional: Custom Groq model (default: llama-3.3-70b-versatile)
   GROQ_MODEL=llama-3.3-70b-versatile

   # Required for web search: Google API credentials
   GOOGLE_API_KEY=your_google_api_key_here
   GOOGLE_CSE_ID=your_custom_search_engine_id_here

   # Optional: MCP Server URL (default: http://127.0.0.1:8000/mcp)
   MCP_URL=http://127.0.0.1:8000/mcp

   # Optional: Agent configuration
   AGENT_MAX_ITERATIONS=6
   AGENT_TIMEOUT_SECONDS=90
   MEMORY_WINDOW_SIZE=8
   MCP_CONNECT_TIMEOUT=12

   # Optional: Enable/disable verbose logging (default: true)
   VERBOSE_LOGGING=true

🏗️ 项目结构

.
├── client.py              # Main MCP client with Groq integration
├── mcp_server.py         # MCP server with streamable HTTP transport
├── streamlit_app.py      # Streamlit web interface
├── requirements.txt      # Python dependencies
├── README.md            # This file
└── .env                 # Environment variables (create this)

🎯 用法

1.启动MCP服务器

在一个终端中，启动MCP服务器：

python mcp_server.py

服务器将于启动 http://127.0.0.1:8000/mcp 默认情况下。您应该看到：

🚀 Starting MCP server (streamable-http)
📡 Transport: streamable-http
🔧 Available tools: get_time, calculate, web_search

2.运行客户端（CLI模式）

在另一个终端中，运行客户端：

python client.py

这将启动一个交互式CLI，您可以在其中与代理聊天：

================================================================================
MCP Client (Groq)
================================================================================
Connecting to services...
Connected successfully!
Tools available: 3

Assistant Ready!
Type 'exit' to quit
================================================================================

You: What's the current time?

3.运行Streamlit Web界面

为了获得更好的用户体验，请使用Streamlit界面：

streamlit run streamlit_app.py

重要：使用 streamlit run，不 python streamlit_app.py

该应用程序将在您的浏览器中打开 http://localhost:8501

🛠️ 可用工具

MCP服务器提供以下工具：

1. get_time

以ISO格式返回当前日期和时间。

用法示例:

• 用户：“现在几点了？”
• 客服：电话 get_time() → 返回当前日期时间

2. calculate

安全地计算数学表达式。

用法示例:

• 用户：“什么是15\*23+45？”
• 客服：电话 calculate("15 * 23 + 45") → 返回结果

3. web_search

使用Google自定义搜索API搜索互联网。

参数:

• query （必填）：搜索查询字符串
• num_results （可选，默认值：5）：要返回的结果数（最大值：10）

用法示例:

• 用户：“最新的人工智能趋势是什么？”
• 客服：电话 web_search({"query": "latest AI trends", "num_results": 5}) → 返回搜索结果

📊 详细日志记录

客户端具有全面的实时执行跟踪功能。当 VERBOSE_LOGGING=true，您将看到：

日志输出示例

🚀================================================================================
📝 USER QUERY: What are the current news trends in AI?
🚀================================================================================

🤖 Starting agent execution...

================================================================================
🤔 STEP 1: LLM Thinking...
================================================================================

💡 Agent Reasoning: I need to search the internet for current AI news trends...

🔧 Agent decided to call: web_search
   with args: {'query': 'current AI news trends', 'num_results': 5}

--------------------------------------------------------------------------------
🔧 TOOL CALL: web_search
📥 Input:
{
  "query": "current AI news trends",
  "num_results": 5
}
--------------------------------------------------------------------------------

✅ Tool 'web_search' returned result
   Result preview: {'status': 'success', 'query': 'current AI news trends'...

✅================================================================================
📤 FINAL RESPONSE:
--------------------------------------------------------------------------------
Based on the latest search results, here are the current AI trends...
✅================================================================================

日志记录功能

• 步骤编号：每个LLM推理步骤都有编号
• 工具调用：显示调用了哪些工具以及使用了哪些参数
• 工具输出：显示工具结果（为了可读性而截断）
• 链执行：跟踪代理链中的执行流
• 错误记录：带有上下文的全面错误消息

⚙️ 配置选项

环境变量

\*仅在使用时需要 web_search 工具

🐛 故障排除

连接错误

问题：“无法连接到MCP服务器”

• 解决方案：确保MCP服务器在预期端口上运行（默认值：8000）
• 检查 MCP_URL 在你的 .env 文件与服务器地址匹配

缺少API密钥

问题：“缺少GROQ_API_KEY”

• 解决方案：将您的Groq API密钥添加到 .env 文件
• 确保 .env 文件位于项目根目录中

Web搜索不起作用

问题：Web搜索返回错误

• 解决方案:

1. 验证 GOOGLE_API_KEY 和 GOOGLE_CSE_ID 设置正确 1. 确保您的Google API密钥已启用自定义搜索API 1. 检查您的自定义搜索引擎是否配置正确

流光灯警告

问题：“缺少ScriptRunContext”警告

• 解决方案：始终使用 streamlit run streamlit_app.py，不 python streamlit_app.py

工具架构错误

问题：“工具调用验证失败”错误

• 解决方案：Groq的API可能会出现这种情况。确保使用兼容的工具模式
• 检查工具是否在中正确定义 mcp_server.py

🔌 添加新工具

要向MCP服务器添加新工具，请编辑 mcp_server.py:

@mcp.tool()
def your_new_tool(param1: str, param2: int = 5) -> Dict[str, Any]:
    """
    Description of what your tool does.
    
    Args:
        param1: Description of param1
        param2: Description of param2 (default: 5)
    
    Returns:
        Dictionary with results
    """
    try:
        # Your tool logic here
        result = do_something(param1, param2)
        return {
            "status": "success",
            "result": result
        }
    except Exception as e:
        return {"status": "error", "error": str(e)}

重启服务器后，该工具将自动对客户端可用。

📝 查询示例

以下是一些您可以尝试的示例查询：

时间查询:

• “现在几点了？”
• “获取当前日期和时间”

计算查询:

• “计算125\*342”
• “850的15%是多少？”
• “求解：（100+50）/2”

Web搜索查询:

• “搜索最新的Python更新”
• “机器学习的当前趋势是什么？”
• “查找有关LangChain的信息”

组合查询:

• “现在几点了，搜索今天的新闻？”
• “计算100\*50，然后搜索计算器工具”

🏛️ 建筑

┌─────────────────┐
│  Streamlit UI   │
│  streamlit_app  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   MCP Client    │
│   client.py     │◄─── LangGraph Agent
│                 │     + Groq LLM
└────────┬────────┘
         │
         │ (Streamable HTTP)
         ▼
┌─────────────────┐
│   MCP Server    │
│  mcp_server.py  │
│                 │
│  Tools:         │
│  - get_time     │
│  - calculate    │
│  - web_search   │
└─────────────────┘

🧪 测试

测试基本功能：

1. 启动服务器:

   python mcp_server.py

1. 在另一个终端中，测试客户端:

   python client.py

1. 尝试这些查询:

- “现在几点了？” - “计算2+2” - “搜索Python文档”

📚 依赖项

关键依赖关系包括：

• LangChain：构建LLM应用程序的框架
• LangGraph：用于代理编排和工作流
• Groq：快速LLM推理
• 主控程序：用于工具集成的模型上下文协议
• 溪流：Web UI框架
• FastMCP：MCP服务器实现
• httpx：异步HTTP客户端

看 requirements.txt 查看完整列表。

🤝 贡献

请随意：

• 添加新工具 mcp_server.py
• 增强Streamlit UI
• 改进详细日志记录
• 向客户端添加新功能

📄 许可证

MIT许可证-您可以自由地将此项目用于您自己的目的。

🙏 致谢

• LangChain 对于框架
• Groq 用于快速LLM推理
• 溪流 对于UI框架
• 主控程序 对于协议规范

📞 支持

对于问题或疑问：

1. 检查故障排除部分
2. 查看日志（启用详细日志记录）
3. 验证所有环境变量是否设置正确

______________________________________________________________________