yardmcp

A programmable server for exploring and querying Ruby gem documentation using YARD and the FastMCP protocol.

Overview

yardmcp exposes Ruby gem and YARD documentation as a set of programmable tools via a FastMCP server. It enables clients to:

  • List installed gems with YARD docs
  • Explore classes, modules, and methods
  • Fetch documentation, code snippets, and source locations
  • Perform fuzzy/full-text search across documentation
  • Introspect inheritance, mixins, and related objects

This is useful for building documentation browsers, code assistants, or integrating Ruby/YARD docs into other systems.

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
  • List Methods: List all methods for a class/module
  • Hierarchy: Get inheritance and inclusion info
  • Ancestors: Get the full ancestor chain
  • Related Objects: Find included modules, mixins, and subclasses
  • 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

As a Gem

You can build and install the gem locally:

gem build yardmcp.gemspec
gem install yardmcp-0.1.0.gem

This will install the yardmcp executable in your PATH.

Usage

Running the Server

The server is designed to be run as a long-lived process. Startup may take some time as it builds an index of all YARD documentation for installed gems. During startup, progress and logs (including Index built ...) are printed to stderr. Clients should wait for the Index built message on stderr before sending requests.

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:

yard gems <gemname>

or call BuildGemDocsTool explicitly.

Tool List

The following tools are available (use tools/list to discover):

  • ListGemsTool
  • BuildGemDocsTool
  • ListClassesTool
  • GetDocTool
  • ChildrenTool
  • MethodsListTool
  • HierarchyTool
  • SearchTool
  • SourceLocationTool
  • CodeSnippetTool
  • AncestorsTool
  • RelatedObjectsTool

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:

yard://gem/yard/object/YARD::Registry
yard://gem/yard/source/YARD::CodeObjects::Base#name

Development

  • Run tests: sh bundle exec rspec The test suite starts a persistent server process for all tests and waits for the server to be ready before running examples.
  • Code style: sh bundle exec rubocop
  • Regenerate YARD docs for a gem: sh yard gems <gemname>

Requirements

  • Ruby 3.2+
  • Bundler
  • Gems: fast-mcp, levenshtein, yard, rspec (for tests)

License

MIT License. See LICENSE for details.