mulewatch

---

功能

mulewatch 将 MCP 客户端——Claude Desktop、Claude Code、Cursor、OpenClaw——连接到 MuleSoft Anypoint Platform，让你可以用通俗语言询问 Mule 环境的情况，并从平台 API 获取真实答案。它面向的是值班人员，而不是编写流程的人员：无需本地 Mule 项目，且所有工具均为只读。

• 应用日志来自 Runtime Manager，并统一了 CloudHub 2.0、Runtime Fabric 和旧版 CloudHub 的日志格式。
• 通过 Anypoint Monitoring Archive API 搜索历史日志，查找早已超出实时日志滚动缓冲区的事件。
• 适用于分析的日志负载——标准化日志行，以及按优先级、日志记录器和副本统计的数量。
• 涵盖 Application Manager、CloudHub 和混合式本地部署目标的 Runtime Manager 清单。
• API Manager 实例和 Exchange 资产，让单个服务即可回答“部署了什么、由什么提供入口，以及出了什么问题”。

所有内容都不会针对单一客户进行硬编码：业务组、环境和凭据均来自你自己的已连接应用。

与 MuleSoft 官方 MCP 服务的关系

MuleSoft 发布了自己的 MCP 服务（mulesoft-mcp-server，文档）。它是一款开发工具——主要在 IDE 的本地项目中搭建 Mule 项目、生成流程和 API 规范，并部署应用。

mulewatch 是一款运维工具。它不会对你的环境进行写入，不要求本地项目，并且涵盖了官方服务完全未涉及的领域：获取和搜索应用日志，包括 Monitoring Archive 中的历史日志。两者可以轻松并行运行；如果你需要部署或项目搭建工具，请使用官方服务。

要求

• Node.js 20+
• Anypoint Platform 账户，并有权访问要读取的业务组
• 已连接应用（推荐），并启用 “以自身名义执行操作”，或使用平台凭据
• 仅用于搜索历史日志：组织已启用 Anypoint Monitoring

已连接应用的范围

为计划使用的界面授予相应范围，并限定在需要的业务组和环境中。如果缺少范围，Anypoint 会返回一个不附带说明的 403 Forbidden；mulewatch 会捕获该错误，并指出你可能需要的范围。

界面	范围
环境、业务组	View Environments、View Organization
Runtime Manager 应用和日志	Read Applications
历史存档搜索	Anypoint Monitoring Viewer
API Manager 实例	View APIs Configuration
Exchange 资产	Exchange 查看者访问权限

设置

在 Anypoint Platform → Access Management → Connected Apps 中创建一个已连接应用，选择 "App acts on its own behalf (client credentials)"，授予上述范围，并复制客户端 ID 和密钥。

配置仅通过环境变量完成——没有配置文件，也没有默认组织。

ANYPOINT_CLIENT_ID=your_connected_app_client_id
ANYPOINT_CLIENT_SECRET=your_connected_app_client_secret

变量	必需	用途
ANYPOINT_CLIENT_ID / ANYPOINT_CLIENT_SECRET	一种身份验证方式	已连接应用客户端凭据，自动化场景首选
ANYPOINT_USERNAME / ANYPOINT_PASSWORD	一种身份验证方式	Platform 登录
ANYPOINT_ACCESS_TOKEN	一种身份验证方式	预先生成的 bearer token；优先于另外两种方式
ANYPOINT_ORG_ID	否	业务组 ID。未设置时，使用“凭据所属的组织”
ANYPOINT_ALLOWED_ENVIRONMENTS	否	以逗号分隔的环境名称或 ID；设置后，所有工具都会拒绝访问列表之外的环境
ANYPOINT_BASE_URL	否	控制平面主机，默认为 https://anypoint.mulesoft.com
ANYPOINT_MONITORING_BASE_URL	否	Monitoring 主机，默认为 https://monitoring.anypoint.mulesoft.com

业务组

环境属于业务组，而非根组织。如果 anypoint_list_environments 返回空列表，说明凭据解析到了根组织——调用 anypoint_list_business_groups 列出 ID，然后将其中一个传入 orgId，或通过 ANYPOINT_ORG_ID 固定指定。

限制对生产环境的访问

ANYPOINT_ALLOWED_ENVIRONMENTS 限制的是整个服务，而非单个工具。设置为

ANYPOINT_ALLOWED_ENVIRONMENTS=Dev,Sandbox

后，无论目标业务组是什么，所有工具都会拒绝访问列表之外的环境，并说明原因。为加强纵深防御，可同时使用仅能访问这些环境的已连接应用。

运行

无需安装——将 MCP 客户端指向 npx：

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

该代码块可直接用于 Claude Desktop（claude_desktop_config.json）、Cursor（.cursor/mcp.json）和 OpenClaw。Claude Code 的配置如下：

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

也可以从克隆的仓库运行：

npm install
npm run build
npm start

该服务使用 stdio 通信，这是 MCP 客户端所需的方式。首先调用 anypoint_whoami，确认凭据、业务组和范围，然后再进行其他操作。

---

工具

所有工具均为只读。每个工具都接受 orgId，用于覆盖已配置的业务组。

anypoint_whoami

确认服务正在使用的凭据、业务组、主机和环境允许列表。无需参数。遇到任何故障时，请先调用此工具。

anypoint_list_business_groups

列出凭据所属组织下的业务组及其 ID 和嵌套深度。

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

anypoint_list_environments

列出某个业务组的环境；设置了 ANYPOINT_ALLOWED_ENVIRONMENTS 时，会按该变量进行筛选。

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

anypoint_list_deployed_apps

按 environmentId 或 environmentName 列出某个环境中已部署的 Mule 应用。

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

选项	用途
target	application_manager（默认）、cloudhub、hybrid 或 all
limit	返回的最大记录数，默认为 100
includeRaw	在响应中包含原始 API 对象
includeErrors	目标端点不可用或无访问权限时，包含各目标的错误信息

application_manager 涵盖 CloudHub 2.0 和 Runtime Fabric 部署，cloudhub 指旧版 CloudHub，hybrid 指本地 Runtime Manager。all 会查询所有目标，并报告各目标的失败情况，而不是中止查询。

anypoint_list_app_logs

列出应用在 Runtime Manager 中的最新日志。

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

选项	用途
environmentId	用于替代 environmentName
deploymentId	当应用名称不明确或已知时使用
specId	特定的 Application Manager 部署规范／配置 ID
target	auto（默认）、application_manager 或 cloudhub
limit	最大日志条目数，默认为 100，上限为 500
offset	Application Manager 日志偏移量，默认为 0
descending	是否按最新优先排列，默认为 true
startTime / endTime	Application Manager 时间筛选条件，采用 ISO 8601 格式
includeRaw	包含原始 API 响应
includeErrors	当 target 为 auto 时，包含失败目标的错误信息

对于 CloudHub 2.0 和 Runtime Fabric，该工具会将 appName 解析为部署，解析当前规范，然后读取该规范的日志。对于旧版 CloudHub，该工具会直接调用 CloudHub 日志端点。

anypoint_get_app_logs_for_analysis

数据源与上文相同，但返回适用于分析的负载，而不是原始列表。诊断问题时优先使用此工具。

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

支持 anypoint_list_app_logs 的所有选项，此外还有：

选项	用途
searchTerms	不区分大小写的筛选词，与时间戳、优先级、消息、日志记录器、线程或实例进行匹配
errorOnly	仅返回 ERROR 和 FATAL 行

响应中包含 analysis.totalFetched、analysis.totalMatched、analysis.priorityCounts、analysis.loggerCounts、analysis.instanceCounts 和 analysis.logs。计数描述所有已获取的内容；logs 包含匹配的内容。

anypoint_search_archived_logs

通过 Anypoint Monitoring Archive API 搜索历史日志，适用于实时日志流无法查看的日期。

这是其他工具无法替代的工具。anypoint_list_app_logs 和 anypoint_get_app_logs_for_analysis 读取的是 Runtime Manager 的实时日志流——这是一个较小的滚动缓冲区，在繁忙的应用中，几分钟内就可能滚动过去，无论你传入什么 startTime/endTime。每个十分钟时间窗口结束后约十分钟，归档中就会存入相应文件，并且这些文件会保留更长时间。

要求组织已启用 Anypoint Monitoring。 未启用时，每次调用都会返回 403 或 404；请改用 Runtime Manager UI 手动导出 Download Logs。

{
  "environmentName": "Prod",
  "appName": "my-mule-app",
  "date": "2026-08-09",
  "searchTerms": ["Started product import", "Import finished"]
}

选项	用途
date	必填，YYYY-MM-DD（UTC）
endDate	可选的包含式范围结束日期，YYYY-MM-DD（UTC），总范围最多 7 天
searchTerms	不区分大小写的文本筛选条件
errorOnly	仅返回 ERROR 和 FATAL 行
maxEntities	全量扫描回退期间探测的副本实体上限，默认值为 150，最大值为 300
maxFiles	下载并解析的归档文件上限，默认值为 100，最大值为 500
limit	返回的匹配行数上限，默认值为 500，最大值为 2000
includeRaw	在规范化字段旁包含解析后的原始条目

查找日志的方式。 Archive API 按副本／Pod（{appName}_{replicaId}）而非应用建立索引，因此必须先确定副本，才能读取日志。mulewatch 会先尝试 Runtime Manager 实时日志流中可见的副本 ID（entityResolution: "live-replica"）——Pod 通常在重新部署前会长期运行，因此近期过去日期的日志通常也由同一副本生成，一般只需调用几次归档 API。如果该副本在请求日期没有文件（例如应用此后已重新部署），则会回退到列出该应用曾使用过的所有副本并逐一探测（entityResolution: "full-scan"），探测范围受 maxEntities 限制。

Archive API 的请求限额为每分钟 60 次；客户端会将请求速率控制在该限额以下，并在收到 429 时退避。跨多个副本进行全量扫描回退可能需要一些时间，因此请尽可能缩小日期范围。响应会说明采用了哪种路径，以及结果是否因达到上限而被截断。

anypoint_list_api_manager_instances

列出环境中由 API Manager 管理的 API 实例。

{ "environmentName": "Dev", "assetId": "my-api" }

选项	用途
assetId	按 Exchange 资产 ID 筛选
technology	按技术筛选，例如 mule4、flexGateway
limit / offset	分页，默认值分别为 100 / 0
includeRaw	包含原始 API 对象

anypoint_search_exchange_assets

搜索组织中的 Anypoint Exchange 资产。

{ "search": "customer", "types": ["rest-api"], "limit": 20 }

选项	用途
search	在资产名称和描述中进行自由文本搜索
types	按资产类型筛选，例如 rest-api、connector、template、example
limit / offset	分页，默认值分别为 50 / 0
includeRaw	包含原始 API 对象

---

技术栈

层	技术
运行时	Node.js 20+，ES 模块
语言	TypeScript 5.7，启用 strict，编译到 dist/
协议	Model Context Protocol SDK 1.30，stdio 传输
验证	zod 4
身份验证	Anypoint client_credentials 令牌流程、用户名／密码或 bearer 令牌
测试	node:test，无运行器依赖

仓库结构

.
├── src/
│   ├── index.ts          # bin entry: config check, stdio wiring
│   ├── tools.ts          # MCP tool registration and argument schemas
│   ├── client.ts         # AnypointClient: auth, org resolution, all API calls
│   ├── config.ts         # env-var config, environment allowlist
│   ├── normalize.ts      # envelope unwrapping, log normalization, analysis
│   ├── archive-parse.ts  # archive log line parsing, date range enumeration
│   └── errors.ts         # AnypointApiError and message formatting
├── test/                 # unit tests for the pure logic
├── docs/
│   ├── logo.png          # project mark, used in this README
│   └── og-image.png      # social preview card
├── server.json           # MCP registry manifest
├── PRICING.md            # positioning notes
└── .env.example

验证状态

开发期间，已针对一个正在运行的 Anypoint 组织测试读取路径：

工具	状态
anypoint_whoami	已在线验证
anypoint_list_business_groups	已在线验证
anypoint_list_environments	已在线验证
anypoint_list_deployed_apps	已在线验证（application_manager；未测试 cloudhub/hybrid 目标）
anypoint_list_app_logs	已在线验证（Application Manager 路径）
anypoint_get_app_logs_for_analysis	已在线验证（Application Manager 路径）
anypoint_search_exchange_assets	已在线验证
anypoint_search_archived_logs	已在线验证——live-replica 快速路径和 full-scan 回退路径均已验证
anypoint_list_api_manager_instances	未验证——测试用的已连接应用缺少 View APIs Configuration 范围，因此调用返回了 403

在此次检查所用的应用中，归档存有 669 个历史副本实体。搜索当天的数据时，通过实时副本快速路径处理，仅探测了其中 1 个，找到 127 个归档文件并解析了 2,859 行日志。搜索上次重新部署之前日期的数据时，则正确地回退到完整扫描路径；这是较慢的情况，设置 maxEntities 上限正是为了限制这种情况。

备注

• 所有工具均为只读。按设计，不提供部署、停止、重启或修改策略的工具——LLM 不应修改生产 Mule 环境，而且 MuleSoft 官方服务已涵盖部署功能。
• 令牌会缓存在内存中，直到过期前一分钟，绝不会写入磁盘。
• 仅从环境中读取凭据；不会记录任何信息。
• 缺少已连接应用范围时，Anypoint 会直接返回 403。系统会捕获这些错误，并注明可能缺少的范围。
• 通过覆盖 ANYPOINT_BASE_URL 和 ANYPOINT_MONITORING_BASE_URL，即可使用 EU 及其他控制平面。

许可证

Apache-2.0。MuleSoft、Anypoint Platform 和 CloudHub 是 Salesforce, Inc. 的商标；本项目为独立项目，与 Salesforce 无关，也未获得 Salesforce 的认可。

---