ARTEMIS-6118 Add a Model Context Protocol (MCP) server for Artemis

[k-krawczyk]

Early WIP / proposal — not a merge candidate.
This is a reference implementation opened to make the proposal concrete and
easy to evaluate. There is no dev@ consensus yet: a [DISCUSS] thread on
dev@activemq.apache.org has not been started. The design, scope and even
whether this belongs in the main repo are open questions for that discussion,
and this PR may change substantially or be closed as a result. Please treat it
as a discussion starter rather than something to review for merge.

What

Adds a new artemis-mcp-server reactor module: a Model Context Protocol (MCP)
server that exposes broker operations as MCP tools over the STDIO transport, so
AI agents can inspect, monitor and administer an Artemis broker through a
standard protocol.

JIRA: https://issues.apache.org/jira/browse/ARTEMIS-6118

Tools (15)

Read-only (always available):
list_queues, list_addresses, get_broker_overview, get_queue_stats, browse_messages

Admin (registered only when mode=admin):
create_queue, create_address, delete_queue, delete_address, purge_queue,
delete_messages, move_messages, retry_dlq, send_message, consume_message*

(*) destructive — require confirm=true, enforced by both the tool input schema and the handler.

Design

• Read-only mode is the DEFAULT; admin tools are not registered unless mode=admin.
• Monitoring/management uses Artemis management messages to activemq.management
  (single broker connection, no open JMX required).
• Messaging uses the Core/JMS client (browse = QueueBrowser, send = producer,
  consume = consumer).
• MCP layer uses the MCP Java SDK (MIT / ASF Category A).

Testing

• 24 unit + integration tests against an embedded broker; green via mvn install.
• Builds inside the reactor; Artemis checkstyle clean.
• Verified end-to-end against an Apache Artemis broker running in Docker via real
  JSON-RPC tools/call (create/list/stats/browse/send/consume/purge/move/delete),
  including confirm-gating on destructive tools.

Open questions for dev@ (not yet discussed)

• Is an MCP server in scope for the project at all, and should it live in the main
  repo, in examples, or as a separate addon?
• New dependency footprint: the MCP Java SDK pulls in Jackson 3.x,
  json-schema-validator, snakeyaml-engine and reactor-core (all ASF Category A).
• Logging binding, docs (docs/) and a binary-distribution LICENSE/NOTICE entry
  for the MIT SDK to be settled once the direction is agreed.

[jbertram]

I'm not convinced adding a new module to the Artemis code-base is actually necessary given the availability of https://github.com/jolokia/jolokia-mcp-server. What benefits would this module have over the Jolokia solution?

[k-krawczyk]

Thanks Justin — fair question. jolokia-mcp-server is a solid generic JMX→MCP
bridge and for read-only metrics it covers a lot. A few concrete differences this
module is aiming for:

1. No Jolokia/JMX HTTP agent required. It talks to the broker via management
   messages over the normal Core/JMS acceptor, so it works against a stock broker
   with no extra endpoint, no JMX exposure, and no additional port/security
   surface to operate.

2. Messaging, not just management. It exposes send / browse / consume of actual
   messages, plus DLQ retry / move / purge with Artemis semantics. A generic JMX
   bridge (listMBeans / readAttribute / executeOperation) doesn't cover
   message-level operations.

3. A curated, safe tool surface for agents. Instead of "discover the MBean
   ObjectName and call executeMBeanOperation with the right signature", it offers
   purpose-built tools (get_broker_overview, get_queue_stats, purge_queue, …) with
   explicit JSON schemas. It's read-only by default; destructive tools are only
   registered in admin mode and require confirm=true. The generic JMX bridge
   exposes writeMBeanAttribute/executeMBeanOperation with no such guardrails.

That said, your underlying question — does this belong in the Artemis codebase? —
is exactly what I'd like the project to decide. I'm equally happy for it to live as
a separate addon (as jolokia-mcp-server does) rather than in-tree, if that's the
preference.

[jbertram]

...jolokia-mcp-server is a solid generic JMX→MCP bridge and for read-only metrics it covers a lot...

For what it's worth, it can also write MBean attributes and execute MBean operations (https://github.com/jolokia/jolokia-mcp-server#features).

...it works against a stock broker with no extra endpoint, no JMX exposure, and no additional port/security surface to operate.

A default broker starts with Jolokia listening on port 8161. The Jolokia MCP server can integrate with this, right? If so, then there's no "extra endpoint" to deal with.

A generic JMX bridge (listMBeans / readAttribute / executeOperation) doesn't cover message-level operations.

There are, in fact, management operations to send a message as well as browse messages. That's how the web console is able to offer this functionality.

Instead of "discover the MBean ObjectName and call executeMBeanOperation with the right signature", it offers
purpose-built tools (get_broker_overview, get_queue_stats, purge_queue, …) with explicit JSON schemas.

In my opinion, this tight coupling can be a weakness rather than a strength because when the management API changes those changes ripple out to other layers (like this one), increasing the maintenance burden.

...does this belong in the Artemis codebase?

At this point I'd say, "no," but I'm willing to discuss further.

[k-krawczyk]

Thanks Justin — that's all fair, and you're right on the specifics:

• the default broker does ship Jolokia on 8161, so "no extra endpoint" doesn't really hold;
• send/browse are available as management operations (as the console uses), so that isn't unique either;
• and the coupling/maintenance point is legitimate.

The piece I still think has value is a curated, safety-gated tool surface for autonomous agents — read-only by default, destructive ops behind an explicit confirm — rather than a generic execute-any-MBean-operation bridge. But I agree that doesn't need to live in the Artemis codebase. I'll take this out of tree and develop it as a standalone addon (the way jolokia-mcp-server is), and close this PR on that basis. Thanks for taking the time to look at it.