html2rss 0.28.0 → 0.29.1

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

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module MCP
+    module Server
+      ##
+      # MCP tool registration and outcome mapping over public html2rss APIs.
+      module Tools # rubocop:disable Metrics/ModuleLength -- declarative registry + substantive handlers
+        # Declarative MCP tool registrations consumed by {register_all}.
+        TOOLS = [
+          {
+            name: 'scrape',
+            kind: :url,
+            description: 'One-shot article extraction as JSON Feed items. ' \
+                         'Use when you need articles now without a saved config. ' \
+                         'strategy "auto" triggers fallback chain (faraday → botasaurus) for JS-rendered sites.',
+            input_schema: Contract::SCRAPE_INPUT_SCHEMA,
+            handler: :scrape_outcome
+          },
+          {
+            name: 'inspect',
+            kind: :url,
+            description: 'Diagnostic page analysis (scrapers, SST, segments, final URL, status, ' \
+                         'rel=alternate feeds). Use recon for BUILD/DEFER/DROP verdict and native_feed preference.',
+            input_schema: Contract::INSPECT_INPUT_SCHEMA,
+            call: lambda { |url:, strategy: 'auto', **|
+              Outcome.inspect(
+                report: PageRecon::Diagnostics.call(
+                  url:, strategy: Runtime.coerce_strategy(strategy), deep: false
+                )
+              )
+            }
+          },
+          {
+            name: 'recon',
+            kind: :url,
+            description: 'Curation verdict and native_feed preference for a URL. ' \
+                         'Use after inspect when alternates warrant deeper recon, or when you need BUILD/DEFER/DROP.',
+            input_schema: Contract::RECON_INPUT_SCHEMA,
+            call: lambda { |url:, strategy: 'auto', **|
+              Outcome.recon(result: Html2rss.recon(url, strategy: Runtime.coerce_strategy(strategy)))
+            }
+          },
+          {
+            name: 'batch_scrape',
+            kind: :batch,
+            batch_method: :batch_scrape,
+            limit_default: 10,
+            description: 'Scrape multiple URLs in parallel with per-URL error isolation. ' \
+                         'Returns structured JSON Feed items and extraction counts.',
+            input_schema: Contract::BATCH_SCRAPE_INPUT_SCHEMA
+          },
+          {
+            name: 'batch_inspect',
+            kind: :batch,
+            batch_method: :batch_inspect,
+            description: 'Inspect multiple URLs in parallel with per-URL error isolation. ' \
+                         'Returns final redirected URLs, status codes, and rel="alternate" feeds.',
+            input_schema: Contract::BATCH_INSPECT_INPUT_SCHEMA
+          },
+          {
+            name: 'batch_recon',
+            kind: :batch,
+            batch_method: :batch_recon,
+            description: 'Run recon across multiple URLs in parallel with per-URL error isolation. ' \
+                         'Returns verdict, native_feed, and surface classification per URL.',
+            input_schema: Contract::BATCH_RECON_INPUT_SCHEMA
+          },
+          {
+            name: 'capture',
+            kind: :capture,
+            description: 'Derive a reusable html2rss feed config from a URL. ' \
+                         'Use when the goal is a durable YAML (then test → apply). ' \
+                         'Returns YAML inside payload.yaml (same serializer as CLI capture). ' \
+                         'Draft only — catalog feeds still need directory.topics and title/url; ' \
+                         'enhance defaults from admission evidence (false when chrome drops are high). ' \
+                         'Full schema options live in resource html2rss://schema.',
+            input_schema: Contract::CAPTURE_INPUT_SCHEMA,
+            handler: :capture_outcome
+          },
+          {
+            name: 'validate',
+            kind: :config_xor,
+            description: 'Validate a feed config hash XOR yaml string against the html2rss JSON schema. ' \
+                         'Call before test. Failures return isError with payload.errors. ' \
+                         'Full schema lives in resource html2rss://schema.',
+            input_schema: Contract::CONFIG_XOR_SCHEMA,
+            annotations: Contract::ANNOTATIONS_VALIDATE,
+            call: lambda { |config: nil, yaml: nil, **|
+              validation = Html2rss::Config.validate(ConfigArgument.parse(config:, yaml:).config)
+              Outcome.validate(errors: validation.success? ? nil : validation.errors.to_h)
+            }
+          },
+          {
+            name: 'test',
+            kind: :config_xor,
+            description: 'Validate schema and execute live extraction (asserting >= min_items items). ' \
+                         'Call after capture or validate; on success next_step is apply. ' \
+                         'Returns test summary in payload with sample items, timing, failure_kind, ' \
+                         'and quality_report (warnings for duplicate URLs, junk titles, native feed). ' \
+                         'Set strict_quality to fail on duplicate URLs, >50% junk titles, or short titles.',
+            input_schema: Contract::TEST_INPUT_SCHEMA,
+            call: lambda { |config: nil, yaml: nil, min_items: 1, strict_quality: false,
+                              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_result = Html2rss.test(feed_config, **test_args)
+              Outcome.test(test_result)
+            }
+          },
+          {
+            name: 'apply',
+            kind: :config_xor,
+            description: 'Apply a validated feed config (hash XOR yaml) and return RSS XML in payload.rss. ' \
+                         'isError when the feed has zero items (ship gate). payload.item_count is RSS item count. ' \
+                         'Use after test succeeds.',
+            input_schema: Contract::APPLY_INPUT_SCHEMA,
+            handler: :apply_outcome
+          }
+        ].freeze
+
+        class << self # rubocop:disable Metrics/ClassLength -- registration engine + handlers
+          ##
+          # Registers all MCP tools on +server+ via +registrar+ (Server.define_envelope_tool).
+          #
+          # @param server [::MCP::Server]
+          # @param registrar [Proc]
+          # @return [void]
+          def register_all(server, registrar:)
+            TOOLS.each { |entry| register_tool(server, registrar, entry) }
+          end
+
+          private
+
+          def register_tool(server, registrar, entry)
+            case entry[:kind]
+            when :url then register_url_tool(server, registrar, entry)
+            when :batch then register_batch_tool(server, registrar, entry)
+            when :config_xor then register_config_xor_tool(server, registrar, entry)
+            when :capture then register_capture_tool(server, registrar, entry)
+            else raise ArgumentError, "unknown tool kind: #{entry[:kind].inspect}"
+            end
+          end
+
+          def register_url_tool(server, registrar, entry)
+            handler = entry[:handler] ? method(entry[:handler]) : entry[:call]
+            registrar.call(
+              server,
+              name: entry[:name],
+              description: entry[:description],
+              input_schema: entry[:input_schema],
+              annotations: entry.fetch(:annotations, Contract::ANNOTATIONS_OPEN_WORLD)
+            ) do |**kwargs|
+              handler.call(**tool_kwargs(kwargs))
+            end
+          end
+
+          def register_batch_tool(server, registrar, entry) # rubocop:disable Metrics/MethodLength
+            name = entry[:name]
+            batch_method = entry[:batch_method]
+            limit_default = entry[:limit_default]
+            registrar.call(
+              server,
+              name:,
+              description: entry[:description],
+              input_schema: entry[:input_schema]
+            ) do |urls:, strategy: 'auto', **kwargs|
+              concurrency = kwargs.fetch(:concurrency, Batch::DEFAULT_CONCURRENCY)
+              batch_args = { urls:, strategy: Runtime.coerce_strategy(strategy), concurrency: }
+              batch_args[:limit] = kwargs.fetch(:limit, limit_default) unless limit_default.nil?
+              Outcome.public_send(name, Batch.public_send(batch_method, **batch_args))
+            end
+          end
+
+          def register_config_xor_tool(server, registrar, entry)
+            handler = entry[:handler] ? method(entry[:handler]) : entry[:call]
+            registrar.call(
+              server,
+              name: entry[:name],
+              description: entry[:description],
+              input_schema: entry[:input_schema],
+              annotations: entry.fetch(:annotations, Contract::ANNOTATIONS_OPEN_WORLD)
+            ) do |**kwargs|
+              handler.call(**tool_kwargs(kwargs))
+            end
+          end
+
+          def register_capture_tool(server, registrar, entry)
+            handler = method(entry[:handler])
+            registrar.call(
+              server,
+              name: entry[:name],
+              description: entry[:description],
+              input_schema: entry[:input_schema]
+            ) do |**kwargs|
+              handler.call(**tool_kwargs(kwargs))
+            end
+          end
+
+          def tool_kwargs(inputs)
+            args = inputs.dup
+            args.delete(:server_context)
+            args
+          end
+
+          def scrape_outcome(url:, strategy: 'auto', limit: 25, items_selector: nil)
+            wire = Batch.scrape_wire(url:, strategy: Runtime.coerce_strategy(strategy), limit:, items_selector:)
+            Outcome.scrape(
+              items: wire[:items],
+              requested_strategy: wire[:strategy],
+              channel_title: wire[:channel_title],
+              admission_drops: wire[:admission_drops],
+              botasaurus_configured: Runtime.botasaurus_configured?
+            )
+          end
+
+          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)
+            result = Html2rss::Capture.build(
+              url,
+              strategy: plan,
+              items_selector:,
+              force:,
+              topics:,
+              title:,
+              summary:,
+              enhance:,
+              limit:,
+              max_redirects:,
+              max_requests:
+            )
+            Outcome.capture(
+              yaml: result.yaml,
+              articles_count: result.articles_count,
+              has_selectors: result.has_selectors,
+              channel_title: result.channel_title,
+              requested_strategy: plan,
+              segment_strategy: result.segment_strategy,
+              selected_strategy: result.selected_strategy,
+              admission_drops: result.admission_drops,
+              native_feed: result.native_feed,
+              suggested_channel_url: result.suggested_channel_url
+            )
+          end
+
+          def apply_outcome(url:, config: nil, yaml: nil)
+            feed_config = HashUtil.deep_dup(ConfigArgument.parse(config:, yaml:).config)
+            feed_config[:channel] ||= {}
+            feed_config[:channel][:url] ||= url
+            outcome, feed_result = FeedPipeline.new(feed_config).to_outcome_and_result
+            apply_feed_outcome(feed_config, feed_result, outcome)
+          end
+
+          def apply_feed_outcome(feed_config, feed_result, outcome) # rubocop:disable Metrics/MethodLength -- quality_report + RSS payload
+            rss = feed_result.to_rss
+            quality_report = Html2rss::Test.quality_report_for(
+              rss.items,
+              channel_url: feed_config.dig(:channel, :url).to_s,
+              raw_config: feed_config,
+              feed_result:,
+              pipeline_outcome: outcome,
+              probe_native_feed: false
+            )
+            Outcome.apply(
+              rss: rss.to_s,
+              item_count: rss.items.size,
+              empty: feed_result.empty?,
+              quality_report: quality_report.to_h
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/html2rss/mcp/server.rb

@@ -20,6 +20,68 @@ module Html2rss
       # Loopback bind for HTTP transport (local use only).
       HTTP_BIND_HOST = '127.0.0.1'
 
+      # Declarative MCP resource registrations consumed by {register_resources}.
+      RESOURCES = [
+        {
+          uri: 'html2rss://schema',
+          name: 'Configuration JSON Schema',
+          description: 'Full JSON Schema for html2rss feed configurations',
+          mime_type: 'application/json',
+          body: lambda {
+            [{ uri: 'html2rss://schema', mimeType: 'application/json',
+               text: Html2rss::Config.json_schema_json(pretty: true) }]
+          }
+        },
+        {
+          uri: 'html2rss://extractors',
+          name: 'Available Extractors',
+          description: 'Registered extractor names for selector configs ' \
+                       '(full option docs live in html2rss://schema $defs)',
+          mime_type: 'application/json',
+          body: lambda {
+            extractors = Html2rss::Selectors::Extractors::NAME_TO_CLASS.keys.map(&:to_s).sort
+            [{ uri: 'html2rss://extractors', mimeType: 'application/json',
+               text: JSON.pretty_generate(extractors) }]
+          }
+        },
+        {
+          uri: 'html2rss://strategies',
+          name: 'Available Strategies',
+          description: 'Published MCP request strategy names',
+          mime_type: 'application/json',
+          body: lambda {
+            [{ uri: 'html2rss://strategies', mimeType: 'application/json',
+               text: JSON.generate(Contract::STRATEGIES) }]
+          }
+        },
+        {
+          uri: 'html2rss://runtime',
+          name: 'Runtime capabilities',
+          description: 'Gem version, MCP contract version, catalog fingerprint, tool names, and Botasaurus config',
+          mime_type: 'application/json',
+          body: lambda {
+            [{ uri: 'html2rss://runtime', mimeType: 'application/json',
+               text: JSON.pretty_generate(Runtime.snapshot.to_h) }]
+          }
+        }
+      ].freeze
+
+      # Declarative MCP prompt registrations; SDK argument objects built at {register_prompts} time.
+      PROMPTS = [
+        {
+          name: 'scrape-webpage',
+          description: 'Guided one-shot scrape: one scrape call (auto already falls back)',
+          arguments: [{ name: 'url', description: 'URL to scrape', required: true }],
+          body: ->(args) { Outcome::Playbook.scrape_webpage_prompt(args.fetch(:url)) }
+        },
+        {
+          name: 'capture-feed-config',
+          description: 'Guided capture → test → apply; YAML draft plus catalog rewrite',
+          arguments: [{ name: 'url', description: 'URL to analyze', required: true }],
+          body: ->(args) { Outcome::Playbook.capture_feed_config_prompt(args.fetch(:url)) }
+        }
+      ].freeze
+
       class << self # rubocop:disable Metrics/ClassLength
         ##
         # Starts the MCP server with the given transport.
@@ -140,28 +202,8 @@ module Html2rss
                 "(#{error.message}). Install them or use --transport stdio."
         end
 
-        def instructions_text # rubocop:disable Metrics/MethodLength -- agent decision tree is the published contract
-          <<~TEXT.strip
-            html2rss MCP — decide which tool to call:
-
-            1. Need articles now (no saved config)? → scrape_url (1 call)
-               - strategy "auto" runs Faraday → Botasaurus AutoFallback. Do not retry with explicit faraday after auto.
-               - Empty scrape is still success (articles-now). Follow next_step / guidance (read_runtime if Botasaurus unset).
-            2. Need a reusable feed YAML? → capture_config → validate_config → apply_config
-               - capture_config returns YAML inside payload.yaml. Draft only: if destination is html2rss-configs, rewrite for directory.topics and explicit channel title/url. Strive enhance: true (false only when chrome leaks).
-               - validate_config / apply_config accept config hash XOR yaml string.
-               - apply_config isError when zero RSS items (ship gate). Confirm payload.item_count.
-            3. Weak scrape/capture or recon (final URL, status, https→http, rel=alternate feeds)? → inspect_url only if weak or recon.
-            4. Have a config already? → validate_config (must succeed) → apply_config
-            5. Schema / extractors / strategies / runtime → resources html2rss://schema|extractors|strategies|runtime
-
-            Prefer capture_config for durable config; scrape_url for one-shot extraction.
-            Follow envelope next_step and guidance. Botasaurus needs BOTASAURUS_SCRAPER_URL in this process env (boolean at html2rss://runtime; the URL is never returned).
-          TEXT
-        end
-
-        def botasaurus_configured?
-          !ENV['BOTASAURUS_SCRAPER_URL'].to_s.strip.empty?
+        def instructions_text
+          Outcome::Playbook.instructions
         end
 
         def tool_error_response(error)
@@ -175,7 +217,7 @@ module Html2rss
           tool_error_response(error)
         end
 
-        # rubocop:disable Metrics/MethodLength -- listing fields stay together
+        # rubocop:disable-next Metrics/MethodLength -- listing fields stay together
         def define_envelope_tool(server, name:, description:, input_schema:,
                                  annotations: Contract::ANNOTATIONS_OPEN_WORLD)
           run = method(:handle_tool_call)
@@ -190,201 +232,38 @@ module Html2rss
             run.call { yield(**kwargs) }
           end
         end
-        # rubocop:enable Metrics/MethodLength
 
         def register_tools(server)
-          register_scrape_url(server)
-          register_inspect_url(server)
-          register_capture_config(server)
-          register_validate_config(server)
-          register_apply_config(server)
-        end
-
-        def register_scrape_url(server)
-          define_envelope_tool(
-            server,
-            name: 'scrape_url',
-            description: 'One-shot article extraction as JSON Feed items. ' \
-                         'Use when you need articles now without a saved config. ' \
-                         'strategy "auto" triggers fallback chain (faraday → botasaurus) for JS-rendered sites.',
-            input_schema: Contract::SCRAPE_INPUT_SCHEMA
-          ) do |server_context:, url:, strategy: 'auto', limit: 25, items_selector: nil| # rubocop:disable Lint/UnusedBlockArgument
-            scrape_outcome(url:, strategy:, limit:, items_selector:)
-          end
-        end
-
-        def scrape_outcome(url:, strategy:, limit:, items_selector:)
-          plan = (strategy || :auto).to_sym
-          feed_result = Html2rss.auto_feed_result(url, strategy: plan, limit:, items_selector:)
-          feed = feed_result.to_json_feed
-          Outcome.scrape(
-            items: feed[:items] || [],
-            requested_strategy: plan,
-            channel_title: feed[:title],
-            admission_drops: feed_result.status.admission_drops,
-            botasaurus_configured: botasaurus_configured?
-          )
-        end
-
-        def register_inspect_url(server)
-          define_envelope_tool(
-            server,
-            name: 'inspect_url',
-            description: 'Diagnostic page analysis (scrapers, SST, segments) plus recon: ' \
-                         'final_url, status, scheme_downgrade, rel=alternate RSS/Atom feeds. ' \
-                         'Use when scrape/capture is weak or you need those recon facts.',
-            input_schema: Contract::INSPECT_INPUT_SCHEMA
-          ) do |server_context:, url:, strategy: 'auto'| # rubocop:disable Lint/UnusedBlockArgument
-            Outcome.inspect(payload: Inspect.call(url:, strategy:))
-          end
-        end
-
-        def register_capture_config(server) # rubocop:disable Metrics/MethodLength
-          define_envelope_tool(
-            server,
-            name: 'capture_config',
-            description: 'Derive a reusable html2rss feed config from a URL. ' \
-                         'Use when the goal is a durable YAML (then validate_config). ' \
-                         'Returns YAML inside payload.yaml (same serializer as CLI capture). ' \
-                         'Draft only — catalog feeds still need directory.topics and title/url; ' \
-                         'strive enhance: true. Full schema options live in resource html2rss://schema.',
-            input_schema: Contract::CAPTURE_INPUT_SCHEMA
-          ) do |server_context:, url:, strategy: 'auto', items_selector: nil| # rubocop:disable Lint/UnusedBlockArgument
-            capture_outcome(url:, strategy:, items_selector:)
-          end
-        end
-
-        def capture_outcome(url:, strategy:, items_selector:) # rubocop:disable Metrics/MethodLength -- CaptureResult maps 1:1 onto Outcome
-          plan = (strategy || :auto).to_sym
-          result = Html2rss::Capture.build(url, strategy: plan, items_selector:)
-          Outcome.capture(
-            yaml: Config.to_yaml(result.config),
-            articles_count: result.articles_count,
-            has_selectors: result.has_selectors,
-            channel_title: result.channel_title,
-            requested_strategy: plan,
-            segment_strategy: result.segment_strategy,
-            selected_strategy: result.selected_strategy,
-            admission_drops: result.admission_drops
-          )
-        end
-
-        def register_validate_config(server) # rubocop:disable Metrics/MethodLength -- description is the published contract
-          define_envelope_tool(
-            server,
-            name: 'validate_config',
-            description: 'Validate a feed config hash XOR yaml string against the html2rss JSON schema. ' \
-                         'Call before apply_config. Failures return isError with payload.errors. ' \
-                         'Full schema lives in resource html2rss://schema.',
-            input_schema: Contract::CONFIG_XOR_SCHEMA,
-            annotations: Contract::ANNOTATIONS_VALIDATE
-          ) do |server_context:, config: nil, yaml: nil| # rubocop:disable Lint/UnusedBlockArgument
-            validate_outcome(config:, yaml:)
-          end
-        end
-
-        def validate_outcome(config:, yaml:)
-          validation = Html2rss::Config.validate(ConfigArgument.parse(config:, yaml:).config)
-          Outcome.validate(errors: validation.success? ? nil : validation.errors.to_h)
-        end
-
-        def register_apply_config(server)
-          define_envelope_tool(
-            server,
-            name: 'apply_config',
-            description: 'Apply a validated feed config (hash XOR yaml) and return RSS XML in payload.rss. ' \
-                         'isError when the feed has zero items (ship gate). payload.item_count is RSS item count. ' \
-                         'Use after validate_config succeeds.',
-            input_schema: Contract::APPLY_INPUT_SCHEMA
-          ) do |server_context:, url:, config: nil, yaml: nil| # rubocop:disable Lint/UnusedBlockArgument
-            apply_outcome(url:, config:, yaml:)
+          Tools.register_all(server, registrar: method(:define_envelope_tool))
+        end
+
+        def register_resources(server)
+          RESOURCES.each do |entry|
+            server.define_resource(
+              uri: entry[:uri],
+              name: entry[:name],
+              description: entry[:description],
+              mime_type: entry[:mime_type]
+            ) do |server_context: nil| # rubocop:disable Lint/UnusedBlockArgument
+              entry[:body].call
+            end
           end
         end
 
-        def apply_outcome(url:, config:, yaml:)
-          feed_config = ConfigArgument.parse(config:, yaml:).config
-          feed_config[:channel] ||= {}
-          feed_config[:channel][:url] ||= url
-          feed_result = Html2rss.feed_result(feed_config)
-          rss = feed_result.to_rss
-          Outcome.apply(rss: rss.to_s, item_count: rss.items.size, empty: feed_result.empty?)
-        end
-
-        def register_resources(server) # rubocop:disable Metrics/MethodLength
-          configured = method(:botasaurus_configured?)
-          server.define_resource(
-            uri: 'html2rss://schema',
-            name: 'Configuration JSON Schema',
-            description: 'Full JSON Schema for html2rss feed configurations',
-            mime_type: 'application/json'
-          ) do |server_context: nil| # rubocop:disable Lint/UnusedBlockArgument
-            schema = Html2rss::Config.json_schema_json(pretty: true)
-            [{ uri: 'html2rss://schema', mimeType: 'application/json', text: schema }]
-          end
-
-          server.define_resource(
-            uri: 'html2rss://extractors',
-            name: 'Available Extractors',
-            description: 'Registered extractor names for selector configs ' \
-                         '(full option docs live in html2rss://schema $defs)',
-            mime_type: 'application/json'
-          ) do |server_context: nil| # rubocop:disable Lint/UnusedBlockArgument
-            extractors = Html2rss::Selectors::Extractors::NAME_TO_CLASS.keys.map(&:to_s).sort
-            [{ uri: 'html2rss://extractors', mimeType: 'application/json',
-               text: JSON.pretty_generate(extractors) }]
-          end
-
-          server.define_resource(
-            uri: 'html2rss://strategies',
-            name: 'Available Strategies',
-            description: 'Published MCP request strategy names',
-            mime_type: 'application/json'
-          ) do |server_context: nil| # rubocop:disable Lint/UnusedBlockArgument
-            [{ uri: 'html2rss://strategies', mimeType: 'application/json',
-               text: JSON.generate(Contract::STRATEGIES) }]
-          end
-
-          server.define_resource(
-            uri: 'html2rss://runtime',
-            name: 'Runtime capabilities',
-            description: 'Whether optional transports are configured in this MCP process (never leaks secrets)',
-            mime_type: 'application/json'
-          ) do |server_context: nil| # rubocop:disable Lint/UnusedBlockArgument
-            [{ uri: 'html2rss://runtime', mimeType: 'application/json',
-               text: JSON.pretty_generate(botasaurus_configured: configured.call) }]
-          end
-        end
-
-        def register_prompts(server)
-          register_scrape_webpage_prompt(server)
-          register_capture_feed_config_prompt(server)
-        end
-
-        def register_scrape_webpage_prompt(server) # rubocop:disable Metrics/MethodLength -- SDK prompt types stay together
+        def register_prompts(server) # rubocop:disable Metrics/MethodLength -- prompt argument mapping
           to_result = method(:prompt_result)
-          text_for = method(:scrape_webpage_text)
-          server.define_prompt(
-            name: 'scrape-webpage',
-            description: 'Guided one-shot scrape: one scrape_url call (auto already falls back)',
-            arguments: [
-              ::MCP::Prompt::Argument.new(name: 'url', description: 'URL to scrape', required: true)
-            ]
-          ) do |args, server_context:| # rubocop:disable Lint/UnusedBlockArgument
-            to_result.call(text_for.call(args.fetch(:url)))
-          end
-        end
-
-        def register_capture_feed_config_prompt(server) # rubocop:disable Metrics/MethodLength -- SDK prompt types stay together
-          to_result = method(:prompt_result)
-          text_for = method(:capture_feed_config_text)
-          server.define_prompt(
-            name: 'capture-feed-config',
-            description: 'Guided capture → validate → apply; YAML draft plus catalog rewrite',
-            arguments: [
-              ::MCP::Prompt::Argument.new(name: 'url', description: 'URL to analyze', required: true)
-            ]
-          ) do |args, server_context:| # rubocop:disable Lint/UnusedBlockArgument
-            to_result.call(text_for.call(args.fetch(:url)))
+          PROMPTS.each do |entry|
+            arguments = entry[:arguments].map do |spec|
+              ::MCP::Prompt::Argument.new(name: spec[:name], description: spec[:description],
+                                          required: spec.fetch(:required, false))
+            end
+            server.define_prompt(
+              name: entry[:name],
+              description: entry[:description],
+              arguments:
+            ) do |args, server_context:| # rubocop:disable Lint/UnusedBlockArgument
+              to_result.call(entry[:body].call(args))
+            end
           end
         end
 
@@ -395,26 +274,6 @@ module Html2rss
             ]
           )
         end
-
-        def scrape_webpage_text(url)
-          <<~MSG.strip
-            Scrape #{url} with scrape_url (strategy auto). One call is enough — auto already runs Faraday then Botasaurus.
-            Follow envelope next_step and guidance. Call inspect_url only if articles are empty/weak or you need recon (final_url, status, scheme_downgrade, alternate_feeds).
-            Do not retry scrape_url with explicit faraday after auto. Read html2rss://runtime if next_step is read_runtime.
-            Return payload.items (not a raw JSON array).
-          MSG
-        end
-
-        def capture_feed_config_text(url)
-          <<~MSG.strip
-            Build a reusable html2rss feed config for #{url}:
-            1) capture_config — YAML is payload.yaml. Check payload.articles_count and payload.has_selectors. Strive to keep enhance: true (false only when chrome leaks into items).
-            2) Follow next_step. If weak or you need recon, inspect_url. Auto already hops to Botasaurus; do not retry capture with botasaurus unless Faraday was blocked.
-            3) validate_config with yaml (or config hash) — must not be isError
-            4) apply_config — isError if zero items. Confirm payload.item_count before shipping.
-            If the destination is html2rss-configs, rewrite the draft for directory.topics and explicit channel title/url. Return YAML.
-          MSG
-        end
       end
     end
   end

data/lib/html2rss/mcp.rb

@@ -3,6 +3,9 @@
 module Html2rss
   ##
   # MCP server for AI client consumption.
+  #
+  # {include:file:lib/html2rss/mcp/README.md}
+  #
   # Lazy-loads the mcp gem; no cost when the server is not started.
   module MCP
     class << self