# rfd-mcp

`rfd-mcp` is a standalone local stdio MCP server for searching and monitoring RedFlagDeals topics.

It has no source or package dependency on the RFD frontend repository. It references RFD only through the cached JSON feed configured with `RFD_TOPICS_URL` or `RFD_TOPICS_FILE`. By default it reads the deployed `rfd-fyi` feed at:

    https://github.com/carteakey/rfd

The default data endpoint is:

    https://rfd-fyi.pages.dev/topics.json

For local development, set `RFD_TOPICS_FILE` to a JSON file or set `RFD_TOPICS_URL` to a local Pages/Wrangler endpoint.

## Install and build

From this repository root:

    npm ci
    npm run build

The compiled server is `dist/index.js`.

## Configure an MCP client

For Claude Code:

    claude mcp add rfd -- node /absolute/path/to/rfd-mcp/dist/index.js

Or add an entry like this to an MCP client configuration. The environment variables are optional.

    {
      "mcpServers": {
        "rfd": {
          "command": "node",
          "args": ["/absolute/path/to/rfd-mcp/dist/index.js"],
          "env": {
            "RFD_TOPICS_URL": "https://rfd-fyi.pages.dev/topics.json",
            "RFD_MCP_DATA_DIR": "/absolute/path/to/rfd-mcp-data"
          }
        }
      }
    }

## Tools

- `search_deals` searches topic titles and retailer names. It supports additional filter chips, `/regular expression/` filters, retailer filtering, score bounds, the same six sort keys as the frontend, and a result limit.
- `get_deal` returns the complete cached topic record plus the forum and direct-offer links for a `topic_id`.
- `monitor_search` saves a search and keeps the latest 500 seen topic IDs.
- `check_monitors` checks one or all saved searches and returns only unseen deals.
- `list_monitors` lists saved searches and their last-check state.
- `delete_monitor` removes a saved search.

RFD's cached topic schema does not contain Marketplace-style location, price, or category fields. Those filters are intentionally not exposed; the server uses the fields the RFD scraper actually stores.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `RFD_TOPICS_URL` | `https://rfd-fyi.pages.dev/topics.json` | Cached topics endpoint |
| `RFD_TOPICS_FILE` | unset | Read topics from a local JSON file instead of HTTP |
| `RFD_FORUM_BASE_URL` | `https://forums.redflagdeals.com` | Base URL for thread links |
| `RFD_MCP_CACHE_TTL_MS` | `30000` | In-memory topics cache lifetime |
| `RFD_MCP_DATA_DIR` | `~/.rfd-mcp` | Directory for monitor state |
| `RFD_MCP_MONITORS_FILE` | `$RFD_MCP_DATA_DIR/monitors.json` | Exact monitor state path |

## Tests

    npm test
    npm run build

The server uses MCP stdio transport, so stdout is reserved for protocol traffic. Diagnostics are returned as tool errors or written by dependencies to stderr.