dsh-mcp-lens

dsh plugin --profile web add dsh-mcp-lens

DeepSeek Harness 的 MCP Lens

[English](README.md) | 简体中文





把大型 MCP 工具库收缩成模型只看见的两个工具。

MCP Lens 让 DeepSeek Harness 通过两个稳定入口搜索并调用 1,000 个远端工具。它不会在每轮请求中塞入全部工具 Schema，而是只在真正需要工具时，为少量排序候选揭示准确 Schema。

用户最关心的四件事：

• 更省输入成本：在带日期的三任务实测里，DeepSeek V4 Flash 预估费用从 $0.0307204 降到 $0.0034707。
• 更少占上下文：同一组实测里，request/header.tools JSON 从 674,249 B 降到 27,401 B。
• 更容易找回相关的已覆盖调用：在冻结的 MCP-Atlas 衍生便利 Holdout 上，304 个未触碰 Prompt 的 Recall@5 从 0.062610 提升到 0.246656。这只是词法检索证据，不是 MCP-Atlas 官方分数或端到端成绩。
• 避免每次查询重复构建同一索引：rc.9 会复用每个 Lens 自有冻结目录与策略世代的分词索引，并在目录变化时自动失效。
• 缩小模型的选工具范围：搜索只揭示少量排序候选的准确 Schema，最终 server/tool 仍然受 allowTools / denyTools 限制。
• 在已测任务里保持完成率：真模型实测两侧都完成 3/3，Lens 多用了一次搜索步骤。

如果你有几十到几千个 MCP 工具、多个 Server，或者很多长尾能力不值得每轮都暴露给模型，这个插件适合你。只有几个固定工具、而且几乎每轮都会用到时，直接客户端通常更简单。

安装 rc.9

前置要求：DeepSeek Harness 0.1.0-rc.6、Node.js ^22.19.0 或 >=24.0.0，并且 pnpm 已在 PATH 中。dsh plugin 会把安装交给 pnpm 执行。

下面的命令为 rc.9 预先准备；只有当 Release 页面列出 .tgz 附件与 SHA-256 后才可执行。先下载文件，把本地摘要与该附件显示的摘要逐字比较，确认一致后再把本地文件安装到 Harness Profile。某些 pnpm 版本直接接收 GitHub 重定向后的附件 URL 时会报 ERR_PNPM_MISSING_TARBALL_INTEGRITY。

curl -fL --retry 3 -o dsh-mcp-lens-0.1.0-rc.9.tgz \
  https://github.com/labmimors/dsh-mcp-lens/releases/download/v0.1.0-rc.9/dsh-mcp-lens-0.1.0-rc.9.tgz
shasum -a 256 dsh-mcp-lens-0.1.0-rc.9.tgz
# 与 rc.9 Release 页面中 .tgz 附件显示的 SHA-256 逐字比较。
dsh plugin --profile web add ./dsh-mcp-lens-0.1.0-rc.9.tgz

Windows 用户可从 rc.9 Release 页面下载同一附件，把 Get-FileHash -Algorithm SHA256 的结果与附件显示的摘要逐字比较；只有一致时才把本地路径交给 dsh plugin add。

上面的三条命令依次完成下载、校验和安装。要真正开始使用，请继续完成[连接第一个 MCP Server](#连接第一个-mcp-server)；其中的复制粘贴配置会同时添加 Server 和你要放行的准确工具。然后验证并启动 Profile：

dsh --profile web --dump-config
dsh --profile web

完成后像平常一样提问即可，不需要在 Prompt 里手动写 mcp_search 或 mcp_call。

可以直接试试本地目录测量页：把你当前的工具 Schema 粘进去，浏览器会本地计算准确 UTF-8 bytes，并可复制不含 Schema 的分享链接或 Markdown。分享结果固定标注为用户自报的本地测量（self-reported local measurement），URL 只编码有边界的数字字段，不包含工具名、描述或 Schema。数字校验只能发现意外修改，不是签名，也不能证明测量真实发生过。如果希望把它变成可重复的 CI 约束，可以用 [Schema 预算 Action](#在-ci-里阻止-schema-失控增长)，在工具数量或 Schema 字节超过上限时让 Workflow 失败。

如果你想把同样的测量放进 CI，这个仓库也附带了一个零依赖 GitHub Action：读取仓库内的工具 JSON，输出模型可见工具数、标准 Schema 字节数，以及相对 Lens 固定两工具面的字节降幅。

- uses: labmimors/dsh-mcp-lens@v0.1.0-rc.7
  with:
    tools-file: fixtures/request-header-tools.json

生产环境如需不可变引用，请固定到已审核的 rc.7 Commit：f21169f921e7ed032a4db5062685afb6f948c2d1。

<p align="center">

<img src="assets/mcp-lens-comparison.zh-CN.svg" alt="DeepSeek Harness 实测对比：两侧都完成三项任务，MCP Lens 大幅减少模型可见工具、请求工具 JSON 和预估 API 成本" width="100%">

</p>

为什么图中是 27，而不是 2？ 两侧都包含同样的 25 个非 MCP Harness 工具：直接客户端是 25 + 1,000 = 1,025 个完整工具，Lens 是 25 + 2 = 27 个。MCP 工具面本身是 1,000 → 2。

它具体解决什么问题

你的问题 · MCP Lens 带来的改变

MCP 工具越多，每轮 API 输入越大 · MCP 工具面初始只有 mcp_search 和 mcp_call。在三任务实测中，V4 Flash 预估费用降低 88.702%。

大段工具定义长期挤占上下文 · 同一个 1,000 工具 Server 下，Harness 完整请求中的工具 JSON 从 674,249 B 降至 27,401 B。

担心压缩工具面会牺牲任务完成率 · 在已测的客户、中文工单和 GitHub 任务中，Lens 与直接客户端都以正确参数和结果完成 3/3。

大量相似工具会扩大单次候选暴露面 · 先缩小模型一次看到的候选集合并返回准确 inputSchema，再按明确的 server/tool 身份调用。

没有用到的 Server 也消耗连接资源 · 连接按需建立；插件激活时不启动 MCP 进程，也不打开 MCP Socket。

一个 Server 故障不应该阻塞其他 Server · 其他 Server 会继续工作；刷新失败时仍保留上一份可用目录。

危险工具应该默认不可见 · 远端工具只有匹配 allowTools 才会出现；denyTools 在搜索和调用中永远优先。

在 DeepSeek 实测中，MCP Lens 和官方直接客户端都完成了 3/3 项任务。Lens 会多一次搜索，并在这组样本中产生更多输出 Token，因此它针对的是大型、多 Server、长尾工具库，而不是每轮都会用到的几个固定工具。完整数据见[中文实测报告](docs/LIVE_DEEPSEEK_PILOT.zh-CN.md)。

Release 附件是预编译 tarball，不需要依赖构建权限。下面使用的 MCP 文档 Server 不需要额外 API Key；Harness 仍然需要你已经配置好的模型 Provider。

<details>

<summary>改为安装已审核的源码</summary>

rc.9 Tag 发布后：

dsh plugin --profile web add github:labmimors/dsh-mcp-lens#v0.1.0-rc.9

Git 安装会下载源码并运行 prepare。使用 pnpm 10+ 时，请在 $DSH_HOME/profiles/web/pnpm-workspace.yaml（默认 ~/.dsh/profiles/web/pnpm-workspace.yaml）中加入准确包名，然后重新安装：

allowBuilds:
  dsh-mcp-lens: true

授予构建权限前请先审查源码，并固定 Tag 或 Commit SHA。

</details>

连接第一个 MCP Server

插件默认不携带 Server，也不会开放任何远端工具。打开：

$DSH_HOME/profiles/web/cordis.patch.yml

如果没有设置 DSH_HOME，默认路径是 ~/.dsh/profiles/web/cordis.patch.yml。如果文件内容只有 []，请用下面的配置块替换 []；如果已经存在其他 - id 项，请把它追加为另一个顶层列表项。它会连接公开的官方 MCP 文档 Server，但只开放其中两个只读查询工具：

- id: mcp-lens
  config:
    servers:
      - name: mcp-docs
        transport: streamable-http
        url: https://modelcontextprotocol.io/mcp

    cachePath: !!js dshHomePath('mcp-lens/catalog.json')
    allowTools:
      - mcp-docs/search_model_context_protocol
      - mcp-docs/query_docs_filesystem_model_context_protocol
    denyTools: ['mcp-docs/submit_feedback']

先检查最终组装的 Profile，再启动 Harness：

dsh --profile web --dump-config
dsh --profile web

现在像平时一样提问：

使用官方 MCP 文档 Server，解释 MCP Client 应该在什么情况下使用 Streamable HTTP。

MCP Lens 会在内部完成两段式路由：

你的请求
  → mcp_search("搜索 MCP 文档中的 Streamable HTTP")
  → mcp-docs/search_model_context_protocol 的准确输入 Schema
  → mcp_call("mcp-docs", "search_model_context_protocol", arguments)
  → 工具结果

正常使用时，你不需要在 Prompt 中提到 mcp_search 或 mcp_call。

<details>

<summary>带身份验证的 Streamable HTTP 示例</summary>

- id: mcp-lens
  config:
    servers:
      - name: knowledge
        transport: streamable-http
        url: https://mcp.example.com/rpc
        header

…(truncated)