MCP tools reference

The server exposes its tools in three groups. Documentation and scaffolding tools work everywhere with no dependencies. The CLI bridge tools require @imqueue/cli (imq) on your PATH — call cli_status first, and if it is missing either cli_install it or fall back to the offline scaffold_* tools.

Which of them you get depends on how you connect. The local install has all thirteen. The hosted endpoint has six, all read-only: the documentation and scaffolding tools plus local_install_guide. The CLI-bridge tools act on your own machine — your files, your processes, your CLI config — which a server on Cloudflare's edge cannot reach, so it does not offer them at all. They are not in its tool list.

You never call these by hand — your agent picks them based on their descriptions. This page is so you know what it can do, and what is safe.

Documentation

search_docs

Search the official @imqueue docs (guides, tutorial, CLI manual, API reference, articles) and return the most relevant pages with their URLs.

• Input: query (string) — what you want to find; limit (1–20, default 6).
• Returns: a ranked list of matching pages with titles, sections and URLs.
• Side effects: none (read-only; fetches imqueue.org).
• Example prompt: "How do I expose a method on an @imqueue service?"

get_doc

Fetch the full markdown of a documentation page by its URL (as returned by search_docs), ready to read and quote.

• Input: url (string) — an imqueue.org page URL.
• Returns: the page as plain markdown.
• Side effects: none. Host-locked to imqueue.org — it will not fetch any other host.
• Example prompt: "Read the getting-started guide and summarise the steps."

list_packages

The main @imqueue packages with a one-line summary and install command, so the agent picks the right one before writing code.

• Input: none.
• Returns: the package catalog (e.g. @imqueue/rpc, @imqueue/core, @imqueue/cli) with install commands.
• Side effects: none.
• Example prompt: "Which @imqueue package do I need for delayed jobs?"

Scaffolding (offline)

scaffold_service

Generate an idiomatic @imqueue/rpc service — an IMQService subclass with @expose()d, JSDoc-typed methods plus a bootstrap that starts it.

• Input: name (string); methods (optional array of { name, description?, params?, returns? }).
• Returns: ready-to-save TypeScript. Omitting methods yields a starter template.
• Side effects: none — returns code as text; writes nothing.
• Example prompt: "Scaffold an @imqueue user service with getUser and createUser."

scaffold_client

@imqueue generates the real typed client from a running service, so types never drift. This tool returns the exact command to do that plus an illustrative usage snippet — it does not fabricate a client that could go stale.

• Input: service (string); methods (optional, to shape the example).
• Returns: the imq client generate command and an example call.
• Side effects: none.
• Example prompt: "How do I get a typed client for my user service?"

CLI bridge tools

The CLI bridge tools drive the real imq binary. Every call runs with stdin closed and a timeout, so a command that would prompt interactively fails fast with guidance rather than hanging your agent.

cli_status

Detect whether imq (@imqueue/cli) is installed and report its version. The agent should call this before any other CLI-bridge tool.

• Input: none. Read-only.
• Example prompt: "Is the @imqueue CLI installed?"

cli_install

Install @imqueue/cli globally via npm install -g @imqueue/cli when it is missing.

• Input: version (optional npm version/tag, default latest).
• Side effects: installs a global npm package (may need a writable prefix or elevated permissions).
• Example prompt: "Install the @imqueue CLI for me."

cli_help

Run imq [command] --help and return the exact, version-accurate flags — the agent uses this to build a non-interactive create_service call.

• Input: command (optional, e.g. "service create"). Read-only.
• Example prompt: "What flags does imq service create take?"

create_service

Scaffold a real, provider-wired service via imq service create.

• Input: name; path?; flags? (from cli_help); cwd?; apply?.
• Safety: runs as a dry-run by default (shows the plan, writes nothing). A real run requires apply: true — it can write files, init git, configure CI and push to a remote, so an agent should only apply with your clear intent.
• Example prompt: "Create a payments service — show me the plan first."

generate_client

Run imq client generate <Service> to emit the real, fully-typed client.

• Input: service; path?; cwd?.
• Requirement: the target service must be running — the CLI introspects the live service.
• Example prompt: "Generate the typed client for the running UserService."

fleet

Run imq ctl <action> over a directory of service repositories.

• Input: action (start | stop | restart | status); path?; services?; update?; calm?; verbose?; cwd?.
• Safety: status is read-only; start / stop / restart change running processes.
• Example prompt: "Start my local fleet and tell me what's running."

config

Run imq config <action> to manage CLI configuration.

• Input: action (check | get | set | init); option? (dot-path for nested keys); value?; cwd?.
• Safety: check / get are read-only; set writes one value; init is interactive, so automation should prefer set.
• Example prompt: "Set my default CI provider to github-actions."

logs

Work with logs of services started by imq ctl.

• Input: action (dump (default) | clean); services?; prefix?; cwd?.
• Safety: dump reads the current combined logs and exits — it never follows/streams, and output is capped so it can't flood the agent; clean deletes collected logs.
• Example prompt: "Show me the recent logs for the auth service."

Hosted endpoint only

local_install_guide

Registered only on the hosted server (mcp.imqueue.org), where it is how an agent discovers that the CLI-bridge tools need a local install. The local server does not expose it — there is nothing left to install.

• Input: none.
• Returns: the exact steps to install the full MCP server on your machine.
• Side effects: none — it returns instructions, it does not install anything. That is also why it is named local_install_guide rather than install_locally, as it was before 3.0.0: a tool's name has to describe what it actually does.
• Example prompt: "Why can't you start my fleet?"

The CLI-bridge tools above are absent from the hosted server's tool list — it does not list them and cannot run them. Until 3.0.0 it listed them and answered with install guidance instead, which was worse: an agent that picked fleet got prose rather than a fleet. See Safety & troubleshooting.

Read-only vs state-changing @imqueue MCP tools

A quick map of which @imqueue MCP tools are safe to let an agent call freely, and which change your machine:

Every tool declares this in machine-readable form too. Each one carries the MCP readOnlyHint, destructiveHint and openWorldHint annotations, so a client can decide what to run without asking you rather than guessing from the name. Tools that accept a mix of operations own their worst case: fleet is marked destructive because stop is, even though status is not. Every tool on the hosted endpoint is readOnlyHint: true.

See Safety & troubleshooting for the full trust model, and Agent workflows for how these tools chain together in practice.