# mcp-page-monitor

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](tests/)

A **Model Context Protocol (MCP) server** that watches web pages and fires alerts
when their content changes. Designed to be dropped into any MCP client (Claude
Desktop, WorkBuddy, custom agents) so an AI assistant can "keep an eye on" pages
without polling them itself.

```
┌────────────┐   add_target / check_target   ┌──────────────────┐
│  MCP Client │ ───────────────────────────▶ │  page-monitor    │
│ (assistant) │ ◀─────────────────────────── │  (FastMCP)       │
└────────────┘      change status / alert    └────────┬─────────┘
                                                      │
                              ┌───────────────────────┼───────────────────────┐
                              ▼                       ▼                       ▼
                        ┌──────────┐          ┌──────────────┐        ┌────────────┐
                        │ fetcher  │          │  differ      │        │ alert sink │
                        │(requests)│ ───────▶ │(hash + LCS)  │ ─────▶ │(console/..)│
                        └──────────┘          └──────────────┘        └────────────┘
```

## Why this exists

LLMs are bad at *polling* — they can't sit and wait. But they're great at *reacting*
to a change notification. `mcp-page-monitor` bridges that gap: register URLs once,
and the server tells the assistant *what changed* in plain text whenever a page moves.

## Features

| Feature | Notes |
|---------|-------|
| Multi-target watching | Register many URLs, each with its own sensitivity |
| Robust diffing | SHA-256 hashing + `difflib` LCS; whitespace/case-insensitive |
| Adjustable sensitivity | `threshold` (default 0.98) suppresses cosmetic noise |
| Pluggable alerts | `ConsoleAlertSink` built in; subclass `AlertSink` for Slack/email/webhook |
| Network-free core | Diff/monitor/alert logic is 100% testable without internet |

## Install

```bash
pip install -r requirements.txt
```

## Use as an MCP server

```bash
python -m mcp_page_monitor.server
```

Then in your MCP client config point to the module. Tools exposed:

- `add_target(url, name?, threshold?)` — start watching a page
- `check_target(url)` — fetch, diff vs baseline, return change status

## Use the engine directly

```python
from mcp_page_monitor.monitor import PageMonitor
from mcp_page_monitor.alerts import ConsoleAlertSink
from mcp_page_monitor.fetching import fetch_url

mon = PageMonitor(fetcher=fetch_url, alert_sink=ConsoleAlertSink())
mon.add("https://example.com", threshold=0.95)
mon.check("https://example.com")   # baseline
mon.check("https://example.com")   # alerts if content shifted
```

## Architecture in one line

> fetch ➜ normalize ➜ hash+diff ➜ (changed?) ➜ alert

The diff math (identities verified by tests):

- identical pages ⇒ `similarity == 1.0`, `changed == False`
- one line changed in 100 ⇒ `similarity ≈ 0.99`, `changed == True` under strict threshold
- first observation is always a *baseline* and never alerts

## Project layout

```
mcp-page-monitor/
├── mcp_page_monitor/
│   ├── __init__.py
│   ├── differ.py      # hashing + diff (no deps)
│   ├── monitor.py     # polling engine (fetcher injected)
│   ├── alerts.py      # alert sinks
│   ├── fetching.py    # requests-based fetcher (prod only)
│   └── server.py      # MCP/FastMCP adapter (lazy import of mcp)
├── tests/
│   └── test_monitor.py
├── conftest.py
├── requirements.txt
├── README.md
├── LICENSE
└── .gitignore
```

## License

MIT © wzx11223344