使用说明
简单的MCP聊天
蟒蛇 Web 应用 用于与调用工具的AI模型聊天 Workato企业MCP 服务器(或任何MCP服务器),为 跨模型对这些服务器/配方进行基准测试和优化 为了令牌效率, 延迟和正确性。
内置于 溪流,它为您提供了一个图形聊天界面, 并排 基准工作区 (比较 模型 或 MCP服务器), 点击MCP服务器管理,保存系统提示,保护ish凭据 存储, 每种型号的成本估算,以及详细的每次通话指标。选择哪些服务器 以及使用哪个模型,在多个模型(或一个模型)上运行相同的提示 多台服务器),并查看每台服务器的确切成本 美元、令牌、延迟和 工具可靠性。将整个基准运行导出为可粘贴的外部提示 LLM进行分析。
该项目最初是一组命令行脚本,现在是一个单一的web应用程序。这 提供者工具调用逻辑存在
providers/+mcp_core.py其他一切 (服务器、凭据、提示、对话、日志、基准测试)在SQLite中持久化。
支持的AI提供商 (从侧边栏中选择每个聊天):
- 开放人工智能 --云;型号列表 从API实时获取
- 克劳德 (Anthropic)——云;型号列表 从API实时获取
- 奥拉玛 --本地开源模型(llama3.2、mistral、qwen等)
- LM 工作室 --通过其OpenAI兼容服务器的本地模型
使用Docker运行(推荐——无需编码)
这是运行应用程序的最简单方法。 码头工人 打包一切(Python, Streamlit和所有依赖项)合并到一个可运行的映像中,所以你唯一需要做的就是 安装是Docker本身。一切都在运转 在你自己的电脑上 以及您的数据 呆在那里。
1.安装Docker桌面 (一次) 从以下网址下载适用于Windows或Mac的 https://www.docker.com/products/docker-desktop/,安装它,然后打开一次 等到鲸鱼图标停止动画制作——这意味着Docker正在运行。
2.拿到 docker-compose.yml 文件
你只需要一个文件(从这个仓库下载,或者问谁分享了
它的应用程序)。把它放在文件夹里,例如。 Documents/mcp-chat/.
3.启动应用程序 打开终端 在该文件夹中:
- 窗户: 按住Shift键并右键单击文件夹→ 在此处打开PowerShell窗口
- 雨衣: 右键单击该文件夹→ 服务 → 文件夹中的新终端
然后运行:
docker compose up -d # downloads the app the first time, then starts it
打开 http://localhost:8501 在浏览器中添加书签。
4.第一次设置,在浏览器中
- ⚙️ 设置 → 添加OpenAI和/或Claude API密钥→ 保存.
- 🔌 MCP服务器 → 添加服务器(名称+URL+身份验证类型)。
- 添加一个 OAuth 服务器开始自动登录--单击 🔐 登录链接 出现并登录(稍后用重新运行 🔄 重新连接MCP服务器 如果需要)。
- 💬 家 → 挑个模特开始聊天。
日常使用
docker compose down # stop the app (your data is kept)
docker compose up -d # start it again later
docker compose pull && docker compose up -d # update to the newest version
我的数据在哪里? 保存对话、API密钥、服务器、登录和日志
在一个 data/ 您旁边的文件夹 docker-compose.yml (数据库、OAuth令牌、,
以及日志),因此它们可以在重启和更新后幸存下来,并且易于备份或移动。
(删除该文件夹会擦除所有内容。)
如果出了什么问题
- “无法连接到Docker守护进程”/什么都没有发生 --Docker桌面不是 跑步。启动它,等待鲸鱼图标稳定下来,然后重试。
- 端口已在使用中 --其他东西正在使用
8501或8080.编辑ports:线条在docker-compose.yml(保持8080mapped——OAuth登录需要它)。 - 本地AI服务器(Ollama/LM Studio) --在Docker内部,
localhost意味着 容器,而不是你的电脑。在 设置,将他们的URL指向host.docker.internal例如。http://host.docker.internal:11434.
同样的快速启动也出现在图像上 Docker Hub页面.
从源代码运行(面向开发人员)
uv sync # install dependencies (incl. Streamlit)
uv run streamlit run app.py # open http://localhost:8501
然后:
- 打开 ⚙️ 设置 (左导航),并添加至少一个API密钥(例如OpenAI或Claude)。
- 打开 🔌 MCP服务器,添加/启用服务器,并在使用OAuth时进行身份验证。
- 回去 💬 家,选择提供商/型号以及要使用的服务器,然后开始聊天。
- 打开 ⚗️ 基准 在多个模型或MCP服务器上运行一个提示并进行比较。
如果您以前使用过命令行版本 .env 和
mcp_servers.json (如有) 自动导入 首先进入数据库
启动——您的设置无需手动步骤即可完成。此进口是一次性的;之后
该应用程序完全由数据库驱动。(OAuth令牌未导入;单击 🔐 重新验证
在MCP服务器页面上。)
它的作用
- 连接 同时连接到一个或多个MCP服务器。
- 发现 每个服务器公开的工具(CRM数据、电子表格、工单等)。
- 聊天 人工智能会自动调用正确的工具来回答你。
- 措施 每次LLM和工具调用,以便您可以调整哪些服务器/配方和模型 以最少的令牌和最少的延迟给出最佳答案。
例如,在连接Salesforce MCP服务器的情况下:
- “向我展示我超过5万美元的开放机会”
- “上周完成了哪些交易?”
使用多个服务器(例如Salesforce+谷歌表格):
- “提取我的管道数据并将其添加到我的预测电子表格中”
AI从正确的服务器中选择正确的工具,并用自然语言进行回复。工具
名称会自动以服务器名称作为前缀(例如。 salesforce__Query_Records)
为了避免冲突,这也让应用程序可以过滤提供给模型的工具
您选择的服务器。
关键概念
什么是MCP?
MCP(模型上下文协议) 是AI模型使用外部工具和 数据源——一个通用适配器,允许任何人工智能与任何服务通信。
什么是Workato企业MCP?
Workato提供连接到企业服务(CRM、数据库等)的托管MCP服务器, 生产力工具),具有OAuth 2.0安全性、审计日志记录和速率限制。此应用程序 与这些服务器以及任何使用JSON-RPC的MCP服务器兼容。
什么是工具(函数)调用?
当你问一个问题时,模型会决定是否需要外部数据。如果是这样,它命名为 工具调用;应用程序在MCP服务器上调用它,将结果返回给模型 该模型生成一个人类可读的答案——循环多步查询。
使用应用程序
该应用程序有一个聊天页面,左导航中还有五个页面,顺序如下: 💬 家, ⚗️ 基准, 🔌 MCP服务器, 📝 系统提示, ⚙️ 设置, 📊 日志.
💬 主页(聊天)
- 提供者 和 模型 侧边栏中的选择器。对于OpenAI和Claude,模型列表为 从提供程序API实时获取 (缓存)。只有具有 价格 是 提供(在设置页面上设置/调整价格);当地Ollama/LM Studio模特始终 表演。使用以下命令重新获取实时列表 🔄 刷新模型 在 ⚙️ 设置 页面。
- MCP服务器 --一个多选项,用于选择向模型提供哪些服务器的工具。 使用1、2或全部;默认设置为所有已启用的服务器。
- 系统提示 --可以选择应用已保存的提示(或“(无)”)。
- 每一次对话都是 锁定到它开始时使用的提供程序 (在聊天过程中切换 混合不兼容的消息格式)。要使用其他型号,请单击 ➕ 新聊天.
- 对话会自动保存;重新打开或从侧边栏中删除它们。
- 状态标题显示活动提供商/型号和所选服务器/工具计数,以及 一 💲 美国东部时间。迄今为止的成本 为了谈话;每台服务器的发现错误以 警告(在MCP服务器页面上修复它们)。
- 当模型工作时,a 实时状态面板 显示每个工具调用及其预览 结果。
- 扩展 📊 日志和使用情况(此聊天) 查看令牌总数、LLM时间、工具调用计数, 预估成本,以及每个呼叫的表(提供者、呼叫类型、提示/完成 令牌、持续时间、结果大小, 成功/错误, 重试尝试、服务器、工具 参数,以及预览)。
⚗️ 基准
跑 一个提示 在几个变体中,然后并排比较它们——核心调优 循环。两种模式(a 比较 切换):
- 模型 --在多个应用程序中运行提示 (供应商×型号) 针对选定对象的变体 MCP服务器集。找到最便宜/最快的型号,它仍然回答得很好。
- MCP服务器 --修复一个模型并运行 每个MCP服务器一个变体 (可选加上 “所有服务器”基线)。查看模型在隔离每个服务器时的行为(工具 可靠性、延迟、应答质量)。
步骤:输入 提示,选一个 系统提示,选择变体(型号或服务器 根据模式),可选择添加 标签 和 笔记,然后单击 ▶ 运行基准测试.
每个变体都在自己的对话中运行,并标记为 benchmark_run_id;进度条
追踪跑步。这 比较 每种变体显示: 总转弯时间,总计/提示/
完成 代币LLM呼叫和LLM时间, 工具调用, 刀具错误, 重试,
估计费用($),以及 最终答案 (可扩展,用于质量检查),加
代币、总时间和成本的条形图。下面:
- 🔍 本次跑步的每次通话详细信息 --所有变体中的每个LLM和工具调用(相同 列作为“日志”页面,并带有前导 变体 列)。
- 🧠 用于LLM分析的导出 --单击一下 📋 复制到剪贴板 复制按钮
单个 JSON 有效载荷(分析指令+运行元数据+每个变量的度量和成本
- 每个呼叫行+最终答案),以及预览/下载。将其粘贴到任何LLM中以获得 对跑步的全面分析。(复制发生在浏览器中,因此它也适用于Docker。)
缺少API密钥的变体报告为失败,而不是导致运行崩溃。选择一个 过去的跑步 运行选择器 查看(和导出)其数据。更改配方或切换 模型/服务器,重新运行相同的提示符,看看哪些更便宜/更快,而不会损害 回答。
🔌 MCP服务器
添加、编辑、启用/禁用和删除MCP服务器。为每台服务器选择一种身份验证类型:
-
无 --无身份验证标头
-
令牌 --静电
Authorization: Bearer <token> -
OAuth --基于浏览器的OAuth 2.0(见下文)
-
添加OAuth服务器会自动启动身份验证 一 🔐 登录链接 出现(浏览器在本机运行时打开);完成登录后,您已连接。
-
🔄 重新连接MCP服务器 (页面顶部)-对任何启用的OAuth服务器进行身份验证 缺少有效令牌并重新发现工具。
-
对于每个OAuth服务器,页面显示了存储的令牌的到期时间(或“还没有令牌”)和 🔐 重新验证 按钮(重新)运行流程;显示登录链接,使其正常工作 浏览器是否打开(例如在Docker中)。可以提供可选的OAuth覆盖 服务器配置字段中的JSON格式。
📝 系统提示
使用Markdown编辑器创建、编辑和删除可重用的系统提示 实时预览. 点击 💾 保存 要添加新提示,字段会自动清除,以便您为 下一个。所选提示将作为聊天的系统消息发送。
⚙️ 设置
- API密钥 --添加
OPENAI_API_KEY/CLAUDE_API_KEY(当前值显示为掩码;留下 字段空白以保持不变)。 - 提供程序默认值 —
OPENAI_MODEL,CLAUDE_MODEL,OLLAMA_BASE_URL,OLLAMA_MODEL,LMSTUDIO_BASE_URL,LMSTUDIO_MODEL,以及APP_LOG_LEVEL. - 行为 --切换 注入当前日期/时间 进入系统提示(默认打开) 调试:记录完整的工具调用和响应 到应用程序日志文件(默认关闭)。
- 模型 — 🔄 刷新模型 重新获取实时的Claude/OpenAI模型列表。
- 模型定价 --每种型号的可编辑成本费率表(美元/ 1M代币,输入
并输出, 仅限Claude和OpenAI).以已知的速率播种;添加/编辑/删除行。模型
按精确ID匹配,然后按最长ID匹配 家族前缀 (所以
claude-sonnet-4还有价格 过时的快照,如claude-sonnet-4-5-20250929).发现的没有价格的模型是 此处自动添加为空白行以供填写,并且仅 定价 模特出现在聊天中/ 基准下跌。 - 维护 — 清除储存的秘密, 清除所有身份验证令牌 (删除OAuth 令牌/注册和重新发现工具),或 清除所有基准运行 (全部由 确认)。
📊 日志
浏览和基准测试--请参阅 记录和基准测试。包括a 全局CSV可导出日志表,每个对话的详细信息、模型和MCP服务器/工具比较 图表、应用程序日志查看器和用于清除一个聊天记录、所有日志或所有日志的防护按钮 对话。
提供商
在侧边栏中选择提供商/型号;默认值在中配置 设置.
OpenAI/Claude(云)
添加 OPENAI_API_KEY 和 CLAUDE_API_KEY 在设置中。模型下拉列表为 取回
从提供商API直播 (/v1/models)并准确反映您的密钥可以访问的内容——否
要维护的硬编码列表。OpenAI的结果被过滤为支持聊天的模型,并注明日期
快照(例如。 gpt-4o-2024-08-06)被隐藏起来,以支持他们滚动的别名(gpt-4o);
该列表已缓存,并可通过以下方式刷新 🔄 刷新模型 在 ⚙️ 设置 页面。仅
模型具有 价格 (设置→ 模型定价)在下拉菜单中提供;未定价的
一个停在价格表中供您填写。如果无法访问API或没有键
设置后,下拉列表会回落到一个小的内置列表。
Ollama(当地)
- 从以下位置安装Ollama 奥拉玛 并确保其正常运行
(
curl http://localhost:11434/api/tags). - 拉动支持的模型 函数调用:
ollama pull llama3.2(其他:mistral,qwen2.5,llama3.1). - 在设置中
OLLAMA_BASE_URL(默认值http://localhost:11434)以及OLLAMA_MODEL.
并非所有Ollama型号都支持工具调用。使用一个(参见 ollama.ai/图书馆).web应用程序不会自动拉取模型-- 先拉他们。
LM工作室(本地)
- 安装 LM 工作室,加载可调用函数的模型,然后启动 其本地服务器。
- 在设置中
LMSTUDIO_BASE_URL(默认值http://localhost:1234/v1).
Ollama和LM Studio使用其配置/静态模型名称,而不是实时API发现。
| 提供商 | 成本 | 隐私 | 注意事项 |
|---|---|---|---|
| OpenAI | 每代币 | 云 | 快速、可靠;实时模型列表 |
| Claude | Per token | Cloud | 推理能力强,上下文长;实时列表 |
| Ollama | 免费 | 本地 | 开源模型,需要功能强大的GPU |
| LM Studio | 免费 | 本地 | OpenAI兼容的本地服务器 |
MCP服务器身份验证
在上配置服务器 🔌 MCP服务器 页面。
基于代用券 --将承载令牌粘贴到服务器的表单中;它被发送为
Authorization: Bearer <token>.
OAuth 2.0 --将身份验证类型设置为 oauth。身份验证开始 自动当你
添加服务器 (并且可以随时重新运行 🔐 重新验证 或 🔄 重新连接MCP
服务器).应用程序:
- 自动通过以下方式发现OAuth端点
.well-known/oauth-authorization-server. - 通过动态客户端注册自动注册OAuth客户端(RFC 7591)。
- 显示a 登录链接 (并在本机运行时打开浏览器),使用本地 回调(默认端口8080)。
- 使用以下代码交换令牌 PKCE (RFC 7636)。
- 将令牌存储在数据库中并自动刷新。
如果稍后有请求返回 401,应用程序会静默刷新令牌一次并重试
在出现错误之前。可选OAuth覆盖(client_id, client_secret, scopes,
redirect_port, auth_url, token_url)可以在服务器的OAuth配置中以JSON格式提供
字段(如果服务器需要)。
Docker注意事项: 当容器在 同一台机器 如你的 浏览器(默认的本地设置)。浏览器被重定向到
http://localhost:8080/ callback,通过已发布的端口到达集装箱--keep 8080 地图。
记录和基准测试
每次LLM调用和MCP工具调用都会记录到SQLite中(chat_logs 表)--没有日志文件
管理。对于每次呼叫,应用程序都会记录:提供商、型号、呼叫类型(initial_request /
tool_followup)、令牌使用情况(提示/完成/总计)、延迟(毫秒)(LLM响应时间
和 MCP往返时间)、使用的MCP服务器+工具(带参数)和 数据大小
返回,以及响应预览。工具调用额外记录 成功/错误,the
重试尝试 编号(该工具在该回合内的第N次调用; >1 标记重试),以及
benchmark_run_id 当作为基准的一部分时。共享转弯跑步者也会进行测量 总转弯数
时间 (一条用户消息的端到端挂钟)。工人 作业ID 从以下位置自动检测
工具响应头/正文(如果存在)。
在哪里可以看到它:
- 每次聊天: 这 📊 日志和使用情况 聊天页面上的扩展器(令牌总数、LLM时间、工具 电话, 预估成本,以及完整的每次通话表),加上 💲 美国东部时间。迄今为止的成本 标题。
- ⚗️ 基准页面: 一个提示的并排变体比较——总转弯时间, 令牌、工具调用/错误、重试、, 预估成本,以及最终答案;一 每次呼叫 细节 桌子;只需轻轻一点 JSON导出 外部LLM分析(见 使用 应用).
- 📊 日志页面:
- 每个日志行的全局CSV可导出表。
- 每次对话 指标+明细表。每个呼叫表(聊天、每次对话、聊天记录), 基准)共享一个列集:提供者、调用类型、提示/完成/总令牌, 持续时间、结果大小、成功/错误、尝试、服务器、工具 参数,并预览。
- 模型 --令牌和按提供商/模型划分的平均延迟(调整您的模型选择)。
- MCP服务器和工具 --通话次数、平均/最大往返时间和平均 返回的数据大小(调整要保留的服务器/工具)。
- 按钮到 清除一个聊天记录, 清除所有日志,或 删除所有对话.
这使得成本/性能的权衡变得明显——例如,发现模型何时发布广泛的MCP 返回巨大有效负载的查询,会膨胀下一个调用的提示令牌和延迟。
应用程序日志(文件)与对话日志(数据库)
两个不同的可观察性层:
- 对话日志 (上图)活在数据库中——每回合令牌、工具、计时和 可靠性 聊天中发生了什么.
- 应用日志 是一个旋转文件,
logs/app.log(1 MB×3个备份),捕获 应用程序是否 本身是健康的 --错误、回溯和MCP/Outh/工具故障。每一个错误都出现在 UI也写在这里。查看或清除其尾巴 🐞 应用日志 部分在 日志页面底部;通过以下方式设置冗长 应用程序日志级别 在设置中(重新启动以应用)。
完整工具I/O调试(选择加入): 启用 “调试:将完整的工具调用和响应记录到应用程序日志中
文件“ 在设置中写入每个MCP工具调用的完整参数、响应头、正文,
以及任何检测到的Workato作业ID logs/app.log默认情况下,它处于关闭状态(有效载荷可以是
大);数据库总是只保留一个简洁的预览。
当前注射日期/时间
随着 “注入当前日期/时间” 在“设置”中启用(默认打开),当前日期/时间为 附加到系统提示中,以便模型可以解析相对日期(“最近3天”、“此 周)。对于具有历史数据的测试,禁用它。
数据和存储
所有内容都存在于一个SQLite数据库中, mcp_chat.db (git忽略)。其表格:
| 表 | 保持 |
|---|---|
servers |
MCP服务器配置(名称、URL、身份验证类型、已启用、OAuth配置) |
oauth_tokens |
每台服务器的OAuth访问/刷新令牌+客户端凭据 |
secrets |
API密钥和设置(密钥/值) |
system_prompts |
保存的、可重复使用的系统提示 |
conversations |
聊天会话(锁定到提供商/型号) |
messages |
完整消息历史记录(提供程序本机格式) |
chat_logs |
每次调用指标:令牌、延迟、数据大小、成功/重试、参数等。 |
benchmark_runs |
一次基准运行(提示+标签+注释+模式:模型/服务器) |
benchmark_variants |
运行的每个变量结果(提供者/型号、服务器、状态、总时间、对话链接) |
model_prices |
每个模型的成本率(每100万输入/输出代币的美元),种子+可编辑 |
模式是在第一次运行时创建的;在较新版本中添加的新列将应用
幂等 ALTER TABLE 迁移,因此现有数据库升级到位。
安全说明: 秘密存储在
mcp_chat.db作为 纯文本 --相同的曝光 水平为a.env文件,只是集中。使数据库不受版本控制( 已经在内.gitignore).
首次启动时,应用程序会导入任何现有的 .env 和 mcp_servers.json,则完全
DB驱动。数据库和 logs/ 默认情况下,位于代码旁边;设置
MCP_CHAT_DATA_DIR 用于重新定位所有持久状态的环境变量(Docker
图像将其指向已安装的 /app/data 体积)。
项目结构
simple-mcp-chat/
├── app.py # Streamlit entry point + Chat page
├── pages/ # Benchmark, MCP Servers, System Prompts, Settings, Logs
├── providers/ # Provider catalog + live model fetch + chat backends
│ ├── __init__.py # registry, get_provider(), fetch_models()
│ ├── base.py # Provider interface (chat_turn)
│ ├── claude.py # Anthropic Claude provider
│ └── openai_like.py # OpenAI / Ollama / LM Studio provider
├── chat_runner.py # Shared turn runner (logging, success/retry, total time)
├── mcp_core.py # Shared MCP client (discover + call tools, job-id detection)
├── db.py # SQLite store (servers, tokens, keys, prompts, chats, logs, benchmarks)
├── oauth_store.py # OAuth 2.0 / PKCE flow with DB-backed token storage
├── logging_setup.py # Rotating app-log file configuration
├── ui_common.py # Shared Streamlit helpers (nav, MCP discovery, model lists)
├── Dockerfile # Container image (Alpine + uv); CMD runs Streamlit
├── docker-compose.yml # Local run: ports 8501/8080, ./data volume
├── .dockerignore # Keeps local state/secrets out of the image
├── DOCKERHUB.md # Paste-ready text for the Docker Hub repo page
├── data/ # Runtime state when using Docker (DB + logs; git-ignored)
├── mcp_chat.db # SQLite database for `uv run` (auto-generated, don't commit!)
├── mcp_servers.json # Optional seed config (imported once if present)
├── .env # Optional seed config (imported once if present)
├── pyproject.toml / uv.lock # Dependencies
└── README.md # You're reading it
先决条件
- Python 3.10+
- 紫外线 包管理器(安装)
- 一 AI提供商:OpenAI或Claude API密钥,或本地Ollama/LM工作室
- 一个或多个 MCP服务器URL (例如,从您的Workato工作区)
依赖关系(来自 pyproject.toml): openai, anthropic, python-dotenv, requests,
streamlit, urllib3 (≥2.7,安全层)。或者只使用Docker——不需要Python/uv。
故障排除
“未发现工具”/服务器发生故障 检查MCP服务器页面上的服务器URL。对于令牌身份验证,请验证令牌;对于OAuth, 点击 🔐 重新验证。如果一台服务器出现故障,其他服务器仍能正常工作——聊天标题 每个服务器的表面错误。
401未经授权
- 令牌认证:令牌可能已过期——在MCP服务器页面上更新它。
- OAuth:应用程序自动刷新一次;如果失败,请单击 🔐 重新验证.
OAuth:“身份验证失败”
- 浏览器未打开→ 点击 🔐 登录链接 如UI中所示。
- 端口8080正在使用中→ 设置不同
redirect_port在服务器的OAuth配置中(在Docker中, 也在中发布该端口docker-compose.yml). - 服务器不支持动态注册→ 提供
client_id/client_secret在 OAuth配置。
下拉列表中缺少模型 仅 定价 显示了Claude/OpenAI模型。打开 ⚙️ 设置→ 模型定价 并给予 模型输入/输出速率(一旦发现就会自动列出);然后它出现在 聊天和基准选择器。始终显示当地Ollama/LM Studio模型。
模型下拉列表为空或已过期 点击 🔄 刷新模型 在 ⚙️ 设置 页面,以便从提供程序API重新复制。随着 没有键或离线时,列表会回退到一个小的内置集。
“未设置API密钥” 添加提供者的密钥 ⚙️ 设置.
Ollama:无法连接/找不到型号
确保Ollama正在运行(curl http://localhost:11434/api/tags)然后拉动模型
(ollama pull llama3.2).使用支持函数调用的模型。
LM Studio:无法连接/未调用工具
确保LM Studio的本地服务器已启动 LMSTUDIO_BASE_URL 比赛。加载一个模型
支持工具使用(例如Mistral Instruct、Qwen、函数调用Llama)。
对话中无法切换模型 这是故意的——对话被锁定在他们的提供者身上。点击 ➕ 新聊天.
许可证
麻省理工学院
