Add API documentation with GitHub Pages deployment

[jonathanhefner]

This adds automated deployment of a versioned API documentation landing page using GitHub Pages. The landing page links to documentation hosted on RubyDoc.info, the de facto standard documentation site for the Ruby ecosystem. The landing page will update to reflect new releases.

Changes

1. Documentation generation script (see bin/generate-gh-pages.sh)

   Copies and commits documentation files to the gh-pages branch. The script uses git worktrees to isolate the process from the main workspace.

   The script:

   • Creates the gh-pages branch as an orphan branch if it doesn't exist
   • Parses semantic versions from tag names, ignoring arbitrary prefixes (e.g., tags 1.2.3, v1.2.3, and release-1.2.3 all create v1.2.3)
   • Determines the latest version using semantic version sorting
   • Copies static Jekyll template files from docs/ to the gh-pages root (for the latest version only)
   • Generates docs/_data/versions.yml with a list of all versions for the Jekyll templates to consume

2. Jekyll template files (see docs/ directory)

   • docs/_config.yml - Jekyll configuration
   • docs/index.md - Landing page template that links to all versions on RubyDoc.info based on generated docs/_data/versions.yml
   • docs/latest/index.html - Redirect page template that redirects to the latest documentation on RubyDoc.info

3. GitHub Actions workflow (see .github/workflows/release.yml)

   Added a publish_gh_pages job that runs after the publish_gem job on release events. The job invokes the generation script with the release tag name, then pushes the updated gh-pages branch to deploy the documentation.

4. CI validation (see .github/workflows/ci.yml)

   Added a yard job that runs YARD validation with --no-output. This ensures YARD can successfully parse the codebase (without generating output), catching documentation issues early in CI.

5. YARD dependencies (see Gemfile)

   Added yard and yard-sorbet gems as development dependencies to support documentation validation in CI.

   YARD documentation is automatically generated and hosted by RubyDoc.info when the gem is published to RubyGems.org.

6. Documentation links (see README.md and mcp.gemspec)

   Added links to the published API documentation on RubyDoc.info in the README and gemspec metadata.

Documentation URL

Custom documentation will be available at: https://modelcontextprotocol.github.io/ruby-sdk/

RubyDoc.info documentation will be accessible at:

• https://rubydoc.info/gems/mcp (latest version)
• https://rubydoc.info/gems/mcp/1.2.3 (specific versions)

---

You can see a preview of the landing page at: https://jonathan.hefner.pro/mcp-ruby-sdk/. (Ignore the v99.9.9 tag — I created that for testing purposes.)

Note that this page is fully customizable via docs/index.md, and it can link to SDK-specific guides in the future.

Eventually, I intend to link to this page from the modelcontextprotocol.io SDKs page. And, ultimately, I think it would be nice have something like sdks.modelcontextprotocol.io such that https://sdks.modelcontextprotocol.io/ruby-sdk/ resolves to https://modelcontextprotocol.github.io/ruby-sdk/.

If desired, I can also submit a PR for the gh-pages branch to populate docs/index.md before the next release.

[koic]

Custom documentation will be available at: https://modelcontextprotocol.github.io/ruby-sdk/

I confirmed that https://modelcontextprotocol.github.io/python-sdk/ already exists. Since users will likely refer to the documentation first, having this kind of documentation available should improve the overall user-friendly tool experience. Thank you for working on this!