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>
- 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.
This commit implements optional JSON Schema validation for tool outputs according to the MCP specification:
- Add MCP::Tool::OutputSchema class mirroring InputSchema functionality
- Support output_schema in class definitions, Tool.define, and OutputSchema objects
- Include validate_result method for runtime validation
- Update MCP::Client::Tool to track output schemas
- Add comprehensive test coverage with 249 passing tests
- Update README with dedicated Tool Output Schemas section
- Follow MCP spec requirements for server/client validation
According to the specification, `destructive_hint`, `idempotent_hint`, `open_world_hint`,
and `read_only_hint` of `ToolAnnotations` are optional with default values:
https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations
This PR sets their default values in accordance with the specification.
Additionally, for readability, the hints have been reordered to follow the specification.
Follow-up to #109.
The introduction of `title` in #109 is still a draft and is not supported in the latest specification, `Version 2025-06-18 (latest)`.
In this PR, the README.md will be updated to mention this point and restore the references to the removed `annotations.title`.
This aims to inform users that, as of `Version 2025-06-18 (latest)`, the use of `annotations.title` is considered stable.
Additionally, separate validation for these parameters could be added.
Please refer to the following comment regarding `annotations.title` and `title`:
https://github.com/modelcontextprotocol/modelcontextprotocol/pull/663#issuecomment-2963519737
In Ruby, it is generally not customary to add parentheses to methods without arguments.
This PR removes such redundant parentheses from the documentation.
`MCP::Server` does not have a `protocol_version=` method.
```console
$ bin/console
irb(main):001> MCP::Server.protocol_version = "2024-11-05"
(irb):1:in '<main>': undefined method 'protocol_version=' for class MCP::Server (NoMethodError)
from bin/console:15:in '<main>'
```
This PR fixes an incorrect example that causes the above error.
Currently, MCP has three versions: 2024-11-05, 2025-03-26, and 2025-06-18.
- https://modelcontextprotocol.io/specification/2024-11-05/basic/transports (stdio and HTTP with SSE)
- https://modelcontextprotocol.io/specification/2025-03-26/basic/transports (stdio and Streamable HTTP)
- https://modelcontextprotocol.io/specification/2025-06-18/basic/transports (stdio and Streamable HTTP)
The newer specification supports stdio and Streamable HTTP as transport mechanisms.
Only the oldest version, 2024-11-05, supports stdin and HTTP with SSE,
but that version is now considered legacy.
Given the current behavior of the Ruby SDK, it likely makes more sense to set
the default protocol version to the latest one, 2025-06-18, rather than the oldest, 2024-11-05.
Ideally, the implementation should adjust its behavior based on the version,
but this PR is limited to updating the default protocol version only.
## Motivation and Context
Currently, MCP supports the following three protocol versions:
"2025-06-18", "2025-03-26", and "2024-11-05".
https://modelcontextprotocol.io/introduction
As shown in the changes to `test/mcp/configuration_test.rb`,
the `protocol_version` value is not currently being validated,
which allows unexpected `protocol_version` values to be accepted.
This PR ensures that only supported protocol versions are accepted.
## How Has This Been Tested?
Existing tests have been updated and new tests have been added.
## Breaking Changes
None. If it becomes an issue, it means a value that was not originally intended has been used.
## Additional context
While one possible approach might be to fall back to a default protocol version
when an invalid `protocol_version` value is provided,
this PR opts to reject invalid `protocol_version` values explicitly.
The reasoning is that encouraging users to provide intentional,
valid input is preferable to silently falling back to a default,
which could lead to unexpected behavior.
