AI导哈

MCP客户端工具

一个用于本地MCP演示的Chainlit UI客户端，通过stdio连接MCP服务器，将发现的工具传递给OpenAI兼容的聊天模型，并在浏览器中呈现逐步的ReAct工作流程。

  • by YI-TING-EE13
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 YI-TING-EE13/chainlit-mcp-client

使用说明

MCP客户端

用于本地MCP演示的Chainlit UI客户端。它通过stdio连接到MCP服务器， 将发现的工具传递给与OpenAI兼容的聊天模型，并呈现 在浏览器中逐步重新执行工作流。

此回购针对的是兄弟 ../mcp-server ArXiv Insight演示服务器。 chainlit-mcp-client 是同一远程和当前的另一个工作副本 包含其他本地重构工作。

需求

  • Python 3.12+
  • uv
  • 用于完整UI演示的LM Studio或其他与OpenAI兼容的API
  • API端点支持OpenAI样式工具调用的模型

Ollama不是必需的。遗产 OLLAMA_* 变量仍然支持作为 现有设置的回退。

安装

uv sync --frozen

复制 .env.example 到 .env 并为您的后端进行更新。

LLM后端配置

新的设置应该使用通用的OpenAI兼容变量：

LLM_BASE_URL=http://localhost:1234/v1
LLM_API_KEY=lm-studio
LLM_MODEL=google/gemma-4-e4b

读取优先级：

  1. LLM_BASE_URL, LLM_API_KEY, LLM_MODEL
  2. OLLAMA_HOST, OLLAMA_KEY, OLLAMA_MODEL
  3. LM Studio样式默认值： http://localhost:1234/v1, lm-studio, google/gemma-4-e4b

google/gemma-4-e4b 是此LM Studio显示的当前模型标识符 本地服务器。如果加载其他模型，请使用LM显示的标识符 Studio本地服务器。

运行时模型选择

当Chainlit启动时，UI显示 LM工作室模型 聊天中的选择器 设置。模型列表从配置的 OpenAI兼容端点：

GET http://localhost:1234/v1/models

启动默认值保持不变 LLM_MODEL=google/gemma-4-e4b.选择另一个 模型仅更改当前Chainlit会话；它不会编辑 .env.

对于LM Studio，客户端还从 LLM_BASE_URL例如：

http://localhost:1234/v1 -> http://localhost:1234/api/v1

当本机API可用时，切换模型会尝试卸载 在加载所选模型之前，先加载当前已加载的模型。这是LM 工作室特定。其他兼容OpenAI的后端可能只支持 /v1/models; 在这种情况下，UI会继续工作，在可能的情况下更新运行时模型，以及 如果加载失败，则要求您在LM Studio中手动切换模型。

MCP服务器配置

客户阅读 mcp.json 从repo根目录。默认的本地演示配置为：

{
  "mcpServers": {
    "arxiv-insight": {
      "command": "uv",
      "args": ["--directory", "../mcp-server", "run", "main.py"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

这 fetch 服务器是可选的，第一次可能需要网络访问 uvx 安装它。

A.没有LM Studio的本地验证

这些检查不需要Ollama、LM Studio或任何LLM后端：

uv sync --frozen
uv run python scripts\smoke_test.py
uv run python scripts\mcp_integration_test.py

烟雾测试验证：

  • mcp.json 指向兄弟姐妹 ../mcp-server.
  • 配置的服务器目录存在。
  • LLM_* 默认值有效。
  • OLLAMA_* 回退仍然有效。
  • LLM_* 当新变量和遗留变量都设置时获胜。

MCP集成测试启动兄弟 ../mcp-server 通过stdio 命令已配置 mcp.json它验证协议级连接， tools/list, tools/call health_check, resources/list，以及 prompts/list. 它不需要LM Studio，也不调用arXiv或任何外部网络 服务。

如果集成测试失败，请检查 mcp.json，兄弟姐妹 ../mcp-server 首先确定服务器依赖关系、路径和服务器依赖关系。

通过这些检查并不意味着完整的Chainlit+LM Studio+MCP工具 调用demo已成功。

B.LM Studio的完整演示

此流程需要使用正在运行的LM Studio服务器进行手动验证：

  1. 打开LM工作室。

  2. 负载 google/gemma-4-e4b，或具有稳定工具调用的另一个可用模型。

  3. 启动LM Studio本地服务器/OpenAI兼容的API服务器。

  4. 确认端点，通常 http://localhost:1234/v1.

  5. 集 .env:

    LLM_BASE_URL=http://localhost:1234/v1
LLM_API_KEY=lm-studio
LLM_MODEL=google/gemma-4-e4b

  6. 在 ../mcp-server，跑 uv run python scripts\smoke_test.py.

  7. 在此仓库中，运行 uv run python scripts\smoke_test.py.

  8. 启动Chainlit：

    uv run main.py

  9. 打开http://localhost:8000.

  10. 在Chainlit中，问：

    Run health_check, then search for three recent papers about retrieval augmented generation.

预期成功行为：

  • Chainlit启动并连接到已配置的MCP服务器。
  • 资源列表显示 papers://recent 从 arxiv-insight.
  • 模型实际上调用 health_check.
  • 然后，模型调用 search_arxiv.
  • arXiv结果来自MCP工具输出，而不是模型发明引用。

此完整的端到端演示已在Windows上通过LM Studio Local进行了验证 服务器、Chainlit、MCP工具调用和兄弟 ../mcp-server.

验证基线：

  • 端点： http://localhost:1234/v1
  • 型号标识符： google/gemma-4-e4b
  • 显示的资源： papers://recent
  • 成功的工具调用： health_check那么 search_arxiv

验证状态

  1. 本地静态/结构验证：可用。
  2. MCP服务器烟雾测试：可用 ../mcp-server.
  3. MCP客户端配置冒烟测试：此仓库中提供。
  4. 完整Chainlit+LM Studio+MCP工具调用演示：在Windows上验证。

目前的确切结论：

repos通过了不依赖于LLM后端的本地烟雾测试。这 完整的Windows+LM Studio+Chainlit+MCP工具调用流程也已完成 手动验证 google/gemma-4-e4b 在 http://localhost:1234/v1.

故障排除

未安装Ollama

这不是问题。建议的设置是LM Studio或其他 OpenAI兼容端点。 OLLAMA_* 变量只是遗留的后备方案 设置。

用途：

LLM_BASE_URL=http://localhost:1234/v1
LLM_MODEL=<LM Studio model identifier>

LM Studio服务器未运行

症状：

  • connection refused
  • Chainlit启动，但模型没有响应
  • 演示提示从不触发工具调用

修复：

  • 打开LM工作室。
  • 加载模型。
  • 启动本地服务器。
  • 确认端口和URL。
  • 制造 .env LLM_BASE_URL 匹配LM Studio服务器URL。

型号名称不匹配

症状：

  • model not found
  • API表示该模型不可用
  • Chainlit无法获得模型响应

修复：

  • 检查LM Studio本地服务器中的实际模型标识符。
  • 集 .env LLM_MODEL 到那个确切的标识符。
  • 不要假定README示例名称是API标识符。

型号列表为空

症状：

  • Chainlit型号选择器仅显示 .env 违约。
  • /v1/models 失败或不返回模型ID。

修复：

  • 确认LM Studio本地服务器正在运行。
  • 打开 http://localhost:1234/v1/models 并验证它是否返回模型ID。
  • 如果API暂时不可用，请继续使用默认模型。

模型卸载失败

症状：

  • UI报告卸载当前模型失败。
  • 所选模型未加载。

修复：

  • 检查LM Studio是否通过其本机公开加载的模型实例ID API
  • 在LM Studio中手动卸载模型，然后重试。
  • 如果VRAM仍满，请关闭其他加载的模型或重新启动LM Studio 本地服务器。

模型加载失败

症状：

  • UI报告加载所选模型失败。
  • 会话继续使用之前的模型。

修复：

  • 确认所选模型已安装并可在LM Studio中加载。
  • 检查可用VRAM。
  • 请先尝试在LM Studio中手动加载模型。

LM Studio本机API不可用

症状：

  • 模型选择器工作，但UI显示本机卸载/加载不可用。

修复：

  • 这适用于非LM Studio OpenAI兼容的后端。
  • 对于LM Studio，确认您的版本是否公开 http://localhost:1234/api/v1.
  • 如果本机模型管理不可用，请在LM Studio中手动切换模型 然后在Chainlit中选择匹配模型。

模型不可靠地支持工具调用

症状：

  • Chainlit返回普通文本，但不调用MCP工具。
  • health_check 未被触发。
  • 该模型声称它在没有工具输出的情况下搜索论文。
  • arXiv的结果看起来是虚构的。

修复：

  • 跑 uv run python scripts\smoke_test.py 在这个回购和 ../mcp-server.
  • 确认客户端将MCP工具作为OpenAI兼容的工具定义公开。
  • 尝试另一个具有更强工具调用支持的LM Studio模型。
  • 将工具调用成功视为取决于模型能力、LM Studio端点支持和客户端实现。

LM工作室报告 Model reloaded

症状：

400 - {'error': 'Model reloaded.'}

当LM Studio重新加载所选模型时，这种情况可能会短暂发生。等待 模型完成加载，然后重试相同的提示。

获取服务器资源警告

症状：

Error listing resources from fetch: Method not found

这是一个非阻塞警告。可选 fetch 服务器不公开MCP 资源，因此该服务器的资源列表可能会失败，而 arxiv-insight 服务器仍然工作。

health_check 有效但arXiv搜索失败

这通常意味着MCP服务器正在运行。问题更可能是网络 连接、arXiv API可用性、查询参数或其他外部 服务问题。

检查 health_check 先测试 search_arxiv 通过一个小查询和 max_results.

内存在运行之间承载上下文

设置：

MEMORY_ENABLED=false

或者如果启用了内存，则使用隐身设置。

演示失败日志检查表

如果完整演示失败，请收集：

  • 链式终端输出或 .demo-logs 输出。
  • LM Studio本地服务器日志。
  • 非敏感 .env 值： LLM_BASE_URL, LLM_MODEL，以及是否 LLM_API_KEY 已设置。
  • mcp.json.
  • Chainlit是否显示 papers://recent.
  • 是否 health_check 和 search_arxiv 显示为实际的工具调用。
  • 确切的错误消息。

不要粘贴真正的API密钥、令牌或私人凭据。

相关 MCP