38 个工具，不吃上下文：KwaFlux 的 MCP 服务是怎么设计的

要点速览

• MCP 服务提供的每个工具都要向模型描述一遍，这些描述占用的上下文，本可以留给你的请求。
• 加载全部 38 个工具时，KwaFlux 的工具清单是 51,004 字节，在 60,000 字节的预算之内；只加载核心分组，就降到 7,077 字节。
• 工具分组让你只加载用得到的部分：设置 KWAFLUX_MCP_TOOLSETS，没选的分组根本到不了模型那里。
• 预算由测试把关。哪次改动让工具清单、核心分组或服务说明超出预算，测试就会失败。

功能多的 MCP 服务有一项不显眼的开销：每个工具的名称、描述和输入结构都要发给模型，模型才知道有这个工具。工具少的时候无所谓；到了 38 个，你一个字还没打，它就可能占掉上下文窗口里相当可观的一块。

KwaFlux 的 MCP 服务就是围绕这项开销来设计的：结构定义是生成的，不是手写的；工具按组提供，可以关掉；结果是结构化的，不啰嗦；体积有预算，由测试来执行。

本文会讲 MCP 服务的上下文开销从哪儿来、KwaFlux 怎么测量和限制它、怎样少加载一些工具，以及让长时间视频任务也省上下文的几项设计。

目录

1. 一个 MCP 工具要占多少上下文？
2. KwaFlux 的实测数字
3. 由测试执行的预算
4. 只加载用得到的分组
5. 从应用配置生成的结构定义
6. 不用读两遍的结果
7. 长任务：靠进度和取消，不靠轮询
8. 用提示词承载多步工作流
9. 常见问题

一个 MCP 工具要占多少上下文？

一个 MCP 工具占用的上下文，就是它的定义有多大：名称、标题、描述，以及输入和输出的 JSON Schema。会话里的每次请求，宿主都会把这些定义交给模型。

宿主通过 tools/list 请求拿到这些定义，大多数宿主会把它们放进模型上下文，让模型从中挑选工具。MCP 规范要求服务端以稳定的顺序返回工具，理由之一是这样“在工具被放进模型上下文时，能提高大模型提示缓存的命中率”。由此也能看出，工具定义进上下文是常态。

KwaFlux 的实测数字

完整清单约 51 KB 的 JSON。折合多少 token 取决于模型的分词器，但它是每个会话都要先付的一笔固定开销。只加载核心分组，大约是它的七分之一。

由测试执行的预算

写在设计文档里的体积目标会慢慢走样，写进测试里的不会。

KwaFlux 的 MCP 服务有一个测量脚本，作为测试的一部分运行。它生成真实的 tools/list 响应，按字节测量；再单独测核心分组，并按字符数测服务说明。任何一项超出预算，测试就失败。

这改变了写工具的方式。新工具必须塞得进去，于是冗长的描述会被删减，重复的解释挪进共享的服务说明，一段讲“哪些值合法”的文字被一个枚举取代。完整清单的预算还留了约 9 KB 的余量，给以后的功能用。

只加载用得到的分组

KwaFlux 的 38 个工具分成若干组，下表列出主要的几组。核心分组在任何配置下都会加载，其余的由环境变量 KWAFLUX_MCP_TOOLSETS 选择；没选中的分组压根不会注册，也就不占上下文。

比如你只用助手做转换和修复，可以在宿主的 MCP 配置里，给 KwaFlux 这一项加上环境变量：

{
  "mcpServers": {
    "kwaflux": {
      "command": "<path to node>",
      "args": ["<path to kwaflux_mcp.mjs>"],
      "env": { "KWAFLUX_MCP_TOOLSETS": "convert,repair" }
    }
  }
}

command 和 args 请从 KwaFlux 的 设置 › Agent（MCP） 页面复制，别手敲；位置见上手指南。各家宿主的配置格式不同，env 放在你的宿主要求的位置。

技巧： 刚开始摸索助手能做什么时，先全部加载；熟悉之后，再精简到真正常用的几组。工具清单小了，模型挑错工具的可能也会变小。

从应用配置生成的结构定义

工具清单里，大部分字节是输入结构。手写的结构往往越写越长：字段用一段话来描述，合法取值在描述里列一遍、结构里又列一遍，还有各种例外说明。

KwaFlux 的增强工具，结构定义是和应用界面从同一份配置文件生成的。每个设置都成了一个有类型的字段，带着真实的取值范围或真实的选项列表，模型看到的是 "enum": [...]，而不是一句“允许哪些值”的说明。照片版的参数也来自这份文件。漂移测试怎样让生成的规则和应用保持一致，见控制面这篇。

这也让工具保持窄。每个工具只收一个人会自己选的那几项，完整任务由 KwaFlux 自己生成。如果一个工具要接收原始任务描述，它的结构就得涵盖引擎能做的一切，体积更大，也更难检查。

不用读两遍的结果

KwaFlux 的每个工具都声明了 outputSchema。按 MCP 规范，工具一旦声明了输出结构，“服务端必须提供符合该结构的结构化结果”，客户端“应当按该结构校验结构化结果”。

对上下文来说，这意味着结果是字段固定的紧凑 JSON：任务号、状态、输出文件名。模型不必读一段话才知道成没成，宿主也不用问模型就能检查结果。结果里也不放模型用不上的东西，详见路径与隐私这篇。

长任务：靠进度和取消，不靠轮询

视频任务动辄几分钟。助手跟进任务最直接的办法，是一遍遍问“好了没”，而每问一次都要往上下文里加一点。

KwaFlux 的核心分组里有一个等待工具，用来替代这种轮询：

• 进度。 宿主带上 progressToken 时，KwaFlux 会在任务运行期间发送 notifications/progress。宿主把它显示成进度条，不占模型上下文。
• 取消。 你在宿主里停止这次请求（宿主会发送 notifications/cancelled），KwaFlux 立即停止等待。之后，如果你需要，助手可以再把任务本身取消。

一次等待调用取代了一连串状态查询，所以一个 10 分钟的导出和一个 10 秒钟的导出，占用的上下文差不多。

用提示词承载多步工作流

有些活要按顺序调用好几个工具，比如先诊断，再修复，再增强，最后导出。要是在每个工具的描述里都讲一遍这个顺序，每次请求都要多付这些字节。KwaFlux 把它做成了四个 MCP 提示词：

• 修复损坏视频
• 按平台导出
• 下载后转换
• AI 画质修复

MCP 规范把提示词定义为“由用户控制”的，通常以斜杠命令的形式出现。你不选，它就不占任何开销；选中之后，它把这项工作的步骤交给模型。每一步做什么，见能力说明这篇。

结语

把工具清单当成预算，而不是目录：测量它，在测试里给它封顶，让用户只加载需要的分组。再让每次调用都省着用：输入由真实配置生成并带类型，结果结构化，用进度代替轮询。KwaFlux 就是这样把 38 个工具放进一个服务，又不挤占你的请求。

需要哪些工具就加载哪些

KwaFlux 的本地 MCP 服务为 Codex、Claude、Cursor 等 MCP 应用提供最多 38 个工具，按组开关，核心分组常驻。AI 处理在你自己的 GPU 上运行，媒体文件不会为了处理而上传。可在 Windows 10（64 位，1809 或更新版本）、Windows 11，以及搭载 Apple Silicon 的 macOS 12 或更新版本上运行。导入文件和浏览应用都不需要账号。仅在导出、转换、文件修复和从链接下载文件时需要登录并购买付费方案。

下载 KwaFlux · 查看方案