woods 2.0.0 → 2.1.0

data/lib/woods/mcp/index_reader.rb

@@ -46,12 +46,15 @@ module Woods
 
       # Most output directories contain one unit type. RailsSourceExtractor
       # emits gem_source units in rails_source/, while GraphQL publishes four
-      # subtypes in graphql/. Directory-filtered search retains its historical
-      # family labels while artifact readers preserve the actual unit type.
+      # subtypes in graphql/. Search accepts directory-family aliases and
+      # concrete types, and returns each unit's actual public type.
       UNIT_TYPES_BY_DIR = DIR_TO_TYPE.transform_values { |type| [type].freeze }
                                      .merge('rails_source' => %w[rails_source gem_source].freeze,
                                             'graphql' => %w[graphql_type graphql_mutation graphql_resolver graphql_query].freeze)
                                      .freeze
+      UNIT_TYPE_TO_DIR = UNIT_TYPES_BY_DIR.each_with_object({}) do |(directory, types), result|
+        types.each { |type| result[type] = directory }
+      end.freeze
 
       # Maximum number of loaded unit files to cache in memory.
       MAX_UNIT_CACHE = 50
@@ -375,14 +378,14 @@ module Woods
       def find_unit(identifier, type: nil)
         if type
           return with_pinned_generation do
-            dir = UNIT_TYPES_BY_DIR.find { |_, types| types.include?(type) }&.first
+            dir = UNIT_TYPE_TO_DIR[type] || TYPE_TO_DIR[type]
             next nil unless dir
             raise IOError, "symlink unit directory: #{dir}" if current_payload_dir.join(dir).symlink?
 
             next nil unless search_index_entries(dir).any? { |entry| entry['identifier'] == identifier }
 
             unit = read_published_unit(dir, identifier)
-            unit if unit['type'] == type
+            unit if unit['type'] == type || !UNIT_TYPE_TO_DIR.key?(type)
           end
         end
         ensure_fresh!
@@ -489,6 +492,7 @@ module Woods
       # @api private
       def search_within_pin(query = nil, types: nil, fields: %w[identifier], limit: 20,
                             exact_prefix: nil, exact_suffix: nil, packages: nil, source_paths: nil)
+        types = normalize_search_types(types)
         scope = search_scope(packages, source_paths, types)
         prefix = exact_prefix.blank? ? nil : exact_prefix.downcase
         suffix = exact_suffix.blank? ? nil : exact_suffix.downcase
@@ -508,7 +512,7 @@ module Woods
         phase2_scanned = 0
 
         begin
-          dirs = scope || !types ? TYPE_DIRS : types.filter_map { |type| TYPE_TO_DIR[type] }.uniq
+          dirs = types ? types.map { |type| UNIT_TYPE_TO_DIR.fetch(type) }.uniq : TYPE_DIRS
           # Identifier matches retain priority. Deep candidates are interleaved
           # across types so an early large directory cannot consume their budget.
           phase2_queues = {}
@@ -516,7 +520,13 @@ module Woods
             dirs.each do |dir|
               type_name = DIR_TO_TYPE[dir]
               entries = search_index_entries(dir)
-              entries = scoped_search_entries(entries, dir, scope) if scope
+              entries = if scope
+                          scoped_search_entries(entries, dir, scope)
+                        elsif types
+                          typed_search_entries(entries, dir, types, results)
+                        else
+                          entries
+                        end
               if entries.size > 1
                 matching_count = entries.count do |entry|
                   identifier_passes_filters?(entry['identifier'], pattern, prefix, suffix)
@@ -527,11 +537,13 @@ module Woods
               end
 
               entries.each do |entry|
-                type_name = entry.fetch('scope_type', DIR_TO_TYPE[dir])
                 id = entry['identifier']
                 next unless identifier_passes_prefix_suffix?(id, prefix, suffix)
 
                 if fields.include?('identifier') && pattern.match?(id)
+                  type_name = search_entry_type(entry, dir, results)
+                  next unless type_name
+
                   results.add(identifier: id, type: type_name, match_field: 'identifier')
                   throw :search_done if results.result_limit_reached?
 
@@ -539,7 +551,7 @@ module Woods
                 end
                 next unless fields.include?('metadata') || fields.include?('source_code')
 
-                (phase2_queues[dir] ||= []) << [type_name, id]
+                (phase2_queues[dir] ||= []) << [entry, dir]
               end
             end
 
@@ -553,10 +565,21 @@ module Woods
                   results.stop('scan_budget')
                   throw :search_done
                 end
-                type_name, id = queue.shift
+                entry, dir = queue.shift
+                id = entry['identifier']
                 progressed = true
                 phase2_scanned += 1
-                unit = scope ? scope.metadata_store.find(StorageIdentity.key(id, type_name)) : load_search_unit(type_name, id)
+                type_name = search_entry_type(entry, dir, results)
+                next unless type_name
+
+                unit = if scope
+                         scope.metadata_store.find(StorageIdentity.key(id, type_name))
+                       else
+                         readable_search_unit(type_name, id, results)
+                       end
+                next unless unit
+
+                type_name = unit['type']
                 field = if fields.include?('source_code') && unit['source_code'] && pattern.match?(unit['source_code'])
                           'source_code'
                         elsif fields.include?('metadata') && unit['metadata'] && pattern.match?(unit['metadata'].to_json)
@@ -593,6 +616,53 @@ module Woods
       end
       private :search_scope
 
+      def normalize_search_types(types)
+        return nil if types.nil? || types == []
+        unless types.is_a?(Array) && types.all?(String)
+          raise ArgumentError, 'search types must be an array of type names'
+        end
+
+        types.flat_map do |type|
+          if TYPE_TO_DIR.key?(type)
+            UNIT_TYPES_BY_DIR.fetch(TYPE_TO_DIR.fetch(type))
+          elsif UNIT_TYPE_TO_DIR.key?(type)
+            [type]
+          else
+            raise ArgumentError, "unknown search type: #{type}"
+          end
+        end.uniq
+      end
+      private :normalize_search_types
+
+      # Modern summaries carry their public type. Resolve legacy family types
+      # only when a type filter or matching candidate needs that identity.
+      def search_entry_type(entry, dir, results)
+        actual = entry['scope_type'] || entry['type']
+        possible = UNIT_TYPES_BY_DIR.fetch(dir)
+        actual ||= possible.one? ? possible.first : readable_search_unit(DIR_TO_TYPE.fetch(dir), entry['identifier'], results)&.fetch('type')
+        return actual if possible.include?(actual)
+
+        results.stop('unreadable_or_corrupt_source')
+        nil
+      end
+      private :search_entry_type
+
+      def readable_search_unit(type, identifier, results)
+        load_search_unit(type, identifier)
+      rescue JSON::ParserError, IOError, SystemCallError
+        results.stop('unreadable_or_corrupt_source')
+        nil
+      end
+      private :readable_search_unit
+
+      def typed_search_entries(entries, dir, types, results)
+        entries.filter_map do |entry|
+          actual = search_entry_type(entry, dir, results)
+          entry.merge('scope_type' => actual) if types.include?(actual)
+        end
+      end
+      private :typed_search_entries
+
       def scoped_search_entries(entries, dir, scope)
         entries.flat_map do |entry|
           UNIT_TYPES_BY_DIR.fetch(dir).filter_map do |type|
@@ -870,7 +940,7 @@ module Woods
             expected_dir.join('manifest.json').to_s, File::RDONLY
           )
           file.flock(File::LOCK_SH)
-          marker = @generation.current
+          marker = published_marker
           resolved = resolve_payload_dir(marker)
           marker_still_matches = marker.number.zero? || (same_generation?(marker) && resolved == expected_dir)
           if marker_still_matches && expected_dir.directory?
@@ -881,13 +951,16 @@ module Woods
           file.flock(File::LOCK_UN)
           file.close
           load_generation(marker) unless marker.number.zero?
+        rescue Woods::Generation::InvalidMarker
+          file&.close unless file&.closed?
+          raise
         rescue Errno::ENOENT
           file&.close unless file&.closed?
           return if saw_missing_manifest && missing_manifest_dir == expected_dir
 
           saw_missing_manifest = true
           missing_manifest_dir = expected_dir
-          marker = @generation.current
+          marker = published_marker
           load_generation(marker) unless marker.number.zero?
         end
       end
@@ -934,13 +1007,26 @@ module Woods
         return nil if @pin_depth.positive?
 
         signature = generation_signature
-        return nil if signature.nil? || signature == @generation_signature
+        if signature.nil?
+          published_marker if @loaded_generation
+          return nil
+        end
+        return nil if signature == @generation_signature
 
+        marker = published_marker
+        resolve_payload_dir(marker)
+        load_generation(marker) unless marker.number.zero? || same_generation?(marker)
         @generation_signature = signature
-        marker = @generation.current
-        return nil if marker.number.zero? || same_generation?(marker)
+        @loaded_generation
+      end
 
-        load_generation(marker)
+      def published_marker
+        marker = @generation.current!
+        if marker.number.zero? && @loaded_generation&.positive? && current_payload_dir != @index_dir
+          raise Woods::Generation::InvalidMarker, 'Published generation marker is missing'
+        end
+
+        marker
       end
 
       # Adopt one already-read marker as the reader's loaded generation.
@@ -949,8 +1035,9 @@ module Woods
       # @param marker [Woods::Generation::Marker]
       # @return [void]
       def load_generation(marker)
+        directory = resolve_payload_dir(marker)
         reload!
-        @payload_dir = resolve_payload_dir(marker)
+        @payload_dir = directory
         @loaded_token = marker.token
         @loaded_generation = marker.number
       end
@@ -968,7 +1055,7 @@ module Woods
 
         marker = Woods::Generation.new(output_dir: @index_dir).current
         resolve_payload_dir(marker).join('manifest.json').file?
-      rescue TypeError, NoMethodError
+      rescue TypeError, NoMethodError, Woods::Generation::InvalidMarker
         # Match Bootstrapper's startup preflight for malformed marker shapes.
         # Keep this local: errors during later generation refresh still surface.
         false
@@ -995,7 +1082,12 @@ module Woods
       # @param marker [Woods::Generation::Marker]
       # @return [Pathname]
       def resolve_payload_dir(marker)
-        Woods::Generation.new(output_dir: @index_dir).payload_dir(marker)
+        directory = Woods::Generation.new(output_dir: @index_dir).payload_dir(marker)
+        if marker.payload && !marker.payload.empty? && directory == @index_dir
+          raise Woods::Generation::InvalidMarker, 'Published generation payload is unavailable or outside the index'
+        end
+
+        directory
       end
 
       # Compare the *token*, not the number.
@@ -1103,9 +1195,11 @@ module Woods
       #   generation file
       def generation_signature
         stat = File.stat(@generation.path)
-        [stat.mtime.to_f, stat.size, stat.ino]
-      rescue SystemCallError
+        [stat.mtime.to_f, stat.ctime.to_f, stat.size, stat.ino]
+      rescue Errno::ENOENT
         nil
+      rescue SystemCallError
+        raise Woods::Generation::InvalidMarker, 'Published generation marker is unavailable'
       end
 
       # Case-insensitive literal prefix/suffix check on an identifier.
@@ -1211,8 +1305,9 @@ module Woods
       # Read the selected type bucket, never the identifier-only lookup map.
       # Keep the existing per-file signature checks and LRU cache for deep reads.
       def load_search_unit(type, identifier)
-        data = load_unit(TYPE_TO_DIR.fetch(type), unit_filename(identifier))
-        unless valid_published_unit?(data, TYPE_TO_DIR.fetch(type), identifier)
+        directory = TYPE_TO_DIR[type] || UNIT_TYPE_TO_DIR.fetch(type)
+        data = load_unit(directory, unit_filename(identifier))
+        unless valid_published_unit?(data, directory, identifier)
           raise IOError, "typed unit identity mismatch: #{type}:#{identifier}"
         end
 
@@ -1263,7 +1358,13 @@ module Woods
         data = File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
           raise IOError, "non-regular unit file: #{dir}/#{filename}" unless file.stat.file?
 
-          JSON.parse(file.read)
+          # Decode the checked descriptor's bytes as UTF-8, independent of the
+          # process locale. JSON parsers may accept invalid UTF-8 verbatim, so
+          # validate before parsing instead of replacing malformed source bytes.
+          content = file.binmode.read.force_encoding(Encoding::UTF_8)
+          raise JSON::ParserError, "invalid UTF-8 in unit file: #{dir}/#{filename}" unless content.valid_encoding?
+
+          JSON.parse(content)
         end
         unless valid_published_unit?(data, dir, identifier)
           raise IOError, "typed unit identity mismatch: #{dir}/#{filename}"

data/lib/woods/mcp/index_reader_pinning.rb

@@ -64,6 +64,15 @@ module Woods
           return super unless reader && tool_names&.include?(request[:name])
 
           reader.with_pinned_generation { super }
+        rescue Woods::Generation::InvalidMarker
+          message = 'Published generation marker is unavailable or malformed; run woods:validate and restore or rebuild the index.'
+          meta = { error_code: :corrupt_artifact, tool: request[:name] }
+          meta[:completeness] = SearchResults.unavailable if request[:name] == 'search'
+          ::MCP::Tool::Response.new(
+            [{ type: 'text', text: message }], error: true,
+                                               structured_content: { text: message },
+                                               meta: meta
+          ).to_h
         end
 
         def read_resource_contents(request, **kwargs)
@@ -71,6 +80,13 @@ module Woods
           return super unless reader
 
           reader.with_pinned_generation { super }
+        rescue Woods::Generation::InvalidMarker => e
+          raise ::MCP::Server::RequestHandlerError.new(
+            'Published generation marker is unavailable or malformed.', request,
+            error_type: :internal_error, original_error: e,
+            error_code: ::JsonRpcHandler::ErrorCode::INTERNAL_ERROR,
+            error_data: { uri: request[:uri], error_code: 'corrupt_artifact' }
+          )
         end
       end
     end

data/lib/woods/mcp/origin_guard.rb

@@ -2,7 +2,7 @@
 
 require 'json'
 
-require_relative '../util/host_guard'
+require_relative 'origin_policy'
 
 module Woods
   module MCP
@@ -21,17 +21,13 @@ module Woods
     # also requiring Host to appear in the allow-list (or to be a loopback
     # address), we close that gap even when Rails is bound to 0.0.0.0.
     #
-    # Port-matching: an allow-list entry WITHOUT a port (`http://localhost`)
-    # matches that host on any port. An entry WITH a port (`http://localhost:3000`)
-    # requires an exact port match. Specify explicit ports when port isolation
-    # matters.
+    # Cross-origin entries match exactly. A portless entry also permits
+    # same-authority requests on other ports; cross-port browser clients need
+    # their actual origin explicitly configured, as required by the SDK.
     #
     # Also answers CORS preflight (OPTIONS) with the matching allow-list.
     class OriginGuard
-      DEFAULT_ALLOWED = %w[
-        http://localhost http://127.0.0.1 http://[::1]
-        https://localhost https://127.0.0.1 https://[::1]
-      ].freeze
+      DEFAULT_ALLOWED = OriginPolicy::DEFAULT_ORIGINS
 
       # Hosts that always pass the Host-header check even without an explicit
       # allow-list entry — they resolve to loopback by definition and cannot
@@ -56,6 +52,7 @@ module Woods
       #   which runs after Rails railtie initializers captured the middleware
       #   arguments — still takes effect (#183). Empty/nil falls back to
       #   {DEFAULT_ALLOWED}.
+      # @param policy [OriginPolicy, nil] Captured policy also passed to the SDK
       # @param path [String, nil] When set, only requests whose PATH_INFO
       #   starts with this prefix are guarded — everything else passes
       #   straight through to the app. Nil (the default) guards every request.
@@ -82,27 +79,35 @@ module Woods
         method = env['REQUEST_METHOD']
         host = env['HTTP_HOST']
 
-        return forbidden if origin && !origin_allowed?(origin)
-        return forbidden_host if host && !host_allowed?(host)
+        return forbidden unless policy.origin_allowed?(origin, host: host)
+        return forbidden_host unless policy.host_allowed?(host)
 
         return preflight(origin) if method == 'OPTIONS'
 
         status, headers, body = @app.call(env)
-        headers = cors_headers(origin).merge(headers) if origin && origin_allowed?(origin)
+        headers = cors_headers(origin).merge(headers) if origin
         [status, headers, body]
       end
 
+      # The same lazily captured immutable policy is passed to the transport.
+      # @return [OriginPolicy]
+      def policy
+        return @policy if @policy
+
+        @policy_mutex.synchronize do
+          @policy ||= OriginPolicy.new(allowed_origins: @allowed_source.call)
+        end
+      end
+
       private
 
-      def initialize_options(app, allowed_origins: nil, path: nil, enabled: nil)
+      def initialize_options(app, allowed_origins: nil, path: nil, enabled: nil, policy: nil)
         @app = app
         @path = path
         @enabled = enabled
-        if allowed_origins.respond_to?(:call)
-          @allowed_source = allowed_origins
-        else
-          build_allow_list(allowed_origins)
-        end
+        @policy = policy
+        @policy_mutex = Mutex.new
+        @allowed_source = allowed_origins.respond_to?(:call) ? allowed_origins : -> { allowed_origins }
       end
 
       # @param env [Hash] Rack environment
@@ -114,66 +119,8 @@ module Woods
         true
       end
 
-      # Normalize a raw allow-list into `@allowed` + `@allowed_hosts`.
-      #
-      # @param origins [Array<String>, nil]
-      # @return [Array<String>] the normalized allow-list
-      def build_allow_list(origins)
-        allowed = Array(origins).compact.reject { |o| o.to_s.strip.empty? }.map { |o| normalize(o) }
-        allowed = DEFAULT_ALLOWED.dup if allowed.empty?
-        @allowed_hosts = allowed.map { |o| extract_host(o) }.compact.uniq
-        @allowed = allowed
-      end
-
-      # The allow-list, resolving a deferred source on first use. Memoized —
-      # configuration is settled by the time the first request arrives.
-      #
-      # @return [Array<String>]
-      def allowed
-        @allowed || build_allow_list(@allowed_source.call)
-      end
-
-      # @return [Array<String>] hosts extracted from the allow-list
-      def allowed_hosts
-        allowed
-        @allowed_hosts
-      end
-
-      def normalize(origin)
-        origin.to_s.sub(%r{/\z}, '').downcase
-      end
-
-      def extract_host(origin)
-        host = origin.to_s.sub(%r{\Ahttps?://}, '').sub(%r{/.*\z}, '').downcase
-        host.empty? ? nil : host
-      end
-
-      def host_allowed?(host)
-        # Canonicalize (strip port, trailing dot, IPv6 brackets) via the
-        # shared helper so Qdrant and OriginGuard stay in sync on bypass
-        # notations. `normalized` keeps the port for literal allow-list
-        # lookups; `bare` drops it for loopback matching.
-        normalized = host.to_s.downcase.sub(/\.\z/, '')
-        bare = Util::HostGuard.canonicalize(host)
-
-        # Reject non-canonical numeric hosts. Net::HTTP / getaddrinfo
-        # would happily resolve `0x7f000001` or `2130706433` to 127.0.0.1,
-        # bypassing the loopback allow-list.
-        return false if Util::HostGuard.suspicious_numeric_host?(bare)
-
-        return true if LOOPBACK_HOSTS.include?(bare)
-
-        allowed_hosts.include?(normalized) || allowed_hosts.include?(bare)
-      end
-
-      def origin_allowed?(origin)
-        return false if origin.match?(/[[:cntrl:]]/)
-
-        allowed.include?(normalize(origin)) || allowed.include?(normalize(origin).sub(/:\d+\z/, ''))
-      end
-
       def preflight(origin)
-        headers = origin && origin_allowed?(origin) ? cors_headers(origin) : {}
+        headers = origin ? cors_headers(origin) : {}
         [204, headers, []]
       end
 

data/lib/woods/mcp/origin_policy.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative '../util/host_guard'
+
+module Woods
+  module MCP
+    # Immutable HTTP policy shared by Woods preflight and the MCP transport.
+    # Explicit cross-origin entries normalize HTTP(S) default ports. A portless entry also permits
+    # same-authority requests on another port, which the SDK accepts natively.
+    # No request header is rewritten and SDK rebinding protection stays enabled.
+    class OriginPolicy
+      LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+      DEFAULT_ORIGINS = %w[
+        http://localhost http://127.0.0.1 http://[::1]
+        https://localhost https://127.0.0.1 https://[::1]
+      ].freeze
+
+      # @param allowed_origins [Array<String>, nil] Explicit browser origins
+      def initialize(allowed_origins: nil)
+        entries = Array(allowed_origins).compact.reject do |entry|
+          entry.to_s.valid_encoding? && entry.to_s.strip.empty?
+        end
+        @explicit_origins = entries.map { |entry| configured_origin(entry) }.uniq.freeze
+        @allowed = (@explicit_origins.empty? ? DEFAULT_ORIGINS : @explicit_origins).freeze
+        @allowed_hosts = @explicit_origins.map do |origin|
+          host = authority(origin)
+          # SDK bare IPv6 host entries omit brackets; host:port entries retain
+          # them. URI#host alone retains brackets and loses explicit ports.
+          (host.end_with?(']') ? host[1...-1] : host).freeze
+        end.uniq.freeze
+        @transport_options = { allowed_origins: transport_origins, allowed_hosts: @allowed_hosts }.freeze
+        freeze
+      end
+
+      # @return [Hash] Constructor options supported by the MCP SDK
+      attr_reader :transport_options
+
+      # @param host [String, nil] Unmodified HTTP Host header
+      # @return [Boolean] Whether the request authority is allowed
+      def host_allowed?(host)
+        return true if host.nil?
+        return false unless host.is_a?(String) && host.valid_encoding?
+
+        parsed = parsed_origin("http://#{host}")
+        return false unless parsed
+
+        hostname = parsed.hostname.downcase
+        return false if Util::HostGuard.suspicious_numeric_host?(hostname)
+        return true if LOOPBACK_HOSTS.include?(hostname)
+
+        @allowed_hosts.include?(host.downcase) || @allowed_hosts.include?(hostname)
+      end
+
+      # @param origin [String, nil] Unmodified HTTP Origin header
+      # @param host [String, nil] Unmodified HTTP Host header
+      # @return [Boolean] Whether preflight and SDK dispatch can both accept it
+      def origin_allowed?(origin, host:)
+        return true if origin.nil?
+        return false unless parsed_origin(origin)
+
+        normalized = normalized_origin(origin)
+        return true if @explicit_origins.include?(normalized)
+        return false unless @allowed.include?(normalized) || @allowed.include?(normalized.sub(/:\d+\z/, ''))
+        return false unless host.is_a?(String) && host.valid_encoding?
+
+        # Matches the SDK's same-authority rule. The origin's scheme selects
+        # its default port; request.scheme is unreliable behind reverse proxies.
+        default_port = normalized.start_with?('https://') ? ':443' : ':80'
+        authority(normalized).delete_suffix(default_port) == host.downcase.delete_suffix(default_port)
+      end
+
+      private
+
+      def configured_origin(entry)
+        raw = entry.to_s
+        normalized = raw.downcase.sub(%r{/\z}, '') if raw.valid_encoding?
+        unless parsed_origin(normalized)
+          label = raw.b.byteslice(0, 160).inspect
+          raise ArgumentError, "Invalid MCP allowed origin #{label}: expected http(s)://host[:port] without a path"
+        end
+
+        normalized_origin(normalized).freeze
+      end
+
+      def normalized_origin(origin)
+        value = origin.downcase
+        value.delete_suffix(value.start_with?('https://') ? ':443' : ':80')
+      end
+
+      # The SDK compares configured origins literally. Include equivalent
+      # default-port spellings without rewriting the incoming request headers.
+      def transport_origins
+        @explicit_origins.flat_map do |origin|
+          parsed = parsed_origin(origin)
+          default = parsed.scheme == 'https' ? 443 : 80
+          parsed.port == default ? [origin, "#{origin}:#{default}"] : [origin]
+        end.uniq.map(&:freeze).freeze
+      end
+
+      def authority(origin)
+        origin.sub(%r{\Ahttps?://}, '')
+      end
+
+      # Parse only serialized HTTP origins, never URLs with paths, userinfo,
+      # query strings, fragments or whitespace. The comparison layer handles
+      # default-port equivalence separately from parsing.
+      def parsed_origin(origin)
+        return unless origin.is_a?(String) && origin.valid_encoding? && origin.ascii_only?
+        return if origin.match?(/[[:space:][:cntrl:]]/)
+
+        parsed = URI.parse(origin)
+        return unless %w[http https].include?(parsed.scheme&.downcase)
+        return unless parsed.host && !parsed.host.empty?
+        return unless parsed.path.to_s.empty? && !parsed.userinfo && !parsed.query && !parsed.fragment
+        return unless parsed.port&.between?(1, 65_535)
+
+        parsed
+      rescue URI::InvalidURIError, ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/woods/mcp/renderers/markdown_renderer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../../source_contributors'
+
 module Woods
   module MCP
     module Renderers
@@ -16,7 +18,11 @@ module Woods
           lines = []
           lines << "## #{data['identifier']} (#{data['type']})"
           lines << ''
-          lines << "**File:** `#{data['file_path']}`" if data['file_path']
+          if SourceContributors.multiple?(data)
+            lines << SourceContributors.label(data)
+          elsif data['file_path']
+            lines << "**File:** `#{data['file_path']}`"
+          end
           lines << "**Namespace:** #{data['namespace']}" if data['namespace']
           lines << ''
 

data/lib/woods/mcp/renderers/plain_renderer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../../source_contributors'
+
 module Woods
   module MCP
     module Renderers
@@ -14,7 +16,7 @@ module Woods
           lines = []
           lines << "#{data['identifier']} (#{data['type']})"
           lines << DIVIDER
-          lines << "File: #{data['file_path']}" if data['file_path']
+          lines << SourceContributors.label(data) if data['file_path']
           lines << "Namespace: #{data['namespace']}" if data['namespace']
           lines << ''
 

data/lib/woods/mcp/search_results.rb

@@ -65,7 +65,13 @@ module Woods
           }
         }
         result[:partial] = true unless complete
-        result[:hint] = NARROWING_HINT unless complete
+        unless complete
+          result[:hint] = if @reason == 'unreadable_or_corrupt_source'
+                            'Run woods:validate and repair or republish unreadable unit artifacts.'
+                          else
+                            NARROWING_HINT
+                          end
+        end
         result[:note] = note unless note.nil? || note.empty?
         result
       end