Ollama MCP Chat App

Ollama MCP 聊天应用

一个现代的、实时聊天界面，用于与（助手）互动 MCP-Ollama - 一个集成了模型上下文协议（MCP）服务器的Ollama大型语言模型（LLM）。使用Next.js 15、TypeScript和Tailwind CSS构建。

特点/特性

• 实时流媒体通过 WebSocket 实现逐令牌流式响应
• 双模式：

- 简单模式直接LLM流式传输（更快，无需工具） - 代理模式全面集成MCP工具（速度较慢，但功能更强大）

• 现代用户界面简洁、响应迅速的界面，支持深色模式
• 自动重连自动重连，采用指数退避策略
• 工具调用可视化查看正在调用哪些MCP工具
• 系统消息可折叠调试信息
• 冗长流式传输可选详细视图，显示所有流式传输消息及其类型和原始数据
• 聊天记录会话期间持久保存的对话历史
• 错误处理优雅的错误显示与恢复

先决条件

在运行这个聊天应用之前，您需要：

1. Node.js 18及以上版本 安装好的；已安装的
2. MCP-Ollama 服务器 跑步（见 ../mcp-ollama（这个路径或文件名直接翻译为中文可能保持原样，因为“mcp-ollama”是一个特定的项目或文件名，没有直接的中文对应。但如果要解释其可能的含义，可以大致翻译为“../MCP-Ollama（机器学习项目/框架等，具体根据上下文确定）”，不过通常我们会直接使用原名。））

- 默认URL： ws://localhost:8000/ws

1. Ollama（注：Ollama是一个用于本地运行大型语言模型的工具或框架的名称，直接翻译可能无具体含义，故保留原英文形式） 在本地运行
2. （可选） MCP服务器 用于带有工具的代理模式

快速入门

1. 安装依赖项

npm install

2. 配置环境

复制示例环境文件：

cp .env.example .env.local

编辑 .env.local 如果你的 MCP-Ollama 服务器位于不同的 URL 上：

NEXT_PUBLIC_WS_URL=ws://localhost:8000/ws

# Enable verbose streaming to see all message types and raw data
NEXT_PUBLIC_VERBOSE_STREAMING=true

3. 启动开发服务器

npm run dev

开放 http://localhost:3000 翻译为中文是：“本地主机：3000 端口”。不过，通常我们不会直接翻译网址的格式，而是说明其含义或用途，比如“访问本地运行的服务器，端口为3000”。但按照您的要求，网址本身可翻译为上述表述 开始聊天吧！

项目结构

chat-app/
├── app/
│   ├── page.tsx              # Main page (renders ChatInterface)
│   ├── layout.tsx            # Root layout
│   └── globals.css           # Global styles
├── components/
│   ├── ChatInterface.tsx     # Main chat component
│   ├── ChatMessage.tsx       # Individual message component
│   ├── ChatInput.tsx         # Input form with mode selector
│   └── ConnectionStatus.tsx  # WebSocket status indicator
├── hooks/
│   └── useOllamaStream.ts    # WebSocket hook for mcp-ollama
├── .env.local                # Environment configuration
└── .env.example              # Environment template

组件

聊天界面

负责协调所有交互的主要聊天组件。

特点：

• 连接状态显示
• 带有自动滚动功能的消息历史
• 带有光标的流式响应
• 清除聊天记录功能
• 带有说明的空状态

\useOllamaStream\ 钩子（Hook）

自定义的React钩子，用于管理WebSocket连接和消息处理。

出口：

{
  messages: StreamMessage[]           // Raw stream messages
  chatHistory: ChatMessage[]          // Formatted chat history
  currentResponse: string             // Current streaming response
  toolCalls: ToolCallData[]          // Active tool calls
  systemMessages: string[]           // System/debug messages
  isConnected: boolean               // Connection status
  isStreaming: boolean               // Streaming status
  error: string | null               // Error message
  sendPrompt: (prompt, mode) => void // Send message
  clearMessages: () => void          // Clear history
}

消息协议

WebSocket 连接使用以下消息格式：

客户端 → 服务器

{
  "prompt": "Your message here",
  "mode": "simple" | "agent"
}

服务器 → 客户端

{
  "type": "ollama" | "mcp" | "tool_call" | "tool_result" | "system" | "error" | "done",
  "data": "content or object"
}

消息类型：

• ollama大语言模型（LLM）响应标记
• mcpMCP服务器响应
• tool_call工具调用（名称，参数）
• tool_result工具执行结果
• system状态/调试信息
• error错误信息
• done流媒体结束

使用示例

基本聊天

1. 在输入框中输入您的信息
2. 选择模式（简单或代理）
3. 按发送键或按回车键
4. 实时观看流式响应的出现

使用工具（代理模式）

1. 切换到“代理”模式
2. 提出一个需要工具的问题：

   "Calculate the MD5 hash of 'hello world'"
   "What's the weather in San Francisco?"

1. 工具调用显示在响应下方

快捷键

• 输入发送消息
• Shift + Enter（在中文中通常直接表述为“Shift加Enter键”或“Shift和Enter键”）消息中的新行

冗长流模式

启用详细模式以查看流媒体期间所有 WebSocket 消息的详细信息：

1. 设置环境变量于 .env.local：

   NEXT_PUBLIC_VERBOSE_STREAMING=true

1. 重启开发服务器：

   npm run dev

1. 当你发送消息时，你会看到一个“详细流”部分，其中显示：

- 消息类型为每种消息类型（ollama、mcp、tool_call 等）设置彩色徽章 - 消息ID用于追踪相关消息的唯一标识符 - 原始数据每条消息中的实际数据载荷 - 可扩展详情点击信息图标以展开并查看完整消息详情

消息类型：

• ollama (蓝色)：大型语言模型（LLM）的响应标记
• mcp (紫色)：MCP服务器响应
• tool_call (橙色): 带有参数的工具调用
• tool_result (绿色)：工具执行结果
• system (灰色): 状态/调试信息
• error (红色)：错误信息
• done (天蓝色)：流媒体信号结束

这适用于：

• 调试流媒体问题
• 理解消息流
• 开发集成
• 了解协议的工作原理

配置

环境变量

定制化

更改主题颜色编辑 app/globals.css 以及组件中的 Tailwind 类

调整自动重连设置修改 reconnectAttempts 逻辑在 useOllamaStream.ts

添加自定义消息类型扩展 StreamMessage 界面和更新渲染逻辑

发展

在开发中运行

npm run dev

该应用程序使用Turbopack运行，以实现快速热重载。

构建生产环境

npm run build
npm start

代码检查（或代码规范检查）

npm run lint

故障排除

连接问题

问题“断开连接”状态或连接错误

解决方案：

1. 确保mcp-ollama服务器正在运行：

   cd ../mcp-ollama
   python server.py

1. 检查服务器URL .env.local
2. 验证mcp-ollama服务器是否已配置CORS
3. 检查浏览器控制台中的 WebSocket 错误

无流式响应

问题消息已发送，但未收到回复

解决方案：

1. 检查mcp-ollama服务器日志
2. 验证Ollama是否正在运行： curl http://localhost:11434/api/tags
3. 直接测试服务器： wscat -c ws://localhost:8000/ws
4. 检查浏览器的网络标签页以查看 WebSocket 消息

工具调用不起作用

问题代理模式不调用工具

解决方案：

1. 确保MCP服务器正在运行，并在mcp-ollama中进行了配置
2. 使用代理模式（而非简单模式）
3. 检查mcp-ollama服务器信息： curl http://localhost:8000/info
4. 验证提示实际上需要使用工具

暗黑模式问题

问题暗色模式的颜色看起来不对

解决方案：

1. 检查系统的深色模式设置
2. 验证 Tailwind 暗色模式是否已启用（默认已启用）
3. 检查元素并查看应用的类

技术栈

• 框架： Next.js 15 使用 App Router
• 语言： TypeScript
• 造型设计： Tailwind CSS 4
• 实时WebSocket API
• 后端： MCP-Ollama（注：MCP可能代表某个特定项目、组织或概念，Ollama是一个开源的大型语言模型服务，但具体含义需根据上下文确定，此处仅为直译） (FastAPI + WebSocket) 翻译为中文是：(快速API + WebSocket)

演出

• 包装尺寸约200KB初始（gzip压缩后）
• 交互响应时间在快速连接上\<1秒
• 流媒体延迟每标记（token）小于100毫秒
• 重新连接时间1-10秒，采用指数退避策略

浏览器支持

• Chrome/Edge 90及以上版本
• Firefox 88及以上版本
• Safari 14及以上版本
• 所有支持WebSocket的现代浏览器

许可证

麻省理工学院（MIT）

相关项目

• MCP-Ollama（注：这里的“MCP”可能是一个特定项目、组织或技术的缩写，但没有上下文无法确定其具体含义，因此直接音译；“Ollama”可能是指一个具体的项目、技术或产品名，同样直接音译） - 后端WebSocket服务器
• MCP - 模型上下文协议
• Ollama（注：Ollama是一个用于训练和运行大型语言模型的工具，但在此处作为专有名词直接翻译，不添加额外解释） - 本地LLM运行时

做出贡献

欢迎贡献！请随时提交拉取请求。

支持

对于问题或疑问：

1. 查看上面的故障排除部分
2. 查看mcp-ollama文档
3. 在GitHub上提交一个问题