Search @imqueue docs and scaffold typed services & clients from your AI coding agent.
org.imqueue/mcp Model Context Protocol (MCP) Server
A Model Context Protocol server for @imqueue that enables AI coding agents (e.g., Claude Code, ChatGPT, Codex, Cursor, VS Code, JetBrains) to search @imqueue documentation, scaffold typed services and clients, and drive the imq CLI to generate correct, idiomatic @imqueue code. It is intended for per-client setup and complete usage docs.
Search the official @imqueue docs (guides, tutorial, CLI manual, articles) and every exported symbol of every @imqueue package that publishes a generated API reference, returning the most relevant pages with their URLs. Each result names the package it belongs to. Takes a plain question or an exact symbol name such as 'RedisQueue.send', 'PgPubSub.listen' or 'watcherCheckDelay'. Answers 'how do I do X in @imqueue' and confirms a signature before code is written against it. Every result carries the page URL, which get_doc reads in full. Some capabilities are covered by two mutually exclusive packages — @imqueue/pg-prisma vs @imqueue/pg-sequelize, @imqueue/opentelemetry vs @imqueue/datadog — so for a query like 'tracing' or 'database', call list_packages for the choosing rule rather than taking whichever package ranks first, and pass `package` here to search within the one you settled on.
Parameters3
query
string
required
A question or a symbol name, e.g. 'expose a service method', 'delayed jobs' or 'IMQOptions.safeDelivery'
limit
integer
optional
Max results (default 6)
package
string
optional
Restrict results to one package, e.g. 'http-protect' or '@imqueue/opentelemetry'. Use it once you know which package you want — the same words appear in several packages' symbols.
Raw schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "A question or a symbol name, e.g. 'expose a service method', 'delayed jobs' or 'IMQOptions.safeDelivery'"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 20,
"description": "Max results (default 6)"
},
"package": {
"type": "string",
"description": "Restrict results to one package, e.g. 'http-protect' or '@imqueue/opentelemetry'. Use it once you know which package you want — the same words appear in several packages' symbols."
}
},
"required": [
"query"
],
"additionalProperties": false,
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
get_doc
Fetch the markdown of an @imqueue documentation page by its URL (as returned by search_docs). Returns plain markdown suitable for reading and quoting. Pass a URL with a #fragment — which is what search_docs returns for a section result — to get just that section plus the heading path above it; pass the URL without one to read the whole page. Only imqueue.org (framework docs) and imqueue.com (licensing, pricing, support) URLs are fetched; anything else is refused. Very large pages are truncated, which the result reports.
Parameters1
url
string
required
An imqueue.org or imqueue.com page URL, e.g. https://imqueue.org/get-started/
The complete, authoritative catalogue of documented @imqueue packages, each with its current version, licence, minimum Node version, a one-line summary and its exact install command. Call this BEFORE adding any @imqueue dependency: search_docs can only find a package you already suspect exists, and this is the list. Covers typed RPC over a message queue, the Redis queue engine, the `imq` CLI, jobs and scheduling, Prisma and Sequelize database toolkits, method caching, tag-invalidated caching, PostgreSQL LISTEN/NOTIFY, Zod validation, OpenTelemetry or Datadog tracing, async logging, GraphQL N+1 batching across services, CIDR/IP checks and HTTP rate limiting. Some pairs are mutually exclusive — pg-prisma vs pg-sequelize, opentelemetry vs datadog — and installing both of a pair breaks silently, so read the `pick` rule on those entries before choosing. For one package's release history, links and the framework-wide Node and Redis requirements, use package_status.
The current version, licence, minimum Node version and last release date of any published @imqueue package — or of all of them. Use it when the user asks which version of an @imqueue package is current, what licence it is under, or which Node or Redis version it needs. Covers every published package, including @imqueue/cli and @imqueue/mcp, and also returns the framework-wide licence, Node and Redis requirements, with a `licenseNote` that states the licence terms in a sentence. The facts are read from the npm registry by imqueue.org, and the result says when. Pass `package` for one entry, with or without the @imqueue/ scope; omit it for all of them.
Parameters1
package
string
optional
One package, with or without the scope: 'rpc', '@imqueue/rpc'. Omit for every package.
Raw schema
{
"type": "object",
"properties": {
"package": {
"type": "string",
"description": "One package, with or without the scope: 'rpc', '@imqueue/rpc'. Omit for every package."
}
},
"additionalProperties": false,
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
scaffold_service
READ-ONLY: returns generated source code as text and writes nothing to disk, creates no project and runs no command. Generates an idiomatic @imqueue/rpc service (an IMQService subclass with @expose()d, JSDoc-typed methods) plus a bootstrap that starts it. Provide the methods you want, or omit them for a starter template. Any non-primitive parameter or return type also gets a types.ts with the required @classType()/@property() declarations — without those the generated client types it `any`, which compiles. Use create_service (local install only) if you want files actually written.
Parameters2
name
string
required
Service name, e.g. 'user' or 'UserService'
methods
array
optional
Methods to expose
Raw schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Service name, e.g. 'user' or 'UserService'"
},
"methods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Method name"
},
"description": {
"type": "string",
"description": "What the method does"
},
"params": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string",
"description": "TypeScript type, e.g. 'string' or 'number[]'"
},
"description": {
"type": "string"
},
"optional": {
"type": "boolean",
"description": "Mark the parameter optional. @expose() publishes required parameters as mandatory, so callers of the generated client must pass a value for every non-optional one — set this for any parameter a caller may legitimately skip."
}
},
"required": [
"name",
"type"
],
"additionalProperties": false
}
},
"returns": {
"type": "string",
"description": "TypeScript return type WITHOUT Promise<> — e.g. 'User' or 'string'"
}
},
"required": [
"name"
],
"additionalProperties": false
},
"description": "Methods to expose"
}
},
"required": [
"name"
],
"additionalProperties": false,
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
scaffold_client
READ-ONLY: returns text and writes nothing to disk, and does NOT run the command it shows you. Explains how to generate and use the fully-typed client for an @imqueue service: @imqueue generates the real client from a running service via `imq client generate`, so this returns that exact command plus an illustrative usage snippet. The generated file exports a single namespace holding the client class, so the import shape is not the obvious one — take it from `namespace` rather than guessing. Use generate_client (local install only) if you want the command actually run.
Parameters2
service
string
required
The service to call, e.g. 'user' or 'UserService'
methods
array
optional
Known methods (used to shape the example call)
Raw schema
{
"type": "object",
"properties": {
"service": {
"type": "string",
"description": "The service to call, e.g. 'user' or 'UserService'"
},
"methods": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Method name"
},
"description": {
"type": "string",
"description": "What the method does"
},
"params": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string",
"description": "TypeScript type, e.g. 'string' or 'number[]'"
},
"description": {
"type": "string"
},
"optional": {
"type": "boolean",
"description": "Mark the parameter optional. @expose() publishes required parameters as mandatory, so callers of the generated client must pass a value for every non-optional one — set this for any parameter a caller may legitimately skip."
}
},
"required": [
"name",
"type"
],
"additionalProperties": false
}
},
"returns": {
"type": "string",
"description": "TypeScript return type WITHOUT Promise<> — e.g. 'User' or 'string'"
}
},
"required": [
"name"
],
"additionalProperties": false
},
"description": "Known methods (used to shape the example call)"
}
},
"required": [
"service"
],
"additionalProperties": false,
"$schema": "https://json-schema.org/draft/2020-12/schema"
}
local_install_guide
Return the setup instructions for running the full @imqueue MCP server on your own machine. The local server adds the CLI-backed tools, which act on your project files and running services and so cannot be offered by a hosted server. Returns instructions only — it installs nothing.
A Model Context Protocol server for @imqueue. It lets AI coding agents (Claude Code, ChatGPT, Codex, Cursor, VS Code, JetBrains, …) search the @imqueue documentation, scaffold typed services & clients, and drive the imq CLI — so they generate correct, idiomatic @imqueue code instead of guessing.
📖 Full documentation: imqueue.org/mcp — per-client setup, complete tools reference, agent workflows and the safety model.
Tools
Two surfaces, and they are not the same. The local server (npx -y @imqueue/mcp) has all 14 tools. The hosted server (mcp.imqueue.org/mcp) has seven, all read-only — see below for why.
Hosted + local
Tool
What it does
search_docs
Search the official docs (guides, tutorial, CLI manual, API reference, articles) and return the most relevant pages + URLs.
get_doc
Fetch the full markdown of a doc page by URL.
list_packages
List the documented @imqueue packages with install commands, current versions and licences.
package_status
The current version, licence, minimum Node and last release date of any published @imqueue package, or all of them.
scaffold_service
Generate an IMQService subclass with @expose()d, JSDoc-typed methods + a bootstrap (offline, no CLI needed).
scaffold_client
Show how to generate and use the fully-typed client for a service (offline).
All six are read-only: they fetch or generate text and write nothing.
All five also declare an MCP outputSchema and return structuredContent alongside the human-readable markdown, so a client can consume results as data — take results[0].url from search_docs and hand it to get_doc, or write scaffold_service's files[] straight to disk — instead of parsing prose and code fences. For the scaffolders and the catalogue the markdown is rendered from that same structure, so the two can't drift.
get_doc's schema is metadata only, on purpose — and that turns out to be the more interesting design than having no schema at all. A schema obliges the server to send structuredContent, but nothing says structuredContent must repeat what is in content: it describes the structured part of the answer. So the page travels once, in content, and the schema carries url (the mirror actually fetched, which is not always the URL you passed), mimeType, bytes (so a caller can decide before reading) and truncated. Putting markdown in there as well would have doubled the largest response the server can produce — measured on /api/rpc/latest/, 16.6 kB of text plus 16.6 kB of structure for one read. The absence of a body field is itself self-describing: a caller reading the schema sees no content field and knows the page is in content, which is where every client already looks.
The CLI-backed tools have no schema: they return imq stdout, which has no shape worth promising.
CLI-backed tools — local only (require @imqueue/cli on PATH)
These drive the real CLI, so they act on the machine the server runs on. They exist in the local install only; the hosted server does not register them.
Tool
What it does
cli_status
Detect imq and report its version.
cli_install
Install @imqueue/cli globally (npm i -g @imqueue/cli) when it's missing.
cli_help
imq <command> --help — exact, version-accurate flags (no side effects).
create_service
imq service create — dry-run by default (writes nothing); pass apply: true to actually create the project.
generate_client
imq client generate <Service> — the real typed client (the service must be running).
fleet
imq ctl <start|stop|restart|status> — manage a directory of service repos. status is read-only.
config
imq config <check|get|set|init> — read/write CLI configuration (set for automation; init is interactive).
logs
imq log — dump current fleet logs (never follows; capped) or clean them.
Calls run with stdin closed and a timeout, so a missing-flag prompt fails fast instead of hanging. If imq isn't installed, run cli_install or use the offline scaffold_* tools.
Docs are fetched live from imqueue.org's machine-readable feeds, so the server never ships stale content: /llms.txt for the curated page index, per-page …/index.md mirrors for bodies, /search-index.json, /search-text.json and /search-sections.json for the search corpus, and /status.json for package versions and licences. imqueue.com's /llms.txt and peer feeds are read too, for the commercial pages. Nothing outside those two hosts is ever fetched — the allowlist is enforced in src/docs.ts and refuses anything else.
Versions and licences come from that last feed rather than being compiled in, deliberately: @imqueue releases far more often than this server does, so a baked-in version would be wrong within days and wrong with total confidence. npmjs.com serves bot detection to an unattended fetch, which is why imqueue.org reads the registry at build time and republishes the answer where anything can read it.
Install
Requires Node.js ≥ 18. No build step for users — run straight from npm:
bash
npx -y @imqueue/mcp
Claude Code
bash
claude mcp add imqueue -- npx -y @imqueue/mcp
ChatGPT & Codex
@imqueue is listed in OpenAI's plugin directory — shared by ChatGPT and Codex. In ChatGPT, open the Plugins tab and install it; in the Codex CLI, run /plugins. No config file, no Node.
That route installs the hosted server, so it is the seven read-only tools and none of the CLI bridge (see below). Codex can run the local server alongside it — MCP servers live under mcp_servers in ~/.codex/config.toml, in TOML rather than the usual JSON:
VS Code and Visual Studio use a top-level servers key with "type": "stdio" instead of mcpServers. See imqueue.org/mcp/installation for the exact config file path and snippet for every client.
Hosted server (no install)
If your client supports remote MCP servers and you only need docs and scaffolding, point it at the hosted endpoint instead:
It serves seven tools, all read-only: the six above plus local_install_guide, which returns the setup steps for the local install. This is also what OpenAI's plugin directory installs for ChatGPT and Codex — the same endpoint under the same limits, packaged as one click.
It does not offer the CLI-backed tools, by design. Those act on your machine — your project files, your running services, your CLI config — which a server running on Cloudflare's edge cannot reach. Advertising them there would mean listing tools that can never do what their names say, so they are not registered at all in remote mode. If you need them, install locally.
Develop
bash
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
The unit tests cover what does not need the network: the ranker on a fixed corpus,
the exact identifiers the scaffolders emit, URL resolution, telemetry, and the hosted
Worker's HTTP surface — worker/worker.ts is a plain fetch handler, so it is called
with a Request and asserted on the Response, with no wrangler and no deploy.
The hosted surface has its own check, because it is a different contract:
bash
npm run dev:worker # wrangler dev on :8787
node scripts/remote-smoke.mjs http://localhost:8787/mcp
npm run smoke:remote # or against production
It asserts the exact seven-tool list and that every one of them is read-only — the assertion that stops a future refactor from quietly re-exposing a CLI tool on the hosted endpoint.
Example
User:"Create an @imqueue user service with a getUser(id) method."
The agent calls scaffold_service({ name: "user", methods: [{ name: "getUser", params: [{ name: "id", type: "number" }], returns: "User" }] }) and gets a ready-to-paste UserService + bootstrap, then search_docs("run a service") / get_doc(...) to wire it up.
License
GPL-3.0 — free and open source.
Commercial licensing
Need to use @imqueue/mcp in a closed-source product, or want commercial support? A commercial license is available — see imqueue.com.
Full docs: imqueue.org/mcp. See SPEC.md for the design and registry-distribution plan.