#3113 MCP tools loaded in backend but not injected into Web UI chat session

本文

# Strata MCP 工具注入问题技术说明

**文档版本**：2026-10-18（已补充 HTTP 桥验证）  
**适用环境**：Strata 0.1.45 + Qwen3.8-Flash-Next（512k）

---

## 1. 问题概述

在 Strata 0.1.45（及此前测试的 0.1.25）中，通过 `mcp.json` 加载的 MCP 服务器（以官方 `@modelcontextprotocol/server-filesystem` 为例），无论采用 **stdio** 还是 **HTTP** 传输，后端均能成功启动并获取工具列表，但这些工具**无法注入到 Web UI 聊天会话的模型工具列表**中，导致模型无法调用任何文件相关工具。

同一配置下的其他 MCP 服务器（如 local-memory，HTTP 传输）的工具可以正常注入并被模型调用。

---

## 2. 环境信息

| 项目         | 值                                                           |
| ------------ | ------------------------------------------------------------ |
| Strata 版本  | 0.1.45（引擎通过 `BUILD.json` 与文件时间戳确认）             |
| 模型         | Qwen3.8-Flash-Next（`--max-context 524288`）                 |
| 启动命令     | `python serve/server.py --engine strata --config strata-q2_0-512k.json --port 8080 --mcp-config mcp.json` |
| MCP 配置路径 | `E:\PCCS\MCP\DuckDuckGo\mcp.json`                            |
| 操作系统     | Windows                                                      |
| 对比参考     | local-memory MCP（自定义 HTTP 服务，端口 9100）工具可正常使用 |

---

## 3. 复现步骤

1. 在 `mcp.json` 中添加：

   ```json
   "filesystem": {
     "command": "npx",
     "args": ["-y", "@modelcontextprotocol/server-filesystem", "F:\\"]
   }
   ```

2. 使用上述启动命令启动 Strata。

3. 观察启动日志，确认出现：

   ```
   [strata] MCP server 'filesystem': 14 tools (read_file, read_text_file, read_media_file, read_multiple_files, write_file, edit_file, create_directory, list_directory, ...)
   ```

4. 打开 Web UI（`http://127.0.0.1:8080/`），新建对话。

5. 要求模型列出当前可用工具，或直接要求调用 `list_directory`。

   **结果**：模型报告的工具列表中不包含任何 filesystem 工具。

---

## 4. 已观察到的现象

- **后端加载成功**：启动日志明确列出 filesystem 的 14 个工具名称。
- **模型侧不可见**：新建对话后，模型列出的可用工具仅包含：
  - 环境与时间（`get_datetime`、`get_info`）
  - 网络搜索与网页抓取
  - 文档查询
  - 本地记忆（`add_memory`、`search_memory`、`list_memories`、`delete_memory`）
- **HTTP 桥验证失败**：使用自定义 Python stdio-to-HTTP 桥（`fs_http_bridge.py`，监听 `http://127.0.0.1:9110/mcp`）将官方 filesystem 服务器暴露为 HTTP 后：
  - 桥本身能正常接收 filesystem 服务器的 JSON-RPC 响应。
  - 在 `mcp.json` 中配置为 `"filesystem-http": {"url": "http://127.0.0.1:9110/mcp"}` 并重启 Strata。
  - 启动日志显示该服务器未能成功连接或工具未进入会话。
  - 新建对话后，模型可用工具列表中**仍然不包含**任何文件相关工具。
- **传输方式无关**：stdio 与 HTTP 两种传输方式下，filesystem 工具均无法注入；而 local-memory（HTTP）可正常注入。  
- **版本无关**：在 Strata 0.1.25 与 0.1.45 上均复现。  
- **路径范围无关**：将允许目录从 `F:\` 缩小到 `F:\Memories-work` 后问题依旧。

---

## 5. 已排除因素

| 因素               | 排除依据                                                     |
| ------------------ | ------------------------------------------------------------ |
| 模型本身能力不足   | 同一模型可正常调用 local-memory 的 MCP 工具                  |
| mcp.json 配置错误  | 后端成功启动并枚举工具，格式符合官方文档                     |
| 引擎版本过旧       | 已确认运行 0.1.45 引擎（`BUILD.json` + 文件大小/日期）       |
| 路径权限或范围问题 | 缩小允许目录后仍无法注入                                     |
| 传输方式差异       | 将 filesystem 通过自定义 HTTP 桥暴露后，工具仍无法注入；local-memory（HTTP）正常 |
| 浏览器缓存         | 强制刷新后现象不变                                           |

---

## 6. 可能原因分析

问题位于 **Strata Web UI 聊天 agent 的工具注入环节**，而非 MCP 服务器本身、传输方式或模型：

- 服务端能够启动 MCP 并获取工具列表（stdio 与 HTTP 桥均验证）。

- 部分 MCP 服务器（HTTP 类型的 local-memory）的工具能被正确传递到会话。

- filesystem 工具（无论 stdio 还是 HTTP）均未能进入当前会话的工具列表。

  可能涉及：

- 工具注册时的过滤逻辑（按服务器名称、类型或工具数量）

- 会话初始化时对 MCP 工具的选择性加载

- 前端与后端之间工具元数据传递的遗漏

- 对特定 MCP 服务器实现的兼容性差异

  具体代码位置推测在 `serve/server.py` 或 `serve/mcp.py` 中负责将 MCP 工具合并到聊天请求的部分。

---

## 7. 当前影响与临时替代方案

**影响**：

- 模型无法直接执行文件列举、读取、写入等操作。

- 依赖文件系统的自动化流程（如记忆落盘校验、SHA1 计算）无法由模型独立完成。

  **临时替代**：

- 用户在本地终端执行 `dir` / `Get-ChildItem` 等命令，将输出粘贴给模型进行分析。

- 记忆相关需求继续使用已正常工作的 local-memory MCP。

- 重要结论通过 local-memory 的 `add_memory` 记录。

---

## 8. 建议后续行动

1. **反馈上游**  
   在 [Niko1221/Strata Issues](https://github.com/Niko1221/Strata/issues) 提交问题，建议附上：
   - 本说明中的启动日志片段
   - 模型报告的工具列表（仅含 local-memory 等，不含 filesystem）
   - `mcp.json` 中 filesystem 与 local-memory 的对比配置（脱敏）
   - 关键结论：**无论 stdio 还是 HTTP 传输，filesystem 工具均无法注入；同一会话中 local-memory 可正常使用**

2. **关注更新**  
   跟踪后续版本是否修复 MCP 工具在 Web UI 聊天中的注入逻辑。

3. **备选路径**（如需紧急文件能力）  
   考虑官方 `llama-server --agent`，但会失去 Strata 对大 MoE 模型的性能优化。

4. **内部记录**  
   将本问题状态记入本地记忆，避免后续会话重复排查。当前已停止继续尝试 stdio / HTTP 桥路径。

---

## 9. 相关文件与路径

- 启动脚本：桌面 `启动Strata-new.bat`
- 模型配置：`C:\Users\liu_d\Desktop\Strata-new\strata-q2_0-512k.json`
- MCP 配置：`E:\PCCS\MCP\DuckDuckGo\mcp.json`
- 引擎：`C:\Users\liu_d\Desktop\Strata-new\engine\strata.exe`
- 本地记忆服务：桌面 `local_memory_mcp.py`（端口 9100）

---

*文档结束*