Skip to content

mcp-server.mdx

Latest commit

 

History

History
137 lines (90 loc) · 5.74 KB

mcp-server.mdx

File metadata and controls

137 lines (90 loc) · 5.74 KB
Raw
title MCP Server Reference
description Model Context Protocol tools, resources, prompts, and transports for the html2rss gem.

import { Code } from "@astrojs/starlight/components";

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

Start

<Code code={`

stdio (default for desktop clients)

html2rss mcp

HTTP on loopback only

html2rss mcp --transport http --port 8080 `} lang="bash" />

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 use strategy: "auto" by default so html2rss can choose an available fetch path from the scrape result. Prefer native RSS/Atom when present; weak homepage URLs may be rewritten via entry resolution.

Keep auto for normal use. Pin strategy: "botasaurus" only when a diagnostic requires browser rendering or browser-specific controls.

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:

<Code code={{ "ok": true, "next_step": "test", "guidance": "...", "payload": {} }} lang="json" />

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 / default / 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 Runtime strategy names for client discovery; prefer auto, default, or botasaurus
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.