PlatformUp2Date

mcp
Security Audit
Fail
Health Warn
  • License — License: Apache-2.0
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Fail
  • rm -rf — Recursive force deletion command in ci/check-backend-build-version.sh
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Monitors your running application for version drift against the latest upstream release. Integrates with Prometheus, Grafana and MCP

README.md

PlatformUp2Date logo PlatformUp2Date

edge
release
license

You run a platform, a home lab or just a pile of apps. They're all out of date... let's change that!

If an app exposes its version anywhere (an HTTP endpoint, a container image
tag, ssh/os-release, or even a Prometheus metric), its
version drift can be monitored.

PlatformUp2Date monitors deployed applications against their latest upstream
releases and shows, per app, whether it's up-to-date or behind. "Current" is
always as close as we can get to the app's actually-observed running state, never a declared value
like a GitOps repo pin. "Latest" comes from an independent upstream source
such as GitHub Releases or a container registry's tag list. (See
ARCHITECTURE.md about how we reason here.)

Monitor version drift for

  • Kubernetes deployments
  • Docker Compose images
  • VMs
  • Bare-metal machines
  • OpenWrt routers
  • Random services you have no control over, purely to demonstrate your superiority at staying on top of things
  • Coffee makers?

It integrates with Prometheus/Grafana and ships its own frontend — deploy it
or don't :) It also serves an MCP endpoint, so an AI agent
can ask what's outdated and read the changelogs while helping you upgrade.

The board: every monitored app with its current and latest version, color-coded by drift status

Quick taste (no toolchain required)

All you need is Docker:

git clone https://github.com/sreyardship/PlatformUp2Date.git
cd PlatformUp2Date
docker compose -f compose.quickstart.yml up

Then open localhost:3000. You
should see three application rows:

  • mastodon current is read from the public
    chaos.social instance's API (an observed running
    version, not a repo pin); latest comes from GitHub Releases.
    chaos.social upgrades conservatively, so this card is usually behind,
    showing what drift detection looks like: a red/orange card with the
    current and latest versions side by side, and a changelog link to the
    release it's missing.
  • gitea current is read from the public
    gitea.com SaaS instance's version API; latest comes
    from Gitea's official image tags on Docker Hub. gitea.com tracks upstream
    closely, so this card is usually green (up to date).
  • demo-always-behind is not a live service: current is read from a
    fixture file in this repo (docs/demo-current.json,
    pinned to Prometheus 2.53.0) and latest comes from Prometheus's GitHub
    Releases (3.x). This card is always behind by a major version, so the
    quickstart shows a drift card even on a day when both live services above
    happen to be current. Delete it when you add your own apps.

The first two are live third-party services, so their colors on any given day
depend on what they happen to be running. None of the three needs credentials.

Monitor your own apps

The quickstart mounts the sample config,
deploy/k8s/base/platform-config.yaml,
into the backend. Add an entry under apps: and restart to watch something
of your own:

    - name: my-app
      changelog-url: https://github.com/me/my-app/releases/tag/v{version}
      current:
        type: http-json             # ask the running instance itself
        url: https://my-app.example.com/api/version
      latest:
        type: github-release
        repo: me/my-app

current and latest are independent, pluggable sources. Every source type
(http-json, http-header, http-prometheus, k8s-image, ssh-os-release,
github-release, oci-registry, http-regex) and every key is documented in
docs/configuration.md.

Documentation

  • docs/configuration.md — every version-source
    type, every config key, version schemes, changelog-link templates.
  • docs/deployment.md — running this for real:
    Kubernetes (the primary target, though any OCI runtime works), HA and
    replicas, Valkey, RBAC for the k8s-image source, Prometheus scraping,
    alert rules, the Grafana dashboard.
  • RELEASE.md — image channels (edge, sha-<short>, semver),
    what each CI trigger publishes, and how a release is cut.
  • ARCHITECTURE.md — the design principles behind the
    substrate-agnostic version-source model.
  • CONTEXT.md — glossary of project-specific terms.
  • docs/adr/ — architecture decision records for individual
    design choices.

Metrics & Alerting

The backend exposes a Prometheus scrape endpoint at /metrics. Six metric families are exported:
pu2d_version_drift_level, pu2d_application_info, pu2d_scrape_last_success_timestamp_seconds,
pu2d_scrape_last_failure_timestamp_seconds, pu2d_config_error and pu2d_config_unnamed_apps
— see docs/deployment.md for the full list. The core one for version monitoring is a gauge:

# HELP pu2d_version_drift_level How far the deployed version is behind latest (0=current, 1=patch, 2=minor, 3=major)
# TYPE pu2d_version_drift_level gauge
pu2d_version_drift_level{app="argo-cd"} 3
pu2d_version_drift_level{app="git-tea"} 0

One gauge answers both questions: whether an app is outdated, and how far
behind it is. The value is the highest-significance difference between the
deployed and latest version; calver apps (e.g. Ubuntu's 24.04) report on
the same scale, graded by what the changed token means, and dotnet apps (e.g.
Sonarr's 4.0.20.3014) grade by changed component. The full grading rules
(pre-releases, build metadata, calver token classes, the dotnet revision) are in
docs/deployment.md and
docs/configuration.md.
pu2d_application_info carries the actual current/latest version strings and
covers every configured app, including ones that haven't resolved yet.

For more detail than the gauges carry, use the frontend or the
GET /api/v1/version endpoint. For scraping setup, example alert rules, and
the bundled Grafana dashboard on a k8s cluster, see
docs/deployment.md.

The bundled Grafana dashboard: fleet stats and a per-app drift table

MCP endpoint

The backend exposes a Model Context Protocol server
so an AI agent can ask "which monitored applications are out of date, how far behind,
and what changed between the versions?" without any custom integration. It is a third
read surface over the same data as /metrics and GET /api/v1/version: any
MCP-capable host can connect and discover the tools at runtime.

Transport is Streamable HTTP, served at /api/mcp on the backend's HTTP port. It runs
stateless (each request auto-initialises its own throwaway session), so the endpoint works
behind multiple replicas with no session affinity.

Tools

  • list_outdated_applications(minSeverity?) returns the applications running behind
    their latest upstream release, each as
    { name, current, latest, outdated, drift, changelogUrl, … } where drift is
    PATCH / MINOR / MAJOR. The optional minSeverity argument
    (PATCH | MINOR | MAJOR) filters by how far behind an app is; omit it to get every
    app with any drift.
  • get_application(name) returns the status of a single application by exact name,
    or a tool error if it isn't monitored.
  • list_applications_with_failed_scrapes() returns applications whose most recent
    scrape of either the current or latest side failed. It excludes sides that have never
    been attempted; a failed scrape describes the read, not the health of the application.
  • list_misconfigured_applications() returns recorded configuration defects as
    { application, scope, message } entries. The scope is CURRENT, LATEST, APP, or
    CHANGELOG; this is distinct from a transient failed scrape.
  • trigger_scrape(): requests an immediate full scrape. It returns scrape telemetry,
    including an outcome of SCRAPED, RATE_LIMITED, or IN_PROGRESS, rather than
    application versions.
  • scrape_applications(targets) requests a targeted scrape for a list of
    { name, side } entries, where side is current, latest, or both. It uses a
    separate targeted-scrape budget and returns per-target results when the scrape runs.

changelogUrl links the release notes of the latest upstream release (if the app has a
changelog-link template configured,
null otherwise), so an agent can read what changed (breaking changes included) before
starting update work.

The drift verdict is computed server-side by the same tested semver logic that backs the
metrics gauge, so the caller never has to compare versions itself.

Connecting a client

Point any MCP client that supports remote Streamable HTTP servers at:

https://platformup2date.example.com/api/mcp

Most MCP-capable CLIs have a built-in subcommand for registering a remote HTTP
server (consult your client's docs); the shape is generally
<your-mcp-client> mcp add --transport http platformup2date <url>.

Authentication

Every surface is open by default; protection is opt-in. The backend can act
as an OAuth 2.1 resource server against one shared OIDC issuer, with the MCP
endpoint (/api/mcp) and the web UI + REST API (/api/v1) each gated
independently by its own role:

OIDC_ISSUER=https://auth.example.com/realms/yourrealm
OIDC_AUDIENCE=platformup2date
MCP_OIDC_ROLE=pu2d-mcp   # gates /api/mcp
WEB_OIDC_ROLE=pu2d-web   # gates /api/v1, and thereby the web UI

An MCP client that supports the MCP authorization spec discovers the issuer
from the endpoint's RFC 9728 protected-resource metadata and logs in
natively, with no bearer token to fetch or attach by hand. For the web UI,
the React SPA itself becomes an OIDC client (Authorization Code + PKCE) via
two frontend variables, OIDC_AUTHORITY and OIDC_CLIENT_ID. /metrics
and /q/health are never gated.

The full contract (variable semantics, boot-failure rules, what each gate
does and doesn't cover) is in
docs/configuration.md;
the cluster-level consequences (MCP's one extra ingress rule, IdP
prerequisites, edge-proxy interactions, dev-mode CORS) are in
docs/deployment.md.

Contributing

See CONTRIBUTING.md

Reviews (0)

No results found