html2rss 0.32.4 → 0.34.0

data/lib/html2rss/link_destination/text_classifier.rb

@@ -2,8 +2,10 @@
 
 module Html2rss
   module LinkDestination
-    # Classifies visible anchor text for utility and recommendation chrome.
-    class TextClassifier
+    # Classifies visible anchor text for utility, recommendation and read-more chrome in en, de, fr, es, it,
+    # nl, pl, sv and ja. Letters with an accented variant are alternations, not classes: with +/i+, Ruby on
+    # Linux does not fold an uppercase accented letter against a class that also holds its ASCII base.
+    class TextClassifier # rubocop:disable Metrics/ClassLength -- nine-language vocabulary tables
       # Prefix labels that usually identify navigation or subscription links.
       UTILITY_PREFIX_PATTERN = /
         \A\s*(
@@ -14,7 +16,17 @@ module Html2rss
           # Spanish
           ver\s+todos|ver\s+todo|todas\s+las\s+noticias|suscribirse|bolet(i|í)n|comentarios\s+feed|unirse|
           # French
-          voir\s+tout|voir\s+tous|toutes\s+les\s+nouvelles|s['’]abonner|flux\s+de\s+commentaires|rejoindre
+          voir\s+tout|voir\s+tous|toutes\s+les\s+nouvelles|s['’]abonner|flux\s+de\s+commentaires|rejoindre|
+          # Italian
+          vedi\s+tutto|vedi\s+tutti|tutte\s+le\s+notizie|abbonati|newsletter|iscriviti|
+          # Dutch
+          bekijk\s+alles|alles\s+bekijken|al\s+het\s+nieuws|abonneren|nieuwsbrief|lid\s+worden|
+          # Polish
+          zobacz\s+wszystko|wszystkie\s+wiadomo(ś|s)ci|subskrybuj|newsletter|do(łą|la)cz|
+          # Swedish
+          visa\s+alla|se\s+alla|alla\s+nyheter|prenumerera|nyhetsbrev|bli\s+medlem|
+          # Japanese
+          すべて見る|全て見る|ニュースレター|メルマガ|会員登録|購読
         )\b
       /ix
       # Short labels that usually identify non-article navigation links.
@@ -35,7 +47,22 @@ module Html2rss
           # French
           (a|à)\s+propos|(a|à)propos|contact|commentaires?|rejoindre|
           se\s+connecter|login|membre|abonnement|recommand(e|é)(\s+pour\s+vous)?|
-          voir\s+tout|partager|s['’]inscrire|s['’]abonner|newsletter
+          voir\s+tout|partager|s['’]inscrire|s['’]abonner|newsletter|
+          # Italian
+          chi\s+siamo|contatti|commenti|accedi|iscriviti|condividi|abbonati|registrati|vedi\s+tutto|
+          consigliato(\s+per\s+te)?|abbonamento|
+          # Dutch
+          over\s+ons|contact|reacties|inloggen|aanmelden|delen|abonneren|registreren|bekijk\s+alles|
+          aanbevolen(\s+voor\s+jou)?|nieuwsbrief|lid\s+worden|lidmaatschap|
+          # Polish
+          o\s+nas|kontakt|komentarze|zaloguj\s+si(ę|e)|zarejestruj\s+si(ę|e)|udost(ę|e)pnij|subskrybuj|
+          zobacz\s+wszystko|polecane(\s+dla\s+ciebie)?|do(łą|la)cz|
+          # Swedish
+          om\s+oss|kontakt|kommentarer|logga\s+in|bli\s+medlem|dela|prenumerera|registrera\s+dig|visa\s+alla|
+          se\s+alla|rekommenderat(\s+f(ö|o)r\s+dig)?|nyhetsbrev|medlemskap|
+          # Japanese
+          会社概要|お問い合わせ|コメント|ログイン|会員登録|新規登録|シェア|共有|購読|すべて見る|全て見る|
+          もっと見る|おすすめ|ニュースレター|メルマガ
         )\b
       /ix
       # Labels for recommendation chrome rather than source articles.
@@ -44,21 +71,90 @@ module Html2rss
           recommended(\s+for\s+you)?|
           empfohlen(\s+f(ue|ü)r\s+dich)?|
           recomendado(\s+para\s+ti)?|
-          recommand(e|é)(\s+pour\s+vous)?
+          recommand(e|é)(\s+pour\s+vous)?|
+          consigliato(\s+per\s+te)?|
+          aanbevolen(\s+voor\s+jou)?|
+          polecane(\s+dla\s+ciebie)?|
+          rekommenderat(\s+f(ö|o)r\s+dig)?|
+          おすすめ
         )\b
       /ix
 
+      # Whole read-more labels that stand alone ("Continue reading", "Lire la suite", "続きを読む").
+      READ_MORE_PHRASE = /
+        read\s+more|read\s+on|continue\s+reading|keep\s+reading|learn\s+more|find\s+out\s+more|
+        read\s+(?:the\s+)?(?:full\s+|whole\s+)?(?:story|article)|read\s+the\s+rest|
+        weiterlesen|weiter\s+lesen|mehr\s+lesen|mehr\s+erfahren|mehr\s+dazu|mehr\s+zum\s+thema|
+        lesen\s+sie\s+(?:mehr|weiter)|(?:den\s+)?(?:ganzen|gesamten|vollst(?:ä|a)ndigen)\s+artikel\s+lesen|
+        lire\s+la\s+suite|lire\s+plus|lire\s+l['’]article(?:\s+complet)?|en\s+savoir\s+plus|
+        pour\s+en\s+savoir\s+plus|plus\s+d['’]infos?|plus\s+d['’]informations?|
+        leer\s+m(?:á|a)s|seguir\s+leyendo|continuar\s+leyendo|saber\s+m(?:á|a)s|
+        m(?:á|a)s\s+informaci(?:ó|o)n|leer\s+(?:todo|el\s+art(?:í|i)culo\s+completo)|
+        leggi\s+tutto|leggi\s+di\s+pi(?:ù|u)|leggi\s+l['’]articolo|continua\s+a\s+leggere|scopri\s+di\s+pi(?:ù|u)|
+        maggiori\s+informazioni|ulteriori\s+informazioni|per\s+saperne\s+di\s+pi(?:ù|u)|approfondisci|
+        lees\s+meer|lees\s+verder|verder\s+lezen|meer\s+lezen|meer\s+informatie|meer\s+weten|
+        lees\s+(?:het\s+)?(?:hele|volledige)\s+artikel|
+        czytaj\s+wi(?:ę|e)cej|czytaj\s+dalej|dowiedz\s+si(?:ę|e)\s+wi(?:ę|e)cej|wi(?:ę|e)cej\s+informacji|
+        czytaj\s+ca(?:ł|l)o(?:ś|s)(?:ć|c)|zobacz\s+wi(?:ę|e)cej|
+        l(?:ä|a)s\s+mer|l(?:ä|a)s\s+vidare|forts(?:ä|a)tt\s+l(?:ä|a)sa|mer\s+information|
+        l(?:ä|a)s\s+hela\s+artikeln|
+        続きを読む|もっと読む|続きはこちら|詳しくはこちら|詳細を見る|詳細はこちら|全文を読む|続きを見る
+      /ix
+      # "More about X" lead-ins: a read-more phrase or a bare "more", then a topic preposition.
+      READ_MORE_TOPIC_LEAD = /
+        (?:#{READ_MORE_PHRASE.source}|more|mehr|plus\s+d['’]infos?|m(?:á|a)s|altro|di\s+pi(?:ù|u)|meer|wi(?:ę|e)cej|mer)
+        \s+(?:about|on|from|zu|zum\s+thema|zum|zur|(?:ü|ue)ber|von|sur|
+        (?:à|a)\s+propos\s+de|de|sobre|su|riguardo|over|van|
+        o|na\s+temat|om|av)
+      /ix
+      # A read-more label as a whole text, optionally wrapped in punctuation or arrows. The topic after a
+      # lead-in counts only when quoted ("More about «X»", „X“, "X", 'X', 「X」), so a headline that merely
+      # opens with one ("Mehr über die Zukunft der Rente") stays a headline; Japanese topic forms put the
+      # topic first.
+      READ_MORE_PATTERN = /
+        \A[\s\p{P}\p{S}]*(?:
+          (?:#{READ_MORE_PHRASE.source})|
+          (?:#{READ_MORE_TOPIC_LEAD.source})\s*[«„"“”'‘’‹「].+[»"“”'’›」]|
+          \S{1,40}(?:の続きを読む|をもっと読む|について詳しく(?:はこちら)?|の詳細(?:を見る|はこちら))
+        )[\s\p{P}\p{S}]*\z
+      /ix
+
+      # Visible new-window notice that trails a link label, in parentheses or brackets.
+      NEW_WINDOW_NOTICE = /
+        \s*[(\[（【]\s*(?:
+          opens\s+in\s+(?:a\s+)?new\s+(?:window|tab)|
+          (?:ö|oe)ffnet\s+(?:sich\s+)?in\s+(?:einem\s+neuen|neuem)\s+(?:fenster|tab)|
+          ouvre\s+dans\s+(?:une\s+)?nouvel(?:le)?\s+(?:fen(?:ê|e)tre|onglet)|
+          se\s+abre\s+en\s+(?:una\s+)?nueva\s+(?:ventana|pesta(?:ñ|n)a)|
+          si\s+apre\s+in\s+(?:una\s+)?nuova\s+(?:finestra|scheda)|
+          opent\s+in\s+(?:een\s+)?nieuw(?:e)?\s+(?:venster|tabblad)|
+          otwiera\s+si(?:ę|e)\s+w\s+nowym\s+(?:oknie|karcie)|
+          (?:ö|o)ppnas\s+i\s+(?:ett\s+)?nytt\s+(?:f(?:ö|o)nster|flik)|
+          新しい(?:ウィンドウ|ウインドウ|タブ)で開く
+        )\s*[)\]）】]\s*\z
+      /ix
+
       # @param text [String, #to_s] visible anchor text
       # @return [Boolean] true when text matches a utility label
-      def utility?(text) = text.to_s.match?(UTILITY_PATTERN)
+      def utility?(text) = normalize(text).match?(UTILITY_PATTERN)
 
       # @param text [String, #to_s] visible anchor text
       # @return [Boolean] true when text begins with a utility label
-      def utility_prefix?(text) = text.to_s.match?(UTILITY_PREFIX_PATTERN)
+      def utility_prefix?(text) = normalize(text).match?(UTILITY_PREFIX_PATTERN)
 
       # @param text [String, #to_s] visible anchor text
       # @return [Boolean] true when text identifies recommendation chrome
-      def recommended?(text) = text.to_s.match?(RECOMMENDED_PATTERN)
+      def recommended?(text) = normalize(text).match?(RECOMMENDED_PATTERN)
+
+      # @param text [String, #to_s] visible anchor text or extracted title
+      # @return [Boolean] true when the whole text is a read-more label, bare or with its topic
+      def read_more?(text) = normalize(text).match?(READ_MORE_PATTERN)
+
+      private
+
+      # Every label is read in NFC, so a decomposed accent matches the precomposed vocabulary, and without
+      # its trailing new-window notice ("(opens in new tab)").
+      def normalize(text) = text.to_s.unicode_normalize(:nfc).sub(NEW_WINDOW_NOTICE, '')
     end
   end
 end

data/lib/html2rss/mcp/README.md

@@ -39,6 +39,7 @@ Every tool result is one JSON object (text body and `structuredContent`):
 | `next_step` | Bare verb name or `done` / `read_runtime`                    |
 | `guidance`  | Agent instruction (from `Outcome::Playbook`)                 |
 | `payload`   | Tool-specific data (`yaml`, `rss`, `items`, recon fields, …) |
+| `cache`     | Optional: `{ hits, max_age_seconds }` when cached pages fed the result |
 
 `Contract.response` builds the wire body; `Outcome` owns `next_step` policy.
 
@@ -64,7 +65,7 @@ Do not duplicate playbook prose in `server.rb`.
 | `html2rss://schema`     | Full JSON Schema for feed configurations                   |
 | `html2rss://extractors` | Registered extractor names                                 |
 | `html2rss://strategies` | Published MCP strategies (`auto`, `default`, `httpx`, `botasaurus`) |
-| `html2rss://runtime`    | `version`, `mcp_contract_version`, `catalog_fingerprint`, `tools`, `botasaurus_configured` (never the scraper URL). Fingerprint covers tool names, required keys, and `oneOf` branches; bump `mcp_contract_version` for envelope semantics. |
+| `html2rss://runtime`    | `version`, `mcp_contract_version`, `catalog_fingerprint`, `tools`, `botasaurus_configured`, `response_cache_ttl` (never the scraper URL). Fingerprint covers tool names, required keys, and `oneOf` branches; bump `mcp_contract_version` for envelope semantics. |
 
 ## Prompts
 
@@ -73,6 +74,17 @@ Do not duplicate playbook prose in `server.rb`.
 | `scrape-webpage`      | One `scrape` call; `inspect` only if weak or recon needed    |
 | `capture-feed-config` | Capture YAML → test → apply; catalog rewrite; strive enhance |
 
+## Response cache
+
+The MCP process is long-lived, so an agent iterating `inspect → capture → validate → test` on one URL should not refetch it. `RequestService::ResponseCache` is installed at server start, **on by default with a 300s TTL**. Set `HTML2RSS_RESPONSE_CACHE_TTL=<seconds>` to change it, or `0` / `off` / `false` to disable; an unusable value logs a warning and uses the default.
+
+- Only initial 2xx fetches are cached, keyed by a digest of URL, strategy, headers, request options, and policy limits. Follow-ups and block pages always hit the network.
+- Memory is bounded: at most 32 entries and 32 MiB of bodies, oldest evicted first.
+- When a result was built from cached pages, the envelope carries `cache: { hits, max_age_seconds }`; absent means everything was fetched live. Wait out the TTL or restart with the cache off to force a refetch.
+- `html2rss://runtime` publishes `response_cache_ttl` (`null` when off).
+
+The one-shot CLI has no use for it; use `capture` or `--input -` for offline iteration.
+
 ## Strategy note
 
 `scrape` / `capture` with `strategy: "auto"` run the full AutoFallback chain. `inspect` maps `auto` to default (HTTPX) for cheap diagnostics; pin `botasaurus` when you need browser rendering for inspect.

data/lib/html2rss/mcp/config_argument.rb

@@ -8,22 +8,26 @@ module Html2rss
     #
     # Config does not know MCP. YAML parsing stays on {Html2rss::Config.from_yaml}.
     class ConfigArgument
+      # Raised unless exactly one of +config+ or +yaml+ is present.
+      class ExclusiveInputError < Html2rss::InvalidOption; end
+
       class << self
         ##
         # @param config [Hash, nil] feed configuration hash
         # @param yaml [String, nil] feed configuration YAML
         # @return [ConfigArgument]
-        # @raise [ArgumentError] unless exactly one of +config+ or +yaml+ is present
+        # @raise [ExclusiveInputError] unless exactly one of +config+ or +yaml+ is present
+        # @raise [Html2rss::InvalidOption] when +config+ is not a Hash or +yaml+ is not a String
         # @raise [Contract::UnpublishedRequestError] when the parsed config uses
         #   an unpublished MCP strategy or +request.local_file_path+
         def parse(config: nil, yaml: nil)
           parsed = case [present?(config), present?(yaml)]
                    in [true, false]
-                     HashUtil.deep_symbolize_keys(config, context: 'config')
+                     HashUtil.deep_symbolize_keys(require_type!(config, Hash, 'config'), context: 'config')
                    in [false, true]
-                     Config.from_yaml(yaml)
+                     Config.from_yaml(require_type!(yaml, String, 'yaml'))
                    else
-                     raise ArgumentError, 'Provide exactly one of config or yaml'
+                     raise ExclusiveInputError, 'Provide exactly one of config or yaml'
                    end
           Contract.assert_published_request!(parsed)
           new(config: parsed)
@@ -31,6 +35,12 @@ module Html2rss
 
         private
 
+        def require_type!(value, type, name)
+          return value if value.is_a?(type)
+
+          raise Html2rss::InvalidOption, "#{name} must be a #{type}, got #{value.class}"
+        end
+
         def present?(value)
           case value
           in nil then false

data/lib/html2rss/mcp/contract.rb

@@ -16,11 +16,11 @@ module Html2rss
       ALL_ACCEPTED_STRATEGIES = (STRATEGIES + MIGRATION_STRATEGIES).freeze
 
       # Bump when tool names, required inputs, or envelope semantics change (independent of gem +VERSION+).
-      MCP_CONTRACT_VERSION = 3
+      MCP_CONTRACT_VERSION = 4
       public_constant :MCP_CONTRACT_VERSION
 
       # Raised when apply/validate config uses an unpublished MCP request adapter.
-      class UnpublishedRequestError < ArgumentError; end
+      class UnpublishedRequestError < Html2rss::InvalidOption; end
 
       # JSON Schema property for a source page URL.
       URL_PROPERTY = {
@@ -103,7 +103,7 @@ module Html2rss
         properties: {
           url: URL_PROPERTY,
           strategy: STRATEGY_PROPERTY,
-          limit: { type: 'integer', description: 'Max articles to keep (default 25)', default: 25 },
+          limit: { type: 'integer', minimum: 1, description: 'Max articles to keep (default 25)', default: 25 },
           items_selector: { type: 'string', description: 'Optional CSS selector hint for items' }
         }.freeze,
         required: %w[url]
@@ -135,9 +135,9 @@ module Html2rss
           title: { type: 'string', description: 'Channel title override' },
           summary: { type: 'string', description: 'Directory summary override' },
           enhance: { type: 'boolean', description: 'Force enhance on or off' },
-          limit: { type: 'integer', description: 'Max articles to keep' },
-          max_redirects: { type: 'integer', description: 'Optional redirect limit override' },
-          max_requests: { type: 'integer', description: 'Optional request budget override' }
+          limit: { type: 'integer', minimum: 1, description: 'Max articles to keep' },
+          max_redirects: { type: 'integer', minimum: 0, description: 'Optional redirect limit override' },
+          max_requests: { type: 'integer', minimum: 1, description: 'Optional request budget override' }
         }.freeze,
         required: %w[url]
       }.freeze
@@ -163,6 +163,8 @@ module Html2rss
             strategy: strategy_property,
             concurrency: {
               type: 'integer',
+              minimum: 1,
+              maximum: 10,
               description: 'Max parallel worker threads (1..10, default: 5)',
               default: 5
             },
@@ -177,7 +179,7 @@ module Html2rss
         urls_description: 'List of page URLs to scrape (1..25)',
         strategy_property: STRATEGY_PROPERTY,
         extra_properties: {
-          limit: { type: 'integer', description: 'Max articles per URL to keep (default 10)', default: 10 }
+          limit: { type: 'integer', minimum: 1, description: 'Max articles per URL to keep (default 10)', default: 10 }
         }
       ).freeze
 
@@ -242,7 +244,14 @@ module Html2rss
               ok: { type: 'boolean' },
               next_step: { type: 'string', enum: Outcome::NextStep::ALL.keys.map(&:to_s) },
               guidance: { type: 'string' },
-              payload: { type: 'object' }
+              payload: { type: 'object' },
+              cache: {
+                type: 'object',
+                description: 'Present when part of this result came from the response cache instead of the live page',
+                additionalProperties: false,
+                required: %w[hits max_age_seconds],
+                properties: { hits: { type: 'integer' }, max_age_seconds: { type: 'integer' } }
+              }
             }
           }
         end
@@ -251,9 +260,11 @@ module Html2rss
         # One envelope Hash, one compact JSON body, no +_meta+.
         #
         # @param outcome [Outcome]
+        # @param cache_ages [Array<Integer>] ages in seconds of cached page fetches behind this result
         # @return [::MCP::Tool::Response]
-        def response(outcome)
+        def response(outcome, cache_ages: [])
           wire = outcome.to_h
+          wire[:cache] = { hits: cache_ages.size, max_age_seconds: cache_ages.max } unless cache_ages.empty?
           ::MCP::Tool::Response.new(
             [{ type: 'text', text: JSON.generate(wire) }],
             error: !outcome.ok,

data/lib/html2rss/mcp/outcome.rb

@@ -8,8 +8,9 @@ module Html2rss
     # Typed MCP tool result. Owns next-step policy; guidance copy lives in
     # {Playbook}.
     class Outcome # rubocop:disable Metrics/ClassLength -- next-step policy + factories stay co-located
-      # Matches {ConfigArgument} XOR +ArgumentError+ messages.
-      XOR_ERROR = /exactly one of config or yaml/
+      # Raised when an outcome is built with a wrong-typed next step or payload.
+      class InvalidError < Html2rss::ContractError; end
+
       NextStep = Data.define(:name, :guidance)
 
       ##
@@ -22,7 +23,7 @@ module Html2rss
         ##
         # @param name [Symbol, String]
         # @return [NextStep]
-        def self.[](name) = ALL.fetch(name.to_sym) { raise ArgumentError, "unknown next_step: #{name.inspect}" }
+        def self.[](name) = ALL.fetch(name.to_sym) { raise InvalidOption, "unknown next_step: #{name.inspect}" }
       end
 
       ##
@@ -31,8 +32,8 @@ module Html2rss
       # @param guidance [String]
       # @param payload [Hash]
       def initialize(ok:, next_step:, guidance:, payload:) # rubocop:disable Naming/MethodParameterName -- +ok+ is the envelope field
-        raise ArgumentError, 'next_step must be a NextStep' unless next_step.is_a?(NextStep)
-        raise ArgumentError, 'payload must be a Hash' unless payload.is_a?(Hash)
+        raise InvalidError, 'next_step must be a NextStep' unless next_step.is_a?(NextStep)
+        raise InvalidError, 'payload must be a Hash' unless payload.is_a?(Hash)
 
         super(ok: !!ok, next_step:, guidance: guidance.to_s.freeze, payload: payload.dup.freeze)
       end
@@ -60,7 +61,7 @@ module Html2rss
         ##
         # @param report [PageRecon::Diagnostics::Report]
         # @return [Outcome]
-        def inspect(report:)
+        def inspect_report(report:)
           next_step = inspect_next_step(report)
           guidance = Playbook.inspect_guidance(report)
           new(ok: true, next_step:, guidance:, payload: report.to_wire_h)
@@ -194,7 +195,7 @@ module Html2rss
           NextStep[:scrape]
         end
 
-        def capture_next_step(articles_count:, has_selectors:, native_feed: nil)
+        def capture_next_step(articles_count:, has_selectors:, native_feed:)
           return NextStep[:done] if native_feed
 
           articles_count.positive? && has_selectors ? NextStep[:test] : NextStep[:inspect]
@@ -205,7 +206,6 @@ module Html2rss
 
           kind = test_result.failure_kind
           return NextStep[:validate] if kind&.schema?
-          return NextStep[:capture] if kind&.execution? || kind&.min_items? || kind&.quality?
 
           NextStep[:capture]
         end
@@ -219,12 +219,18 @@ module Html2rss
           warnings = test_result.quality_report&.warnings
           return base if warnings.nil? || warnings.empty?
 
-          "#{base} Review payload.quality_report warnings: #{warnings.join(', ')}."
+          "#{base} Review payload.quality_report warnings: #{warnings.join(', ')}.#{items_without_url_hint(warnings)}"
+        end
+
+        def items_without_url_hint(warnings)
+          return '' unless warnings.include?(:items_without_url)
+
+          ' Items were dropped for having no URL: fix the selectors.url selector (it must match a link on each item).'
         end
 
         def capture_payload(yaml:, articles_count:, has_selectors:, channel_title:, requested_strategy:, # rubocop:disable Metrics/ParameterLists
-                            segment_strategy:, selected_strategy:, admission_drops:, native_feed: nil,
-                            suggested_channel_url: nil)
+                            segment_strategy:, selected_strategy:, admission_drops:, native_feed:,
+                            suggested_channel_url:)
           {
             yaml:, articles_count:, has_selectors:, channel_title:, requested_strategy: requested_strategy.to_s,
             **(native_feed ? { native_feed: native_feed.to_s } : {}),
@@ -238,15 +244,10 @@ module Html2rss
         def next_step_for_error(error)
           case error
           when RequestService::BotasaurusConfigurationError then NextStep[:read_runtime]
-          when Contract::UnpublishedRequestError then NextStep[:validate]
-          when ArgumentError then argument_error_next_step(error)
+          when Contract::UnpublishedRequestError, ConfigArgument::ExclusiveInputError then NextStep[:validate]
           else NextStep[:inspect]
           end
         end
-
-        def argument_error_next_step(error)
-          XOR_ERROR.match?(error.message) ? NextStep[:validate] : NextStep[:inspect]
-        end
       end
     end
   end

data/lib/html2rss/mcp/runtime.rb

@@ -11,34 +11,64 @@ module Html2rss
         :mcp_contract_version,
         :catalog_fingerprint,
         :tools,
-        :botasaurus_configured
+        :botasaurus_configured,
+        :response_cache_ttl
       )
 
-      module_function
+      # Seconds an initial page fetch is reused when +HTML2RSS_RESPONSE_CACHE_TTL+ is unset.
+      DEFAULT_RESPONSE_CACHE_TTL = 300
+      # Values of +HTML2RSS_RESPONSE_CACHE_TTL+ that disable the cache.
+      CACHE_OFF_VALUES = %w[0 off false].freeze
+      private_constant :CACHE_OFF_VALUES
 
-      ##
-      # @return [Boolean] whether Botasaurus transport is configured in this process
-      def botasaurus_configured?
-        !ENV['BOTASAURUS_SCRAPER_URL'].to_s.strip.empty?
-      end
+      class << self
+        ##
+        # @return [Boolean] whether Botasaurus transport is configured in this process
+        def botasaurus_configured?
+          !ENV['BOTASAURUS_SCRAPER_URL'].to_s.strip.empty?
+        end
 
-      ##
-      # @return [Snapshot] runtime capabilities and catalog identity for MCP clients
-      def snapshot
-        Snapshot.new(
-          version: Html2rss::VERSION,
-          mcp_contract_version: Contract::MCP_CONTRACT_VERSION,
-          catalog_fingerprint: Contract.catalog_fingerprint,
-          tools: Contract.catalog_tools,
-          botasaurus_configured: botasaurus_configured?
-        )
-      end
+        ##
+        # Installs the initial-fetch cache for the long-lived MCP process, so an agent iterating
+        # +inspect -> capture -> validate -> test+ on one URL fetches it once per TTL window.
+        # +HTML2RSS_RESPONSE_CACHE_TTL+ sets the seconds ({DEFAULT_RESPONSE_CACHE_TTL} when unset);
+        # +0+, +off+ or +false+ disables caching. An unusable value logs a warning and uses the default.
+        #
+        # @return [void]
+        def install_response_cache!
+          ttl = response_cache_ttl
+          RequestService.response_cache = ttl && RequestService::ResponseCache.new(ttl:)
+        end
+
+        ##
+        # @return [Snapshot] runtime capabilities and catalog identity for MCP clients
+        def snapshot
+          Snapshot.new(
+            version: Html2rss::VERSION,
+            mcp_contract_version: Contract::MCP_CONTRACT_VERSION,
+            catalog_fingerprint: Contract.catalog_fingerprint,
+            tools: Contract.catalog_tools,
+            botasaurus_configured: botasaurus_configured?,
+            response_cache_ttl: RequestService.response_cache&.ttl
+          )
+        end
+
+        private
+
+        def response_cache_ttl
+          raw = ENV['HTML2RSS_RESPONSE_CACHE_TTL'].to_s.strip.downcase
+          return DEFAULT_RESPONSE_CACHE_TTL if raw.empty?
+          return if CACHE_OFF_VALUES.include?(raw)
+
+          ttl = Integer(raw, 10, exception: false)
+          ttl&.positive? ? ttl : invalid_cache_ttl(raw)
+        end
 
-      ##
-      # @param strategy [String, Symbol, nil]
-      # @return [Symbol]
-      def coerce_strategy(strategy)
-        (strategy || :auto).to_sym
+        def invalid_cache_ttl(raw)
+          Log.warn("HTML2RSS_RESPONSE_CACHE_TTL=#{raw.inspect} is not a positive integer; " \
+                   "using #{DEFAULT_RESPONSE_CACHE_TTL}s")
+          DEFAULT_RESPONSE_CACHE_TTL
+        end
       end
     end
   end

data/lib/html2rss/mcp/server/tools.rb

@@ -36,9 +36,9 @@ module Html2rss
             input_schema: Contract::INSPECT_INPUT_SCHEMA,
             annotations: Contract::ANNOTATIONS_OPEN_WORLD,
             call: lambda { |url:, strategy: 'auto', **|
-              Outcome.inspect(
+              Outcome.inspect_report(
                 report: PageRecon::Diagnostics.call(
-                  url:, strategy: Runtime.coerce_strategy(strategy), deep: false
+                  url:, strategy: Option.strategy(strategy), deep: false
                 )
               )
             }
@@ -51,7 +51,7 @@ module Html2rss
             input_schema: Contract::RECON_INPUT_SCHEMA,
             annotations: Contract::ANNOTATIONS_OPEN_WORLD,
             call: lambda { |url:, strategy: 'auto', **|
-              Outcome.recon(result: Html2rss.recon(url, strategy: Runtime.coerce_strategy(strategy)))
+              Outcome.recon(result: Html2rss.recon(url, strategy: Option.strategy(strategy)))
             }
           ),
           Tool.new(
@@ -63,7 +63,7 @@ module Html2rss
             annotations: Contract::ANNOTATIONS_OPEN_WORLD,
             call: lambda { |urls:, strategy: 'auto', concurrency: Batch::DEFAULT_CONCURRENCY, limit: 10, **|
               Outcome.batch_scrape(
-                Batch.batch_scrape(urls:, strategy: Runtime.coerce_strategy(strategy), concurrency:, limit:)
+                Batch.batch_scrape(urls:, strategy: Option.strategy(strategy), concurrency:, limit:)
               )
             }
           ),
@@ -76,7 +76,7 @@ module Html2rss
             annotations: Contract::ANNOTATIONS_OPEN_WORLD,
             call: lambda { |urls:, strategy: 'auto', concurrency: Batch::DEFAULT_CONCURRENCY, **|
               Outcome.batch_inspect(
-                Batch.batch_inspect(urls:, strategy: Runtime.coerce_strategy(strategy), concurrency:)
+                Batch.batch_inspect(urls:, strategy: Option.strategy(strategy), concurrency:)
               )
             }
           ),
@@ -89,7 +89,7 @@ module Html2rss
             annotations: Contract::ANNOTATIONS_OPEN_WORLD,
             call: lambda { |urls:, strategy: 'auto', concurrency: Batch::DEFAULT_CONCURRENCY, **|
               Outcome.batch_recon(
-                Batch.batch_recon(urls:, strategy: Runtime.coerce_strategy(strategy), concurrency:)
+                Batch.batch_recon(urls:, strategy: Option.strategy(strategy), concurrency:)
               )
             }
           ),
@@ -136,7 +136,7 @@ module Html2rss
                               compare_enhance: false, **kwargs|
               feed_config = ConfigArgument.parse(config:, yaml:).config
               test_args = { min_items:, strict_quality:, compare_enhance: }
-              test_args[:strategy] = Runtime.coerce_strategy(kwargs[:strategy]) if kwargs.key?(:strategy)
+              test_args[:strategy] = Option.strategy(kwargs[:strategy]) if kwargs.key?(:strategy)
               Outcome.test(Html2rss.test(feed_config, **test_args))
             }
           ),
@@ -163,7 +163,7 @@ module Html2rss
           # @param items_selector [String, nil]
           # @return [Outcome]
           def scrape_outcome(url:, strategy: 'auto', limit: 25, items_selector: nil)
-            wire = Batch.scrape_wire(url:, strategy: Runtime.coerce_strategy(strategy), limit:, items_selector:)
+            wire = Batch.scrape_wire(url:, strategy: Option.strategy(strategy), limit:, items_selector:)
             Outcome.scrape(
               items: wire[:items],
               requested_strategy: wire[:strategy],
@@ -189,7 +189,7 @@ module Html2rss
           # @return [Outcome]
           def capture_outcome(url:, strategy: 'auto', items_selector: nil, force: false, topics: nil, title: nil, # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
                               summary: nil, enhance: nil, limit: nil, max_redirects: nil, max_requests: nil)
-            plan = Runtime.coerce_strategy(strategy)
+            plan = Option.strategy(strategy)
             result = Html2rss::Capture.build(
               url,
               strategy: plan,

data/lib/html2rss/mcp/server.rb

@@ -23,6 +23,9 @@ module Html2rss
       # Supported transport names.
       TRANSPORTS = Set[:stdio, :http].freeze
 
+      # Raised when the HTTP transport's optional gems (+rackup+, +webrick+) cannot be loaded.
+      class HttpTransportUnavailable < Html2rss::Error; end
+
       # Declarative MCP resource registrations consumed by {register_resources}.
       RESOURCES = [
         {
@@ -95,10 +98,13 @@ module Html2rss
         #
         # @param transport [Symbol] +:stdio+ or +:http+
         # @param port [Integer] port for HTTP transport
+        # @raise [InvalidOption] for an unknown transport
+        # @raise [HttpTransportUnavailable] when +:http+ is requested without the rackup and webrick gems
         def start(transport: :stdio, port: 8080)
-          raise ArgumentError, "Unknown transport: #{transport.inspect}" unless TRANSPORTS.include?(transport)
+          raise InvalidOption, "Unknown transport: #{transport.inspect}" unless TRANSPORTS.include?(transport)
 
           configure_daemon_logging!
+          Runtime.install_response_cache!
           app = build
           Log.info(start_banner(transport:, port:))
           return start_http(app, port:) if transport == :http
@@ -204,7 +210,7 @@ module Html2rss
             Logger: Html2rss.logger
           )
         rescue LoadError => error
-          raise LoadError,
+          raise HttpTransportUnavailable,
                 'HTTP transport requires the rackup and webrick gems ' \
                 "(#{error.message}). Install them or use --transport stdio."
         end
@@ -218,8 +224,11 @@ module Html2rss
           Contract.response(Outcome.from_error(error))
         end
 
-        def handle_tool_call
-          Contract.response(yield)
+        def handle_tool_call(&)
+          outcome, cache_ages = RequestService.observe_cache_hits(&)
+          Contract.response(outcome, cache_ages:)
+        rescue Html2rss::ContractError
+          raise
         rescue StandardError => error
           tool_error_response(error)
         end