mulewatch

<div align="center">
  <img src="https://raw.githubusercontent.com/brbousnguar/mulewatch/main/docs/logo.png" width="72" alt="mulewatch" />
  <h1>mulewatch</h1>
  <p><strong>Read-only observability for MuleSoft Anypoint Platform, over MCP.</strong><br/>Application logs, historical archive search, Runtime Manager, API Manager and Exchange — for any Anypoint customer, using their own credentials.</p>

  <p>
    <img src="https://img.shields.io/badge/platform-stdio-174f3d?style=flat-square" alt="Platform" />
    <img src="https://img.shields.io/badge/MCP%20SDK-1.30-5b21b6?style=flat-square" alt="MCP SDK" />
    <img src="https://img.shields.io/badge/Node.js-20%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js" />
    <img src="https://img.shields.io/badge/MuleSoft-Anypoint%20Platform-00A2DF?style=flat-square" alt="MuleSoft Anypoint" />
    <img src="https://img.shields.io/npm/v/mulewatch?style=flat-square&color=cb3837&logo=npm&logoColor=white" alt="npm" />
    <img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License" />
  </p>
</div>

---

## What it does

mulewatch bridges an MCP client — Claude Desktop, Claude Code, Cursor, OpenClaw — to MuleSoft Anypoint Platform, so you can ask about a Mule estate in plain language and get real answers from the platform APIs. It is aimed at the person holding the pager, not the person writing the flow: no local Mule project is required, and **every tool is read-only**.

- **Application logs** from Runtime Manager, normalized across CloudHub 2.0, Runtime Fabric and legacy CloudHub.
- **Historical log search** through the Anypoint Monitoring Archive API, reaching incidents long past the live tail's rolling buffer.
- **Analysis-ready log payloads** — normalized lines plus counts by priority, logger and replica.
- **Runtime Manager inventory** across Application Manager, CloudHub and hybrid on-prem targets.
- **API Manager** instances and **Exchange** assets, so a single server answers "what is deployed, what is it fronted by, and what broke".

Nothing is hardcoded to one customer: business groups, environments and credentials all come from your own connected app.

### How this relates to the official MuleSoft MCP server

MuleSoft publishes its own MCP server ([`mulesoft-mcp-server`](https://www.npmjs.com/package/mulesoft-mcp-server), [docs](https://docs.mulesoft.com/mulesoft-mcp-server)). It is a **development** tool — it scaffolds Mule projects, generates flows and API specs, and deploys applications, largely from a local project in an IDE.

mulewatch is an **operations** tool. It never writes to your estate, it assumes no local project, and it covers the one area the official server does not address at all: **retrieving and searching application logs**, including historical logs from the Monitoring Archive. The two run happily side by side, and if you want deployment or scaffolding tools, use the official one.

## Requirements

- Node.js 20+
- An Anypoint Platform account with access to the business group you want to read
- A **connected app** (recommended) with *"acts on its own behalf"* enabled, or platform credentials
- For historical log search only: **Anypoint Monitoring enabled** for the organization

### Connected-app scopes

Grant the scopes for the surfaces you intend to use, on the business groups and environments you care about. Anypoint returns a bare `403 Forbidden` when a scope is missing; mulewatch catches that and names the scope you probably need.

| Surface | Scope |
|---|---|
| Environments, business groups | `View Environments`, `View Organization` |
| Runtime Manager apps and logs | `Read Applications` |
| Historical archive search | Anypoint Monitoring `Viewer` |
| API Manager instances | `View APIs Configuration` |
| Exchange assets | Exchange viewer access |

## Setup

Create a connected app in **Anypoint Platform → Access Management → Connected Apps**, choose *"App acts on its own behalf (client credentials)"*, grant the scopes above, and copy the client id and secret.

Configuration is environment variables only — there is no config file and no organization default.

```dotenv
ANYPOINT_CLIENT_ID=your_connected_app_client_id
ANYPOINT_CLIENT_SECRET=your_connected_app_client_secret
```

| Variable | Required | Purpose |
|---|---|---|
| `ANYPOINT_CLIENT_ID` / `ANYPOINT_CLIENT_SECRET` | one auth method | Connected app client credentials, preferred for automation |
| `ANYPOINT_USERNAME` / `ANYPOINT_PASSWORD` | one auth method | Platform login |
| `ANYPOINT_ACCESS_TOKEN` | one auth method | Pre-generated bearer token; takes precedence over the other two |
| `ANYPOINT_ORG_ID` | no | Business group id. Unset means "the organization the credentials belong to" |
| `ANYPOINT_ALLOWED_ENVIRONMENTS` | no | Comma-separated environment names or ids; when set, every tool refuses anything outside the list |
| `ANYPOINT_BASE_URL` | no | Control plane host, defaults to `https://anypoint.mulesoft.com` |
| `ANYPOINT_MONITORING_BASE_URL` | no | Monitoring host, defaults to `https://monitoring.anypoint.mulesoft.com` |

### Business groups

Environments live on **business groups**, not on the root organization. If `anypoint_list_environments` comes back empty, your credentials resolved to the root org — call `anypoint_list_business_groups` to list the ids, then pass one as `orgId` or pin it with `ANYPOINT_ORG_ID`.

### Keeping production out of reach

`ANYPOINT_ALLOWED_ENVIRONMENTS` scopes the whole server, not one tool. With

```dotenv
ANYPOINT_ALLOWED_ENVIRONMENTS=Dev,Sandbox
```

every tool refuses an environment outside the list and says why, whichever business group is targeted. Combine it with a connected app that only has access to those environments for defence in depth.

## Run

Nothing to install — point your MCP client at `npx`:

```json
{
  "mcpServers": {
    "mulewatch": {
      "command": "npx",
      "args": ["-y", "mulewatch"],
      "env": {
        "ANYPOINT_CLIENT_ID": "your_connected_app_client_id",
        "ANYPOINT_CLIENT_SECRET": "your_connected_app_client_secret"
      }
    }
  }
}
```

That block works as-is in Claude Desktop (`claude_desktop_config.json`), Cursor (`.cursor/mcp.json`) and OpenClaw. For Claude Code:

```bash
claude mcp add mulewatch --env ANYPOINT_CLIENT_ID=... --env ANYPOINT_CLIENT_SECRET=... -- npx -y mulewatch
```

From a clone instead:

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

The server speaks `stdio`, which is what MCP clients expect. Start with `anypoint_whoami` to confirm credentials, business group and scope before anything else.

---

## Tools

Every tool is read-only. All of them accept `orgId` to override the configured business group.

### `anypoint_whoami`

Confirms which credentials, business group, hosts and environment allowlist the server is running with. No arguments. Call this first when anything fails.

### `anypoint_list_business_groups`

Lists the business groups beneath the credentials' organization, with ids and nesting depth.

```json
{ "rootOrgId": "optional-root-organization-id" }
```

### `anypoint_list_environments`

Lists environments for a business group, filtered by `ANYPOINT_ALLOWED_ENVIRONMENTS` when set.

```json
{ "orgId": "your-business-group-id" }
```

### `anypoint_list_deployed_apps`

Lists deployed Mule applications for an environment, by `environmentId` or `environmentName`.

```json
{ "environmentName": "Dev", "target": "all" }
```

| Option | Purpose |
|---|---|
| `target` | `application_manager` (default), `cloudhub`, `hybrid`, or `all` |
| `limit` | Maximum records to return, default `100` |
| `includeRaw` | Include raw API objects in the response |
| `includeErrors` | Include per-target errors when a target endpoint is unavailable or not permitted |

`application_manager` covers CloudHub 2.0 and Runtime Fabric deployments, `cloudhub` legacy CloudHub, `hybrid` on-prem Runtime Manager. `all` queries every target and reports per-target failures instead of aborting.

### `anypoint_list_app_logs`

Lists the latest Runtime Manager logs for an application.

```json
{ "environmentName": "Dev", "appName": "my-mule-app" }
```

| Option | Purpose |
|---|---|
| `environmentId` | Use instead of `environmentName` |
| `deploymentId` | Use when the app name is ambiguous or already known |
| `specId` | A specific Application Manager deployment spec/config id |
| `target` | `auto` (default), `application_manager`, or `cloudhub` |
| `limit` | Maximum log entries, default `100`, max `500` |
| `offset` | Application Manager log offset, default `0` |
| `descending` | Latest first, default `true` |
| `startTime` / `endTime` | Application Manager time filter, ISO 8601 |
| `includeRaw` | Include the raw API response |
| `includeErrors` | Include failed target errors when `target` is `auto` |

For CloudHub 2.0 and Runtime Fabric the tool resolves `appName` to a deployment, resolves the current spec, then reads that spec's logs. For legacy CloudHub it calls the CloudHub logs endpoint directly.

### `anypoint_get_app_logs_for_analysis`

Same sources as above, but returns an analysis-ready payload rather than a raw list. Prefer it when diagnosing something.

```json
{ "environmentName": "Dev", "appName": "my-mule-app", "limit": 200, "errorOnly": true }
```

Takes every option of `anypoint_list_app_logs`, plus:

| Option | Purpose |
|---|---|
| `searchTerms` | Case-insensitive filters matched against timestamp, priority, message, logger, thread or instance |
| `errorOnly` | Only return `ERROR` and `FATAL` lines |

The response carries `analysis.totalFetched`, `analysis.totalMatched`, `analysis.priorityCounts`, `analysis.loggerCounts`, `analysis.instanceCounts` and `analysis.logs`. Counts describe everything fetched; `logs` holds what matched.

### `anypoint_search_archived_logs`

Searches historical logs through the **Anypoint Monitoring Archive API**, for dates beyond what the live tail can see.

This is the tool the others cannot replace. `anypoint