AI导哈

AI聊天客户端

一个简化的AI聊天客户端，连接本地Ollama模型和MCP服务器，提供实时聊天和工具调用功能。

  • by parthashirolkar
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 parthashirolkar/mcp-client

使用说明

MCP客户端-简化的AI聊天界面

一个简化的模型上下文协议（MCP）客户端web应用程序，连接到本地Ollama模型和MCP服务器。该项目已从复杂的多服务架构完全重构为具有现代Claude.ai风格界面的专注、可维护的聊天应用程序。

🚀 最新动态（2025年11月）

  • 主要架构重构：代码减少60%，从约2000+行减少到约800行
  • Claude.ai灵感UI：完全重新设计，采用橙色强调色和深色/浅色主题
  • 简化后端：从15+个服务合并到2个核心文件
  • 增强的聊天体验：使用markdown渲染进行实时WebSocket通信
  • 注重简单：删除了复杂的功能，同时保留了核心功能

架构概述

当前实施（重构后）

mcp-client/
├── backend/                     # Simplified FastAPI backend (~800 lines)
│   ├── mcp_client.py           # Core MCP client with Ollama integration
│   ├── simple_main.py          # FastAPI server with WebSocket support
│   ├── run_server.py           # Server startup script
│   ├── mcp.json                # MCP server configuration
│   └── pyproject.toml          # Minimal dependencies (FastAPI, MCP, Ollama)
└── frontend/                   # React 19 + TypeScript + Material-UI
    ├── src/
    │   ├── components/Chat/     # Chat interface components
    │   │   ├── ChatInterface.tsx # Main chat with markdown rendering
    │   │   └── Sidebar.tsx     # Collapsible navigation
    │   ├── context/ThemeContext.tsx # Theme management
    │   ├── hooks/useThemeMode.ts   # Theme persistence
    │   └── App.tsx              # Main app component
    └── package.json             # React + Material-UI dependencies

关键简化

  • 移除：数据库持久化、热重载、多服务架构
  • 合并的：15+后端文件→ 2 核心文件
  • 流线型：复杂的依赖关系管理→ 5 核心包
  • 维护：所有聊天、MCP和Ollama功能

特性

✅ 核心功能

  • 实时聊天：与本地Ollama模型进行基于WebSocket的通信
  • MCP集成：连接到MCP服务器并使用其工具
  • 工具调用：支持JSON模式验证的完整函数调用
  • 32k上下文窗口：扩展对话上下文以提高连续性
  • 现代用户界面：以Claude.ai为灵感的设计，采用深色/浅色主题

🎨 用户界面

  • 响应式设计：适用于台式机和移动设备
  • 暗/亮主题：具有本地存储持久性的全面主题系统
  • 可折叠侧边栏：节省空间的导航（280px↔ 60像素）
  • Markdown渲染：富文本，带有代码突出显示和表格支持
  • 实时更新：即时消息传递，无需刷新页面

⚡ 技术特性

  • TypeScript：整个应用程序的全类型安全
  • 材料UI 7：现代组件库
  • WebSocket集成：实时双向通信
  • 错误处理：全面的错误恢复和用户反馈
  • Docker就绪：设计用于基于Docker的MCP服务器

快速开始

先决条件

  • Python 3.13+ 随着 紫外线 安装
  • Node.js 17+ 安装了npm
  • 码头工人 （适用于MCP服务器）
  • 奥拉马 本地安装 qwen2.5:3b 模型

1.克隆和设置

# Clone the repository
git clone https://github.com/your-username/mcp-client.git
cd mcp-client

# Setup backend
cd backend
uv sync
cd ..

# Setup frontend
cd frontend
npm install
cd ..

2.设置Olama

# Install Ollama (if not already installed)
curl -fsSL https://ollama.ai/install.sh | sh

# Pull the required model
ollama pull qwen2.5:3b

# Start Ollama service
ollama serve

3.设置MCP服务器（印度股票分析）

# Build and run the Indian Stock MCP server
docker build -t indian-stock-mcp-server /path/to/indian-stock-mcp-server
docker run -d --name indian-stock-mcp-server indian-stock-mcp-server

4.启动应用程序

后端（终端1）：

cd backend
uv run python run_server.py

前端（2号航站楼）：

cd frontend
npm start

5.访问应用程序

打开浏览器并导航到 http://localhost:3000

使用指南

开始对话

  1. 启动时，应用程序会自动连接到配置的MCP服务器
  2. 在聊天界面中键入您的信息，然后按Enter键
  3. 人工智能将使用当地Ollama进行响应，并可访问MCP工具
  4. 当股票市场分析需要时，工具调用会自动执行

主题定制

  • 切换主题：单击侧栏中的太阳/月亮图标
  • 折叠侧边栏：单击汉堡包菜单展开/折叠
  • 偏好设置：主题选项会自动保存

当前MCP工具

该应用程序配置了印度股市分析工具，这些工具提供：

  • 当前股价和公司基本面
  • 历史数据和技术指标
  • 市场概况和行业表现
  • 股票搜索和最新消息

API 文档

后端运行后，请访问 http://localhost:8000/docs 用于交互式API文档。

关键终点

  • POST /chat -使用MCP工具集成发送聊天消息
  • GET /health -检查应用程序和MCP服务器状态
  • GET /tools -列出可用的MCP工具
  • WebSocket /ws -实时聊天通信

配置

MCP服务器配置

编辑 backend/mcp.json 配置不同的MCP服务器：

{
  "mcpServers": {
    "your-server-name": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "container-name",
        "uv",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

Olama模型配置

默认模型为 qwen2.5:3b。要更改它，请修改 default_model 参数在 mcp_client.py.

发展

后端开发

cd backend

# Start with auto-reload
uv run uvicorn simple_main:app --reload --host 0.0.0.0 --port 8000

# Check dependencies
uv tree

前端开发

cd frontend

# Start development server
npm start

# Build for production
npm run build

# Run tests
npm test

代码质量

# Backend linting and formatting
cd backend
uv run ruff check .
uv run ruff format .

# Frontend linting (if configured)
cd frontend
npm run lint

故障排除

常见问题

  1. 后端无法启动:

    • 确保安装了紫外线： curl -LsSf https://astral.sh/uv/install.sh | sh
    • 检查Python版本： python --version （需要3.13+）
    • 确认Ollama正在运行： ollama list

  2. 前端连接错误:

    • 验证后端是否在端口8000上运行
    • 检查端口是否可用： netstat -tlnp | grep :8000
    • 确保没有防火墙阻止

  3. MCP服务器连接问题:

    • 验证Docker容器是否正在运行： docker ps
    • 检查容器名称是否匹配 mcp.json 配置
    • 如果可能，手动测试MCP服务器

  4. Ollama连接问题:

    • 确保Ollama服务正在运行： ollama serve
    • 检查型号是否可用： ollama list
    • 验证模型与工具调用的兼容性

调试模式

启用详细日志记录：

# Backend
export RUST_LOG=debug
cd backend && uv run python run_server.py

# Frontend (check browser console)
# No special setup needed - React DevTools recommended

项目历史

最近的重大重构（2025年11月）

该项目经历了重大的建筑简化：

之前：

  • 复杂的多业务架构（约2000+条线路）
  • 15+后端文件，具有单独的管理器、服务和处理程序
  • 使用SQLAlchemy实现数据库持久化
  • 热重载配置管理
  • 复杂依赖树

之后：

  • 简化实施（约800行）
  • 2个具有整合功能的核心后端文件
  • 内存对话管理
  • 使用mcp.json进行静态配置
  • 最小依赖集

优点：

  • 代码库大小减少60%
  • 更快的开发和部署
  • 更易于理解和维护
  • 减少攻击面
  • 更好的性能（更少的开销）

UI/UX大修（2025年11月）

受Claude.ai启发的完整界面重新设计：

  • 橙色强调配色方案
  • 暗/亮主题系统
  • 可折叠侧边栏导航
  • 增强的markdown渲染
  • 改进的无障碍性

许可证

该项目根据MIT许可证获得许可。

贡献

  1. 分叉存储库
  2. 创建要素分支： git checkout -b feature-name
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

支持

对于问题和疑问：

  • 检查上面的故障排除部分
  • 查看API文档，网址： /docs
  • 在GitHub上打开一个问题

内置于❤️ 使用FastAPI、React、Material UI、Ollama和模型上下文协议。

相关 MCP