Follow-up to #175.
Since `json_rpc_handler` was merged in #175, it has been removed from AGENTS.md.
The "Dependencies" section was also removed because the information there would have become redundant.
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)
Co-Authored-By: Claude <noreply@anthropic.com>
Consolidates four identical constructions of error `Tool::Response` in
`handle_call_tool_request` into a single private `error_tool_response` method,
reducing duplication and improving maintainability. No behavior change.
For example, the `title` introduced in #109 is not supported in the latest stable protocol version "2025-06-18":
https://modelcontextprotocol.io/specification/2025-06-18
It is supported in the Draft of the next version:
https://modelcontextprotocol.io/specification/draft
In other words, the fact that the Ruby SDK treats "2025-06-18" as the default protocol version while `title` is
only supported in the Draft results in an inconsistency.
Because of this, a new version `"Draft"` has been added to the list of supported versions.
Its value follows the schema below and is defined as `DRAFT-2025-v3`:
14ec41c/schema/draft/schema.ts (L15)
It was also considered to continue using the latest stable version "2025-06-18" as the Ruby SDK default instead of the Draft.
However, in that case, users would need to explicitly specify `MCP::Server.new(protocol_version: 'DRAFT-2025-v3')`,
which adds extra burden. In this PR, Draft is made the default in order to provide the following benefits:
- Users are likely to prefer using the Draft version over the latest stable version
- No need to specify the `protocol_version` option when initializing `MCP::Server`
- Users generally do not need to know the internal development value `DRAFT-2025-v3`
The primary case for specifying `protocol_version` explicitly is when strict adherence to a particular version is required.
However, it seems more practical to prioritize use cases where backward-compatible features, including those from the Draft,
are desirable. This is the rationale behind making the Draft version the default.
In addition, making the Draft version the default protocol version preserves backward compatibility for `MCP::Server`.
NOTE: `DRAFT-2025-v3` is a development code, so its value cannot be set externally.
It is applied either when `protocol_version` is omitted or when `nil` is set explicitly,
such as with `MCP::Configuration.new(protocol_version: nil)`.
This prevents users from creating implementations that depend on development codes like `DRAFT-2025-v3`.
`stateless` was supported in #101. However, as shown in the official specification below,
the supported transports are stdout and Streamable HTTP, and whether it is stateless is
a detail specific to Streamable HTTP:
https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
This PR updates the documentation to describe `stateless` as part of the Streamable HTTP section.
- Create failing tests for `stateless` mode
- Implement `stateless` mode by turning of SSE in Streamable HTTP,
making the interaction a standard HTTP Req/Resp
README is generally better kept focused on information that is most valuable to users.
For that reason, release procedures that are not relevant to end users have been moved to
a separate RELEASE.md file.
Tool execution errors now return successful responses with isError: true
instead of JSON-RPC protocol errors, per the MCP specification.
This allows clients to distinguish between protocol-level errors and
tool execution errors, providing better error context.
Fixes#159
Update test_resources_returns_empty_array_when_no_resources to use
correct mock response format with empty resources array instead of
empty result object. Also reorder test to group with other resources
tests.
Follow up: https://github.com/modelcontextprotocol/ruby-sdk/pull/160
