Add instructions support to MCP::Server
#87
Conversation
The response of the `init` method can include `instructions`. https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle `instructions` appear to be supported starting from the 2025-03-26 specification. - https://modelcontextprotocol.io/specification/2025-03-26/basic/lifecycle (supports `instructions`) - https://modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle (does not support `instructions`) If `instructions` is used with an unsupported protocol version, an `ArgumentError` will be raised. As additional context, the TypeScript SDK also treats `instructions` as optional. https://github.com/modelcontextprotocol/typescript-sdk/blob/1.16.0/src/types.ts#L356-L361
| if @configuration.protocol_version == "2024-11-05" && @instructions | ||
| message = "`instructions` supported by protocol version 2025-03-26 or higher" | ||
| raise ArgumentError, message | ||
| end |
There was a problem hiding this comment.
If accepting the instructions parameter with the older "2024-11-05" protocol version is considered preferable, this logic could be removed as it only introduces unnecessary complexity.
There was a problem hiding this comment.
In case there are picky clients that could error on unexpected properties, I think being safe (backwards compatible) is good here.
But are we doing this kind of check uniformly for all features? Is there a Ruby-friendly annotation technique we could adopt to start doing this more declaratively...
I'm happy with this change as it is, though.
| def index | ||
| server = MCP::Server.new( | ||
| name: "my_server", | ||
| version: "1.0.0", | ||
| instructions: "A simple MCP server with custom tools and prompts", |
There was a problem hiding this comment.
https://modelcontextprotocol.io/specification/2025-06-18/schema describes instructions as:
Instructions describing how to use the server and its features.
This can be used by clients to improve the LLM’s understanding of available tools, resources, etc. It can be thought of like a “hint” to the model. For example, this information MAY be added to the system prompt.
So, it's not meant as a "description" for the server that is intended for humans, but more of a "how to get the best out of me" hint intended for the LLM.
I'm having a hard time coming up with a good example.
Maybe something humourous like "Use this server wisely" or "Use the tools of this server as a last resort"... Just something sounding more like it's intended for the LLM.
| @configuration = MCP.configuration.merge(configuration) | ||
| if @configuration.protocol_version == "2024-11-05" && @instructions |
There was a problem hiding this comment.
Stylistic subjective nitpick:
| @configuration = MCP.configuration.merge(configuration) | |
| if @configuration.protocol_version == "2024-11-05" && @instructions | |
| @configuration = MCP.configuration.merge(configuration) | |
| if @configuration.protocol_version == "2024-11-05" && @instructions |
Motivation and Context
The response of the
initmethod can includeinstructions. https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycleinstructionsappear to be supported starting from the 2025-03-26 specification.instructions)instructions)If
instructionsis used with an unsupported protocol version, anArgumentErrorwill be raised.How Has This Been Tested?
Existing tests have been updated and new tests have been added.
Breaking Changes
None.
Types of changes
Checklist
Additional context
As additional context, the TypeScript SDK also treats
instructionsas optional. https://github.com/modelcontextprotocol/typescript-sdk/blob/1.16.0/src/types.ts#L356-L361