Queue Pilot

Install

Config snippet generator goes here (5 client tabs)

README

# Queue Pilot

[![npm version](https://img.shields.io/npm/v/queue-pilot)](https://www.npmjs.com/package/queue-pilot)
[![license](https://img.shields.io/npm/l/queue-pilot)](LICENSE)
[![CI](https://github.com/LarsCowe/queue-pilot/actions/workflows/ci.yml/badge.svg)](https://github.com/LarsCowe/queue-pilot/actions/workflows/ci.yml)
[![npm downloads](https://img.shields.io/npm/dm/queue-pilot)](https://www.npmjs.com/package/queue-pilot)
[![node](https://img.shields.io/node/v/queue-pilot)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)

MCP server for message queue development — combines message inspection with JSON Schema validation. Supports **RabbitMQ** and **Kafka**.

Designed for integration projects where multiple teams communicate via message brokers: inspect queues/topics, view messages, and validate payloads against agreed-upon schemas — all from your AI assistant.

<p align="center">
  <img src="docs/queue-pilot-diagram.svg" alt="Queue Pilot architecture: MCP clients connect to Queue Pilot, which interfaces with RabbitMQ and Kafka" width="720">
</p>

## Features

- **Multi-broker support** — RabbitMQ and Apache Kafka via a unified adapter interface
- **Message Inspection** — Browse queues/topics, peek at messages without consuming them
- **Schema Validation** — Validate message payloads against JSON Schema definitions
- **Combined Inspection** — `inspect_queue` peeks messages AND validates each against its schema
- **Validated Publishing** — `publish_message` validates against a schema before sending — invalid messages never hit the broker
- **Queue Management** — Create queues/topics, bindings, and purge messages for dev/test workflows
- **Broker Info** — List exchanges, bindings, consumer groups, and partition details

## Prerequisites

- **Node.js >= 22** — Required runtime ([check with `node --version`](https://nodejs.org/))
- **A message broker:**
  - **RabbitMQ** with the [management plugin](https://www.rabbitmq.com/docs/management) enabled (HTTP API on port 15672), or
  - **Apache Kafka** (requires `@confluentinc/kafka-javascript` as peer dependency)
- **An MCP-compatible client** — Claude Code, Claude Desktop, Cursor, VS Code (Copilot), Windsurf, etc.

## Quick Start

### 1. Define your schemas

Create JSON Schema files in a directory:

`schemas/order.created.json`:

```json
{
  "$id": "order.created",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Order Created",
  "description": "Emitted when a new order is placed",
  "version": "1.0.0",
  "type": "object",
  "required": ["orderId", "amount"],
  "properties": {
    "orderId": { "type": "string" },
    "amount": { "type": "number" }
  }
}
```

### 2. Add to your MCP client

Generate the config for your client with `queue-pilot init`:

```bash
npx queue-pilot init --schemas /absolute/path/to/your/schemas --client <name>
```

Supported clients: `claude-code`, `claude-desktop`, `vscode`, `cursor`, `windsurf`. Omit `--client` for generic JSON.

For Kafka, add `--broker kafka`. The generated config automatically includes the required `@confluentinc/kafka-javascript` peer dependency.

Non-default credentials are included as environment variables to avoid exposing secrets in `ps` output:

```bash
npx queue-pilot init --schemas ./schemas --rabbitmq-user admin --rabbitmq-pass secret
```

Run `npx queue-pilot init --help` for all options including Kafka SASL authentication.

> **Windows note:** If `npx` fails to resolve the package, try `cmd /c npx queue-pilot init ...`.

<details>
<summary>Manual configuration (without init)</summary>

Add the following server configuration to your MCP client:

**RabbitMQ:**

```json
{
  "mcpServers": {
    "queue-pilot": {
      "command": "npx",
      "args": [
        "-y",
        "queue-pilot",
        "--schemas", "/absolute/path/to/your/schemas"
      ]
    }
  }
}
```

**Kafka:**

```json
{
  "mcpServers": {
    "queue-pilot": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@confluentinc/kafka-javascript",
        "--package=queue-pilot",
        "queue-pilot",
        "--schemas", "/absolute/path/to/your/schemas",
        "--broker", "kafka"
      ],
      "env": {
        "KAFKA_BROKERS": "localhost:9092"
      }
    }
  }
}
```

> **Schema path tip:** Use an absolute path for `--schemas`. Relative paths resolve from the MCP client's working directory, which may not be your project root.

| Client | Config file |
|--------|------------|
| Claude Code | `.mcp.json` (project) or `~/.claude.json` (user) |
| Claude Desktop | `claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json` |
| VS Code (Copilot) | `.vscode/mcp.json` (uses `"servers"` instead of `"mcpServers"`) |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |

</details>

<details>
<summary>Development (running from source)</summary>

```json
{
  "mcpServers": {
    "queue-pilot": {
      "command": "npx",
      "args": [