openclaw-upgrade-orchestrator-mcp
openclaw-upgrade-orchestrator-mcp
Safe-upgrade advisor for OpenClaw. Detects current version, checks the deployment against a hand-curated catalog of version-specific known regressions, captures pre-upgrade snapshots, diffs them against post-upgrade state, and emits step-by-step upgrade + rollback guides. Read-only — never executes the upgrade itself. Companion to silentwatch-mcp, openclaw-health-mcp, openclaw-cost-tracker-mcp, and openclaw-skill-vetter-mcp.
What it does
Production OpenClaw upgrades carry recurring regressions. 2026.4.8 brought a CPU-spike bug. 2026.4.23-26 broke Discord on_message. 2026.4.30+ surfaced an OOM under sustained 200k-token contexts. The pattern: an operator upgrades on Friday, hits a new failure mode on Tuesday, and spends Wednesday-Thursday excavating field reports. This MCP server moves that excavation upfront — before the upgrade, not after.
> claude: should I upgrade my 2026.4.23 deployment?
[MCP tools: current_version + available_upgrades]
Current: 2026.4.23
Recommended target: 2026.5.2 (no CRITICAL regressions in path)
Available upgrades:
2026.4.24-.26 HIGH R-73421 Discord-receive breakage
2026.4.27 — clean
2026.4.30 HIGH R-OOM-DURING-LARGE-CONTEXT (unfixed)
2026.5.1-.2 HIGH R-OOM + R-LOG-ROTATION-DROP (unfixed)> claude: walk me through upgrading to 2026.4.27.
[MCP tool: upgrade_guide]
2026.4.23 → 2026.4.27 — proceed with mitigations applied.
Applicable known regressions:
R-41372 (HIGH) — Cron --session web-search silent fail.
Mitigation: silentwatch-mcp covers detection until upgrade.
R-73421 (HIGH) — Discord-receive callbacks not firing.
Mitigation: `openclaw skill reload discord` after upgrade.
Pre-upgrade steps:
1. Capture pre-upgrade snapshot (call pre_upgrade_snapshot)
2. Verify backups: cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d)
Upgrade steps:
1. openclaw gateway stop
2. openclaw upgrade --to 2026.4.27
3. openclaw gateway start
Post-upgrade steps:
1. Run post_upgrade_verify(snapshot_id=<your-pre-upgrade-id>)
2. openclaw skill reload discord (R-73421 mitigation)
Rollback steps: stop → openclaw upgrade --to 2026.4.23 → restore backup → start.
Confidence: Path includes 2 HIGH regressions but no CRITICAL.> claude: I just upgraded. Verify it.
[MCP tool: post_upgrade_verify(pre_snapshot_id="snap-...")]
Upgrade 2026.4.23 → 2026.4.27: SUCCESS.
0 new failures, 1 recovered (skills.discord_receive_registered),
0 unchanged failures.Related MCP server: dep-diff-mcp
Why openclaw-upgrade-orchestrator-mcp
Three things existing tools (vendor changelogs, internal runbooks, generic CI/CD orchestrators) don't do:
Catalog-grounded regression awareness. A generic upgrade tool tells you the version exists. This server tells you which versions have known issues, which fix versions remediate them, and which mitigations apply if you have to use the affected version.
Pre/post snapshot diffing tied to the catalog. The same checks run before + after the upgrade. The diff highlights
new_failures(caused by the upgrade) separately fromunchanged_failures(pre-existing) andrecovered(fixed by the upgrade). No more "did this break in 2026.4.27 or was it already broken?"Read-only by design. Never runs
openclaw upgrade --to ...for you. Never modifies state. Operators retain full agency over the actual upgrade — this server gives them the information to make the decision, then verifies it after they execute.
Built for the production-AI operator who owns OpenClaw deployments and has been through enough upgrade-day fire drills.
Tool surface
Tool | What it returns |
| Currently-installed version + detection method |
| Newer versions with regression-count flags + recommended target |
| Captures every check's pass/fail state, persists with snapshot_id |
| Step-by-step plan: pre / upgrade / post / rollback steps + applicable regressions + confidence note |
| Diff post-upgrade against a stored pre-upgrade snapshot — new_failures / recovered / unchanged |
| Recovery plan for a given snapshot — downgrade command + state-restore steps + risk note |
| Full known-regression catalog, optionally filtered to one version |
| All stored snapshots (id + version + summary) |
Resources:
upgrade://current— current version infoupgrade://snapshots— every stored snapshotupgrade://catalog— full regression catalog
Prompts:
plan-upgrade(target_version)— walks through the upgrade decisionverify-upgrade(pre_snapshot_id)— walks through post-upgrade verification
Quickstart
Install
pip install openclaw-upgrade-orchestrator-mcpConfigure for Claude Desktop
{
"mcpServers": {
"openclaw-upgrade": {
"command": "python",
"args": ["-m", "openclaw_upgrade_orchestrator_mcp"],
"env": {
"OPENCLAW_UPGRADE_BACKEND": "mock"
}
}
}
}Backends
Backend | Status | Description |
| ✅ v1.0 | 2026.4.23 deployment with active R-73421 Discord-receive breakage; in-memory snapshots; suitable for protocol verification + bundle demos |
| ✅ v1.0 | Reads |
Regression catalog (v1.0)
8 hand-curated entries covering documented OpenClaw regressions:
R-41372-CRON-WEB-SEARCH-SILENT-FAIL(HIGH, 2026.4.20–2026.5.1)R-63002-POST-UPGRADE-CPU-SPIKE(CRITICAL, 2026.4.8–2026.4.10)R-73421-DISCORD-RECEIVE-BREAKAGE(HIGH, 2026.4.23–2026.4.27)R-GATEWAY-PORT-CONFLICT-2026.4.15(MEDIUM, 2026.4.15–2026.4.18)R-OOM-DURING-LARGE-CONTEXT-2026.4.30(HIGH, 2026.4.30–unfixed)R-STATUS-RECONCILIATION-DRIFT-2026.4.5(LOW, 2026.4.5–2026.4.10)R-CLAWHUB-CACHE-POISONING-2026.3.28(HIGH, 2026.3.28–2026.4.2)R-LOG-ROTATION-DROP-2026.5.1(MEDIUM, 2026.5.1–unfixed)
Use regression_catalog for the full, queryable list.
Risk-aware recommendation logic
available_upgrades flags every version reachable from current and computes a recommended_target:
For each available version V > current:
applicable_regressions = regressions_in_path(current, V)
has_known_critical = any(r.severity == CRITICAL for r in applicable_regressions)
recommended_target = highest V with has_known_critical == Falseregressions_in_path(current, target) includes a regression if:
The target version is in the regression's range (post-upgrade deployment will be affected), OR
The current version is in the regression's range (current deployment is already affected — the operator should know whether the upgrade fixes it)
OpenClaw upgrades atomically (no execution on intermediate versions), so a regression strictly between current and target without affecting either endpoint is NOT included. This avoids over-conservative recommendations.
Roadmap
Version | Scope | Status |
v1.0 | mock + openclaw-system backends, 8 tools / 3 resources / 2 prompts, 8-entry regression catalog, 6 detection checks, GitHub Actions CI matrix, PyPI Trusted Publishing | ✅ |
v1.1 | Catalog auto-fetch from upstream changelog feed; richer detection checks tied to OpenClaw's | ⏳ |
v1.2 | Custom catalog packs (operator can ship internal-only regression entries alongside the canonical catalog); rule-overrides | ⏳ |
v1.x | Webhook emit on detected regression; integration with CI to gate merges of OpenClaw-version bumps | ⏳ |
Need this adapted to your stack?
If your AI deployment uses a different runtime (custom agent harness, internal fork of OpenClaw, vendor-locked deployment) and you want the same regression-aware upgrade discipline, that's a Custom MCP Build engagement.
Tier | Scope | Investment | Timeline |
Simple | Single backend adapter for your existing version-source | $8,000–$12,000 | 1–2 weeks |
Standard | Custom backend + custom regression catalog (initial 10-15 entries from your incident history) + integration with your alerting | $15,000–$25,000 | 2–4 weeks |
Complex | Multi-deployment fleet view + auto-catalog ingestion from internal changelog + per-environment recommendation tuning | $30,000–$45,000 | 4–8 weeks |
To engage:
Email temur@pixelette.tech with subject
Custom MCP Build inquiry — upgrade orchestrationInclude: 1-paragraph description of your runtime + which tier
Reply within 2 business days with a 30-min discovery call slot
This server is part of a production-AI infrastructure MCP suite — companion to silentwatch-mcp, openclaw-health-mcp, openclaw-cost-tracker-mcp, and openclaw-skill-vetter-mcp. Install all five for full operational visibility.
Production AI audits
If you're running production AI and want an outside practitioner to score readiness, find the failure patterns already present (upgrade regression cycles being one of the most damaging), and write the corrective-action plan:
Tier | Scope | Investment | Timeline |
Audit Lite | One system, top-5 findings, written report | $1,500 | 1 week |
Audit Standard | Full audit, all 14 patterns, 5 Cs findings, 90-day follow-up | $3,000 | 2–3 weeks |
Audit + Workshop | Standard audit + 2-day team workshop + first monthly audit included | $7,500 | 3–4 weeks |
Same email channel: temur@pixelette.tech with subject AI audit inquiry.
Contributing
PRs welcome. Detection checks are pluggable — see src/openclaw_upgrade_orchestrator_mcp/checks/__init__.py for the contract.
To add a check:
Define
def run(state: DeploymentState) -> CheckResultin the checks moduleRegister it in
CHECKS: dict[str, callable]Reference its
check_idfrom a regression'sdetection_check_idincatalog.pyAdd tests in
tests/test_checks.py
To add a backend:
Subclass
UpgradeBackendinbackends/<your_backend>.pyImplement
collect_state,save_snapshot,load_snapshot,list_snapshotsRegister in
backends/__init__.pyAdd tests in
tests/test_backends.py
To add a regression entry:
Append to
CATALOGincatalog.pywith stableregression_idReference an existing or new
detection_check_id(or set to None for advisory-only)Add a test confirming version-range membership in
tests/test_catalog.py
Bug reports + feature requests: open a GitHub issue.
License
MIT — see LICENSE.
Related
silentwatch-mcp — cron silent-failure detection
openclaw-health-mcp — deployment health
openclaw-cost-tracker-mcp — token-cost telemetry
openclaw-skill-vetter-mcp — skill security vetting
AI Production Discipline Framework — Notion template, $29 — methodology these MCPs implement
SPEC.md — full server design
Built by Temur Khan — independent practitioner on production AI systems. Contact: temur@pixelette.tech
Available Tools
8 toolsavailable_upgradesA
List newer-than-current versions, flag any that carry CRITICAL regressions, and recommend the highest version with no CRITICAL regressions in its upgrade path.
Inputs: no named parameters.
current_versionA
Return the currently-installed OpenClaw version + how it was detected. Run this first to confirm the backend can read your deployment.
Inputs: no named parameters.
list_snapshotsA
List all stored snapshots (id, captured_at, version, summary).
Inputs: no named parameters.
post_upgrade_verifyA
Take a fresh post-upgrade snapshot and diff against a stored pre-upgrade snapshot. Surfaces new_failures (most important), recovered checks, and unchanged failures. Outcome is one of 'success' / 'degraded' / 'regressed'.
Inputs: pre_snapshot_id (required).
pre_upgrade_snapshotA
Run every detection check against the live deployment and persist the result as a Snapshot. Returns the snapshot_id you'll feed to post_upgrade_verify and rollback_guide.
Inputs: target_version.
regression_catalogA
Return every known regression in the catalog, optionally filtered to a specific version. Each entry has id + version range + severity + description + mitigation + linked field reports.
Inputs: filter_version.
rollback_guideA
Compose the rollback plan for a given pre-upgrade snapshot — downgrade command + state-restore steps + risk notes about data migration loss.
Inputs: snapshot_id (required).
upgrade_guideA
Compose the step-by-step upgrade plan from current → target. Includes pre-upgrade prep steps, the upgrade itself, post-upgrade verification, rollback steps, and any applicable known regressions with their mitigations.
Inputs: target_version (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct aspect of the upgrade workflow: version discovery, upgrade listing, snapshot management, pre/post verification, regression info, and plan generation. No two tools have overlapping purposes, ensuring clear selection.
All tool names follow consistent snake_case and are descriptive (e.g., available_upgrades, pre_upgrade_snapshot, rollback_guide). The pattern is predictable and clearly communicates each tool's function.
With 8 tools, the server covers the core upgrade orchestrator workflow without being bloated. Each tool serves a necessary role, making the set well-scoped for its domain.
The tool set covers most essential operations: version detection, upgrade listing, pre/post snapshots, verification, rollback, and regression catalog. The only minor gap is the lack of a tool to actually execute the upgrade, but the upgrade_guide provides step-by-step instructions.
Related MCP Connectors
Check PyPI and npm upgrades: known vulnerabilities, the safe version, and what each upgrade breaks.
Check exact npm/PyPI upgrades for evidence-backed breaking changes; query APIs and components.
Detect breaking changes, generate changelogs, diff, and validate OpenAPI specs.
MCP deployment checks: required tools, schema drift and verifiable receipts. Free preflight.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceScans OpenClaw/ClawHub skills for security vulnerabilities before installation. Detects prompt injection, data exfiltration, credential theft and RCE risks. Autonomous AI-to-AI flow with zero human intervention required.-
- AlicenseAqualityBmaintenanceTranslates a lockfile diff into a human-readable upgrade plan. For every dependency bump (npm or PyPI) returns semver class, breaking changes from GitHub release notes, CVEs fixed in the range, migration guide links, and a clear per-package recommendation. Bulk tool ranks up to 50 package changes in parallel by risk (security > caution > review > likely-safe > safe).258 npm2MIT
- AlicenseNot gradedqualityDmaintenanceProvides Kubernetes deployment intelligence with typed query tools and AI-synthesized risk briefs, enabling users to list workloads, get detailed snapshots, query Prometheus metrics, record deployment history, and generate risk assessments before promoting to production.Apache 2.0
- AlicenseAqualityCmaintenanceStatic scanner for MCP/agent-gateway readiness anti-patterns, providing a 7-dimension R/Y/G score by scanning code and config for common failure modes.152 npm2MIT