Skip to main content
Glama
headleymonitor-ux

durable-web-monitor-mcp

by headleymonitor-ux
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

durable-web-monitor-mcp

A small, security-conscious reference implementation for durable website-change monitoring with MCP.

It demonstrates a pattern that is useful for long-running assistants and automations:

baseline → detect → notify → acknowledge → durable inbox

The monitor supports two fetch modes:

  • direct HTTPS for ordinary pages;

  • isolated Playwright MCP for pages that need browser rendering.

Each browser fetch launches a fresh, non-persistent Playwright MCP subprocess with --isolated, then tears it down after the snapshot.

Why this exists

A reliable page monitor needs more than "fetch URL and compare strings". It should:

  • avoid alerting on the first observation;

  • normalize content before hashing;

  • persist baseline state across process restarts;

  • keep notifications until they are acknowledged;

  • separate "delivered" notifications from "reviewed" state;

  • use a disposable browser session for dynamic pages;

  • reject obviously unsafe network targets before fetching;

  • make the monitoring state inspectable through MCP.

This repository is deliberately generic. It does not contain private infrastructure, credentials, account identifiers, internal hostnames, or environment-specific deployment configuration.

Related MCP server: Doc Monitor MCP

Security model

This project is a reference implementation, not a network sandbox.

It rejects non-HTTPS URLs and hostnames that resolve to loopback, private, link-local, multicast, reserved, or unspecified IP addresses. Redirect targets are revalidated in the direct HTTP adapter.

Application-level URL checks cannot completely eliminate DNS rebinding or browser redirect risk. For untrusted URLs, run the monitor in a container/VM with restrictive egress rules and no access to metadata services or private networks. See SECURITY.md.

The browser adapter uses Playwright MCP's --sandbox and --isolated modes. Isolation prevents normal browser profile persistence between checks; neither option makes Playwright MCP a complete security boundary.

Requirements

  • Python 3.10+

  • Node.js 18+ and npx only if you use the browser adapter

  • mcp>=2,<3

  • Chromium available either through the pinned Playwright build or as a trusted system executable

Install

python -m venv .venv
source .venv/bin/activate
pip install -e .

The package installs two commands:

  • dwm — CLI for checks and notification handling;

  • dwm-mcp — stdio MCP server.

For the default browser-backed setup, install Chromium once for the Playwright build used by Playwright MCP v0.0.80:

npx -y playwright@1.63.0-alpha-2026-08-31 install chromium

If your deployment manages Chromium separately, point the monitor at that trusted executable instead:

export DWM_BROWSER_EXECUTABLE_PATH=/path/to/chromium

When this variable is set, the browser adapter passes that path to Playwright MCP with --executable-path. The package never hard-codes a host-specific Chromium location.

Run as an MCP server

dwm-mcp

This starts the bundled MCP server over stdio without requiring the optional MCP SDK CLI extra.

The server exposes:

  • check_url

  • list_notifications

  • mark_notifications_reviewed

  • monitor_status

The SQLite database defaults to:

~/.local/share/durable-web-monitor-mcp/state.sqlite3

Override it with DWM_STATE_PATH.

Example MCP flow

  1. Call check_url with a stable monitor name and URL.

  2. The first successful check stores a baseline and emits no notification.

  3. Later content changes create durable notifications.

  4. Call list_notifications(status="new").

  5. After successfully presenting those notifications to the user, call mark_notifications_reviewed(through_seq=...).

That last step matters: reading the inbox does not itself advance the review cursor.

Direct HTTPS example

{
  "name": "example-docs",
  "url": "https://example.com/docs",
  "adapter": "direct",
  "watch_terms": []
}

An empty watch_terms list means any normalized content change is noteworthy.

Browser example

{
  "name": "dynamic-status",
  "url": "https://example.com/status",
  "adapter": "browser",
  "target": "body",
  "watch_terms": ["incident", "degraded"]
}

v0.1.0 deliberately pins the browser integration to the version tested for this release:

npx -y @playwright/mcp@0.0.80 --headless --sandbox --isolated --browser chromium --image-responses omit --codegen none

If DWM_BROWSER_EXECUTABLE_PATH is set, --executable-path <value> is added to that command.

Playwright accessibility snapshots contain generated locator references such as [ref=e17]. The monitor removes those ephemeral references before hashing so locator churn does not create false change alerts.

Do not silently switch the package to @latest in production. Upgrade the pinned Playwright MCP and matching Playwright browser build deliberately, reinstall the browser binary if needed, and rerun the unit and browser integration tests first.

CLI

The same engine can be driven by cron, systemd timers, CI, or another scheduler:

dwm check \
  --name example-docs \
  --url https://example.com/docs \
  --adapter direct

dwm inbox --status new
dwm ack --through-seq 12

A scheduler is intentionally outside this package. Keeping scheduling separate makes the monitor usable with cron, systemd timers, GitHub Actions, container schedulers, or an agent platform without coupling the durable monitoring model to one runtime.

Normalization

Direct HTML fetches are reduced to visible text with scripts/styles/comments removed, HTML entities decoded, and whitespace collapsed.

Browser snapshots are normalized as text by removing generated Playwright locator references, trimming line endings, collapsing horizontal whitespace, and removing repeated blank lines.

The normalized text is SHA-256 hashed. The database stores hashes and bounded excerpts rather than complete page bodies.

Testing

Core tests use only the Python standard library:

python -m unittest discover -s tests -v

The Playwright MCP browser adapter is intentionally an integration boundary and is not launched by the unit tests.

Before publishing a release, also test installation in a fresh virtual environment, start the installed dwm-mcp entry point, and run real direct-HTTPS and isolated-browser checks against non-sensitive public pages. If using a system Chromium deployment, run the browser test with the same DWM_BROWSER_EXECUTABLE_PATH that production will use.

Design notes

See docs/ARCHITECTURE.md for the state machine, notification cursor model, browser-isolation rationale, and known limits.

License

Apache-2.0. See LICENSE.

Available Tools

4 tools
check_urlC

Fetch one public HTTPS page and update its durable baseline.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
nameYes
targetNobody
adapterNodirect
watch_termsNo

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does disclose two real traits: the fetch is outbound to a *public HTTPS* page (a network + reachability constraint) and the call mutates persistent state ('update its durable baseline'), so an agent knows it is not read-only. It stops there, saying nothing about permissions, what happens to the prior baseline, rate limits, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler or redundancy; the action and the state change come first. It is efficient, though the extreme terseness borders on under-specification rather than crispness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter mutation tool with no annotations, no output schema, and no schema descriptions, one sentence is not enough. The agent cannot determine what target, adapter, or watch_terms do, what 'baseline' means, or what the call returns or changes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Five parameters at 0% schema description coverage, and the description names none of them. 'Fetch one public HTTPS page' weakly constrains url, and 'durable baseline' hints at name, but target, adapter, and watch_terms are entirely opaque in both description and schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb pair (fetch + update) and resource (a public HTTPS page / its durable baseline), which is more specific than the sibling names list_notifications or mark_notifications_reviewed. The term 'durable baseline' is internal jargon that isn't defined, so the purpose is clear in shape but not fully in meaning, and it doesn't explicitly differentiate itself from monitor_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, when-not-to-use, or alternative routing is given. With a sibling like monitor_status clearly adjacent in function, the description should say how check_url relates to it, but it offers nothing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_notificationsB

List durable notifications without advancing the review cursor.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
statusNonew

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It usefully discloses that the review cursor is not advanced, which is a key non-mutating behavior. However, it omits other relevant traits such as read-only safety, idempotency, and how defaults/status filtering affect results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with zero waste, front-loading the action and the key behavioral constraint. It is appropriately sized for a simple list tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two undocumented parameters and no output schema, the description is incomplete. It covers purpose and one behavioral trait but omits parameter semantics and return value shape, leaving the agent without enough context to invoke it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has two parameters (limit, status) with 0% description coverage, and the description does not mention either parameter. It adds no meaning beyond the schema's names and defaults, leaving the agent to infer semantics for 'status' and 'limit'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (List) and resource (durable notifications), and the clause 'without advancing the review cursor' distinguishes it from the sibling mark_notifications_reviewed. It is clear without opening the schema, though 'durable' is slightly underspecified.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies when to use this tool (when you want to view notifications without marking them reviewed), but does not explicitly name alternatives or state when-not-to-use. The contrast with the sibling is implicit rather than spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mark_notifications_reviewedA

Advance the durable notification cursor after successful handling.

ParametersJSON Schema
NameRequiredDescriptionDefault
through_seqYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It discloses the key behavioral trait that this is a cursor-advancing mutation and that it's meant to be done post-handling, which guards against premature calls. However, it doesn't state whether advancement is idempotent, reversible, or what effect skipping it has – meaningful gaps for a state mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with no waste; the precondition is front-loaded in the trailing clause so the agent reads the critical 'when' immediately after the action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-param mutation with no annotations and no output schema, the description is minimally viable: it conveys intent and timing but omits parameter meaning and behavioral specifics (idempotency, error effects) that an agent would need to invoke it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, yet it never mentions through_seq or explains that it marks all notifications up to and including that sequence number. The phrase 'durable notification cursor' hints at the concept but provides no semantics for the sole parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('advance') and resource ('durable notification cursor'), and adds the precondition 'after successful handling'. It's clear what it does, though 'durable notification cursor' is jargon that assumes familiarity with the notification model.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The clause 'after successful handling' tells the agent when to call it – following the successful processing of notifications obtained elsewhere (presumably list_notifications). It doesn't name the sibling explicitly or state exclusions, keeping it out of the top tier.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

monitor_statusC

Return bounded durable inbox state and storage location.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, no output schema, and no parameter schema, the description carries the full behavioral burden. "Bounded" hints at a size cap and "durable" hints at persistence, but neither is explained — no indication of what is returned, whether the call is read-only, or what 'storage location' means.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence that is front-loaded with the object of the operation. It is efficient, though the terseness veers toward under-specification rather than tight writing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should describe the returned state more concretely, and it only gestures at it via "bounded durable inbox state and storage location". For a simple zero-parameter read this is minimally adequate but leaves the agent unsure of what it will receive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter-level gaps exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a verb ("Return") and resources ("inbox state", "storage location"), so the basic purpose is inferable. However, "bounded durable inbox state" is opaque jargon, and nothing distinguishes this from sibling list_notifications or explains what an 'inbox' means in this server's context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as list_notifications or check_url. The agent must guess whether this is a diagnostic read, a polling endpoint, or a complement to the notification tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedcheck_url
    • First observedlist_notifications
    • First observedmark_notifications_reviewed
    • First observedmonitor_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored across 4 tools

Disambiguation4/5

Each tool targets a distinct action: check_url for fetching, list_notifications for retrieving, mark_notifications_reviewed for updating state, and monitor_status for reporting. However, list_notifications and monitor_status could overlap if an agent wants to check notifications without advancing the cursor, but the descriptions clarify their distinct purposes.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (check_url, list_notifications, mark_notifications_reviewed, monitor_status). This pattern is predictable and easy to understand.

Tool Count5/5

With only 4 tools, the server is well-scoped and each tool appears to serve a specific purpose in the monitor's workflow. This count is appropriate for a focused durable web monitoring tool.

Completeness4/5

The tool set covers the core lifecycle: checking a URL, listing notifications, marking them reviewed, and checking status. However, there is no tool to configure or remove monitors, which could be a gap for managing multiple URLs or cleaning up baselines.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers