@imqueue

@imqueue/mcp

一个适用于 @imqueue 的 Model Context Protocol 服务。它让 AI 编码 Agent（Claude Code、ChatGPT、Codex、Cursor、VS Code、JetBrains，……）能够搜索 @imqueue 文档、搭建类型化服务和客户端的骨架，并驱动 imq CLI——让它们生成正确、符合惯例的 @imqueue 代码，而不是凭空猜测。

📖 完整文档：imqueue.org/mcp — 各客户端的配置、完整工具参考、Agent 工作流和安全模型。

工具

有两种形式，它们并不相同。本地服务（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	生成一个 IMQService 子类，其中包含带 @expose() 和 JSDoc 类型说明的方法，以及一个启动程序（离线运行，无需 CLI）。
scaffold_client	展示如何生成并使用服务的完全类型化客户端（离线运行）。

这六个工具均为只读：它们会获取或生成文本，不会写入任何内容。

这五个工具还都会声明 MCP outputSchema，并在返回人类可读的 Markdown 的同时返回 structuredContent，因此客户端可以将结果作为数据使用——从 search_docs 获取 results[0].url 并交给 get_doc，或将 scaffold_service 的 files[] 直接写入磁盘——而无需解析散文和代码围栏。对于脚手架工具和目录工具，Markdown 都是根据同一结构生成的，因此两者不会出现偏差。

get_doc 的 schema 只包含元数据，这是有意为之——事实证明，这种设计比完全不提供 schema 更有意思。schema 要求服务发送 structuredContent，但没有规定 structuredContent 必须重复 content 中的内容：它描述的是答案中的结构化部分。因此，页面只在 content 中传输一次，而 schema 则包含 url（实际获取的镜像 URL，不一定是你传入的 URL）、mimeType、bytes（让调用方能在读取前做出判断）和 truncated。如果再把 markdown 放进去，就会让服务可能生成的最大响应翻倍——对 /api/rpc/latest/ 的测量结果为：一次读取中包含 16.6 kB 文本和 16.6 kB 结构。没有正文栏位本身就能说明问题：调用方查看 schema 时，看不到内容栏位，就会知道页面位于 content 中，而所有客户端本来就会从那里读取。

由 CLI 驱动的工具没有 schema：它们返回 imq 标准输出，而这种输出并没有值得承诺的固定结构。

CLI 支持的工具 — 仅限本地（需要将 @imqueue/cli 加入 PATH）

这些工具会驱动真实的 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 和同类信息源，以获取商业页面。绝不会从这两个主机以外的任何位置获取内容 — 白名单在 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 已列入**OpenAI 的插件目录** — 由 ChatGPT 和 Codex 共用。在 ChatGPT 中，打开 Plugins 标签页并安装；在 Codex CLI 中，运行 /plugins。无需配置文件，也无需 Node。

此方式安装的是托管服务，因此它只提供 7 个只读工具，不包含任何 CLI 桥接工具（见下文）。Codex 可以同时运行本地服务 — MCP 服务配置在 ~/.codex/config.toml 的 mcp_servers 下，使用 TOML 而非通常的 JSON：

[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 使用顶层 servers 键，并将 "type": "stdio" 作为配置值，而不是 mcpServers。请参阅 imqueue.org/mcp/installation，了解每个客户端对应的确切配置文件路径和代码片段。

托管服务（无需安装）

如果你的客户端支持远程 MCP 服务，并且你只需要文档和脚手架，请改为连接托管端点：

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

它提供七个工具，全部为只读：上述六个工具，加上 local_install_guide，后者会返回本地安装的设置步骤。这也是 OpenAI 的插件目录 为 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 处理程序，因此测试会传入 Request 并检查 Response，无需 wrangler，也无需部署。

托管接口有专门的检查，因为它遵循不同的契约：

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

它会断言工具列表恰好包含七个工具，并且每个工具都为只读——这项断言可防止未来重构时悄然在托管端点重新暴露 CLI 工具。

示例

用户： “创建一个 @imqueue 用户服务，并提供 getUser(id) 方法。”

Agent 会调用 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。