通用MCP客户端

一个基于网页、可投入生产的AI聊天助手，作为通用的MCP（模型上下文协议）客户端。该助手采用Azure OpenAI、LangGraph、FastAPI、React和PostgreSQL构建。

特点/功能

通用MCP客户端同时连接到多个MCP服务器（通过STDIO和HTTP传输方式）
多运输方式支持支持本地STDIO服务器和远程HTTP服务器
代理工作流LangGraph功能API，支持@entrypoint装饰器和PostgreSQL检查点功能
持续对话基于PostgreSQL的聊天历史记录和状态管理
实时聊天WebSocket和REST API端点
自动工具发现动态发现并使用连接的MCP服务器上的工具
Azure与OpenAI的集成由Azure OpenAI GPT-4o提供智能响应支持
Docker 部署带有多阶段构建的完整容器化堆栈

建筑

┌─────────────────────────────────────────────────────┐
│                   Frontend (React)                   │
│              http://localhost:5173                   │
└──────────────────────┬──────────────────────────────┘
                       │ WebSocket / REST
┌──────────────────────▼──────────────────────────────┐
│              Backend (FastAPI)                       │
│              http://localhost:9000                   │
│  ┌────────────────────────────────────────────┐    │
│  │  LangGraph Agent (Functional API)          │    │
│  │  - @entrypoint with checkpointing          │    │
│  │  - @task for modular operations            │    │
│  └────────────────────────────────────────────┘    │
└───┬────────────┬────────────┬────────────┬─────────┘
    │            │            │            │
    ▼            ▼            ▼            ▼
┌────────┐  ┌────────┐  ┌──────────┐  ┌──────────┐
│ Azure  │  │  MCP   │  │  MCP     │  │ Postgres │
│ OpenAI │  │ Server │  │  Server  │  │ Database │
│        │  │ (FS)   │  │  (SQL)   │  │          │
└────────┘  └────────┘  └──────────┘  └──────────┘

______________________________________________________________________

🏗️ 架构概览 🎯 第三阶段：多运输方式基础已完成

┌─────────────────────────────────────────────────────────┐
│                  FastAPI Backend                         │
│  ┌────────────────────────────────────────────────┐    │
│  │         Enhanced MCPClient                      │    │
│  │  ┌──────────────┬──────────────┬────────────┐ │    │
│  │  │   Factory    │   STDIO      │ Streamable │ │    │
│  │  │              │   Transport  │    HTTP    │ │    │
│  │  └──────────────┴──────────────┴────────────┘ │    │
│  └────────────────────────────────────────────────┘    │
│           ↓                ↓                ↓           │
│    ┌──────────┐    ┌──────────┐    ┌──────────┐       │
│    │ Local FS │    │PostgreSQL│    │ Remote   │       │
│    │  Server  │    │  Server  │    │HTTP Srvr │       │
│    └──────────┘    └──────────┘    └──────────┘       │
└─────────────────────────────────────────────────────────┘
                      ↕ WebSocket/REST
┌─────────────────────────────────────────────────────────┐
│                  React Frontend                          │
│  - Server Management UI                                  │
│  - Multi-Session Management                              │
│  - Real-time Tool Execution Display                      │
└─────────────────────────────────────────────────────────┘

______________________________________________________________________

技术栈

后端：

FastAPI - 支持WebSocket的异步网络框架
LangGraph 功能性API - 使用 @entrypoint/@task 装饰器的代理式编排
Azure OpenAI - GPT-4o用于大型语言模型（LLM）能力
MCP SDK（MCP软件开发工具包） - 模型上下文协议客户端实现
PostgreSQL（译文：波斯特高斯奎尔/波斯特格瑞斯奎尔，但通常直接称为“PostgreSQL”） - 对话历史和LangGraph检查点保存
SQLAlchemy - 使用 psycopg 驱动的异步 ORM
蒸馏器 - 数据库迁移
紫外线 - 快速的Python包管理器

前端：

React 18 - 用户界面（UI）框架
TypeScript - 类型安全的开发
Vite（法语）翻译成中文是“快”。 - 极速构建工具
WebSocket（网络套接字协议） - 实时通信

基础设施：

Docker & Docker Compose - 容器化部署
PostgreSQL 15 - 数据库服务器
Nginx（发音类似“恩吉克斯”，但通常直接使用英文原名） - 前端网络服务器

快速入门Docker（推荐）

先决条件

Docker 和 Docker Compose
拥有API访问权限的Azure OpenAI帐户

1. 克隆并配置

# Clone the repository
git clone 
cd universal-mcp-client

# Copy and configure environment
cp .env.example .env

编辑 .env 使用您的 Azure OpenAI 凭据：

AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key-here
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4o
AZURE_OPENAI_API_VERSION=2025-01-01-preview

# Database (Docker default - change credentials in docker-compose.yml)
DATABASE_URL=postgresql+asyncpg://db_user:db_password@postgres:5432/mcp_chat

# Port Configuration (Optional - change if needed)
POSTGRES_PORT=5432
BACKEND_PORT=9000
FRONTEND_PORT=5173

关于端口的说明所有服务端口现在都可以通过环境变量进行配置。只需更改环境变量中的值即可 .env 并重启 Docker Compose - 无需更改代码！

2. 启动所有服务

docker-compose up -d

这开始了：

PostgreSQL（中文可译为“波斯特格瑞斯数据库”或直接保留原名，因其为专有名词，通常不翻译） 在端口5432上（可通过 POSTGRES_PORT)
后端在9000端口上（可通过 BACKEND_PORT)
前端在5173端口上（可通过 FRONTEND_PORT）

所有端口均可更改 .env 无需修改任何代码！

3. 访问应用程序

前端用户界面（UI）http://localhost:5173 翻译为中文可以是：“本地主机上的5173端口”或“访问本地开发服务器的5173端口”。不过，通常我们不会直接翻译网址，而是根据上下文来解释其含义。在这个例子中，网址表示的是在本地计算机上运行的一个Web应用或开发服务器的地址，可以通过浏览器访问该地址来查看或操作应用
后端APIhttp://localhost:9000 翻译为中文是：“本地主机的9000端口”。不过，通常我们不会直接这样翻译URL，而是根据上下文可能表述为“访问本地服务器的9000端口”或“在本地浏览器中打开http://localhost:9000”
API 文档http://localhost:9000/docs 翻译为中文是：“http://本地主机:9000/文档” 或者更简洁地表述为：“本地9000端口文档页面”。不过，通常我们不会直接翻译网址，而是解释其含义或用途，比如“访问本地9000端口的API文档页面”
健康检查http://localhost:9000/health 翻译为中文是：“本地主机：9000端口/健康检查”。不过，通常在技术语境中，我们可能会简化为“本地9000端口健康检查”或直接保留原URL作为技术文档或说明中的表述

4. 验证状态

# Check running containers
docker-compose ps

# View logs
docker-compose logs backend
docker-compose logs frontend

# Check MCP servers and tools
curl http://localhost:9000/health

本地开发环境设置

先决条件

Python 3.13+
Node.js 20+（版本）
UV包管理器
PostgreSQL 15及以上版本
针对MCP服务器的npm/npx

1. 数据库设置

# Start PostgreSQL (or use Docker)
docker run -d \
  --name postgres \
  -e POSTGRES_USER=your_db_user \
  -e POSTGRES_PASSWORD=your_secure_password \
  -e POSTGRES_DB=mcp_chat \
  -p 5432:5432 \
  postgres:15-alpine

2. 后端设置

# Install dependencies
uv sync

# Run database migrations
uv run alembic upgrade head

# Start backend
./run_backend.sh
# OR
PYTHONPATH=. uv run uvicorn src.api.server:app --reload --host 0.0.0.0 --port 9000

3. 前端设置

cd frontend
npm install
npm run dev

前端将可通过 http://localhost:5173 访问

MCP服务器配置

配置MCP服务器在 config/mcp_servers.json客户端支持两者 STDIO（标准输入输出） （本地）和 HTTP（超文本传输协议） (远程)传输：

STDIO 传输（本地服务器）

{
  "servers": [
    {
      "name": "filesystem",
      "description": "Local filesystem access MCP server",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "enabled": true
    },
    {
      "name": "PostgreSql",
      "description": "PostgreSQL data access MCP server",
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql+asyncpg://db_user:db_password@postgres:5432/mcp_chat"
      ],
      "enabled": true
    }
  ]
}

HTTP传输（远程服务器）

{
  "servers": [
    {
      "name": "exa-code",
      "description": "Fast, efficient web context for coding agents",
      "transport": "http",
      "url": "https://mcp.exa.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      },
      "enabled": true
    },
    {
      "name": "weather-api",
      "description": "Weather data MCP server",
      "transport": "http",
      "url": "http://localhost:8123/mcp",
      "headers": {},
      "enabled": true
    }
  ]
}

注：

对于Docker：使用服务名称 postgres 而不是 localhost 在STDIO服务器连接字符串中
HTTP传输支持本地和远程服务器
可选 headers 用于认证的字段（Bearer令牌、API密钥等）

API终端点

REST 端点

GET / API状态
GET /health - 与MCP服务器进行健康检查并统计工具数量
GET /tools - 列出所有可用的MCP工具
POST /chat - 发送聊天消息（返回响应）
POST /chat/reset - 清除会话的历史记录
GET /chat/history/{session_id} - 获取对话历史记录

WebSocket 终端点

WS /ws/chat - 实时双向聊天通信

示例 WebSocket 消息：

{
  "message": "List files in /tmp",
  "session_id": "user123"
}

项目结构

universal-mcp-client/
├── src/                          # Backend Python code
│   ├── api/                      # FastAPI server and endpoints
│   │   └── server.py            # Main server with lifespan management
│   ├── mcp/                      # MCP client implementation
│   │   └── client.py            # Universal MCP client
│   ├── orchestration/            # LangGraph workflows
│   │   ├── agent.py             # Main agent with @entrypoint
│   │   ├── checkpointer.py      # PostgreSQL checkpointer
│   │   └── state.py             # State type definitions
│   ├── llm/                      # LLM integrations
│   │   └── azure_openai.py      # Azure OpenAI client
│   └── storage/                  # Database layer
│       ├── database.py          # Database manager
│       └── models.py            # SQLAlchemy models
├── frontend/                     # React frontend
│   ├── src/
│   │   ├── components/          # React components
│   │   │   └── Chat.tsx        # Main chat interface
│   │   ├── App.tsx              # Root component
│   │   └── main.tsx             # Entry point
│   ├── Dockerfile               # Frontend Docker build
│   └── nginx.conf               # Nginx configuration
├── config/                       # Configuration files
│   └── mcp_servers.json         # MCP server definitions
├── alembic/                      # Database migrations
│   ├── versions/                # Migration files
│   └── env.py                   # Alembic configuration
├── docs/                         # Documentation
│   ├── LANGGRAPH_FUNCTIONAL_API.md
│   ├── MCP_PROTOCOL.md
│   └── IMPLEMENTATION_REFERENCE.md
├── docker-compose.yml            # Docker orchestration
├── Dockerfile                    # Backend Docker build
├── .env                          # Environment variables
└── README.md                     # This file

当前状态

✅ 已完成（第一阶段、第二阶段及第三阶段A）

使用UV包管理器进行项目设置
\[x\] 使用STDIO传输的MCP客户端
\[x\] HTTP传输支持（可流式传输的HTTP） 🆕 新的
\[x\] 具有抽象层的多运输架构 新增/新（符号常用于表示新内容或新状态）
\[x\] 支持多服务器MCP（文件系统、PostgreSQL、远程HTTP服务器）
\[x\] Azure与OpenAI GPT-4o的集成
\[x\] 带有@entrypoint/@task的LangGraph功能API
\[x\] PostgreSQL 会话持久性
\[x\] LangGraph PostgreSQL 检查点机制
\[x\] 使用REST + WebSocket的FastAPI后端
\[x\] React + TypeScript 前端
\[x\] 使用 Docker Compose 部署
使用Alembic进行数据库迁移
\[x\] 提供15+种MCP工具（文件系统操作、SQL操作、远程API）

🚧 第3B-E阶段：高级功能（进行中/下一步）

\[ \] 增强的前端用户界面/用户体验
\[ \] 实时显示工具执行结果的流式响应
\[ \] 多会话管理
\[ \] 工具执行审批流程（人工介入）
\[ \] 服务器管理界面（动态添加/移除服务器）
\[ \] 基于数据库的服务器配置
\[ \] 可观测性和调试工具
\[ \] 认证与授权
\[ \] 限速和使用追踪

开发命令

后端

# Install dependencies
uv sync

# Run migrations
uv run alembic upgrade head

# Create new migration
uv run alembic revision --autogenerate -m "description"

# Start server with hot reload
uv run uvicorn src.api.server:app --reload

# Run backend directly
./run_backend.sh

前端

cd frontend

# Install dependencies
npm install

# Development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Docker

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend

# Rebuild after code changes
docker-compose up -d --build

# Stop all services
docker-compose down

# Clean volumes (removes database data)
docker-compose down -v

故障排除

后端无法启动

检查环境变量在 .env
确保 PostgreSQL 正在运行且可访问
验证Azure OpenAI凭据
检查日志： docker-compose logs backend

数据库连接问题

# For Docker: Use service name 'postgres' not 'localhost'
DATABASE_URL=postgresql+asyncpg://db_user:db_password@postgres:5432/mcp_chat

# For local dev: Use localhost
DATABASE_URL=postgresql+asyncpg://db_user:db_password@localhost:5432/mcp_chat

MCP服务器连接失败

验证 config/mcp_servers.json 具有正确的路径
对于 Docker：使用与 Docker 兼容的路径和服务名称
检查后端容器中的MCP服务器日志
确保容器中可以使用 npx

前端无法连接到后端

检查后端是否在配置的端口上运行（默认9000，由……设置） BACKEND_PORT)
验证CORS设置 src/api/server.py
检查浏览器控制台中的错误
确保WebSocket连接已建立

端口冲突

如果你遇到“端口已被占用”的错误：

编辑 .env 并更改冲突的端口：

   POSTGRES_PORT=5433    # If 5432 is in use
   BACKEND_PORT=8080     # If 9000 is in use
   FRONTEND_PORT=3000    # If 5173 is in use

重启 Docker Compose：

   docker-compose down
   docker-compose up -d --build

该系统会自动更新所有内部引用，以使用您的新端口！

文档

做出贡献

这是一个作为通用MCP客户端演示的个人项目。欢迎贡献代码、报告问题和提出功能需求！

许可证

麻省理工学院（MIT）

______________________________________________________________________

构建于：

LangGraph 用于代理工作流的功能性API
工具集成的模型上下文协议
Azure OpenAI 用于智能回复
Docker 用于轻松部署

Universal MCP Client

快速接入

详细介绍

通用MCP客户端

特点/功能

建筑

🏗️ 架构概览 🎯 第三阶段：多运输方式基础 已完成

技术栈

快速入门Docker（推荐）

先决条件

1. 克隆并配置

2. 启动所有服务

3. 访问应用程序

4. 验证状态

本地开发环境设置

先决条件

1. 数据库设置

2. 后端设置

3. 前端设置

MCP服务器配置

STDIO 传输（本地服务器）

HTTP传输（远程服务器）

API终端点

REST 端点

WebSocket 终端点

项目结构

当前状态

✅ 已完成（第一阶段、第二阶段及第三阶段A）

🚧 第3B-E阶段：高级功能（进行中/下一步）

开发命令

后端

前端

Docker

故障排除

后端无法启动

数据库连接问题

MCP服务器连接失败

前端无法连接到后端

端口冲突

文档

做出贡献

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

🏗️ 架构概览 🎯 第三阶段：多运输方式基础已完成