# 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`](./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

```bash
npm install
npm run build
```

## Run

```bash
# 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)

```json
{
  "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