ballerina-activemq-mcp-server

An MCP server that automates the full setup and deployment of Ballerina + Apache ActiveMQ (OpenWire/JMS) integrations inside a WSO2 Integrator (BI) workspace — from broker validation to a runnable, BI-low-code-ready project — with minimal user interaction.

It generates code against the ballerinax/activemq connector (v0.1.0, Ballerina 2201.12.10), matching the real connector API (Client / Listener / Caller / Transaction). See INSPECTION_NOTES.md for the Phase 0 API inspection this is built on.

Tools

Tool	Purpose
mq_validate_broker	TCP reachability to the OpenWire port (+ Jolokia console destination listing).
mq_scaffold_project	Main tool. Generate a complete BI-ready Ballerina project.
mq_write_config_toml	Write/rotate the broker Config.toml.
mq_add_queue	Add a queue producer/consumer helper module.
mq_add_topic	Add a topic (pub/sub) publisher helper module.
mq_add_listener	Add a Listener service — the polling-loop carrier — with ack-mode/transaction options.
mq_set_ack_mode	Change the acknowledgement mode on a listener service (edits the @activemq:ServiceConfig).
mq_build_project	Run bal build.
mq_deploy_project	Run bal run; returns PID (+ service URL).

Acknowledgement modes

ack_mode	Ballerina enum	Needs Caller?	Semantics
auto (default)	AUTO_ACKNOWLEDGE	no	auto-ack on successful onMessage return
client	CLIENT_ACKNOWLEDGE	yes	caller->acknowledge(message)
dups-ok	DUPS_OK_ACKNOWLEDGE	no	lazy ack, possible duplicates
transacted	SESSION_TRANSACTED	yes	caller->'commit() / 'rollback()

The ack mode is a compile-time annotation field, so it lives in listener.bal (not Config.toml). mq_set_ack_mode edits the source accordingly.

Build

npm install
npm run build

Run

# stdio (default — for MCP clients that spawn the server)
npm start

# streamable HTTP, bound to 127.0.0.1
npm run start:http            # or: node dist/index.js --http --port 3000

Register with an MCP client (stdio)

{
  "mcpServers": {
    "ballerina-activemq": {
      "command": "node",
      "args": ["/absolute/path/to/ballerina-activemq-mcp-server/dist/index.js"]
    }
  }
}

What gets scaffolded

mq_scaffold_project writes a complete project under <bi_path>/<project_name>/:

Ballerina.toml · Dependencies.toml · Config.toml (+ .example, gitignored) · .gitignore
main.bal · listener.bal · transactions.bal · modules/<dest>/<dest>.bal
docker-compose.yml (apache/activemq-classic:6.2.0) · README.md

• main.bal — configurable broker settings + activemq:Client producer/consumer demo.
• listener.bal — the polling-loop carrier: a declarative service activemq:Service on mqListener per destination, ack mode baked into @activemq:ServiceConfig.
• Virtual topics — publish to topic://VirtualTopic.<name>; consume the queue Consumer.<group>.VirtualTopic.<name>.

Design notes

This is JMS/OpenWire, not Kafka. Consumer groups, offset commits, partitions, and bootstrap.servers have no analog here and are intentionally absent — reliability comes from ack modes and transacted sessions. The closest thing to a consumer group is an ActiveMQ Virtual Topic, modeled as a queue naming convention. See INSPECTION_NOTES.md for the full rejected-Kafka-patterns rationale.

License

Apache-2.0