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

Acknowledgement modes

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.

Related MCP server: OMNI-MQTT-MCP

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