Queue Pilot

Queue Pilot

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.

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)
• 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.

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.

Windows note: If npx fails to resolve the package, 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)

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.

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