MCP Server Reference

html2rss ships a built-in Model Context Protocol (MCP) server for AI agents and IDEs (Cursor, Claude Desktop, Copilot).

Start

# stdio (default for desktop clients)
html2rss mcp
# HTTP on loopback only
html2rss mcp --transport http --port 8080

Transport	Command	Notes
stdio	html2rss mcp	Recommended for Cursor / Claude Desktop
http	html2rss mcp --transport http --port 8080	Bound to 127.0.0.1 only; needs rack, rackup, webrick

Daemon logs go to stderr (stdout is JSON-RPC). Default LOG_LEVEL for the MCP process is info unless you set it.

Strategy

scrape and capture with strategy: "auto" run Faraday → Botasaurus AutoFallback in one call. Prefer native RSS/Atom when present; weak homepage URLs may be rewritten via entry resolution.

inspect with auto stays on Faraday. Pin strategy: "botasaurus" when inspect needs browser rendering.

Read html2rss://runtime for botasaurus_configured (boolean only). Set BOTASAURUS_SCRAPER_URL on the MCP process env.

Result envelope

Every tool returns one JSON object in text content and structuredContent:

{
  "ok": true,
  "next_step": "test",
  "guidance": "...",
  "payload": {}
}

isError matches ok: false. Articles live in payload.items; YAML in payload.yaml; RSS in payload.rss.

next_step is one of: done, inspect, recon, validate, apply, scrape, capture, read_runtime, test.

Tools (7 bare verbs + batch trio)

Golden path for durable YAML: inspect (optional) → recon → capture → test → apply. One-shot articles: scrape. Schema-only side door: validate.

scrape

One-shot article extraction as JSON Feed items (no saved config).

• Parameters: url (required); strategy (auto / faraday / botasaurus, default auto); limit (default 25); optional items_selector
• Payload: items, plus totals / strategy fields when present
• Empty items can still be ok: true — follow next_step / guidance

inspect

Diagnostics: final URL, status, scheme downgrade, rel=alternate feeds, surface category, admission drops.

• Parameters: url (required); strategy (default auto)
• Follow next_step — often recon when alternates warrant it, or scrape / capture

recon

Curation verdict and native_feed preference (BUILD / DEFER / DROP).

• Parameters: url (required); strategy (default auto)

capture

Derive a reusable YAML draft (payload.yaml). Same serializer as CLI html2rss capture. Catalog feeds still need directory.topics and explicit channel title / url.

• Parameters: url (required); strategy; optional items_selector
• Typical next_step: test or inspect

validate

Schema-only check against html2rss://schema. Exactly one of config or yaml.

• Success next_step is usually test

test

Schema validation plus live extraction (min_items, optional strict_quality, compare_enhance).

• Success next_step is apply
• Payload includes sample items, timing, and quality_report when present

apply

Ship gate: build RSS from a config. Required url plus exactly one of config or yaml.

• Payload: rss, item_count
• isError when zero items

Batch trio

Tool	Job
batch_scrape	Parallel scrape with per-URL isolation
batch_inspect	Parallel inspect
batch_recon	Parallel recon

Resources

URI	Description
html2rss://schema	Feed config JSON Schema
html2rss://extractors	Extractor names
html2rss://strategies	auto, faraday, botasaurus (not local_file)
html2rss://runtime	version, mcp_contract_version, catalog_fingerprint, tools, botasaurus_configured — never the scraper URL

validate / apply reject strategy: local_file and request.local_file_path. Use CLI --input for fixtures.

Prompts

Name	Flow
scrape-webpage	One scrape call; inspect only if weak
capture-feed-config	capture → test → apply (catalog rewrite when targeting html2rss-configs)

Client setup

See AI Agent Workflows for Cursor / Claude Desktop mcp.json examples and the html2rss-config skill.