queue-pilot 0.2.0 → 0.5.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Lars
+Copyright (c) 2025-2026 Lars
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,17 +1,33 @@
 # Queue Pilot
 
-MCP server for message queue development — combines RabbitMQ message inspection with JSON Schema validation.
+[![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/)
 
-Designed for integration projects where multiple teams communicate via RabbitMQ: inspect queues, view messages, and validate payloads against agreed-upon schemas — all from your AI assistant.
+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
 
-- **Message Inspection** — Browse queues, peek at messages without consuming them
+- **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, bindings, and purge messages for dev/test workflows
-- **Broker Info** — List exchanges and bindings to understand message routing
+- **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` — install separately: `npm install @confluentinc/kafka-javascript`)
+- **An MCP-compatible client** — Claude Code, Claude Desktop, Cursor, VS Code (Copilot), Windsurf, etc.
 
 ## Quick Start
 
@@ -19,8 +35,9 @@ Designed for integration projects where multiple teams communicate via RabbitMQ:
 
 Create JSON Schema files in a directory:
 
+`schemas/order.created.json`:
+
 ```json
-// schemas/order.created.json
 {
   "$id": "order.created",
   "$schema": "http://json-schema.org/draft-07/schema#",
@@ -38,34 +55,98 @@ Create JSON Schema files in a directory:
 
 ### 2. Add to your MCP client
 
+Generate the config for your client with `queue-pilot init`:
+
+```bash
+# RabbitMQ (default)
+npx queue-pilot init --schemas /absolute/path/to/your/schemas
+
+# Kafka
+npx queue-pilot init --schemas /absolute/path/to/your/schemas --broker kafka
+```
+
+For a specific client, use `--client`:
+
+```bash
+# Claude Code — outputs a ready-to-run `claude mcp add` command
+npx queue-pilot init --schemas ./schemas --client claude-code
+
+# VS Code (Copilot)
+npx queue-pilot init --schemas ./schemas --client vscode
+
+# Cursor
+npx queue-pilot init --schemas ./schemas --client cursor
+
+# Claude Desktop
+npx queue-pilot init --schemas ./schemas --client claude-desktop
+
+# Windsurf
+npx queue-pilot init --schemas ./schemas --client windsurf
+```
+
+Non-default settings are included as environment variables (not CLI args) to avoid exposing credentials in `ps` output:
+
+```bash
+# RabbitMQ with custom credentials
+npx queue-pilot init --schemas ./schemas --rabbitmq-user admin --rabbitmq-pass secret
+
+# Kafka with SASL authentication
+npx queue-pilot init --schemas ./schemas --broker kafka --kafka-brokers kafka:9092 --kafka-sasl-mechanism plain --kafka-sasl-username admin --kafka-sasl-password secret
+```
+
+> **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", "./schemas",
-        "--rabbitmq-url", "http://localhost:15672",
-        "--rabbitmq-user", "guest",
-        "--rabbitmq-pass", "guest"
+        "--schemas", "/absolute/path/to/your/schemas"
       ]
     }
   }
 }
 ```
 
-<details>
-<summary>Where does this config go?</summary>
+**Kafka:**
+
+```json
+{
+  "mcpServers": {
+    "queue-pilot": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "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 | `.claude/mcp.json` (project) or `~/.claude/mcp.json` (global) |
 | Claude Desktop | `claude_desktop_config.json` |
 | Cursor | `.cursor/mcp.json` |
-| VS Code (Copilot) | `.vscode/mcp.json` |
+| VS Code (Copilot) | `.vscode/mcp.json` (uses `"servers"` instead of `"mcpServers"`) |
 | Windsurf | `~/.codeium/windsurf/mcp_config.json` |
 
 </details>
@@ -81,11 +162,9 @@ Add the following server configuration to your MCP client:
       "args": [
         "tsx",
         "src/index.ts",
-        "--schemas", "./schemas",
-        "--rabbitmq-url", "http://localhost:15672",
-        "--rabbitmq-user", "guest",
-        "--rabbitmq-pass", "guest"
-      ]
+        "--schemas", "./schemas"
+      ],
+      "cwd": "/path/to/queue-pilot"
     }
   }
 }
@@ -105,36 +184,76 @@ Ask your assistant things like:
 - "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)
 
 ## MCP Tools
 
-### Read
+### Universal tools (all brokers)
 
 | Tool | Description |
 |------|-------------|
 | `list_schemas` | List all loaded message schemas |
 | `get_schema` | Get the full definition of a specific schema |
 | `validate_message` | Validate a JSON message against a schema |
-| `list_queues` | List all RabbitMQ queues with message counts |
-| `peek_messages` | View messages in a queue without consuming them |
+| `list_queues` | List all queues/topics with message counts |
+| `peek_messages` | View messages in a queue/topic without consuming them |
 | `inspect_queue` | Peek messages + validate each against its schema |
+| `get_overview` | Get broker cluster overview |
+| `check_health` | Check broker health status |
+| `get_queue` | Get detailed information about a specific queue/topic |
+| `list_consumers` | List consumers (RabbitMQ) or consumer groups (Kafka) |
+| `publish_message` | Publish a message with optional schema validation gate |
+| `purge_queue` | Remove all messages from a queue/topic |
+| `create_queue` | Create a new queue/topic |
+| `delete_queue` | Delete a queue/topic |
+
+### RabbitMQ-specific tools
+
+| Tool | Description |
+|------|-------------|
 | `list_exchanges` | List all RabbitMQ exchanges |
+| `create_exchange` | Create a new exchange |
+| `delete_exchange` | Delete an exchange |
 | `list_bindings` | List bindings between exchanges and queues |
+| `create_binding` | Bind a queue to an exchange with a routing key |
+| `delete_binding` | Delete a binding |
+| `list_connections` | List all client connections to the broker |
 
-### Write
+### Kafka-specific tools
 
 | Tool | Description |
 |------|-------------|
-| `publish_message` | Publish a message to an exchange with optional schema validation gate |
-| `purge_queue` | Remove all messages from a queue (returns count purged) |
-| `create_queue` | Create a new queue (idempotent if settings match) |
-| `create_binding` | Bind a queue to an exchange with a routing key |
+| `list_consumer_groups` | List all consumer groups with their state |
+| `describe_consumer_group` | Show members, assignments, and state of a consumer group |
+| `list_partitions` | Show partition details for a topic (leader, replicas, ISR) |
+| `get_offsets` | Show earliest/latest offsets per partition |
+
+## MCP Prompts
+
+Pre-built workflow templates that guide your AI assistant through multi-step operations.
+
+| Prompt | Parameters | Description |
+|--------|-----------|-------------|
+| `debug-flow` | `exchange`, `queue` | Trace bindings from exchange to queue, peek messages, and validate each against its schema |
+| `health-report` | _(none)_ | Check broker health, get cluster overview, flag queues with backed-up messages |
+| `schema-compliance` | `queue` _(optional)_ | Peek messages and validate each against its schema — for one queue or all queues |
+
+Usage example (in any MCP-compatible client):
+
+> "Use the debug-flow prompt for exchange 'events' and queue 'orders'"
+
+## MCP Resources
+
+Each loaded schema is exposed as a readable MCP resource at `schema:///<schema-name>`.
+
+Clients that support MCP resources can read schema definitions directly without calling tools. For example, a schema loaded from `order.created.json` is available at `schema:///order.created`.
 
 ## Schema Format
 
 Schemas follow JSON Schema draft-07 with a few conventions:
 
-- `$id` — Message type identifier (matches the `type` property on RabbitMQ messages)
+- `$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.
 
@@ -142,24 +261,82 @@ Schema matching: when inspecting a queue, the message's `type` property is used
 
 ## CLI Arguments
 
+### General
+
 | Argument | Default | Description |
 |----------|---------|-------------|
 | `--schemas` | (required) | Path to directory containing JSON Schema files |
+| `--broker` | `rabbitmq` | Broker type: `rabbitmq` or `kafka` |
+
+### RabbitMQ
+
+| Argument | Default | Description |
+|----------|---------|-------------|
 | `--rabbitmq-url` | `http://localhost:15672` | RabbitMQ Management API URL |
 | `--rabbitmq-user` | `guest` | RabbitMQ username |
 | `--rabbitmq-pass` | `guest` | RabbitMQ password |
 
+### Kafka
+
+| Argument | Default | Description |
+|----------|---------|-------------|
+| `--kafka-brokers` | `localhost:9092` | Comma-separated broker addresses |
+| `--kafka-client-id` | `queue-pilot` | Kafka client ID |
+| `--kafka-sasl-mechanism` | _(none)_ | SASL mechanism: `plain`, `scram-sha-256`, `scram-sha-512` |
+| `--kafka-sasl-username` | _(none)_ | SASL username |
+| `--kafka-sasl-password` | _(none)_ | SASL password |
+
+## Environment Variables
+
+Connection settings can also be configured via environment variables. CLI arguments take priority over environment variables, which take priority over defaults.
+
+### RabbitMQ
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RABBITMQ_URL` | `http://localhost:15672` | RabbitMQ Management API URL |
+| `RABBITMQ_USER` | `guest` | RabbitMQ username |
+| `RABBITMQ_PASS` | `guest` | RabbitMQ password |
+
+### Kafka
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `KAFKA_BROKERS` | `localhost:9092` | Comma-separated broker addresses |
+| `KAFKA_CLIENT_ID` | `queue-pilot` | Kafka client ID |
+| `KAFKA_SASL_MECHANISM` | _(none)_ | SASL mechanism |
+| `KAFKA_SASL_USERNAME` | _(none)_ | SASL username |
+| `KAFKA_SASL_PASSWORD` | _(none)_ | SASL password |
+
+This is useful with MCP client `env` blocks to avoid exposing credentials in `ps` output:
+
+```json
+{
+  "mcpServers": {
+    "queue-pilot": {
+      "command": "npx",
+      "args": ["-y", "queue-pilot", "--schemas", "/absolute/path/to/your/schemas"],
+      "env": {
+        "RABBITMQ_URL": "http://localhost:15672",
+        "RABBITMQ_USER": "admin",
+        "RABBITMQ_PASS": "secret"
+      }
+    }
+  }
+}
+```
+
 ## Development
 
 ```bash
 npm install
-npm test                    # Unit tests (103 tests)
+npm test                    # Unit tests
 npm run test:coverage       # Coverage report
 npm run build               # TypeScript compilation
-npm run lint                # Type check
+npm run typecheck           # Type check
 
 # Integration tests (requires RabbitMQ)
-docker compose up -d
+docker compose up -d --wait
 npm run test:integration
 ```
 
@@ -170,7 +347,8 @@ npm run test:integration
 - [Ajv](https://ajv.js.org/) for JSON Schema validation
 - [Zod](https://zod.dev/) for MCP tool parameter definitions
 - [Vitest](https://vitest.dev/) for testing
-- RabbitMQ Management HTTP API (no additional broker dependencies)
+- RabbitMQ Management HTTP API
+- [Confluent Kafka JavaScript](https://github.com/confluentinc/confluent-kafka-javascript) (optional, for Kafka support)
 
 ## License
 

package/dist/broker/factory.d.ts

@@ -0,0 +1,25 @@
+import type { BrokerAdapter } from "./types.js";
+import type { ToolDefinition } from "./tool-definition.js";
+export interface RabbitMQBrokerConfig {
+    broker: "rabbitmq";
+    url: string;
+    username: string;
+    password: string;
+}
+export interface KafkaBrokerConfig {
+    broker: "kafka";
+    brokers: string[];
+    clientId?: string;
+    sasl?: {
+        mechanism: "plain" | "scram-sha-256" | "scram-sha-512";
+        username: string;
+        password: string;
+    };
+    ssl?: boolean;
+}
+export type BrokerConfig = RabbitMQBrokerConfig | KafkaBrokerConfig;
+export interface AdapterResult {
+    adapter: BrokerAdapter;
+    tools: ToolDefinition[];
+}
+export declare function createAdapter(config: BrokerConfig): Promise<AdapterResult>;

package/dist/broker/factory.js

@@ -0,0 +1,35 @@
+import { RabbitMQClient } from "../rabbitmq/client.js";
+import { RabbitMQAdapter } from "../brokers/rabbitmq/adapter.js";
+import { createRabbitMQTools } from "../brokers/rabbitmq/tools.js";
+export async function createAdapter(config) {
+    switch (config.broker) {
+        case "rabbitmq": {
+            const client = new RabbitMQClient({
+                url: config.url,
+                username: config.username,
+                password: config.password,
+            });
+            const adapter = new RabbitMQAdapter(client);
+            const tools = createRabbitMQTools(adapter);
+            return { adapter, tools };
+        }
+        case "kafka": {
+            const { KafkaClient } = await import("../kafka/client.js");
+            const { KafkaAdapter } = await import("../brokers/kafka/adapter.js");
+            const { createKafkaTools } = await import("../brokers/kafka/tools.js");
+            const client = new KafkaClient({
+                brokers: config.brokers,
+                clientId: config.clientId,
+                sasl: config.sasl,
+                ssl: config.ssl,
+            });
+            const adapter = new KafkaAdapter(client);
+            const tools = createKafkaTools(adapter);
+            return { adapter, tools };
+        }
+        default: {
+            throw new Error(`Unsupported broker: ${config.broker}`);
+        }
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/broker/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/broker/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AA8BnE,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAoB;IACtD,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;gBAChC,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;aAC1B,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;YAC5C,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;YAC3C,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5B,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;YAC3D,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,6BAA6B,CAAC,CAAC;YACrE,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;YAEvE,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC;gBAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,GAAG,EAAE,MAAM,CAAC,GAAG;aAChB,CAAC,CAAC;YACH,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;YACzC,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;YACxC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5B,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,IAAI,KAAK,CAAC,uBAAwB,MAA6B,CAAC,MAAM,EAAE,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/broker/registry.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SchemaValidator } from "../schemas/validator.js";
+import type { BrokerAdapter } from "./types.js";
+import type { ToolDefinition } from "./tool-definition.js";
+export declare function registerSchemaTools(server: McpServer, validator: SchemaValidator): void;
+export declare function registerUniversalTools(server: McpServer, adapter: BrokerAdapter, validator: SchemaValidator): void;
+export declare function registerCapabilityTools(server: McpServer, adapter: BrokerAdapter): void;
+export declare function registerBrokerTools(server: McpServer, tools: ToolDefinition[]): void;

package/dist/broker/registry.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { hasOverview, hasConsumers, hasConnections } from "./types.js";
+import { listSchemas } from "../tools/list-schemas.js";
+import { getSchema } from "../tools/get-schema.js";
+import { validateMessage } from "../tools/validate-message.js";
+import { listQueues } from "../tools/list-queues.js";
+import { getQueue } from "../tools/get-queue.js";
+import { createQueue } from "../tools/create-queue.js";
+import { deleteQueue } from "../tools/delete-queue.js";
+import { purgeQueue } from "../tools/purge-queue.js";
+import { peekMessages } from "../tools/peek-messages.js";
+import { inspectQueue } from "../tools/inspect-queue.js";
+import { publishMessage } from "../tools/publish-message.js";
+import { checkHealth } from "../tools/check-health.js";
+import { getOverview } from "../tools/get-overview.js";
+import { listConsumers } from "../tools/list-consumers.js";
+import { listConnections } from "../tools/list-connections.js";
+const jsonResponse = (data) => ({
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+});
+export function registerSchemaTools(server, validator) {
+    server.tool("list_schemas", "List all loaded message schemas", {}, async () => {
+        return jsonResponse(listSchemas(validator));
+    });
+    server.tool("get_schema", "Get the full definition of a specific schema", { name: z.string().describe("Schema name (e.g. 'order.created')") }, async ({ name }) => jsonResponse(getSchema(validator, name)));
+    server.tool("validate_message", "Validate a JSON message against a schema", {
+        schemaName: z.string().describe("Schema name to validate against"),
+        message: z.string().describe("JSON message payload to validate"),
+    }, async ({ schemaName, message }) => jsonResponse(validateMessage(validator, schemaName, message)));
+}
+export function registerUniversalTools(server, adapter, validator) {
+    server.tool("list_queues", "List all queues with message counts", {
+        vhost: z.string().default("/").describe("Virtual host / scope (default: '/')"),
+    }, async ({ vhost }) => jsonResponse(await listQueues(adapter, vhost)));
+    server.tool("get_queue", "Get detailed information about a specific queue", {
+        queue: z.string().describe("Queue name"),
+        vhost: z.string().default("/").describe("Virtual host / scope (default: '/')"),
+    }, async ({ queue, vhost }) => jsonResponse(await getQueue(adapter, vhost, queue)));
+    server.tool("create_queue", "Create a new queue. Idempotent if settings match; errors if the queue exists with different settings.", {
+        queue: z.string().describe("Queue name"),
+        durable: z.boolean().default(false).describe("Survive broker restart (default: false)"),
+        auto_delete: z.boolean().default(false).describe("Delete when last consumer disconnects (default: false)"),
+        vhost: z.string().default("/").describe("Virtual host / scope (default: '/')"),
+    }, async ({ queue, durable, auto_delete, vhost }) => jsonResponse(await createQueue(adapter, { queue, durable, auto_delete, vhost })));
+    server.tool("delete_queue", "Delete a queue.", {
+        queue: z.string().describe("Queue name"),
+        vhost: z.string().default("/").describe("Virtual host / scope (default: '/')"),
+    }, async ({ queue, vhost }) => jsonResponse(await deleteQueue(adapter, { queue, vhost })));
+    server.tool("purge_queue", "Remove all messages from a queue. Returns the number of messages purged.", {
+        queue: z.string().describe("Queue name"),
+        vhost: z.string().default("/").describe("Virtual host / scope (default: '/')"),
+    }, async ({ queue, vhost }) => jsonResponse(await purgeQueue(adapter, vhost, queue)));
+    server.tool("peek_messages", "View messages in a queue without consuming them", {
+        queue: z.string().describe("Queue name"),
+        count: z.number().int().min(1).max(50).default(5).describe("Number of messages to peek (default 5, max 50)"),
+        vhost: z.string().default("/").describe("Virtual host / scope (default: '/')"),
+    }, async ({ queue, count, vhost }) => jsonResponse(await peekMessages(adapter, vhost, queue, count)));
+    server.tool("inspect_queue", "View messages in a queue and validate each against its schema", {
+        queue: z.string().describe("Queue name"),
+        count: z.number().int().min(1).max(50).default(5).describe("Number of messages to inspect (default 5, max 50)"),
+        vhost: z.string().default("/").describe("Virtual host / scope (default: '/')"),
+    }, async ({ queue, count, vhost }) => jsonResponse(await inspectQueue(adapter, validator, vhost, queue, count)));
+    server.tool("publish_message", "Publish a message to an exchange. Optionally validates against a schema before publishing — if validation fails, the message is NOT sent.", {
+        exchange: z.string().describe("Exchange name ('amq.default' for direct-to-queue)"),
+        routing_key: z.string().describe("Routing key"),
+        payload: z.string().describe("JSON message payload"),
+        message_type: z.string().optional().describe("Message type (e.g. 'order.created'), used for schema lookup"),
+        headers: z.record(z.union([z.string(), z.number(), z.boolean(), z.null()])).optional().describe("Optional message headers"),
+        validate: z.boolean().default(true).describe("Validate before publishing (default: true)"),
+        vhost: z.string().default("/").describe("Virtual host / scope (default: '/')"),
+    }, async ({ exchange, routing_key, payload, message_type, headers, validate, vhost }) => jsonResponse(await publishMessage(adapter, validator, { exchange, routing_key, payload, message_type, headers, validate, vhost })));
+    server.tool("check_health", "Check broker health status. Returns ok or failed with reason.", {}, async () => jsonResponse(await checkHealth(adapter)));
+}
+export function registerCapabilityTools(server, adapter) {
+    if (hasOverview(adapter)) {
+        const overviewAdapter = adapter;
+        server.tool("get_overview", "Get cluster overview: version info, message rates, queue totals, and object counts.", {}, async () => jsonResponse(await getOverview(overviewAdapter)));
+    }
+    if (hasConsumers(adapter)) {
+        const consumerAdapter = adapter;
+        server.tool("list_consumers", "List all consumers connected to queues in a scope.", {
+            vhost: z.string().default("/").describe("Virtual host / scope (default: '/')"),
+        }, async ({ vhost }) => jsonResponse(await listConsumers(consumerAdapter, vhost)));
+    }
+    if (hasConnections(adapter)) {
+        const connectionAdapter = adapter;
+        server.tool("list_connections", "List all client connections to the broker.", {}, async () => jsonResponse(await listConnections(connectionAdapter)));
+    }
+}
+export function registerBrokerTools(server, tools) {
+    for (const tool of tools) {
+        server.tool(tool.name, tool.description, tool.parameters, async (args) => jsonResponse(await tool.handler(args)));
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/broker/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/broker/registry.ts"],"names":[],"mappings":"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"}

package/dist/broker/tool-definition.d.ts

@@ -0,0 +1,7 @@
+import type { z } from "zod";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, z.ZodTypeAny>;
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}

package/dist/broker/tool-definition.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-definition.js.map

package/dist/broker/tool-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-definition.js","sourceRoot":"","sources":["../../src/broker/tool-definition.ts"],"names":[],"mappings":""}

package/dist/broker/types.d.ts

@@ -0,0 +1,71 @@
+export interface BrokerQueueInfo {
+    name: string;
+    messages_ready: number | null;
+    messages_unacknowledged: number | null;
+    state: string;
+    metadata: Record<string, unknown>;
+}
+export interface BrokerMessage {
+    payload: string;
+    payload_encoding: string;
+    properties: {
+        correlation_id?: string;
+        message_id?: string;
+        type?: string;
+        timestamp?: number;
+        headers?: Record<string, unknown>;
+        content_type?: string;
+    };
+    metadata: Record<string, unknown>;
+}
+export interface BrokerHealthResult {
+    status: string;
+    reason?: string;
+}
+export interface CreateQueueParams {
+    name: string;
+    durable?: boolean;
+    auto_delete?: boolean;
+    scope?: string;
+}
+export interface CreateQueueResult {
+    name: string;
+    created: boolean;
+}
+export interface PurgeResult {
+    messagesRemoved: number;
+}
+export interface PublishParams {
+    destination: string;
+    routing_key: string;
+    payload: string;
+    properties?: Record<string, unknown>;
+    scope?: string;
+}
+export interface PublishResult {
+    published: boolean;
+    routed: boolean;
+}
+export interface BrokerAdapter {
+    listQueues(scope?: string): Promise<BrokerQueueInfo[]>;
+    getQueue(name: string, scope?: string): Promise<BrokerQueueInfo>;
+    createQueue(params: CreateQueueParams): Promise<CreateQueueResult>;
+    deleteQueue(name: string, scope?: string): Promise<void>;
+    purgeQueue(name: string, scope?: string): Promise<PurgeResult>;
+    peekMessages(queue: string, count: number, scope?: string): Promise<BrokerMessage[]>;
+    publishMessage(params: PublishParams): Promise<PublishResult>;
+    checkHealth(): Promise<BrokerHealthResult>;
+    disconnect(): Promise<void>;
+}
+export interface OverviewCapability {
+    getOverview(): Promise<Record<string, unknown>>;
+}
+export interface ConsumerCapability {
+    listConsumers(scope?: string): Promise<Record<string, unknown>[]>;
+}
+export interface ConnectionCapability {
+    listConnections(): Promise<Record<string, unknown>[]>;
+}
+export declare function hasOverview(adapter: BrokerAdapter): adapter is BrokerAdapter & OverviewCapability;
+export declare function hasConsumers(adapter: BrokerAdapter): adapter is BrokerAdapter & ConsumerCapability;
+export declare function hasConnections(adapter: BrokerAdapter): adapter is BrokerAdapter & ConnectionCapability;

package/dist/broker/types.js

@@ -0,0 +1,10 @@
+export function hasOverview(adapter) {
+    return typeof adapter.getOverview === "function";
+}
+export function hasConsumers(adapter) {
+    return typeof adapter.listConsumers === "function";
+}
+export function hasConnections(adapter) {
+    return typeof adapter.listConnections === "function";
+}
+//# sourceMappingURL=types.js.map

package/dist/broker/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/broker/types.ts"],"names":[],"mappings":"AAgFA,MAAM,UAAU,WAAW,CAAC,OAAsB;IAChD,OAAO,OAAQ,OAA8C,CAAC,WAAW,KAAK,UAAU,CAAC;AAC3F,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,OAAO,OAAQ,OAA8C,CAAC,aAAa,KAAK,UAAU,CAAC;AAC7F,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,OAAsB;IACnD,OAAO,OAAQ,OAAgD,CAAC,eAAe,KAAK,UAAU,CAAC;AACjG,CAAC"}