AI导哈

多客户端协议聊天代理

一个基于FastAPI的多客户端协议（MCP）聊天代理服务，集成了Groq大型语言模型和Redis历史记录管理，适用于需要上下文感知对话的应用场景。

  • by SatyamSingh8306
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 SatyamSingh8306/MCP-Client

使用说明

MCP 客户端

概述

这个仓库托管了一个FastAPI服务，该服务提供了一个面向聊天的多客户端协议（MCP）代理。API负责在终端用户、Groq托管的大型语言模型以及任何符合MCP规范且位于MCP服务器后的工具之间进行对话代理。Redis用于用户注册、状态管理和持久聊天记录。

主要特点

  • 由MCP支持的代理 由……提供支持/驱动 langgraph 和 langchain 用于工具感知推理。
  • Groq LLM集成 通过 ChatGroq可根据请求进行配置。
  • 基于Redis的历史记录 该系统追踪每个用户的人类、系统和AI消息。
  • REST API（Representational State Transfer Application Programming Interface，表述性状态传递应用程序编程接口） 具有聊天、继续对话、查看历史记录以及清除/重置上下文的端点。
  • 启用CORS的FastAPI 可在任何网关后部署的服务。

项目结构

app/
  __init__.py          # Loads configuration from .env (host, ports, service URLs)
  __main__.py          # Uvicorn entry point (python -m app)
  main.py              # FastAPI factory and middleware
  routes/
    mcp_agent.py       # REST endpoints exposing the MCP agent
  services/
    chat.py            # Chat session lifecycle and LangChain runnable wrapper
    chat_history.py    # Redis-backed message history helpers
    mcp_service.py     # MCP client + LangGraph agent orchestration
    redis.py           # Redis connection & CRUD utilities
    system_message.py  # Default Coding Club system prompt
  types/
    message_response.py
  utils/
    errors.py          # Reserved for custom exceptions
requirements.txt       # Python dependencies

架构图

高级数据流如图所示 assets/architecture.svg嵌入或直接打开它，以可视化FastAPI层如何与Redis、Groq以及MCP服务器进行交互。

先决条件

  • Python 3.10+（与LangChain和FastAPI兼容支持）
  • 启用了 RedisJSON 模块的 Redis 服务器（此模块为……所必需） redis.commands.json)
  • 运行中的MCP服务器，可通过以下地址访问： MCP_SERVER_URL
  • Groq API密钥，可访问所选模型（默认： qwen/qwen3-32b)

安装

python -m venv .venv
.venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt

环境变量

创建一个 .env 在项目根目录下的文件。支持的变量：

变量 默认值 描述
HOST 0.0.0.0 uvicorn 绑定的接口。
PORT 8001 Uvicorn 服务器监听的端口。
MCP_SERVER_URL http://localhost:8000 MCP服务器的基础URL。
REDIS_URL redis://localhost:6379 Redis 连接字符串。
GROQ_API_KEY 所需的 所使用的API密钥 ChatGroq。

注： REDIS_URL 在（某处）被读了两次 app.__init__; 在其中定义它 .env 确保所有消费者都能获得相同的价值。

运行服务

python -m app

这启动了 uvicorn，并使用了在（某处）定义的配置 app/__main__.py你也可以运行 uvicorn app.main:app --host <HOST> --port <PORT> 如需，可直接（联系/告知）。

FastAPI 将可用在 http://<HOST>:<PORT>。

API 参考文档

所有终端点均归类于 /mcp-agent 除非另有说明。

  • GET / 验证服务是否在线。

  • 获取 /health 轻量级健康检查返回 {"status": "healthy"} （当）准备好了的时候。

  • POST（邮政） /mcp-agent/chat 开始对话（或恢复非活动对话），同时允许可选的系统提示覆盖。

    {
  "user_id": "student-123",
  "message": "Help me debug my code",
  "system_prompt": "Optional custom instructions",
  "model_name": "openai/gpt-oss-120b"
}

    返回助手的回复和完整历史记录（包括系统消息）。

  • POST（邮寄/发帖） /mcp-agent/continue 继续使用现有对话历史进行对话。省略系统提示。

  • GET（获取） /mcp-agent/history/{user_id} 检索为给定用户ID存储的历史记录，包括系统消息。

  • POST（邮政服务/发布） /mcp-agent/history/clear 清除用户的聊天历史记录和缓存的MCP上下文。预期（或：需要） { "user_id": "..." }.

  • POST（邮政） /mcp-agent/reset 用于清除历史记录和代理状态的别名。

对话生命周期

  1. 在 Redis 中注册或激活用户（参见 RedisService.set_user）。
  2. 打电话 /mcp-agent/chat 或者 /continue （与）一起；带有；具有 user_id 并且 message。
  3. Redis通过（某种方式）存储人类和AI的回合/步骤 ChatHistoryService 用于情境感知回复。
  4. 使用 /history/{user_id} 用于调试或 /history/clear 当你需要一个新的开始时。

开发技巧

  • 在调用任何聊天端点之前，请确保Redis可访问；否则 ChatService 将会引发用户注册错误。
  • 自定义默认系统提示语 app/services/system_message.py 以调整团队品牌或行为。
  • 在下方添加额外的路由器 app/routes/ 并将它们包含在 app/main.py 按需使用。
  • 通过在所引用的MCP服务器上注册更多MCP工具来扩展功能 MCP_SERVER_URL。

测试API

进行一个快速的烟雾测试，使用 curl：

curl -X POST http://localhost:8001/mcp-agent/chat \
  -H "Content-Type: application/json" \
  -d '{
        "user_id": "local",
        "message": "Say hello",
        "model_name": "qwen/qwen3-32b"
      }'

预期会收到一个包含助手消息和对话历史的JSON响应。

作者

  • 萨蒂亚姆·辛格 — satyamsingh7734@gmail.com（该邮箱地址翻译为中文仍为原样，因为邮箱地址本身是国际通用的，无需翻译）

持续集成/持续交付（CI/CD）与部署

  • GitHub Actions工作流程在 .github/workflows/deploy.yml 通过手动触发 运行工作流 GitHub Actions 中的按钮（workflow_dispatch）。
  • 渲染部署钩子配置 RENDER_DEPLOY_HOOK_URL 在你的仓库设置中保存秘密。工作流会向这个钩子发布请求以触发部署。
  • 要求渲染服务应提供一个部署挂钩URL，并且部署应与提供的（挂钩）保持一致 Dockerfile 或者您的渲染构建设置。

许可证

这个项目采用MIT许可证授权。请参阅 LICENSE 文件中包含完整详情。

相关 MCP