MCP tools

frankensurf-mcp speaks MCP over stdio. To connect it, see Add to your agent.

Tool	Arguments	Returns
read	url, provider, render, include_images, freshness, identity, allow_handoff, profile, try_harder_than, expect_terms, card_images, acquisition_policy	The page and its receipt. Asks for markdown by default. try_harder_than takes an earlier read’s trace_id and skips every tool it used. expect_terms are words results should mention; a results page that mentions none is flagged off_query. card_images adds cards (link, title, thumbnail). module names a site module (none turns them off); module_override runs an unsaved one.
read_template	module, template, params, expect_terms, card_images, acquisition_policy	A read of a URL built from a saved module’s template, shaped by that module: items, next_url, receipt.module.
site_modules	action (list, get, put, enable, disable, delete), module_id, module	Save and manage site modules.
discover_site_module	url, save, module_id	Up to three validated module drafts from a listing page’s JSON-LD, script JSON, fetched JSON or repeated HTML cards, each with its item count and sample rows. save saves the best.
repair_site_module	trace_id, module	Propose the next version of a module that failed on a read. Validated against the kept page and a fresh read with the old version’s assertions; only the owner promotes it.
trace	trace_id	The full record of an earlier read: tools tried, failures, timings, completeness steps. No page content.
extract	url, adapter, include_images, identity, provider, freshness, acquisition_policy	The page through an adapter: html (default), json or rss.
batch	urls, provider, adapter, identity, include_images, freshness	One result per URL.
search	query, source, limit, identity, provider, acquisition_policy	Attributed results.
paginate	url, adapter, continuation_adapter, acquisition_policy	Every page with an aggregate receipt.
images	urls, identity, max_images, provider	Checked images.
identity_status	identity	Health of your identities.
import_evidence	content, url, observed_at, content_type, image_urls	A stored capture.
import_image_evidence	path, url, observed_at	A stored image capture.
do	intent, identity, action_classes, …	A typed browser action. See Act.
repair	trace_id, repair_policy	A diagnosis of a failed extract.

acquisition_policy takes any setting, for example {"allow_paid_fallbacks": true, "max_cost_usd": 0.05}. JSON null, false and 0 count as set.

MCP results leave out the raw page body. Pass acquisition_policy: {"prefer_markdown": false} to read when you need the HTML structure instead of markdown.

Note

Identities and keys are set up from the command line, never through MCP. watch is available from Python and the CLI.