mlx-serve 工具调用与 MCP 深度实战:schema 驱动自动修复如何让本地 Agent 稳定干活
mlx-serve 工具调用与 MCP 深度实战:schema 驱动自动修复如何让本地 Agent 稳定干活
让本地 AI Agent「稳定干活」是本地推理最难的一环:模型写错了工具参数,整轮调用就作废。mlx-serve 是一个面向 Apple Silicon 的原生 LLM 推理服务器(Zig 后端、无 Python),内置 工具调用(Tool Calling) 与 MCP 客户端,并用一套 schema 驱动的自动修复机制,把弱模型常见的参数错误在到达客户端之前就修好,让 Claude Code、pi 等本地 Agent 少踩坑、少烧 token。
为什么本地 Agent 的工具调用总容易「翻车」
云端大模型的工具调用足够可靠,但本地跑中小模型时,tools 参数稍一变形就会出问题,典型症状有:
- JSON 转义错误:模型写文件时把真实换行、未转义的引号直接塞进
arguments,严格解析器直接丢弃整个调用,文件内容「漏」进聊天正文; - 参数类型不对:声明了
boolean的参数,模型写出了字符串"False",严格客户端(Claude Code、pi)当场拒绝,模型看不到自己的请求,反复重试浪费整轮生成; - 参数放错位置:必填的顶层
path被埋进edits[]数组里,客户端报「缺少必填项」,模型重试三次后放弃编辑、改为整文件重写; - 调用被截断:大文件写入撞上 token 上限,工具调用只剩半个,整轮输出为空。
mlx-serve 的作者在 docs/gotchas/tool-calling.md 里记录了这些真实事故的完整复盘——每一类都对应一条服务端修复规则。
30 秒认识 mlx-serve
一句话:一个端口(默认 http://localhost:11234)同时讲 OpenAI、Anthropic、Ollama、OpenAI Responses 四种线协议,任何现成客户端改个 base URL 就能接上。核心能力包括:
- 🚀 原生 Zig 引擎,无 Python 运行时,MLX 与 GGUF 模型都能跑;
- 🔧 工具调用 + JSON Schema 约束解码,并带 schema 驱动的参数自动修复(本文重点);
- 🔌 MCP 客户端:内置 MCP 服务器市场 + 自定义
mcp.json; - 🤖 完整 API 见 docs/api.md,各 Agent 接入教程见 docs/integrations.md。
核心机制:schema 驱动的自动修复是怎么运作的
mlx-serve 把所有工具调用的解析收口到一个「咽喉点」(server.parseToolCallsForRequest),五个 HTTP 接口(chat/completions、/v1/messages、/v1/responses 等)共用同一条修复流水线,任何客户端都自动受益。
1️⃣ JSON 宽容修复:救回「几乎对」的参数
模型手写的 arguments 本质是一段自己负责转义的 JSON。小模型最常见的错误是把换行、制表符写成了裸控制字符,或漏转义内层引号。严格解析失败后,src/chat.zig 中的 looseRepairToolCallJson 会按「感知位置」重新转义控制字符与内层引号,再走一遍严格解析验证——修坏了就丢弃,绝不让无效 JSON 出门。
2️⃣ 按 schema 矫正类型:"False" 自动变 false
各标签格式(Hermes、Gemma 等)的参数本身不带类型信息,只能靠值长相猜。mlx-serve 不猜:coerceToolArgsToSchema 读取请求里声明的 tools_json schema,按声明的 type 双向矫正标量("False"→false、"42"→42),无法判定的保持原样,让客户端报错保持「诚实」。
3️⃣ 参数「越位」自动归位:埋进数组的必填参数被捞出来
这是最精巧的一层:hoistMisplacedRequiredParams 发现「schema 声明的顶层必填标量参数在容器里、且所有容器项值相同」时,把它提升回顶层;任何有歧义的情况(项之间值不一致、类型不符)都原样放过,不瞎猜。官方 CHANGELOG 里有个真实案例:某 Agent 曾因 path 被埋在 edit 对象里,连续烧掉 3 轮数千 token 的生成才放弃——修复后一次命中。
4️⃣ 幻觉调用过滤 + 永远合法的 JSON 兜底
无标签语法时,解析器会从文本里「猜」出 JSON 对象当工具调用,可能猜出叫 "George Washington" 的幽灵工具。filterInferredBySchema 只放行名字在请求 tools 中声明过的推断调用。最后还有一道结构兜底:parseToolCalls 结束时对每个调用的 arguments 严格复检,实在救不回就降级为空对象 {}——客户端永远拿到合法 JSON,重试才有意义。
5️⃣ 一键关闭:想看模型原始输出时
Settings 里的 Tool-call auto-correct 开关,或 CLI 的 --no-tool-autocorrect(见 docs/cli.md),可关闭类型矫正、原样透传参数——调试模型行为时非常有用。合法性安全网不受影响,始终开启。
连接 MCP:给本地 Agent 装上「外接器官」
App(MLX Core)内置 MCP 市场:GitHub、Docker、Kubernetes、Playwright、Slack、Notion、Filesystem、Shell 等 stdio/HTTP 服务器一键添加,填好 Token 即连;也可以手写 ~/.mlx-serve/mcp.json 接入任意服务器——该文件格式与 Claude Desktop 完全兼容,配置可以直接互贴(实现见 app/Sources/MLXServe/Models/MCPConfig.swift):
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
}
}
}
MCPManager.swift 统一管理子进程生命周期:连接成功后自动聚合各服务器的工具列表并注册为可用工具,模型发起的调用会被路由到正确的服务器执行,失败信息也会回显到界面便于排错。
Agent 模式与沙箱:工具调用「放开用」的安全网
除 MCP 外,mlx-serve 还提供 10 个内置工具(shell、readFile、writeFile、editFile、searchFiles、browse 等),每个工具带 Allow / Deny / Always allow this session 的审批弹窗。想彻底放开手脚?打开 Agent Sandbox——一条命令在 Apple Virtualization 的隔离 Linux 虚拟机里执行,Guest 端口自动映射到本机 localhost,工具调用产生的副作用不会碰你的 Mac。
把现成 Agent 接到本地:一步配置
- Claude Code:
ANTHROPIC_BASE_URL=http://localhost:11234 claude,App 里也有零配置一键启动器(docs/integrations.md 覆盖 pi、OpenCode、Codex、aider 等); - OpenAI 客户端:base URL 指向
http://localhost:11234/v1,tools参数直接可用,流式与非流式行为一致; - Ollama 生态工具(Raycast、Open WebUI、obsidian 插件):改端口到 11234 即可。
常见问题(FAQ)
Q:自动修复会「篡改」模型的正确输出吗? 不会。所有修复只在严格解析失败后触发,且结果必须通过严格复检;完全合规的调用字节级原样透传(回放 4480 条真实流量语料,归位修复触发 0 次)。
Q:修复后客户端仍报类型错误,怎么办?
说明模型输出无法被安全判定,mlx-serve 刻意保留原值让客户端报错「诚实」可见,配合 --no-tool-autocorrect 可切换观察原始参数。
Q:小模型(<4B)工具调用还是不稳定? 优先换更大或工具能力更强的量化版本;同时 App 端的截断续写引导(大文件建议分块写入)与截断恢复会把单轮失败的代价降到最低。
总结
mlx-serve 的差异化不在「能调工具」,而在让工具调用在本地弱模型上也稳定落地:一个统一解析咽喉点 + JSON 宽容修复 + schema 类型矫正 + 参数归位 + 幻觉过滤 + 合法 JSON 兜底,再配上 MCP 市场和沙箱审批体系,本地 Agent 才从「能演示」变成「能干活」。更多实战细节可阅读 docs/app.md 与 docs/gotchas/tool-calling.md。



