MCP Webclient

MCP网络客户端

一个现代化的、可用于生产的web应用程序，用于与Ollama模特聊天，并提供完整的 模型上下文协议（MCP） 支持。想想Open WebUI，但它是用TypeScript和原生MCP集成构建的。

特性

• 实时流媒体聊天 -从Ollama模型中逐个令牌地流式响应
• 完全支持MCP协议 -工具、资源、提示和采样
• 渐进式Web应用程序 -在任何设备上安装，脱机工作
• 多模型支持 -在任何Olama型号之间切换
• 持续聊天记录 -使用Prisma的PostgreSQL存储
• 安全认证 -NextAuth.js提供灵活的提供者
• 混合MCP执行 -客户端用于开发，服务器端用于生产
• 类型安全 -整个堆栈中都有完整的TypeScript

技术栈

Frontend:  Next.js 15 + React + TypeScript + Tailwind CSS
Backend:   Next.js API Routes + Ollama + MCP SDK
Database:  PostgreSQL
ORM:       Prisma
Auth:      NextAuth.js
PWA:       @ducanh2912/next-pwa
Deploy:    Vercel

快速开始

先决条件

• Node.js 18+和npm
• PostgreSQL数据库（本地或托管：Railway、Render、Neon）
• Ollama在本地安装并运行
• 可选：用于工具集成的MCP服务器

安装

1. 克隆存储库

   git clone 
   cd mcp-webclient

1. 安装依赖项

   npm install

1. 设置环境变量

   cp .env.example .env.local
   # Edit .env.local with your configuration

1. 初始化数据库

   npx prisma migrate dev
   npx prisma generate

1. 启动Ollama （在单独的终端中）

   ollama serve

1. 运行开发服务器

   npm run dev

1. 打开浏览器

   http://localhost:3000

项目结构

mcp-webclient/
├── app/                    # Next.js app directory
│   ├── api/               # API routes
│   │   ├── chat/          # Ollama streaming endpoint
│   │   ├── mcp/           # MCP proxy endpoint
│   │   └── messages/      # Message CRUD
│   ├── chat/              # Chat pages
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Home page
├── components/            # React components
│   ├── chat/             # Chat UI components
│   ├── mcp/              # MCP tool components
│   └── ui/               # Shared UI components
├── lib/                   # Utilities and libraries
│   ├── mcp/              # MCP client logic
│   ├── config.ts         # Environment configuration
│   └── db.ts             # Prisma database client
├── prisma/               # Database schema
│   └── schema.prisma
├── public/               # Static assets
│   ├── icons/            # PWA icons
│   └── manifest.json     # PWA manifest
├── CLAUDE.md             # Comprehensive project reference
├── ARCHITECTURE.md       # Technical architecture details
├── SETUP.md              # Detailed setup instructions
└── README.md             # This file

配置

环境变量

看 .env.example 对于所有必需的环境变量。

关键变量：

DATABASE_URL                    # PostgreSQL connection string
NEXTAUTH_SECRET                # NextAuth.js secret key
NEXTAUTH_URL                   # Application URL
OLLAMA_API_URL                 # Ollama API endpoint
MCP_SERVER_URL                 # MCP server endpoint

混合MCP模式

开发（客户端）：

NEXT_PUBLIC_MCP_CLIENT_SIDE=true
NEXT_PUBLIC_MCP_SERVER_URL=http://localhost:8000

生产（服务器端）：

NEXT_PUBLIC_MCP_CLIENT_SIDE=false
MCP_SERVER_URL=https://your-mcp-server.com
MCP_API_KEY=your-secret-key

发展

# Run development server
npm run dev

# Run Prisma Studio (database GUI)
npx prisma studio

# Generate Prisma client after schema changes
npx prisma generate

# Create new migration
npx prisma migrate dev --name migration_name

# Build for production
npm run build

# Start production server
npm start

部署

部署到Vercel

1. 将存储库连接到Vercel

   vercel

1. 设置环境变量 在Vercel仪表板中

- 数据库凭据（Database_URL） - NextAuth密钥（NextAuth_secret） - MCP服务器URL和API密钥

1. 部署

   vercel deploy --prod

数据库设置

1. 设置PostgreSQL数据库（铁路、渲染、霓虹灯或本地）
2. 将连接字符串复制到DATABASE_URL
3. 运行迁移： npx prisma migrate deploy
4. 验证连接： npx prisma db push

用法

基本聊天

1. 打开应用程序
2. 从下拉列表中选择Ollama型号
3. 键入您的信息，然后按Enter键
4. 实时观看响应流

使用MCP工具

1. 连接MCP服务器（在设置中配置）
2. 自动发现工具
3. 聊天时，LLM可以根据需要调用工具
4. 工具结果反馈到对话中

脱机模式

1. 安装PWA（点击“安装”按钮）
2. 邮件缓存在IndexedDB中
3. 脱机时的新邮件队列
4. 连接恢复时自动同步

MCP协议支持

此应用程序实现了完整的MCP规范（版本2025-03-26）：

• ✅ 工具 -执行操作（API调用、文件操作）
• ✅ 资源 -访问只读数据（文件、日志、数据库）
• ✅ 提示 -使用可重用的提示模板
• ✅ 采样 -MCP服务器可以请求LLM完成
• ✅ 进度通知 -工具执行期间的实时更新
• ✅ 可流式传输的HTTP -现代HTTP传输协议
• ✅ 会话管理 -有状态的连接

文档

• CLAUDE.md -Claude Code综合项目参考
• 建筑.md -技术架构和设计决策
• 设置.md -详细的设置和配置指南

贡献

欢迎投稿！请在提交PR之前阅读投稿指南。

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

故障排除

Ollama连接问题

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama if not running
ollama serve

数据库连接问题

# Test database connection
npx prisma db push

# Reset database (WARNING: deletes all data)
npx prisma migrate reset

MCP服务器问题

• 如果使用客户端MCP，请检查CORS配置
• 验证MCP服务器是否正在运行： curl http://localhost:8000
• 检查环境变量中的MCP_SERVER_URL

许可证

MIT许可证-请参阅 许可证 详细信息文件

致谢

• 模型上下文协议 -Anthropic的标准化人工智能集成协议
• 奥拉玛 -本地LLM运行时
• Next.js -React框架
• 棱镜 -下一代TypeScript ORM
• NextAuth.js -Next.js的身份验证
• 打开WebUI -这个项目的灵感

链接

• 文档： 完整文档
• MCP规范： https://modelcontextprotocol.io/specification
• API Ollama： https://github.com/ollama/ollama/blob/main/docs/api.md

______________________________________________________________________

内置❤️ 使用TypeScript和模型上下文协议