MQTT Specification

mqtt-spec-mcp

OASIS の MQTT 3.1.1 および MQTT 5.0 仕様を検索し、引用するためのオフライン Model Context Protocol サーバーです。 エージェントは仕様全体を読み込む代わりに、目的に沿った抜粋を取得できます。

• 検索、セクション取得、アウトライン、完全一致検索を行う読み取り専用ツールを4つ提供します。
• インデックスを同梱しているため、クエリ時にネットワーク、データベース、埋め込み、LLMは不要です。
• 呼び出しごとにバージョンを明示します。デフォルトのバージョンや、複数バージョンをまたぐ検索結果はありません。
• ページ範囲を限定したセクションと、ソースリンク付きの簡潔な検索エビデンスパックを提供します。

サーバーはエビデンスを取得し、推論はエージェントが行います。OASIS の公開資料が正式な情報源であり、取得した抜粋が正しい回答を保証するものではありません。

セットアップ

MCP クライアントは、お使いのマシン上でサーバーを起動し、stdio 経由で通信します。別途インストールする必要はありません。クライアントで uvx mqtt-spec-mcp を実行するよう設定すると、初回に uv が PyPI からパッケージをダウンロードしてキャッシュし、起動します。互換性のある Python（3.10 以降）がない場合は、uv が取得します。クライアントがサーバーを起動するたびに、uv は PyPI で新しいリリースを確認するため、自動的に更新されます。

1. uv をインストールします。
2. 以下の例のように、サーバーをクライアントに追加します。サーバーに環境変数、設定ファイル、フラグは必要ありません。

サーバーは MCP Registry にも io.github.cartertinney/mqtt-spec-mcp として登録されており、そこからインストールするクライアントでも利用できます。

Claude Code、Codex、GitHub Copilot CLI、Gemini CLI

これらはそれぞれ、1つのコマンドですべてのプロジェクトにサーバーを追加できます。

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： Settings → Developer → Edit Config を開くと、claude_desktop_config.json が表示されます。保存後、Claude を終了して再起動してください。
• Cursor： すべてのプロジェクトには ~/.cursor/mcp.json を、1つのプロジェクトには .cursor/mcp.json を使用します。
• Zed： 設定ファイルの context_servers の下に同じエントリを追加します。

ChatGPT と OpenAI Agents SDK

ChatGPT が接続できるのは HTTPS 経由のリモート MCP サーバーのみであるため、このローカルサーバーを起動できません。代わりに、上記の Codex CLI または IDE 拡張機能を使用してください。OpenAI Agents SDK で構築したエージェントから接続する場合は、MCPServerStdio(params={"command": "uvx", "args": ["mqtt-spec-mcp"]}) を使用します。

uv を使わない場合

pipx install mqtt-spec-mcp でパッケージをインストールするか、Python 3.10 以降の環境で pip install mqtt-spec-mcp を実行します。その後、クライアントで uvx mqtt-spec-mcp の代わりに、引数なしで mqtt-spec-mcp コマンドを実行するよう設定します。

トラブルシューティングとアップグレード

• クライアントが uvx を見つけられません。 デスクトップアプリからは、シェルの PATH が見えないことがよくあります。which uvx（macOS および Linux）または where uvx（Windows）で表示された絶対パスを使用してください。
• 初回起動がタイムアウトします。 初回起動時にはパッケージがダウンロードされるため、 数秒かかることがあります。次のコマンドで事前にダウンロードしてください。 uvx --from mqtt-spec-mcp python -c pass
• アップデート。 新しいリリースは、クライアントが次にサーバーを起動したときに使用されます。uv は PyPI の応答を最大 10 分間再利用するため、新しいリリースが反映されるまで その時間がかかることがあります。アップデート後は、新しい会話を開始して、クライアントが キャッシュ済みのツールスキーマを破棄するようにしてください。バージョンを固定するには、 クライアントの引数で mqtt-spec-mcp の代わりに [email protected] を使用してください。
• ネットワークにアクセスできません。 サーバーはオフラインでも動作しますが、uvx で起動する場合は、uv が直近 10 分以内に確認していない限り、PyPI へのアクセスが必要です。ネットワークにアクセスせずに実行するには、一度 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 です。バージョン固有のラベルとコードを別のバージョンに持ち込まないでください。

エージェント向けガイダンス

1. ユーザーが MQTT のバージョンを指定していない場合は、どのバージョンを指しているか尋ねてください。
2. 正確なエンティティを検索するか、質問のキーワードで検索してください。質問の複数の部分は ; で区切ってください。
3. 根拠に基づいて回答し、MUST／SHOULD／MAY とその条件を保持してください。各主張の横にバージョンとセクションを記載してください。
4. 検索結果の抜粋では例外が省略されることがあります。記載がないこと、任意であること、例外がないことを主張する前に、判断に必要なセクションが抜粋されているか、存在しない場合は取得してください。サーバーは、バージョンごとに取得を 1 回まで、再検索を 1 回までにすることを推奨しています。
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 以前）はサポートされておらず、ブローカーでも適合性バリデーターでもありません。

制限事項とロードマップ では、既知の検索上の不足について説明しています。 ベンチマーク では、オフラインでの回帰チェックと、過去のエージェント評価のレポートを扱っています。これらの評価では、非公開のハーネス、コーパス、生データを使用しているため、このリポジトリから再現することはできません。

開発

チェックアウトからの実行、テスト、インデックスの再構築、リリースについては、開発とリリースのチェック を参照してください。ベンチマークチェックはチェックアウト環境でのみ実行でき、サーバーには同梱されていません。

ライセンス

コードはMITライセンスです。 インデックス内の仕様テキストおよび返される抜粋の著作権はOASIS Openに帰属し、MITライセンスではありません。NOTICE には、出典の帰属、変換の詳細、およびOASISの通知が記載されています。