@imqueue

@imqueue/mcp

@imqueue 向けの Model Context Protocol サーバーです。AI コーディングエージェント（Claude Code、ChatGPT、Codex、Cursor、VS Code、JetBrains、…）が @imqueue のドキュメントを検索し、型付きサービスとクライアントをひな形から生成し、imq CLI を操作できるため、推測ではなく、正しく慣用的な @imqueue コードを生成できます。

📖 ドキュメント全文：imqueue.org/mcp — クライアントごとのセットアップ、ツールのリファレンス全文、エージェントのワークフロー、安全性モデルをご覧いただけます。

ツール

2 つの種類があり、同じものではありません。ローカルサーバー（npx -y @imqueue/mcp）には 14 個のツールすべてが備わっています。ホスト型サーバー（mcp.imqueue.org/mcp）には 7 個のツールがあり、すべて読み取り専用です。その理由については以下をご覧ください。

ホスト型 + ローカル

ツール	説明
search_docs	公式ドキュメント（ガイド、チュートリアル、CLI マニュアル、API リファレンス、記事）を検索し、最も関連性の高いページと URL を返します。
get_doc	URL を指定して、ドキュメントページの Markdown 全文を取得します。
list_packages	ドキュメントに記載された @imqueue パッケージの一覧を、インストールコマンド、現在のバージョン、ライセンスとともに表示します。
package_status	公開されている @imqueue パッケージの任意のパッケージ、または全パッケージについて、現在のバージョン、ライセンス、必要な Node の最低バージョン、最終リリース日を表示します。
scaffold_service	@expose() が付与され、JSDoc で型付けされたメソッドを持つ IMQService サブクラスとブートストラップを生成します（オフラインで動作し、CLI は不要です）。
scaffold_client	サービス用の完全に型付けされたクライアントを生成して使用する方法を示します（オフライン）。

6 つのツールはいずれも読み取り専用です。テキストを取得または生成するだけで、何も書き込みません。

5 つのツールはすべて MCP の outputSchema も宣言し、人間が読みやすい Markdown とともに structuredContent を返します。そのため、クライアントは結果をデータとして利用できます。たとえば、search_docs の results[0].url を取得して get_doc に渡したり、scaffold_service の files[] をそのままディスクに書き込んだりできます。文章やコードフェンスを解析する必要はありません。ひな形生成ツールとカタログでは、Markdown は同じ構造からレンダリングされるため、両者の内容が食い違うこともありません。

get_doc のスキーマは、意図的にメタデータのみです — そして、スキーマがまったくない場合よりも興味深い設計になっています。スキーマがあるとサーバーは structuredContent を送信する必要がありますが、structuredContent に content の内容を繰り返し含めなければならないとは決まっていません。これは回答の構造化された部分を記述するものです。したがって、ページは content で一度だけ送られ、スキーマには url（実際に取得したミラーの URL。渡した URL と異なる場合があります）、mimeType、bytes（呼び出し側が読み取り前に判断できるようにするための値）、truncated が含まれます。ここに markdown も含めると、サーバーが生成できる最大のレスポンスが 2 倍になっていました。/api/rpc/latest/ で計測したところ、1 回の読み取りでテキストが 16.6 kB、構造化データが 16.6 kB になりました。本文フィールドがないこと自体が、内容を明確に示しています。スキーマを読む呼び出し側は内容フィールドがないことから、ページが content にあり、すべてのクライアントがすでに参照している場所にあるとわかります。

CLI を使用するツールにはスキーマがありません。形状を保証する価値のない imq の標準出力を返すためです。

CLI ベースのツール — ローカルのみ（PATH 上に @imqueue/cli が必要です）

これらのツールは実際の CLI を操作するため、サーバーが実行されているマシン上で動作します。ローカルインストールでのみ利用でき、ホスト型サーバーには登録されません。

ツール	機能
cli_status	imq を検出し、バージョンを報告します。
cli_install	@imqueue/cli が見つからない場合、グローバルにインストールします（npm i -g @imqueue/cli）。
cli_help	imq <command> --help — 正確で、バージョンに対応したフラグを表示します（副作用はありません）。
create_service	imq service create — デフォルトではドライランです（何も書き込みません）。実際にプロジェクトを作成するには、apply: true を渡します。
generate_client	imq client generate <Service> — 実際に型付けされたクライアントを生成します（サービスが実行中である必要があります）。
fleet	imq ctl <start|stop|restart|status> — サービスリポジトリのディレクトリを管理します。status は読み取り専用です。
config	imq config <check|get|set|init> — CLI 設定を読み取り／書き込みます（自動化には set、対話形式の設定には init を使用します）。
logs	imq log — 現在のフリートのログを dump します（追従せず、上限があります）または clean します。

呼び出しは標準入力を閉じた状態でタイムアウト付きで実行されるため、必須フラグがない場合のプロンプトは停止せず、すぐに失敗します。imq がインストールされていない場合は、cli_install を実行するか、オフラインの scaffold_* ツールを使用してください。

ドキュメントは imqueue.org の機械可読フィードからリアルタイムで取得されるため、サーバーが古いコンテンツを配信することはありません。ページの厳選されたインデックスには /llms.txt、本文にはページごとの …/index.md ミラー、検索コーパスには /search-index.json、/search-text.json、/search-sections.json、パッケージのバージョンとライセンスには /status.json を使用します。商用ページについては、imqueue.com の /llms.txt と関連フィードも読み取ります。この2つのホスト以外から取得することは一切ありません。許可リストは src/docs.ts で適用され、それ以外は拒否されます。

バージョンとライセンスはコードに埋め込まず、意図的に最後のフィードから取得します。@imqueue はこのサーバーよりはるかに頻繁にリリースされるため、バージョンを埋め込むと数日で間違った情報になるうえ、その間違いに強い確信を持ってしまうからです。npmjs.com は自動取得に対してボット検出を返します。そのため imqueue.org はビルド時にレジストリを読み取り、誰でも読み取れる場所に結果を再公開します。

インストール

Node.js ≥ 18 が必要です。ユーザー側でのビルド手順はありません。npm から直接実行します。

npx -y @imqueue/mcp

Claude Code

claude mcp add imqueue -- npx -y @imqueue/mcp

ChatGPT と Codex

@imqueue は ChatGPT と Codex で共有される**OpenAI のプラグインディレクトリに掲載されています。ChatGPT ではPlugins**タブを開いてインストールし、Codex CLI では /plugins を実行します。設定ファイルも Node も必要ありません。

この方法ではホスト型サーバーがインストールされるため、読み取り専用の7つのツールのみが利用でき、CLI ブリッジは含まれません（以下を参照）。Codex ではローカルサーバーを併用できます。MCP サーバーは通常の JSON ではなく TOML 形式で、~/.codex/config.toml の mcp_servers の下に記述します。

[mcp_servers.imqueue]
command = "npx"
args = ["-y", "@imqueue/mcp"]

ChatGPT は HTTP 経由でのみ MCP サーバーに接続するため、ローカルでの利用方法はありません。ChatGPT ではプラグインが唯一の方法です。

その他のクライアント（Cursor、Claude Desktop、JetBrains、Windsurf、Zed、…）

MCP 設定に追加します（.cursor/mcp.json、claude_desktop_config.json など）。

{
  "mcpServers": {
    "imqueue": {
      "command": "npx",
      "args": ["-y", "@imqueue/mcp"]
    }
  }
}

VS Code と Visual Studio では、mcpServers の代わりに、最上位の servers キーと "type": "stdio" を使用します。各クライアントの正確な設定ファイルのパスと設定例については、**imqueue.org/mcp/installation**を参照してください。

ホスト型サーバー（インストール不要）

クライアントがリモート MCP サーバーに対応していて、ドキュメントとスキャフォールディングだけが必要な場合は、代わりにホスト型エンドポイントを指定してください。

{ "mcpServers": { "imqueue": { "url": "https://mcp.imqueue.org/mcp" } } }

読み取り専用のツールを7つ提供します。上記の6つに加えて、ローカルインストールのセットアップ手順を返す local_install_guide があります。これは、OpenAI's plugin directory が ChatGPT と Codex 用にインストールするものでもあります。同じ制限のもと、同じエンドポイントをワンクリックでインストールできる形にしたものです。

設計上、CLI を利用するツールは提供していません。 これらのツールは、お使いのマシン（プロジェクトファイル、実行中のサービス、CLI の設定）に対して動作しますが、Cloudflare のエッジ上で動作するサーバーからはアクセスできません。そこで公開すると、名前どおりの動作を決して実行できないツールを掲載することになるため、リモートモードでは一切登録されません。これらのツールが必要な場合は、ローカルにインストールしてください。

開発

npm install
npm run build      # tsc -> dist/
npm run dev        # run from source with tsx
npm test           # unit tests (node:test under tsx) — no network needed
npm run smoke      # local surface: handshake + tools/list + annotations + tool calls
npm run verify     # all of the above plus both type-checks; also the publish gate

ユニットテストでは、ネットワークが不要な部分を対象にしています。固定コーパスでのランカー、スキャフォルダーが出力する正確な識別子、URL 解決、テレメトリー、ホスト型 Worker の HTTP インターフェースをテストします。worker/worker.ts は通常の fetch ハンドラーなので、wrangler やデプロイを使わず、Request を渡して Response を検証します。

ホスト型インターフェースは別の契約であるため、専用のチェックがあります。

npm run dev:worker                                   # wrangler dev on :8787
node scripts/remote-smoke.mjs http://localhost:8787/mcp
npm run smoke:remote                                 # or against production

このチェックでは、ツールが正確に7つあることと、そのすべてが読み取り専用であることを検証します。これにより、将来のリファクタリングで CLI ツールがホスト型エンドポイントにひそかに再公開されるのを防ぎます。

例

ユーザー： 「getUser(id) メソッドを持つ @imqueue ユーザーサービスを作成してください。」

エージェントは scaffold_service({ name: "user", methods: [{ name: "getUser", params: [{ name: "id", type: "number" }], returns: "User" }] }) を呼び出し、すぐに貼り付けられる UserService とブートストラップを取得します。続いて search_docs("run a service") / get_doc(...) を使って接続します。

ライセンス

GPL-3.0 — 無料のオープンソースです。

商用ライセンス

クローズドソース製品で @imqueue/mcp を使用する必要がある場合や、商用サポートを希望する場合は、商用ライセンスをご利用いただけます。imqueue.com をご覧ください。 ドキュメント全文：imqueue.org/mcp。設計とレジストリ配布計画については、SPEC.md をご覧ください。