yardmcp 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9d5b8dbd42ee1273aeeff0a838eff6163149bb15d919fad96ca2805334e278a
-  data.tar.gz: 969fb019698cd02d4ee29c6d27c8133ecb9b9c88f804759fda894ff96093acd3
+  metadata.gz: 7f804ad6257e87c3c7a2e9ea805b7fb778f4f026006f5c231ab444906ad18c9a
+  data.tar.gz: 90177775b4c69504a1cb6a127137f9bee11b91748815f673a7bf85f0e23af9ae
 SHA512:
-  metadata.gz: 40134673bfd201aa6e191a963f36d650e63beef01972c0b7c4e86f8d4932660ad6b529bd4755f0914d4a29357c8d80983439c539782d72837ee306e38a386c0e
-  data.tar.gz: '015892a44b95e688079da5b935d6913df45a634f90a125735e3f644b52872bf067b05a0b2bf4952a153e4db6bb4eef3ab9303ffa4fe8bf191c7dae6fc550e300'
+  metadata.gz: ff475a131b82fa0a0292e0409828047089cb647d4ee0ff439420107e29970f468e5ba25394781536e31538fd21ad083548e8b83479af67f6e82bd1330a3ae719
+  data.tar.gz: 6b3e94a29e92f4057e327f5df3a42540b79f66977f48b981563f56bc7d66378e780932c1bbf246295ccb56bd3ba15baacc9169b27be570097d3b230e3a2caf41

data/README.md

@@ -16,6 +16,7 @@ This is useful for building documentation browsers, code assistants, or integrat
 ## Features
 
 - **List Gems:** See all installed gems with YARD documentation
+- **Build Gem Docs:** Explicitly build a local YARD index for an installed gem
 - **List Classes/Modules:** Explore all classes/modules in a gem
 - **Fetch Documentation:** Get docstrings, tags, parameters, return types, and more for any class/module/method
 - **List Children:** List constants, classes, modules, and methods under a namespace
@@ -26,6 +27,7 @@ This is useful for building documentation browsers, code assistants, or integrat
 - **Search:** Fuzzy/full-text search across all documentation
 - **Source Location:** Find the file and line number for any object
 - **Code Snippet:** Fetch the source code for any object
+- **MCP Resources:** Read YARD docs and source via `yard://` resource URIs
 
 ## Installation
 
@@ -55,10 +57,20 @@ Start the server:
 yardmcp
 ```
 
+Read-only query tools do not build missing YARD indexes. If a gem is installed
+but has no local YARD index yet, run:
+
+```sh
+yard gems <gemname>
+```
+
+or call `BuildGemDocsTool` explicitly.
+
 ### Tool List
 
 The following tools are available (use `tools/list` to discover):
 - ListGemsTool
+- BuildGemDocsTool
 - ListClassesTool
 - GetDocTool
 - ChildrenTool
@@ -70,7 +82,29 @@ The following tools are available (use `tools/list` to discover):
 - AncestorsTool
 - RelatedObjectsTool
 
-See the code in `lib/yardmcp.rb` for argument details and return formats.
+Tool results return standard MCP text content and machine-readable data in
+`structuredContent`. Tool execution failures return `isError: true` without
+local stack traces.
+
+All tools publish `outputSchema` metadata in `tools/list`.
+
+Object-oriented tool results include `resource_uris` when `gem_name` is supplied,
+so clients can pivot from a tool result to the corresponding documentation or
+source resource.
+
+### Resources
+
+The server exposes templated MCP resources:
+
+- `yard://gem/{gem_name}/object/{+path}` returns JSON documentation for a YARD object.
+- `yard://gem/{gem_name}/source/{+path}` returns source text for a YARD object.
+
+Examples:
+
+```text
+yard://gem/yard/object/YARD::Registry
+yard://gem/yard/source/YARD::CodeObjects::Base#name
+```
 
 ## Development
 
@@ -96,4 +130,4 @@ See the code in `lib/yardmcp.rb` for argument details and return formats.
 
 ## License
 
-MIT License. See [LICENSE](LICENSE) for details.
+MIT License. See [LICENSE](LICENSE) for details.

data/lib/yardmcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module YardMCP
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/yardmcp.rb

@@ -3,21 +3,37 @@
 
 require 'fast_mcp'
 require 'json'
+require 'logger'
 require 'rubygems'
 require 'yard'
 require 'singleton'
 require_relative 'yardmcp/version'
 
 # Utility class for YARD operations
-class YardUtils
+class YardUtils # rubocop:disable Metrics/ClassLength
   include Singleton
 
+  MAX_SOURCE_CHARS = 20_000
+
+  class DocumentationError < StandardError; end
+
+  class AmbiguousObjectError < DocumentationError
+    attr_reader :path, :candidates
+
+    def initialize(path, candidates)
+      @path = path
+      @candidates = candidates
+      super("Multiple gems contain '#{path}'. Pass gem_name.")
+    end
+  end
+
   attr_reader :libraries, :logger, :object_to_gem
 
   def initialize
     @libraries = {}
     @object_to_gem = {}
     @last_loaded_gem = nil
+    @class_cache = {}
     @logger = Logger.new($stderr)
     @logger.level = Logger::INFO unless ENV['DEBUG']
     build_index
@@ -31,38 +47,51 @@ class YardUtils
   def load_yardoc_for_gem(gem_name)
     return if @last_loaded_gem == gem_name
 
-    spec = libraries[gem_name].first
-    ver = "= #{spec.version}"
-    dir = YARD::Registry.yardoc_file_for_gem(spec.name, ver)
-    build_docs(gem_name) unless yardoc_exists?(dir)
-    raise "Yardoc not found for #{gem_name}" unless yardoc_exists?(dir)
+    spec = gem_spec!(gem_name)
+    dir = yardoc_path_for(spec)
+    raise DocumentationError, "YARD documentation is not indexed for gem '#{gem_name}'" unless yardoc_exists?(dir)
 
-    YARD::Registry.load_yardoc(dir)
+    YARD::Registry.load!(dir)
     @last_loaded_gem = gem_name
   end
 
   # Ensures the correct .yardoc is loaded for the given object path
   def ensure_yardoc_loaded_for_object!(object_path)
-    # TODO: Handle multiple gems for the same object path, use some heuristic to determine the correct gem
-    gem_name = @object_to_gem[object_path]&.first
-    raise "No documentation found for #{object_path}" unless gem_name
+    gem_names = @object_to_gem[object_path]
+    raise DocumentationError, "No indexed documentation contains '#{object_path}'. Pass gem_name if you know the gem." if gem_names.nil? || gem_names.empty?
+    raise AmbiguousObjectError.new(object_path, gem_candidates(gem_names)) if gem_names.uniq.size > 1
 
-    load_yardoc_for_gem(gem_name)
+    load_yardoc_for_gem(gem_names.first)
   end
 
   # Lists all installed gems that have a .yardoc file available.
   #
   # @return [Array<String>] An array of gem names with .yardoc files.
   def list_gems
+    libraries.keys.select do |name|
+      yardoc_exists?(yardoc_path_for(gem_spec!(name)))
+    end.sort
+  end
+
+  def list_installed_gems
     libraries.keys.sort
   end
 
+  def gem_candidates(gem_names)
+    gem_names.uniq.sort.map do |gem_name|
+      {
+        gem_name:,
+        versions: Array(libraries[gem_name]).map { |library| library.version.to_s }.uniq.sort
+      }
+    end
+  end
+
   # Lists all classes and modules in the loaded YARD registry.
   #
   # @return [Array<String>] An array of fully qualified class/module paths.
   def list_classes(gem_name)
     load_yardoc_for_gem(gem_name)
-    YARD::Registry.all(:class, :module).map(&:path).sort
+    @class_cache[gem_name] ||= YARD::Registry.all(:class, :module).map(&:path).sort
   end
 
   # Fetches documentation and metadata for a YARD object (class/module/method).
@@ -71,14 +100,7 @@ class YardUtils
   # @return [Hash] A hash containing type, name, namespace, visibility, docstring, parameters, return, and source.
   # @raise [RuntimeError] if the object is not found in the registry.
   def get_doc(path, gem_name = nil) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/MethodLength
-    if gem_name
-      # Load the specific gem's yardoc
-      load_yardoc_for_gem(gem_name)
-    else
-      ensure_yardoc_loaded_for_object!(path)
-    end
-    obj = YARD::Registry.at(path)
-    raise 'Object not found' unless obj
+    obj = object_for!(path, gem_name)
 
     tags = obj.tags.map do |tag|
       {
@@ -102,7 +124,7 @@ class YardUtils
                   text: obj.tag('return').text
                 }
               end,
-      source: obj.respond_to?(:source) ? obj.source : nil,
+      source: capped_source(obj.respond_to?(:source) ? obj.source : nil),
       tags:
     }
 
@@ -121,13 +143,8 @@ class YardUtils
   # @param path [String] The YARD path of the namespace.
   # @return [Array<String>] An array of child object paths.
   # @raise [RuntimeError] if the object is not found in the registry.
-  def children(path)
-    ensure_yardoc_loaded_for_object!(path)
-    obj = YARD::Registry.at(path)
-    unless obj
-      logger.error "Object not found: #{path}"
-      return []
-    end
+  def children(path, gem_name = nil)
+    obj = object_for!(path, gem_name)
     obj.respond_to?(:children) ? obj.children.map(&:path) : []
   end
 
@@ -136,13 +153,8 @@ class YardUtils
   # @param path [String] The YARD path of the class/module.
   # @return [Array<String>] An array of method paths.
   # @raise [RuntimeError] if the object is not found in the registry.
-  def methods_list(path)
-    ensure_yardoc_loaded_for_object!(path)
-    obj = YARD::Registry.at(path)
-    unless obj
-      logger.error "Object not found: #{path}"
-      return []
-    end
+  def methods_list(path, gem_name = nil)
+    obj = object_for!(path, gem_name)
     obj.respond_to?(:meths) ? obj.meths.map(&:path) : []
   end
 
@@ -151,16 +163,11 @@ class YardUtils
   # @param path [String] The YARD path of the class/module.
   # @return [Hash] A hash with :superclass (String or nil), :included_modules (Array<String>), and :mixins (Array<String>).
   # @raise [RuntimeError] if the object is not found in the registry.
-  def hierarchy(path) # rubocop:disable Metrics/CyclomaticComplexity
-    ensure_yardoc_loaded_for_object!(path)
-    obj = YARD::Registry.at(path)
-    unless obj
-      logger.error "Object not found: #{path}"
-      return []
-    end
+  def hierarchy(path, gem_name = nil)
+    obj = object_for!(path, gem_name)
     {
       superclass: obj.respond_to?(:superclass) && obj.superclass ? obj.superclass.path : nil,
-      included_modules: obj.respond_to?(:included_modules) ? obj.included_modules.map(&:path) : [],
+      included_modules: obj.respond_to?(:mixins) ? obj.mixins.map(&:path) : [],
       mixins: obj.respond_to?(:mixins) ? obj.mixins.map(&:path) : []
     }
   end
@@ -169,13 +176,8 @@ class YardUtils
   #
   # @param path [String] The YARD path of the class/module.
   # @return [Array<String>] An array of ancestor paths.
-  def ancestors(path)
-    ensure_yardoc_loaded_for_object!(path)
-    obj = YARD::Registry.at(path)
-    unless obj
-      logger.error "Object not found: #{path}"
-      return []
-    end
+  def ancestors(path, gem_name = nil)
+    obj = object_for!(path, gem_name)
     obj.respond_to?(:inheritance_tree) ? obj.inheritance_tree(true).map(&:path) : []
   end
 
@@ -183,17 +185,13 @@ class YardUtils
   #
   # @param path [String] The YARD path of the class/module.
   # @return [Hash] A hash with :included_modules, :mixins, :subclasses.
-  def related_objects(path) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
-    ensure_yardoc_loaded_for_object!(path)
-    obj = YARD::Registry.at(path)
-    unless obj
-      logger.error "Object not found: #{path}"
-      return {}
-    end
+  def related_objects(path, gem_name = nil)
+    obj = object_for!(path, gem_name)
     subclasses = YARD::Registry.all(:class).select { |c| c.superclass && c.superclass.path == obj.path }.map(&:path)
+    mixins_list = obj.respond_to?(:mixins) ? obj.mixins.map(&:path) : []
     {
-      included_modules: obj.respond_to?(:included_modules) ? obj.included_modules.map(&:path) : [],
-      mixins: obj.respond_to?(:mixins) ? obj.mixins.map(&:path) : [],
+      included_modules: mixins_list,
+      mixins: mixins_list,
       subclasses:
     }
   end
@@ -202,32 +200,12 @@ class YardUtils
   #
   # @param query [String] The search query string.
   # @return [Array<Hash>] An array of hashes with :path and :score for matching object paths, ranked by relevance.
-  def search(query) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+  def search(query, gem_name = nil, limit: 25, offset: 0)
     require 'levenshtein' unless defined?(Levenshtein)
-    results = []
-    YARD::Registry.all.each do |obj|
-      path = obj.path.to_s
-      doc = obj.docstring.to_s
-      next if path.empty?
-
-      score = nil
-      if path == query
-        score = 100
-      elsif path.start_with?(query)
-        score = 90
-      elsif path.include?(query)
-        score = 80
-      elsif doc.include?(query)
-        score = 60
-      else
-        # Fuzzy match: allow up to 2 edits for short queries, 3 for longer
-        dist = Levenshtein.distance(path.downcase, query.downcase)
-        score = 70 - dist if dist <= [2, query.length / 3].max
-      end
-      results << { path:, score: } if score
-    end
+    candidates = gem_name ? loaded_objects_for_search(gem_name) : indexed_paths_for_search
+    results = candidates.filter_map { |candidate| score_search_candidate(candidate, query) }
     # Sort by score descending, then alphabetically
-    results.sort_by { |r| [-r[:score], r[:path]] }
+    results.sort_by { |r| [-r[:score], r[:path]] }.slice(offset, limit) || []
   end
 
   # Returns the source file and line number for a YARD object (class/module/method).
@@ -235,13 +213,8 @@ class YardUtils
   # @param path [String] The YARD path (e.g., 'String#upcase').
   # @return [Hash] A hash with :file (String or nil) and :line (Integer or nil).
   # @raise [RuntimeError] if the object is not found in the registry.
-  def source_location(path)
-    ensure_yardoc_loaded_for_object!(path)
-    obj = YARD::Registry.at(path)
-    unless obj
-      logger.error "Object not found: #{path}"
-      return []
-    end
+  def source_location(path, gem_name = nil)
+    obj = object_for!(path, gem_name)
     {
       file: obj.respond_to?(:file) ? obj.file : nil,
       line: obj.respond_to?(:line) ? obj.line : nil
@@ -253,22 +226,85 @@ class YardUtils
   # @param path [String] The YARD path (e.g., 'String#upcase').
   # @return [String, nil] The code snippet if available, otherwise nil.
   # @raise [RuntimeError] if the object is not found in the registry.
-  def code_snippet(path)
-    ensure_yardoc_loaded_for_object!(path)
-    obj = YARD::Registry.at(path)
-    unless obj
-      logger.error "Object not found: #{path}"
-      return []
-    end
-    obj.respond_to?(:source) ? obj.source : nil
+  def code_snippet(path, gem_name = nil, max_chars: MAX_SOURCE_CHARS)
+    obj = object_for!(path, gem_name)
+    capped_source(obj.respond_to?(:source) ? obj.source : nil, max_chars:)
+  end
+
+  def build_docs(gem_name)
+    gem_spec!(gem_name)
+    logger.info "Building docs for #{gem_name}..."
+    YARD::CLI::Gems.new.run(gem_name)
+    @class_cache.delete(gem_name)
+    @last_loaded_gem = nil
+    load_yardoc_for_gem(gem_name)
+    merge_gem_results([collect_current_gem_objects(gem_name)])
+    true
   end
 
   private
 
+  def gem_spec!(gem_name)
+    spec = libraries[gem_name]&.first
+    raise DocumentationError, "Gem '#{gem_name}' is not installed" unless spec
+
+    spec
+  end
+
+  def yardoc_path_for(spec)
+    YARD::Registry.yardoc_file_for_gem(spec.name, "= #{spec.version}")
+  end
+
   def yardoc_exists?(dir)
     dir && File.directory?(dir)
   end
 
+  def object_for!(path, gem_name = nil)
+    gem_name ? load_yardoc_for_gem(gem_name) : ensure_yardoc_loaded_for_object!(path)
+    obj = YARD::Registry.at(path)
+    raise DocumentationError, "Object '#{path}' was not found" unless obj
+
+    obj
+  end
+
+  def capped_source(source, max_chars: MAX_SOURCE_CHARS)
+    return source unless source && source.length > max_chars
+
+    "#{source.byteslice(0, max_chars)}\n... truncated at #{max_chars} bytes"
+  end
+
+  def loaded_objects_for_search(gem_name)
+    load_yardoc_for_gem(gem_name)
+    YARD::Registry.all.map do |obj|
+      { path: obj.path.to_s, docstring: obj.docstring.to_s }
+    end
+  end
+
+  def indexed_paths_for_search
+    @object_to_gem.keys.map { |path| { path:, docstring: '' } }
+  end
+
+  def score_search_candidate(candidate, query)
+    path = candidate[:path]
+    doc = candidate[:docstring]
+    return if path.empty?
+
+    score = search_score(path, doc, query)
+    { path:, score: } if score
+  end
+
+  def search_score(path, doc, query)
+    query_downcase = query.downcase
+    path_downcase = path.downcase
+    return 100 if path == query
+    return 90 if path_downcase.start_with?(query_downcase)
+    return 80 if path_downcase.include?(query_downcase)
+    return 60 if doc.downcase.include?(query_downcase)
+
+    distance = Levenshtein.distance(path_downcase, query_downcase)
+    distance <= [2, query.length / 3].max ? 70 - distance : nil
+  end
+
   # Build an index mapping object paths to gem names
   def build_index # rubocop:disable Metrics/AbcSize
     logger.info 'Building index...'
@@ -296,7 +332,7 @@ class YardUtils
   def merge_gem_results(results)
     results.each do |gem_objects|
       gem_objects.each do |obj_path, gem_names|
-        (@object_to_gem[obj_path] ||= []).concat(gem_names)
+        (@object_to_gem[obj_path] ||= []).concat(gem_names).uniq!
       end
     end
   end
@@ -311,7 +347,10 @@ class YardUtils
       return {}
     end
 
-    # Collect all objects for this gem
+    collect_current_gem_objects(gem_name)
+  end
+
+  def collect_current_gem_objects(gem_name)
     gem_objects = {}
     YARD::Registry.all.each do |obj|
       logger.debug "Adding #{obj.path} to #{gem_name}"
@@ -319,148 +358,496 @@ class YardUtils
     end
     gem_objects
   end
+end
 
-  def build_docs(gem_name)
-    logger.info "Building docs for #{gem_name}..."
-    YARD::CLI::Gems.new.run(gem_name)
+module YardSchemas
+  RESOURCE_URIS_SCHEMA = {
+    type: 'object',
+    properties: {
+      object: { type: 'string' },
+      source: { type: 'string' }
+    },
+    required: %w[object source]
+  }.freeze
+
+  def self.array_schema(name)
+    {
+      type: 'object',
+      properties: {
+        name => { type: 'array', items: { type: 'string' } }
+      },
+      required: [name.to_s]
+    }.freeze
+  end
+
+  def self.path_array_schema(name)
+    {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        gem_name: { type: %w[string null] },
+        resource_uris: RESOURCE_URIS_SCHEMA,
+        name => { type: 'array', items: { type: 'string' } }
+      },
+      required: %w[path resource_uris] + [name.to_s]
+    }.freeze
+  end
+
+  LIST_GEMS_SCHEMA = array_schema(:gems)
+
+  LIST_CLASSES_SCHEMA = {
+    type: 'object',
+    properties: {
+      gem_name: { type: 'string' },
+      classes: { type: 'array', items: { type: 'string' } }
+    },
+    required: %w[gem_name classes]
+  }.freeze
+
+  DOC_OBJECT_SCHEMA = {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      gem_name: { type: %w[string null] },
+      resource_uris: RESOURCE_URIS_SCHEMA,
+      document: {
+        type: 'object',
+        properties: {
+          type: { type: 'string' },
+          name: { type: 'string' },
+          namespace: { type: %w[string null] },
+          visibility: { type: %w[string null] },
+          docstring: { type: 'string' },
+          parameters: { type: %w[array null] },
+          return: { type: %w[object null] },
+          source: { type: %w[string null] },
+          tags: { type: 'array' }
+        },
+        required: %w[type name docstring tags]
+      }
+    },
+    required: %w[resource_uris document]
+  }.freeze
+
+  CHILDREN_SCHEMA = path_array_schema(:children)
+
+  METHODS_SCHEMA = path_array_schema(:methods)
+
+  SOURCE_LOCATION_SCHEMA = {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      gem_name: { type: %w[string null] },
+      resource_uris: RESOURCE_URIS_SCHEMA,
+      source_location: {
+        type: 'object',
+        properties: {
+          file: { type: %w[string null] },
+          line: { type: %w[integer null] }
+        },
+        required: %w[file line]
+      }
+    },
+    required: %w[path resource_uris source_location]
+  }.freeze
+
+  HIERARCHY_SCHEMA = {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      gem_name: { type: %w[string null] },
+      resource_uris: RESOURCE_URIS_SCHEMA,
+      hierarchy: {
+        type: 'object',
+        properties: {
+          superclass: { type: %w[string null] },
+          included_modules: { type: 'array', items: { type: 'string' } },
+          mixins: { type: 'array', items: { type: 'string' } }
+        },
+        required: %w[superclass included_modules mixins]
+      }
+    },
+    required: %w[path resource_uris hierarchy]
+  }.freeze
+
+  SEARCH_SCHEMA = {
+    type: 'object',
+    properties: {
+      query: { type: 'string' },
+      gem_name: { type: %w[string null] },
+      limit: { type: 'integer' },
+      offset: { type: 'integer' },
+      results: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            score: { type: 'integer' }
+          },
+          required: %w[path score]
+        }
+      }
+    },
+    required: %w[query limit offset results]
+  }.freeze
+
+  CODE_SNIPPET_SCHEMA = {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      gem_name: { type: %w[string null] },
+      resource_uris: RESOURCE_URIS_SCHEMA,
+      snippet: { type: 'string' }
+    },
+    required: %w[path resource_uris snippet]
+  }.freeze
+
+  ANCESTORS_SCHEMA = path_array_schema(:ancestors)
+
+  RELATED_OBJECTS_SCHEMA = {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      gem_name: { type: %w[string null] },
+      resource_uris: RESOURCE_URIS_SCHEMA,
+      related_objects: {
+        type: 'object',
+        properties: {
+          included_modules: { type: 'array', items: { type: 'string' } },
+          mixins: { type: 'array', items: { type: 'string' } },
+          subclasses: { type: 'array', items: { type: 'string' } }
+        },
+        required: %w[included_modules mixins subclasses]
+      }
+    },
+    required: %w[path resource_uris related_objects]
+  }.freeze
+
+  BUILD_GEM_DOCS_SCHEMA = {
+    type: 'object',
+    properties: {
+      gem_name: { type: 'string' },
+      indexed: { type: 'boolean' }
+    },
+    required: %w[gem_name indexed]
+  }.freeze
+end
+
+module YardMcpToolListOutputSchema
+  private
+
+  def handle_tools_list(id)
+    tools_list = @tools.values.map do |tool|
+      tool_info = {
+        name: tool.tool_name,
+        description: tool.description || '',
+        inputSchema: tool.input_schema_to_json || { type: 'object', properties: {}, required: [] }
+      }
+      tool_info[:outputSchema] = tool.output_schema if tool.respond_to?(:output_schema) && tool.output_schema
+      tool_info[:annotations] = camel_case_annotations(tool.annotations) unless tool.annotations.empty?
+      tool_info
+    end
+
+    send_result({ tools: tools_list }, id)
+  end
+
+  def camel_case_annotations(annotations)
+    annotations.to_h do |key, value|
+      camel_key = key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }.to_sym
+      [camel_key, value]
+    end
+  end
+end
+
+FastMcp::Server.prepend(YardMcpToolListOutputSchema)
+
+class YardTool < FastMcp::Tool
+  class << self
+    attr_reader :output_schema
+
+    def returns(schema)
+      @output_schema = schema
+    end
+  end
+
+  private
+
+  def ok(structured_content, text: nil)
+    {
+      content: [{ type: 'text', text: text || JSON.pretty_generate(structured_content) }],
+      structuredContent: structured_content,
+      isError: false
+    }
+  end
+
+  def with_yard_errors
+    yield
+  rescue YardUtils::AmbiguousObjectError => e
+    {
+      content: [{ type: 'text', text: e.message }],
+      structuredContent: {
+        error: 'ambiguous_object',
+        path: e.path,
+        candidates: e.candidates
+      },
+      isError: true
+    }
+  rescue YardUtils::DocumentationError, ArgumentError => e
+    {
+      content: [{ type: 'text', text: e.message }],
+      structuredContent: {
+        error: 'documentation_error',
+        message: e.message
+      },
+      isError: true
+    }
+  end
+
+  def resource_uris(gem_name, path)
+    return nil unless gem_name
+
+    {
+      object: "yard://gem/#{gem_name}/object/#{path}",
+      source: "yard://gem/#{gem_name}/source/#{path}"
+    }
+  end
+end
+
+class YardObjectResource < FastMcp::Resource
+  uri 'yard://gem/{gem_name}/object/{+path}'
+  resource_name 'YARD object documentation'
+  description 'Read structured YARD documentation for a gem object'
+  mime_type 'application/json'
+
+  def content
+    JSON.pretty_generate(document: YardUtils.instance.get_doc(params[:path], params[:gem_name]))
+  rescue YardUtils::DocumentationError, ArgumentError => e
+    JSON.pretty_generate(error: e.message)
+  end
+end
+
+class YardSourceResource < FastMcp::Resource
+  uri 'yard://gem/{gem_name}/source/{+path}'
+  resource_name 'YARD object source'
+  description 'Read source code for a documented YARD object'
+  mime_type 'text/plain'
+
+  def content
+    YardUtils.instance.code_snippet(params[:path], params[:gem_name]).to_s
+  rescue YardUtils::DocumentationError, ArgumentError => e
+    "Error: #{e.message}"
   end
 end
 
 # Tool: List all gems with .yardoc files
-class ListGemsTool < FastMcp::Tool
+class ListGemsTool < YardTool
   description 'List all installed gems that have a .yardoc file'
+  annotations(title: 'List all installed gems', read_only_hint: true)
+  returns YardSchemas::LIST_GEMS_SCHEMA
 
   def call
     gems = YardUtils.instance.list_gems
-    { content: gems.map { |gem| { text: gem, type: 'gem' } } }
+    ok({ gems: }, text: gems.join("\n"))
   end
 end
 
 # Tool: List all classes and modules in the loaded YARD registry
-class ListClassesTool < FastMcp::Tool
+class ListClassesTool < YardTool
   description 'List all classes and modules in the loaded YARD registry'
+  annotations(title: 'List all classes and modules', read_only_hint: true)
+  returns YardSchemas::LIST_CLASSES_SCHEMA
   arguments do
     required(:gem_name).filled(:string).description('Name of the gem to list classes for')
   end
 
   def call(gem_name:)
-    classes = YardUtils.instance.list_classes(gem_name)
-    { content: classes.map { |cls| { text: cls, type: 'class' } } }
+    with_yard_errors do
+      classes = YardUtils.instance.list_classes(gem_name)
+      ok({ gem_name:, classes: }, text: classes.join("\n"))
+    end
   end
 end
 
 # Tool: Fetch documentation for a YARD object
-class GetDocTool < FastMcp::Tool
+class GetDocTool < YardTool
   description 'Fetch documentation and metadata for a class/module/method from YARD'
+  annotations(title: 'Fetch documentation', read_only_hint: true)
+  returns YardSchemas::DOC_OBJECT_SCHEMA
   arguments do
     required(:path).filled(:string).description("YARD path (e.g. 'String#upcase')")
     optional(:gem_name).filled(:string).description("Optional gem name to load specific gem's documentation")
   end
 
   def call(path:, gem_name: nil)
-    { content: [YardUtils.instance.get_doc(path, gem_name)] }
+    with_yard_errors do
+      doc = YardUtils.instance.get_doc(path, gem_name)
+      ok({ path:, gem_name:, resource_uris: resource_uris(gem_name, path), document: doc }, text: JSON.pretty_generate(doc))
+    end
   end
 end
 
 # Tool: List children under a namespace
-class ChildrenTool < FastMcp::Tool
+class ChildrenTool < YardTool
   description 'List children under a namespace (class/module) in YARD'
+  annotations(title: 'List children under a namespace', read_only_hint: true)
+  returns YardSchemas::CHILDREN_SCHEMA
   arguments do
     required(:path).filled(:string).description('YARD path of the namespace')
+    optional(:gem_name).filled(:string).description("Optional gem name to load specific gem's documentation")
   end
 
-  def call(path:)
-    children = YardUtils.instance.children(path)
-    { content: children.map { |child| { text: child, type: 'child' } } }
+  def call(path:, gem_name: nil)
+    with_yard_errors do
+      children = YardUtils.instance.children(path, gem_name)
+      ok({ path:, gem_name:, resource_uris: resource_uris(gem_name, path), children: }, text: children.join("\n"))
+    end
   end
 end
 
 # Tool: List methods for a class/module
-class MethodsListTool < FastMcp::Tool
+class MethodsListTool < YardTool
   description 'List methods for a class/module in YARD'
+  annotations(title: 'List methods for a class/module', read_only_hint: true)
+  returns YardSchemas::METHODS_SCHEMA
   arguments do
     required(:path).filled(:string).description('YARD path of the class/module')
+    optional(:gem_name).filled(:string).description("Optional gem name to load specific gem's documentation")
   end
 
-  def call(path:)
-    methods = YardUtils.instance.methods_list(path)
-    { content: methods.map { |method| { text: method, type: 'method' } } }
+  def call(path:, gem_name: nil)
+    with_yard_errors do
+      methods = YardUtils.instance.methods_list(path, gem_name)
+      ok({ path:, gem_name:, resource_uris: resource_uris(gem_name, path), methods: }, text: methods.join("\n"))
+    end
   end
 end
 
 # Tool: Return inheritance and inclusion info
-class HierarchyTool < FastMcp::Tool
+class HierarchyTool < YardTool
   description 'Return inheritance and inclusion info for a class/module in YARD'
+  annotations(title: 'Return inheritance and inclusion info', read_only_hint: true)
+  returns YardSchemas::HIERARCHY_SCHEMA
   arguments do
     required(:path).filled(:string).description('YARD path of the class/module')
+    optional(:gem_name).filled(:string).description("Optional gem name to load specific gem's documentation")
   end
 
-  def call(path:)
-    { content: YardUtils.instance.hierarchy(path) }
+  def call(path:, gem_name: nil)
+    with_yard_errors do
+      hierarchy = YardUtils.instance.hierarchy(path, gem_name)
+      ok({ path:, gem_name:, resource_uris: resource_uris(gem_name, path), hierarchy: })
+    end
   end
 end
 
 # Tool: Perform fuzzy/full-text search
-class SearchTool < FastMcp::Tool
+class SearchTool < YardTool
   description 'Perform fuzzy/full-text search in YARD registry'
+  annotations(title: 'Perform fuzzy/full-text search', read_only_hint: true)
+  returns YardSchemas::SEARCH_SCHEMA
   arguments do
     required(:query).filled(:string).description('Search query')
+    optional(:gem_name).filled(:string).description('Optional gem name to search docstrings and paths within')
+    optional(:limit).filled(:integer, gt?: 0, lteq?: 100).description('Maximum number of results to return')
+    optional(:offset).filled(:integer, gteq?: 0).description('Number of results to skip')
   end
 
-  def call(query:)
-    # Enhanced search: ranked, fuzzy, and full-text
-    results = YardUtils.instance.search(query)
-    { content: results.map { |result| { text: result[:path], score: result[:score], type: 'search_result' } } }
+  def call(query:, gem_name: nil, limit: 25, offset: 0)
+    with_yard_errors do
+      results = YardUtils.instance.search(query, gem_name, limit:, offset:)
+      ok({ query:, gem_name:, limit:, offset:, results: }, text: results.map { |result| "#{result[:score]}\t#{result[:path]}" }.join("\n"))
+    end
   end
 end
 
 # Tool: Fetch source file and line number for a YARD object
-class SourceLocationTool < FastMcp::Tool
+class SourceLocationTool < YardTool
   description 'Fetch the source file and line number for a class/module/method from YARD'
+  annotations(title: 'Fetch the source file and line number', read_only_hint: true)
+  returns YardSchemas::SOURCE_LOCATION_SCHEMA
   arguments do
     required(:path).filled(:string).description("YARD path (e.g. 'String#upcase')")
+    optional(:gem_name).filled(:string).description("Optional gem name to load specific gem's documentation")
   end
 
-  def call(path:)
-    { content: YardUtils.instance.source_location(path) }
+  def call(path:, gem_name: nil)
+    with_yard_errors do
+      location = YardUtils.instance.source_location(path, gem_name)
+      ok({ path:, gem_name:, resource_uris: resource_uris(gem_name, path), source_location: location })
+    end
   end
 end
 
 # Tool: Fetch code snippet for a YARD object from installed gems
-class CodeSnippetTool < FastMcp::Tool
+class CodeSnippetTool < YardTool
   description 'Fetch the code snippet for a class/module/method from installed gems using YARD'
+  annotations(title: 'Fetch the code snippet', read_only_hint: true)
+  returns YardSchemas::CODE_SNIPPET_SCHEMA
   arguments do
     required(:path).filled(:string).description("YARD path (e.g. 'String#upcase')")
+    optional(:gem_name).filled(:string).description("Optional gem name to load specific gem's documentation")
+    optional(:max_chars).filled(:integer, gt?: 0, lteq?: 100_000).description('Maximum number of source characters to return')
   end
 
-  def call(path:)
-    snippet = YardUtils.instance.code_snippet(path)
-    { content: { text: snippet, type: 'code_snippet' } }
+  def call(path:, gem_name: nil, max_chars: YardUtils::MAX_SOURCE_CHARS)
+    with_yard_errors do
+      snippet = YardUtils.instance.code_snippet(path, gem_name, max_chars:)
+      ok({ path:, gem_name:, resource_uris: resource_uris(gem_name, path), snippet: }, text: snippet.to_s)
+    end
   end
 end
 
 # Tool: Fetch the full ancestor chain (superclasses and included modules) for a class/module in YARD
-class AncestorsTool < FastMcp::Tool
+class AncestorsTool < YardTool
   description 'Fetch the full ancestor chain (superclasses and included modules) for a class/module in YARD'
+  annotations(title: 'Fetch the full ancestor chain', read_only_hint: true)
+  returns YardSchemas::ANCESTORS_SCHEMA
   arguments do
     required(:path).filled(:string).description('YARD path of the class/module')
+    optional(:gem_name).filled(:string).description("Optional gem name to load specific gem's documentation")
   end
 
-  def call(path:)
-    ancestors = YardUtils.instance.ancestors(path)
-    { content: ancestors.map { |ancestor| { text: ancestor, type: 'ancestor' } } }
+  def call(path:, gem_name: nil)
+    with_yard_errors do
+      ancestors = YardUtils.instance.ancestors(path, gem_name)
+      ok({ path:, gem_name:, resource_uris: resource_uris(gem_name, path), ancestors: }, text: ancestors.join("\n"))
+    end
   end
 end
 
 # Tool: List related objects: included modules, mixins, and subclasses for a class/module in YARD
-class RelatedObjectsTool < FastMcp::Tool
+class RelatedObjectsTool < YardTool
   description 'List related objects: included modules, mixins, and subclasses for a class/module in YARD'
+  annotations(title: 'List related objects', read_only_hint: true)
+  returns YardSchemas::RELATED_OBJECTS_SCHEMA
   arguments do
     required(:path).filled(:string).description('YARD path of the class/module')
+    optional(:gem_name).filled(:string).description("Optional gem name to load specific gem's documentation")
   end
 
-  def call(path:)
-    { content: YardUtils.instance.related_objects(path) }
+  def call(path:, gem_name: nil)
+    with_yard_errors do
+      related = YardUtils.instance.related_objects(path, gem_name)
+      ok({ path:, gem_name:, resource_uris: resource_uris(gem_name, path), related_objects: related })
+    end
+  end
+end
+
+# Tool: Explicitly build YARD docs for an installed gem
+class BuildGemDocsTool < YardTool
+  description 'Build the local YARD documentation index for an installed gem'
+  annotations(title: 'Build YARD docs for a gem', read_only_hint: false)
+  returns YardSchemas::BUILD_GEM_DOCS_SCHEMA
+  arguments do
+    required(:gem_name).filled(:string).description('Name of the installed gem to index')
+  end
+
+  def call(gem_name:)
+    with_yard_errors do
+      YardUtils.instance.build_docs(gem_name)
+      ok({ gem_name:, indexed: true }, text: "Indexed #{gem_name}")
+    end
   end
 end
 
@@ -468,19 +855,34 @@ module YardMCP
   def self.start_server(preload: true)
     YardUtils.instance if preload
     server = FastMcp::Server.new(name: 'yard-mcp-server', version: YardMCP::VERSION)
-    server.register_tool(ListGemsTool)
-    server.register_tool(ListClassesTool)
-    server.register_tool(GetDocTool)
-    server.register_tool(ChildrenTool)
-    server.register_tool(MethodsListTool)
-    server.register_tool(HierarchyTool)
-    server.register_tool(SearchTool)
-    server.register_tool(SourceLocationTool)
-    server.register_tool(CodeSnippetTool)
-    server.register_tool(AncestorsTool)
-    server.register_tool(RelatedObjectsTool)
+    server.capabilities.clear
+    server.capabilities[:tools] = {}
+    server.capabilities[:resources] = {}
+    register_tools(server)
+    register_resources(server)
     server.start
   end
+
+  def self.register_tools(server)
+    server.register_tools(
+      ListGemsTool,
+      ListClassesTool,
+      GetDocTool,
+      ChildrenTool,
+      MethodsListTool,
+      HierarchyTool,
+      SearchTool,
+      SourceLocationTool,
+      CodeSnippetTool,
+      AncestorsTool,
+      RelatedObjectsTool,
+      BuildGemDocsTool
+    )
+  end
+
+  def self.register_resources(server)
+    server.register_resources(YardObjectResource, YardSourceResource)
+  end
 end
 
 YardMCP.start_server(preload: true) if __FILE__ == $PROGRAM_NAME

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yardmcp
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Roman Shterenzon
@@ -82,7 +82,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Programmable server for Ruby gem/YARD documentation via FastMCP.
 test_files: []