AI-QL/tuui · 上手攻略

仓库：AI-QL/tuui
链接：https://github.com/AI-QL/tuui
分类：skill
作者：Tom
更新：2026-08-22

这是什么

TUUI（Tool Unitary Utility Integration）是一个基于 Model Context Protocol（MCP）的桌面端 AI 客户端，核心定位是跨供应商 LLM API 编排 + MCP 工具集成一体化桌面工具。使用 Electron + Vue 3 + Vuetify 构建，支持 Windows/macOS/Linux。TUUI 同时也是一个"用 AI 协助构建完整项目"的实验性实践——项目内部大量组件由 AI 直接生成或转换而来，并配备了严格的语法检查和命名规范。

解决什么问题

MCP 工具管理碎片化：MCP 生态的服务器（如 filesystem、git、github 等）需要手工配置 JSON，缺少图形化管理和一键连接能力。TUUI 提供桌面 UI 来管理 MCP 服务器配置。
多供应商 LLM API 切换繁琐：Claude GPT、OpenAI、Qwen、DeepInfra 等需要各自配置 Endpoint、API Key、模型列表，TUUI 用统一的 llm.json 配置多供应商，在 UI 层按需切换。
缺乏桌面化 MCP 客户端：官方 MCP 主要面向 Claude Desktop、Cursor 等 IDE 集成，缺少独立的桌面探索/测试工具。
跨供应商 AI 能力编排：TUUI 支持同时配置多个 LLM 后端，通过 MCP 工具调用实现跨供应商的工具协同。

快速安装

直接下载安装包

从 Releases 页面下载最新版本的安装包（支持 Windows/macOS/Linux），解压后运行可执行文件即可。

从源码构建

git clone https://github.com/AI-QL/tuui.git
cd tuui
npm install
npm run build     # 构建应用
npm run dev       # 开发模式运行

前提依赖： - Node.js（用于 NPX/NODE 类型的 MCP 服务器） - Python + UV（用于 UV/UVX 类型的 MCP 服务器） - Docker（用于 Docker 类型的 MCP 服务器）

核心配置

LLM 后端配置

LLM 配置写入 src/main/assets/config/llm.json（构建后位于 resources/assets/config/llm.json）。支持两种格式：

单聊天机器人配置（JSON 对象）：

{
  "name": "Qwen",
  "apiKey": "",
  "url": "https://dashscope.aliyuncs.com/compatible-mode",
  "path": "/v1/chat/completions",
  "model": "qwen-turbo",
  "modelList": ["qwen-turbo", "qwen-plus", "qwen-max"],
  "maxTokensValue": "",
  "mcp": true
}

多聊天机器人配置（JSON 数组）：

[
  {
    "name": "Openrouter && Proxy",
    "apiKey": "",
    "url": "https://api3.aiql.com",
    "urlList": ["https://api3.aiql.com", "https://openrouter.ai/api"],
    "path": "/v1/chat/completions",
    "model": "openai/gpt-4.1-mini",
    "modelList": [
      "openai/gpt-4.1-mini",
      "openai/gpt-4.1",
      "anthropic/claude-sonnet-4",
      "google/gemini-2.5-pro-preview"
    ],
    "maxTokensValue": "",
    "mcp": true
  },
  {
    "name": "DeepInfra",
    "apiKey": "",
    "url": "https://api.deepinfra.com",
    "path": "/v1/openai/chat/completions",
    "model": "Qwen/Qwen3-32B",
    "modelList": [
      "Qwen/Qwen3-32B",
      "Qwen/Qwen3-235B-A22B",
      "meta-llama/Meta-Llama-3.1-70B-Instruct"
    ],
    "mcp": true
  }
]

MCP 服务器配置

MCP 服务器配置写入 src/main/assets/config/mcp.json。配置语法与 MCP 官方文档一致：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/workspace"]
    }
  }
}

远程 MCP 服务器

使用 Cloudflare 的 mcp-remote 实现远程 MCP 服务器（含 Auth）：

{
  "mcpServers": {
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOURDOMAIN.com/sse"]
    }
  }
}

⚠️ 如遇 HTTP 400 错误，清除认证页面浏览器缓存后重试。

MCP 功能支持状态

功能	状态	备注
Tools	✅	MCP 服务器工具调用
Prompts	✅	MCP 服务器 Prompt 模板
Resources	✅	MCP 服务器资源
Roots	🔲	通常仅 Vibe Coding IDE 需要，可通过环境变量配置
Sampling	✅	客户端采样
Elicitation	✅	客户端请求用户确认
Discovery	✅	MCP Registry 实时服务器发现
MCPB (.mcpb)	✅	MCP Bundles（即原 Desktop Extensions .dxt）

典型适用场景

场景	用途
MCP 服务器探索	图形化管理+测试各种 MCP 服务器（filesystem、git、github 等）
多供应商 LLM 横向评测	同时连接 DeepInfra/OpenRouter/Qwen 等多个后端，测试不同模型能力
跨供应商 AI 工具链	通过 MCP 工具编排，让不同 LLM 调用各自擅长的工具
MCP 应用自动化测试	自动化测试 MCP 工具调用流程
本地 AI 工作站	在桌面端整合多个 LLM 和工具，无需浏览器

坑与注意

⚠️ HTTP 400 认证错误：使用 OAuth 自动跳转时可能遇到 400 错误，清除认证页浏览器缓存后重试通常可解决。
API Key 管理：配置文件中 API Key 为空字符串需要手动填写，且保存在 localStorage 中（可从托盘菜单清除存储）。
macOS/Linux 路径问题：非 Windows 系统需要修改 MCP 配置中的 CLI 路径和权限。
Node.js/Python/UV 依赖：NPX 类型服务器需要 Node.js，UVX 类型需要 Python + UV，Dock 类型需要 Docker，需预先安装。
"用 AI 构建 AI 工具"的双刃剑：作者明确表示项目大量组件由 AI 生成，代码质量和安全性依赖严格的 linting 流程约束，开发者在继续开发时需使用项目内置 linting 工具。
配置语法扩展：TUUI 的 llm.json 支持 urlList（故障转移 URL 列表）和 modelList（可用模型列表）等扩展字段，与标准 OpenAI 兼容 API 端点格式不完全一致。

与同类对比

工具	类型	MCP 支持	跨供应商编排	桌面化
TUUI	桌面应用	✅ 完整	✅	✅
Claude Desktop	IDE 集成	✅	❌	✅
Cursor	IDE 插件	✅	❌	✅
MCP Inspector	Web/桌面	✅ 仅测试	❌	✅
StationOne	桌面 Hub	✅	部分	✅
各类 MCP CLI	命令行	✅	❌	❌

TUUI 的差异化在于桌面化 + 跨供应商 LLM 编排的组合，适合需要在单一界面管理多个 AI 后端和 MCP 工具的用户。相比 Claude Desktop 等 IDE 集成方案，TUU I更偏向于"MCP 工具探索 + 多模型横向评测"而非深度编程辅助。

一句话推荐结论

TUUI 是一个面向 MCP 生态的桌面工作台，适合想在一个窗口里管理多个 LLM 后端和 MCP 服务器的开发者或 AI 爱好者。免费开源，Windows/macOS/Linux 全平台支持，但作为实验性项目，代码质量依赖于 AI 生成+linting 约束，生产级使用前建议自行 review 关键代码。

⚠️ 数字核验：本仓库 Stars ~1152（2026-08）；TUUI 官网 https://tuui.com（未经独立核验）；构建依赖 Node.js/npm/Vue 3/Vuetify，版本号请以 package.json 为准。