MQTT Specification

mqtt-spec-mcp

一个离线的 Model Context Protocol 服务，用于搜索和引用 OASIS MQTT 3.1.1 和 MQTT 5.0 规范。 Agent 获取的是聚焦的原文摘录，而不是加载整份规范。

• 提供四种只读工具，用于搜索、获取章节、查看大纲和精确查找。
• 内置索引：查询时无需网络、数据库、嵌入或大模型。
• 每次调用都必须明确选择版本；没有默认版本，也不会返回跨版本结果。
• 提供有页数限制的章节内容，以及包含来源链接的精简搜索证据包。

服务负责检索证据；Agent 负责推理。OASIS 出版物仍是权威来源，检索到的摘录并不能保证答案正确。

设置

MCP 客户端会在你的机器上启动服务，并通过 stdio 与其通信。无需单独安装：将客户端配置为运行 uvx mqtt-spec-mcp 即可；uv 首次运行时会从 PyPI 下载并缓存软件包，然后启动服务。如果你的环境中没有兼容的 Python，uv 也会下载 Python 3.10 或更高版本。每次客户端启动服务时，uv 都会检查 PyPI 上是否有更新版本，因此更新会自动获取。

1. 安装 uv。
2. 按照下方说明将服务添加到客户端。服务不需要环境变量、配置文件或标志。

对于从 MCP Registry 安装的客户端，也可以在 MCP Registry 中找到该服务，名称为 io.github.cartertinney/mqtt-spec-mcp。

Claude Code、Codex、GitHub Copilot CLI 和 Gemini CLI

使用以下一个命令，即可将服务添加到这些工具的所有项目中：

claude mcp add --scope user mqtt-spec -- uvx mqtt-spec-mcp   # Claude Code
codex mcp add mqtt-spec -- uvx mqtt-spec-mcp                 # OpenAI Codex CLI and IDE extension
copilot mcp add mqtt-spec -- uvx mqtt-spec-mcp               # GitHub Copilot CLI
gemini mcp add --scope user mqtt-spec uvx mqtt-spec-mcp      # Gemini CLI

VS Code（GitHub Copilot）

在终端中将服务添加到用户配置文件：

code --add-mcp '{"name":"mqtt-spec","type":"stdio","command":"uvx","args":["mqtt-spec-mcp"]}'

也可以从命令面板运行 MCP: Add Server，或将服务添加到某个项目的 .vscode/mcp.json：

{
  "servers": {
    "mqtt-spec": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mqtt-spec-mcp"]
    }
  }
}

Claude Desktop、Cursor 和其他客户端

大多数其他客户端都读取相同的 mcpServers 配置项：

{
  "mcpServers": {
    "mqtt-spec": {
      "command": "uvx",
      "args": ["mqtt-spec-mcp"]
    }
  }
}

• Claude Desktop： 前往“设置” → “开发者” → “编辑配置”，打开 claude_desktop_config.json。保存后退出并重新打开 Claude。
• Cursor： 所有项目使用 ~/.cursor/mcp.json，单个项目则使用 .cursor/mcp.json。
• Zed： 在其设置文件的 context_servers 下添加相同的配置项。

ChatGPT 和 OpenAI Agents SDK

ChatGPT 只能通过 HTTPS 连接远程 MCP 服务，因此无法启动此本地服务；请改用 Codex CLI 或 IDE 扩展（见上文）。在基于 OpenAI Agents SDK 构建的 Agent 中，可使用 MCPServerStdio(params={"command": "uvx", "args": ["mqtt-spec-mcp"]}) 进行连接。

不使用 uv

使用 pipx install mqtt-spec-mcp 安装软件包，或在 Python 3.10+ 环境中运行 pip install mqtt-spec-mcp。然后将客户端配置为运行命令 mqtt-spec-mcp，不带任何参数，而不是运行 uvx mqtt-spec-mcp。

故障排除与升级

• 客户端找不到 uvx。 桌面应用通常无法读取 shell 的 PATH。请使用 which uvx（macOS 和 Linux）或 where uvx（Windows）打印出的绝对路径。
• 首次启动超时。 首次启动时会下载软件包，可能需要几秒钟。请提前使用 uvx --from mqtt-spec-mcp python -c pass 下载。
• 更新。 下次客户端启动服务时会使用新版本。uv 会复用 PyPI 的响应，最长可达 10 分钟，因此新版本可能需要这么久才会显示。更新后，请开始新的对话，让客户端丢弃缓存的工具架构。若要固定使用某个版本，请在客户端参数中用 [email protected] 替代 mqtt-spec-mcp。
• 无法访问网络。 服务可离线运行，但使用 uvx 启动时需要连接 PyPI，除非 uv 在过去 10 分钟内检查过。若要在无法访问网络时运行，请先使用 uv tool install mqtt-spec-mcp 安装，然后将客户端配置为运行 mqtt-spec-mcp。uvx mqtt-spec-mcp 也会运行已安装的副本，且只有通过 uv tool upgrade mqtt-spec-mcp 才会更新。

工具

每次调用都必须包含 version：值必须严格为 "3.1.1" 或 "5.0"。

工具	用途
mqtt_spec_search	按关键术语、章节 ID 或要求标签查找摘录。
mqtt_spec_get	读取章节，支持限制页数和使用续传游标。
mqtt_spec_outline	浏览章节 ID 和标题，不含正文。
mqtt_spec_lookup	查询数据包、属性、代码、要求或术语表条目。

工具参数示例：

{"version": "5.0", "query": "Receive Maximum default; QoS 0 Receive Maximum"}

将其与 mqtt_spec_search 搭配使用。若要精确查询，请使用 mqtt_spec_lookup：

{"version": "3.1.1", "kind": "return_code", "query": "0x80", "packet": "SUBACK"}

后者返回 Failure。在 MQTT 5.0 中，同一值为 Unspecified error： 不同版本的标签和代码不可混用。

给 Agent 的指南

1. 如果用户未指定 MQTT 版本，请先询问他们指的是哪个版本。
2. 查询确切实体，或使用问题中的关键术语进行搜索。用 ; 分隔问题的各个部分。
3. 根据证据作答，保留 MUST/SHOULD/MAY 及其适用条件。在每项陈述旁注明版本和章节。
4. 搜索摘录可能省略例外情况。若摘录中未包含或缺少相关内容，在断言没有相关内容、某项为可选或不存在例外之前，请先获取起决定作用的章节。服务建议每个版本最多获取一次并重复搜索一次。
5. 比较不同版本时，请分别查询每个版本。在某个版本中未找到，并不能说明另一个版本的情况。

所有参数、分页、结果格式和错误信息，请参阅工具参考。

来源与限制

版本	已编入索引的出版物
3.1.1	MQTT Version 3.1.1 Plus Errata 01，2015 年 12 月 10 日
5.0	MQTT Version 5.0，2019 年 3 月 7 日

索引由固定版本的源文档生成，并在启动时进行验证。 它们是经过转换的检索辅助资料，并非官方出版物。不支持 MQTT 3.1 （OASIS 之前的版本），且本项目不是代理或一致性验证器。

限制与路线图 介绍已知的检索缺口。 基准测试 介绍离线回归检查，以及历史 Agent 评估报告。这些评估使用了私有测试框架、语料库和原始运行记录，因此无法从此代码仓库复现。

开发

有关从检出副本运行、测试、重建索引和发布的信息，请参阅开发与发布检查。基准测试检查仅在检出副本中提供，不随服务一同发布。

许可证

代码采用 MIT 许可证。 索引和返回摘录中的规范文本版权归 OASIS Open 所有，不采用 MIT 许可证。NOTICE 中包含来源归属、转换详情和 OASIS 声明。