Metadata-Version: 2.5
Name: dealmonitor-mcp
Version: 1.0.0
Summary: Track a product's price in any online shop and get notified when it drops to your target.
Project-URL: Homepage, https://dealmonitor.app
Project-URL: Repository, https://github.com/rwkaspar/dealmonitor
Project-URL: Issues, https://github.com/rwkaspar/dealmonitor/issues
Author-email: Robert-William Kaspar <info@dealmonitor.app>
License-Expression: MIT
License-File: LICENSE
Keywords: deals,e-commerce,mcp,model-context-protocol,price,price-alert,price-drop,price-monitoring,price-tracking,shopping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Provides-Extra: http
Requires-Dist: starlette>=0.40; extra == 'http'
Requires-Dist: uvicorn>=0.30; extra == 'http'
Description-Content-Type: text/markdown

<!-- mcp-name: app.dealmonitor/dealmonitor -->

# DealMonitor MCP server

Lets an MCP client — Claude Desktop, Claude Code, any agent framework that
speaks MCP — read the current price of a product in almost any online shop,
and keep watching that price after the conversation ends.

The watching is the part an agent cannot do by itself. A model can read a
page once; it cannot come back tomorrow. This server hands that job to
DealMonitor's scheduler, which keeps checking and notifies the account
owner by email, push or Telegram when the target price is met.

The person the agent is working for never has to deal with DealMonitor:
no site to visit, no watch to set up, nothing to learn. They say "tell me
when this gets cheaper" and later they get the notification.

## Tools

| Tool | Needs a token | What it does |
|---|---|---|
| `check_price(url)` | no | Current price for a product page, read server-side with a real browser when the shop needs one |
| `watch_price(url, target_price)` | yes | Reads the price *and* creates the watch, in one call |
| `list_watches(only_reached=False)` | yes | Every watch with its current price, target, and whether the target is met |
| `price_history(watch_id, limit=60)` | yes | Recorded prices, oldest first, plus the recorded low and high |
| `set_target_price(watch_id, target_price)` | yes | Move a target |
| `stop_watching(watch_id)` | yes | Delete a watch |

Every tool returns a dict with an `ok` field and, on failure, an `error`
code (`auth_required`, `shop_not_trackable`, `request_failed`,
`rate_limited`, `not_found`, `internal`) and a message written to be read by
a model. No tool raises.

## Two ways to run it

**Hosted**, nothing to install:

```
https://mcp.dealmonitor.app/mcp
```

Streamable HTTP. The token travels per request as
`Authorization: Bearer dm_…`, so one endpoint serves everybody and no
request ever borrows another's account. Without a token `check_price` still
works; a hosted anonymous caller is rate-limited per address, and a token
raises that limit considerably.

```json
{
  "mcpServers": {
    "dealmonitor": {
      "type": "http",
      "url": "https://mcp.dealmonitor.app/mcp",
      "headers": { "Authorization": "Bearer dm_…" }
    }
  }
}
```

Authentication is a bearer token, not OAuth — so any client that can set a
header works, and the claude.ai connector dialog, which asks for an OAuth
provider, does not yet.

**Local**, over stdio, if you would rather the process ran on your own
machine: below.

## Install

```bash
pip install dealmonitor-mcp
```

### Claude Desktop / Claude Code

No install needed — `uvx` fetches it on first use:

```json
{
  "mcpServers": {
    "dealmonitor": {
      "command": "uvx",
      "args": ["dealmonitor-mcp"],
      "env": {
        "DEALMONITOR_API_TOKEN": "dm_…"
      }
    }
  }
}
```

With the package installed instead, the command is `dealmonitor-mcp` and
`args` can be dropped.

### From this checkout

```bash
pip install -e .
```

A token is created under **Account → API access** at
<https://dealmonitor.app>. It is shown once. Leave it out and `check_price`
still works; everything that keeps state does not.

| Variable | Default | Meaning |
|---|---|---|
| `DEALMONITOR_API_TOKEN` | — | Account token, `dm_…`. stdio only — the hosted server reads the token from each request and refuses to use this one |
| `DEALMONITOR_API_URL` | `https://api.dealmonitor.app` | For a self-hosted instance |

### Hosting it yourself

```bash
pip install "dealmonitor-mcp[http]"
dealmonitor-mcp-http          # 0.0.0.0:8080, MCP at /mcp, health at /health
```

One worker. The rate-limit counters live in the process, so a second worker
doubles every limit.

| Variable | Default | Meaning |
|---|---|---|
| `DEALMONITOR_MCP_PORT` | `8080` | |
| `DEALMONITOR_MCP_ALLOWED_HOSTS` | `mcp.dealmonitor.app,localhost,127.0.0.1` | `Host` headers answered; the rest get 421 |
| `DEALMONITOR_MCP_MAX_IN_FLIGHT` | `16` | Requests served at once before the next is refused with 503 |
| `DEALMONITOR_MCP_SCRAPE_PER_HOUR_ANON` | `20` | Price reads per address without a token |
| `DEALMONITOR_MCP_SCRAPE_PER_HOUR` | `120` | Price reads per token |
| `DEALMONITOR_MCP_READ_PER_HOUR_ANON` | `60` | Other calls per address |
| `DEALMONITOR_MCP_READ_PER_HOUR` | `600` | Other calls per token |

## Affiliate links

Some shops pay DealMonitor a commission on a purchase made through a tagged
link. Where such a link exists, a tool result carries **both** URLs:

```json
{
  "product_url": "https://www.example-shop.de/p/12345",
  "affiliate_url": "https://www.example-shop.de/p/12345?tag=…",
  "is_affiliate": true,
  "disclosure": "This URL carries an affiliate tag. A commission may be paid on a purchase made through it, at no extra cost to the buyer. If you pass this URL to a person, tell them it is an affiliate link. If you cannot, use product_url instead."
}
```

The disclosure travels in the result rather than in this file, because the
agent is the only party in a position to show it to the person who will
click. An agent whose rules forbid passing on an undisclosed affiliate link
can use `product_url` and lose nothing else. When a shop has no programme,
`is_affiliate` is `false` and `affiliate_url` is `null` — the server never
invents one.

## Limits worth telling a user about

- **Prices come from the shop page.** A crossed-out price, a bundle price or
  a price per unit can be read instead of the one that is paid.
  `check_price` returns a `warning` when the reading is uncertain; pass that
  on rather than swallowing it.
- **Amazon product pages often return no price** on `check_price`: the first
  read of a page is a scrape, and Amazon walls it. A `watch_price` on the
  same URL still works — the recurring check reaches it by other means.
- **A slow shop takes up to two minutes**, because the server escalates to a
  real browser. Both reading tools are shaped for that; do not retry early.
- **Shops that asked not to be read** return `shop_not_trackable`. That is a
  final answer, not a transient error.

## Tests

```bash
pip install -e ".[dev]"
python -m pytest -q
```

No network: the client tests run against `httpx.MockTransport`, the server
tests against a fake client.
