Queue Pilot

🚀 Queue Pilot

A MCP server for message queue development that combines message inspection with JSON Schema validation, supporting RabbitMQ and Kafka.

🚀 Quick Start

1. Define your schemas

Create JSON Schema files in a directory:

schemas/order.created.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:

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:

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.

⚠️ Important Note

If npx fails to resolve the package on Windows, try cmd /c npx queue-pilot init ....

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

{
  "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"
      }
    }
  }
}

{
  "mcpServers": {
    "queue-pilot": {
      "command": "npx",
      "args": [
        "tsx",
        "src/index.ts",
        "--schemas", "./schemas"
      ],
      "cwd": "/path/to/queue-pilot"
    }
  }
}

3. Use it

Ask your assistant things like:

• "Which queues are there and how many messages do they have?"
• "Show me the messages in the orders queue"
• "Inspect the registration queue and check if all messages are valid"
• "What schemas are available?"
• "Validate this message against the order.created schema"
• "Publish an order.created event to the events exchange"
• "Create a queue called dead-letters and bind it to the events exchange"
• "Purge all messages from the orders queue"
• "List all consumer groups" (Kafka)
• "Show me the partition details for the orders topic" (Kafka)

✨ 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

📦 Installation

Prerequisites

• Node.js >= 22 — Required runtime (check with node --version)
• A message broker:
  • RabbitMQ with the management plugin 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.

📚 Documentation

Schema Format

Schemas follow JSON Schema draft-07 with a few conventions:

• $id — Message type identifier (matches the type property on messages)
• version — Schema version (custom field, not validated by JSON Schema)
• Standard JSON Schema validation including required, properties, format etc.

Schema matching: when inspecting a queue, the message's type property is used to find the corresponding schema by $id.

Configuration

CLI arguments take priority over environment variables, which take priority over defaults.

Use environment variables in MCP client env blocks to avoid exposing credentials in ps output.

🔧 Technical Details

Development

npm install
npm test                    # Unit tests
npm run test:coverage       # Coverage report
npm run build               # TypeScript compilation
npm run typecheck           # Type check

# Integration tests (requires RabbitMQ)
docker compose up -d --wait
npm run test:integration

Tech Stack

• TypeScript (strict mode, ESM)
• MCP SDK v1.26.0
• Ajv for JSON Schema validation
• Zod for MCP tool parameter definitions
• Vitest for testing
• RabbitMQ Management HTTP API
• Confluent Kafka JavaScript (optional, for Kafka support)

📄 License

MIT