AI导哈

聊天应用客户端

一个全栈聊天应用程序，连接LLM提供商并利用MCP（模型上下文协议）服务器的工具，具有现代界面和全面的工具执行与可视化功能。

  • by jeffvestal
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 jeffvestal/simple-mcp-client

使用说明

简单MCP客户端

一个连接到LLM提供商并利用MCP（模型上下文协议）服务器工具的全栈聊天应用程序。具有干净、现代的界面，具有全面的工具执行和可视化功能。

当前状态

此应用程序是 功能齐全，生产就绪 具有强大的错误处理能力：

✅ 完整的工具执行流程：端到端工具调用，并提供LLM后续响应
✅ 智能错误恢复：任何MCP服务器验证错误的自动参数校正
✅ 稳健的错误处理：全面的工具故障恢复和OpenAI API合规性
✅ 专业用户界面：带有实时状态指示器的可折叠工具调用显示
✅ 多LLM支持：OpenAI、Gemini和Bedrock兼容的API
✅ MCP服务器管理：远程和本地MCP服务器支持流程管理
✅ 实时状态：实时连接状态和服务器运行状况监控
✅ 暗/亮模式：设计简洁，主题切换持久
✅ 聊天管理：清晰的聊天功能和消息历史记录
✅ 对话历史：多回转工具对话的适当OpenAI API合规性
✅ 重试机制：用于参数校正的验证错误的智能重试逻辑

特性

  • 现代聊天界面：使用markdown支持和用户/助理消息气泡清洁UI
  • 完成工具执行：执行工具时，将结果反馈给LLM以获得自然反应
  • 工具可视化：可扩展的工具调用显示，显示带有状态指示器的请求/响应详细信息
  • 高级错误处理：通过智能参数校正从工具故障中自动恢复
  • OpenAI API合规性：对多回合工具交互进行适当的对话历史管理
  • MCP服务器集成：通过自动工具发现连接和管理多个MCP服务器
  • 本地和远程服务器：支持基于HTTP和基于本地进程的MCP服务器
  • 流程管理：通过运行状况监控自动启动/关闭服务器
  • 多LLM支持：OpenAI、Gemini和Bedrock兼容的API
  • 实时更新：实时连接状态和服务器管理
  • 响应式设计：适用于台式机和移动设备
  • 通用MCP兼容性：通过通用错误解析与任何MCP服务器配合使用

技术栈

  • 前端：React+TypeScript+Vite
  • 用户界面库：Shadcn/ui+顺风CSS+Lucide图标
  • 状态管理状态：
  • 后端：快速API+Python 3.8+
  • 数据库：SQLite（基于文件）
  • 协议：JSON-RPC 2.0上的MCP（HTTP和stdio）
  • 降价：ReactMarkdown用于丰富的消息呈现

快速开始

1.自动设置（推荐）

从项目根目录运行安装脚本：

./setup.sh

此脚本将：

  • 检查系统先决条件（Python 3.8+、Node.js 16+、npm）
  • 创建和配置Python虚拟环境
  • 安装所有Python依赖项
  • 安装所有Node.js依赖项
  • 初始化数据库
  • 提供启动应用程序的明确说明

2.快速开发启动（推荐）

该应用程序支持多种部署环境。使用统一的启动脚本运行后端和前端：

本地开发（默认）

./start-dev.sh
# or: ./start-dev.sh local

车间/Kubernetes环境（Instruqt等）

当后端无法通过localhost访问时，请使用代理模式：

./start-dev.sh proxy

这通过前端开发服务器代理API请求，以避免外部端口访问问题。

自定义后端URL

对于远程后端或自定义部署：

./start-dev.sh custom https://your-backend-url/api
# or: VITE_API_BASE_URL=https://your-backend-url/api ./start-dev.sh custom

快速参考-启动选项

命令 用例 描述
./start-dev.sh 本地开发 默认模式，两台服务器都在本地主机上
./start-dev.sh proxy 研讨会，Kubernetes 前端代理API请求
./start-dev.sh custom URL 远程后端 自定义后端URL

脚本将：

  • 启动后端服务器 http://localhost:8002
  • 启动前端服务器 http://localhost:5173 （或下一个可用端口）
  • 将所有输出记录到 logs/backend.log 和 logs/frontend.log
  • 按Ctrl+C时处理优雅关机
  • 显示实时状态和URL

要停止服务器，请执行以下操作： 按 Ctrl+C 在运行脚本的终端中。

实时监控日志：

# Backend logs
tail -f logs/backend.log

# Frontend logs  
tail -f logs/frontend.log

3.手动设置

如果您更喜欢手动设置或需要进行故障排除：

后端设置

  1. 导航到后端目录：

    cd backend

  2. 创建Python虚拟环境：

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. 安装依赖项：

    pip install -r requirements.txt

  4. 启动FastAPI服务器：

    python main.py

API将于 http://localhost:8002

前端设置

  1. 导航到前端目录：

    cd frontend

  2. 安装依赖项：

    npm install

  3. 启动开发服务器：

    npm run dev

该应用程序将在 http://localhost:5173

用法

入门指南

  1. 配置LLM提供程序:

    • 单击右上角的设置图标
    • 添加您的法学硕士提供者（OpenAI、Gemini或Bedrock）
    • 输入API密钥并配置设置
    • 连接后，状态指示灯将变为绿色

  2. 添加MCP服务器 （可选）：

    • 在设置中，转到MCP服务器部分
    • 添加远程或本地MCP服务器
    • 启动服务器并验证工具发现
    • LLM将自动使用工具

  3. 开始聊天:

    • 返回聊天界面
    • 提问或请求工具使用
    • 观察工具在可折叠显示中执行
    • 根据工具结果获取自然语言响应

交互示例

  • “纽约的天气怎么样？” -使用气象MCP工具
  • “搜索有关…的信息” -使用搜索/web MCP工具
  • “分析此数据…” -使用分析MCP工具
  • 一般对话 -无需工具的直接LLM响应

配置

LLM提供商

该应用程序支持多个LLM提供程序：

  • OpenAI兼容:
    • OpenAI API
    • 当地模特（Ollama、LM Studio等）
    • 其他与OpenAI兼容的端点
  • 谷歌双子座：直接Gemini API集成
  • AWS基岩：克劳德、泰坦和其他基岩模型

MCP服务器

支持两种类型的MCP服务器：

远程MCP服务器（HTTP）

连接到基于HTTP的MCP服务器：

  • 名字：服务器的显示名称
  • 统一资源定位符：JSON-RPC通信的HTTP端点
  • API密钥：可选身份验证令牌
  • 自动发现：在连接时发现工具

本地MCP服务器（进程）

将MCP服务器作为本地进程运行：

  • 名字：服务器的显示名称
  • 命令：可执行命令（例如。， uv, npx, python)
  • 参数：命令参数（每行一个）
  • 工作目录：运行命令的可选目录
  • 自动启动：是否自动启动服务器
  • 流程管理：自动启动、运行状况监视和清理

本地服务器配置示例：

Name: Weather Server
Command: uv
Arguments: 
  run
  weather.py
Working Directory: /path/to/weather-mcp/weather
Auto-start: Yes

安全说明

⚠️ 这是一个演示应用程序 专为开发和测试目的而设计。当前安全考虑：

  • API密钥是用基本哈希存储的（不是生产就绪加密）
  • 未实施身份验证/授权系统
  • 本地MCP服务器以用户权限运行
  • CORS已启用用于开发（仅限本地主机）
  • 综合测井可能会在开发模式下暴露敏感数据

用于生产用途，实施：

  • 对敏感数据存储进行适当加密
  • 用户身份验证和会话管理
  • API速率限制和输入验证
  • 安全MCP服务器沙盒
  • 数据库访问控制
  • 审核和清理所有日志输出

看 CLAUDE.md 详细的安全改进任务和实施指导。

建筑

后端结构

backend/
├── app/
│   ├── api/routes.py               # FastAPI endpoints
│   ├── core/database.py            # SQLite database operations  
│   ├── models/schemas.py           # Pydantic models
│   └── services/
│       ├── llm_service.py          # LLM provider integrations
│       ├── mcp_client.py           # Remote MCP protocol client
│       └── local_mcp_manager.py    # Local MCP process management
├── logs/                           # Application and MCP server logs
└── main.py                         # FastAPI application with lifespan management

前端结构

frontend/
├── src/
│   ├── components/
│   │   ├── ui/                     # Shadcn/ui components
│   │   ├── ChatInterfaceSimple.tsx # Main chat interface with tool execution
│   │   └── SettingsPage.tsx        # Configuration management
│   ├── lib/
│   │   ├── api.ts                  # Backend API client
│   │   └── utils.ts                # Utility functions
│   ├── store/
│   │   └── useStore.ts             # Zustand state management
│   └── types/
│       └── api.ts                  # TypeScript interfaces
├── public/
│   └── robot-logo.png              # Application logo
└── AppMinimal.tsx                  # Main application component

关键组件

  • 聊天接口简单：使用UI完成工具执行管道
  • 工具显示：可折叠工具可视化组件
  • 本地MCPManager：本地MCP服务器的流程管理
  • LLMS服务：多提供商LLM集成与工具调用
  • 数据库：用于配置和服务器状态的SQLite存储

API终点

核心终点

  • GET / -API状态
  • POST /api/chat -发送带有工具执行支持的消息
  • GET /api/llm/configs -列出LLM配置
  • POST /api/llm/configs -创建LLM配置
  • POST /api/llm/configs/{id}/activate -激活LLM配置

MCP管理

  • GET /api/mcp/servers -列出所有MCP服务器
  • GET /api/mcp/servers/{id} -使用工具获取服务器详细信息
  • POST /api/mcp/servers -创建MCP服务器
  • POST /api/mcp/servers/{id}/start -启动本地MCP服务器
  • POST /api/mcp/servers/{id}/stop -停止本地MCP服务器
  • POST /api/mcp/call-tool -执行MCP工具

发展

运行开发服务器

建议使用合并脚本：

# Start both servers
./start-dev.sh

# Stop both servers  
./stop-dev.sh

发展现状和路线图

该应用程序功能齐全，最近对错误处理和OpenAI API合规性进行了改进。有关详细的开发计划和改进任务，请参阅 CLAUDE.md.

最近的改进（已完成）:

  • ✅ 修复了关键工具执行错误和OpenAI API合规性问题
  • ✅ 为MCP验证错误添加了智能参数校正
  • ✅ 为失败的工具调用实现了强大的重试机制
  • ✅ 增强对话历史管理，实现多回合互动
  • ✅ 为所有工具调用场景添加了全面的错误响应处理

计划改进 （按优先级排列 CLAUDE.md):

  • 🔄 第1周（关键）：代码质量修复、错误边界、性能日志记录
  • 🔄 第2周（建筑）：重构大型组件，优化重新渲染，添加缓存
  • 🔄 第3周（用户体验）：用户友好的错误消息、进度指示器、干净的显示
  • 🔄 第4周（波兰语）：单元测试、安全审计、TypeScript严格模式

对于贡献者：参见 CLAUDE.md 获取详细的技术指导、架构文档以及包含特定文件位置和实现细节的全面任务列表。

手动方法：

  1. 后端开发:

    cd backend
source venv/bin/activate  # Windows: venv\Scripts\activate
python main.py

  2. 前端开发:

    cd frontend
npm run dev

主要开发特征

  • 热重新加载：前端和后端都支持热重载
  • 日志记录：全面记录 logs/ 目录
  • 流程管理：自动MCP服务器生命周期管理
  • 错误处理：根据用户反馈进行优雅的错误处理
  • 状态管理：Zustand的持久UI状态

截图

- Chat Conversation with tool call

- Settings page for LLMs and MCP servers

贡献

这是一个示范项目。您可以根据自己的需要自由地分叉和扩展它。

许可证

Apache许可证2.0

相关 MCP