ask-mcp 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae155e99332cb2a3fcec6b65c6d0ac20aa9b2b81b27f1e3aa3c667dc0c7a42fb
-  data.tar.gz: af84c5f5aae82c640e2c12316cde40444fe7733d6ad5aaddd6780242b98e1a1c
+  metadata.gz: d73da1e33a97a8bd6825f2eb3e0f9c770ffbbc8b1a9502db612b49e71fc87193
+  data.tar.gz: 5f7cf6b4cb501db18cf5a8367215292c923cf97c078acb226e7546d86e3218a8
 SHA512:
-  metadata.gz: 62f473ff0fdc35b25adcdadf3aeb2a65c330767f7b73cc85bed204a32bff7fcc28f0348c2ee3f8e8ae1e3d7eaf3977714af67d67038c1be990d9feca2199d81f
-  data.tar.gz: e511364526282fcb429740dbd65bbce3e51d0bde06a06cb672e33a0c30b1b09e1971c663145f1b272d7e01015060349447bb7d53081b8dd9813dea02f19591e9
+  metadata.gz: c932454bfccb278fa718290ea84cb3e721296db46ab449c941005f363f404e5342a3836354660d525604c441088b556e938403f99c1d6c80b9066a68906ed3b0
+  data.tar.gz: c8a46f82f4f4907aed57bb1394856f9894a8d9d4bf727fc011604f0b8f68fd621ba2884d72cd194f7e30b9b4545804aba99e412ab55d0a3cbb2498f6708587a1

data/CHANGELOG.md

@@ -1,3 +1,122 @@
+## [0.4.2] - 2026-08-04
+
+### Added
+
+- **2026-07-28 stateless protocol core (dual-mode)** — new
+  `Ask::MCP::LATEST_PROTOCOL_VERSION` (`"2026-07-28"`) and
+  `SUPPORTED_PROTOCOL_VERSIONS` constants. The client probes
+  `server/discover` and, for a 2026-07-28 peer, skips the `initialize`
+  handshake and sends every request with `_meta`
+  (`io.modelcontextprotocol/protocolVersion`, `clientCapabilities`,
+  `clientInfo`). The server answers `server/discover`, detects stateless
+  requests from `_meta`, and keeps the legacy handshake for older peers. A
+  server that supports only ≤ 2025-11-25 is detected and still handshakes
+  with the negotiated version.
+- **`resultType` on server results** — `"complete"` for stateless peers
+  (`"input_required"` via MRTR).
+- **MRTR (Multi Round-Trip Requests)** — the client resolves
+  `inputRequests` through the `on_elicitation`/`on_sampling`/`on_request`
+  handlers, retries the original request with `inputResponses`, echoes
+  `requestState` verbatim, uses a fresh JSON-RPC id per retry, and caps round
+  trips (`MAX_MRTR_ROUND_TRIPS`).
+- **Server-initiated request framework** — `Client#on_request` plus
+  `on_elicitation` and `on_sampling` conveniences; the client declares
+  support via `client_capabilities`.
+- **Streamable HTTP rework (2026-07-28 shape)** — one POST per message with
+  `MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name` headers (Base64 sentinel
+  value encoding); per-response Content-Type decides single JSON vs SSE
+  stream; SSE keep-alive comments ignored; `subscriptions/listen` long-lived
+  streams via `Transport::StreamableHTTP#listen` / `Client#listen`; x-mcp-
+  header tool parameters mirrored into `Mcp-Param-{Name}` headers. Sessions,
+  the GET endpoint, and `Last-Event-ID` were removed upstream and are not
+  implemented. `base64` added as a runtime dependency (Ruby 3.4+).
+- **x-mcp-header validation (SEP-2243)** — `Ask::MCP::XMcpHeader` validates
+  annotations (empty names, invalid characters, non-primitive types,
+  case-insensitive duplicates, non-`properties`-reachable placement);
+  Streamable HTTP clients exclude invalid tool definitions from `tools/list`
+  with a warning; out-of-range integers are omitted from headers.
+- **OTel trace context (SEP-414)** — `Ask::MCP::TraceContext` extracts
+  `traceparent`/`tracestate`/`baggage` from headers (incl. Rack `HTTP_*`) and
+  `_meta`; clients propagate configured `_meta` fields via `meta:` option.
+- **Server list_changed notifications** — `Server::Stdio#notify_tools_
+  list_changed`, `#notify_resources_list_changed`, `#notify_prompts_
+  list_changed` emit the change notifications (deterministically ordered
+  before the triggering response); the client invalidates its caches on
+  receipt. Verified end-to-end with a dedicated notify test server.
+- **Client ID Metadata Documents (SEP-991)** — `Auth::ClientIdMetadataDocument`
+  builds and validates the self-hosted client metadata document (required
+  fields, https URL client_id with path, URL/client_id match,
+  `application_type` native/web) — the 2026-07-28 recommended replacement
+  for the deprecated Dynamic Client Registration.
+- **RFC 9207 `iss` validation** — `Auth::OAuth#validate_iss!` rejects an
+  `iss` that does not match the recorded issuer.
+- **`CacheableResult`** — `ttlMs` + `cacheScope` (configurable via
+  `cache_ttl_ms`/`cache_scope`) emitted on list/read results for stateless
+  peers; deterministic `tools/list` ordering locked by test.
+- **`ping` removed for 2026-07-28 peers** (Method-not-found); legacy clients
+  still get `{}`.
+- **Error-code allocation policy** — `HEADER_MISMATCH` `-32020`,
+  `MISSING_REQUIRED_CLIENT_CAPABILITY` `-32021`,
+  `UNSUPPORTED_PROTOCOL_VERSION` `-32022`; resource-not-found renumbered to
+  `-32602` for stateless peers.
+- **OIDC Discovery 1.0 (2025-11-25)** — `Auth::OAuth#discover!` resolves
+  endpoints from `/.well-known/openid-configuration` (issuer-derived or
+  explicit URL); `token_url` is now optional at construction.
+- **JSON Schema 2020-12 dialect** — `Validator` accepts schemas declaring the
+  2020-12 metaschema (strips it and retries on the json-schema gem, which
+  lacks 2020-12); `const` and other shared keywords enforced.
+- **2025-11-25 display metadata (SEP-973)** — `Tool`, `Resource`, and
+  `Prompt` now parse (`from_h`) and emit (`to_h`) the optional `title` and
+  `icons` (array of `{src, mimeType, sizes}`) fields, and
+  `Adapters::ToolServer` passes them through in `tools/list` definitions
+  when the tool object provides them. Clients connecting to 2025-11-25
+  servers no longer drop these fields.
+- **Server now serves resources & prompts** — `Server::Stdio` implements
+  `resources/list`, `resources/read`, `resources/templates/list`,
+  `prompts/list`, and `prompts/get` (previously only tools were served).
+  Duck-typed resource/prompt/template objects are serialized from their
+  accessors, and `Server.start_stdio` accepts `resources`, `prompts`, and
+  `resource_templates` keyword args.
+- `RecordingTransport` test helper (`test/support/recording_transport.rb`) —
+  in-memory transport for asserting what `Client` puts on the wire without
+  spawning a subprocess.
+- `docs/SPEC_COMPLIANCE.md` — full compliance status across all three
+  revisions (2025-06-18 / 2025-11-25 / 2026-07-28).
+
+### Changed
+
+- HTTP+SSE transport marked deprecated (2026-07-28 feature lifecycle);
+  still functional for legacy servers. Prefer Streamable HTTP.
+- `send` on transports now accepts an optional extra-headers argument
+  (used for `Mcp-Param-*` mirroring; ignored by stdio/SSE).
+
+### Fixed
+
+- **Client advertised a bogus protocol version** — `Ask::MCP::Client` sent
+  `protocolVersion: "0.1.0"` in `initialize` while `Server::Stdio` pinned
+  `2025-06-18`. The advertised MCP revision is now a single source of truth,
+  `Ask::MCP::PROTOCOL_VERSION` (`"2025-06-18"`), referenced by both client and
+  server; the old per-class constants remain as deprecated aliases.
+- **Flaky subprocess timing tests** — `test_transport_send_and_receive` and
+  `test_sigterm_triggers_shutdown` failed intermittently under CI load.
+  Replaced fixed `sleep`s with a shared `wait_until` poll-until-deadline
+  helper (`test/test_helper.rb`); `test_spawn_and_communicate` now does a
+  real round-trip via `cat` instead of an assertion that could never fail.
+
+## [0.4.1] - 2026-07-31
+
+### Changed
+
+- **`ToolServer` result wrapping** — plain `String` results are always treated
+  as success; result-like objects (`Ask::Result`, OpenStruct, etc.) use
+  `ok?`/`ok` and `output`/`error_message`; any other value is treated as
+  success with `to_s` used for the response.
+
+### Fixed
+
+- **Stdio server protocol version** — pins `PROTOCOL_VERSION` to
+  `2025-06-18` and echoes it back in the `initialize` response.
+
 ## [0.4.0] - 2026-06-26
 
 ### Added

data/README.md

@@ -2,13 +2,18 @@
 
 [![Gem Version](https://badge.fury.io/rb/ask-mcp.svg)](https://badge.fury.io/rb/ask-mcp)
 
-**Model Context Protocol (MCP) client and server for Ruby.** Connect to MCP
-servers via stdio, SSE, or Streamable HTTP transports. Run as an MCP server
-to expose your own tools to any MCP client. No framework lock-in — just
-implement a couple of duck-typed methods and you're done.
-
-MCP is the industry standard for LLM tool discovery — the same protocol used by
-Claude Code, Codex, Cursor, and GitHub Copilot.
+Model Context Protocol (MCP) client and server for Ruby. Connect to MCP
+servers over stdio, SSE, or Streamable HTTP transports, or run as an MCP
+server to expose your own tools to any MCP client (Claude Code, Codex, Cursor,
+GitHub Copilot). No framework lock-in: implement a couple of duck-typed
+methods and you are done.
+
+Speaks the protocol **dual-mode**: legacy `initialize`-handshake revisions
+(`2025-06-18`, `2025-11-25`) and the stateless `2026-07-28` revision
+(`server/discover`, per-request `_meta`, MRTR). Clients negotiate
+automatically; servers answer both eras on one connection. See
+[docs/SPEC_COMPLIANCE.md](docs/SPEC_COMPLIANCE.md) for the full status across
+all three revisions.
 
 ## Installation
 
@@ -16,13 +21,7 @@ Claude Code, Codex, Cursor, and GitHub Copilot.
 gem "ask-mcp"
 ```
 
-Or add to your Gemfile:
-
-```ruby
-gem "ask-mcp", "~> 0.1.0"
-```
-
-## Quick Start — Client
+## Quick Start: Client
 
 Connect to any MCP server and call its tools:
 
@@ -40,16 +39,37 @@ puts result
 client.stop
 ```
 
-## Quick Start — Server
+`start` probes `server/discover` first: a `2026-07-28` server is used
+statelessly (no handshake; every request carries `_meta`), and older servers
+fall back to the `initialize` handshake automatically.
+
+### Server-initiated requests (elicitation, sampling)
 
-Run as a standalone MCP server exposing your own tools to any MCP client
-(Codex, Claude Code, Cursor, etc.). Any object that responds to `name`,
-`description`, `params_schema`, and `call(args)` will work:
+Servers can ask the client for input — user answers (elicitation) or LLM
+completions (sampling). Register handlers; the client answers the server and,
+in the stateless revision, completes the request via
+[MRTR](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr):
+
+```ruby
+client.on_elicitation { |params| { message: "42" } }
+client.on_sampling do |params|
+  # params includes `tools` / `toolChoice` when the server offers tool calling
+  { role: "assistant", content: { type: "text", text: "Paris" } }
+end
+# any on_request("method") { |params| ... } works for custom server requests
+```
+
+Declare support so servers know they can ask:
+`Ask::MCP::Client.new(transport, client_capabilities: { elicitation: {}, sampling: {} })`.
+
+## Quick Start: Server
+
+Run as a standalone MCP server. Any object that responds to `name`,
+`description`, `params_schema`, and `call(args)` works:
 
 ```ruby
 require "ask/mcp"
 
-# Define your tools — no base class needed, just duck typing
 class Greeter
   def name; "greet" end
   def description; "Greets someone by name" end
@@ -61,14 +81,17 @@ class Greeter
   end
 end
 
-# Start the server (blocking — runs until stdin closes)
+# Blocking: runs until stdin closes
 Ask::MCP::Server.start_stdio(
   name: "my-server",
-  tools: [Greeter.new]
+  tools: [Greeter.new],
+  resources: { "greeting://world" => GreetingResource.new },   # uri → object
+  prompts: { "greet" => GreetPrompt.new },                    # name → object
+  resource_templates: { "file:///{path}" => FileTemplate.new }
 )
 ```
 
-Configure your MCP client:
+Point any MCP client at it:
 
 ```json
 {
@@ -81,198 +104,104 @@ Configure your MCP client:
 }
 ```
 
-Tools can return any value the client can use. The server automatically wraps
-the result into MCP's `content` array format.
-
-### What about complex tools?
+The result of `call(args)` may be a plain value, or an object responding to
+`ok?` and `output` / `error_message` (for example an `OpenStruct`). The server
+wraps results into MCP's `content` array format automatically. Resources and
+prompts are duck-typed: objects with `to_h` are serialized directly, otherwise
+accessors (`title`, `description`, `mime_type`, `icons`, `arguments`) are
+collected; `resources/read` and `prompts/get` pull contents from `content` /
+`read` / `messages`.
 
-The result object from `call(args)` should respond to `ok?` (or `ok`) and
-`output` / `error_message`. Use `OpenStruct` for simple cases:
+When your tool/resource/prompt sets change at runtime, tell clients:
 
 ```ruby
-require "ostruct"
-
-class BashTool
-  def name; "bash" end
-  def description; "Run a shell command" end
-  def params_schema
-    { type: "object", properties: { "command" => { "type" => "string" } }, required: ["command"] }
-  end
-  def call(args = {})
-    output = `#{args['command']} 2>&1`
-    OpenStruct.new(ok?: true, output: output)
-  rescue => e
-    OpenStruct.new(ok?: false, error_message: e.message)
-  end
-end
-```
-
-For a production example with shell tools, file ops, and web search,
-see [llm-proxy](https://github.com/ask-rb/llm-proxy).
-
-### Using with ask-tools
-
-If you use the ask-rb ecosystem, you can expose Ask::Tool subclasses directly:
-
-```ruby
-require "ask/mcp"
-require "ask-tools-shell"
-require "ask-web-search"
-
-tools = Ask::Tools::Shell::TOOLS.map(&:new) + [Ask::Tools::WebSearch.new]
-
-Ask::MCP::Server.start_stdio(
-  name: "my-server",
-  tools: tools,
-  capabilities: { tools: {} }
-)
+server.notify_tools_list_changed
+server.notify_resources_list_changed
+server.notify_prompts_list_changed
 ```
 
 ## Transports
 
 ```ruby
-# stdio — local processes
+# stdio: local processes
 Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-github"])
 
-# SSE — remote servers with Server-Sent Events
+# SSE: remote servers with Server-Sent Events (deprecated upstream — prefer Streamable HTTP)
 Ask::MCP.from_sse("https://mcp.example.com/sse")
 
-# Streamable HTTP — remote servers
+# Streamable HTTP: remote servers
 Ask::MCP.from_http("https://mcp.example.com/mcp")
 ```
 
-## API
+Each factory returns a client backed by `Ask::MCP::Transport::Stdio`,
+`Ask::MCP::Transport::SSE`, or `Ask::MCP::Transport::StreamableHTTP`.
 
-### Client Lifecycle
+The Streamable HTTP transport implements the `2026-07-28` shape: one POST per
+message with `MCP-Protocol-Version` / `Mcp-Method` / `Mcp-Name` headers
+(Base64-sentinel value encoding), per-response JSON-or-SSE handling, and
+`subscriptions/listen` long-lived notification streams:
 
 ```ruby
-# Create a client with any transport
-transport = Ask::MCP::Transport::Stdio.new("ruby", ["server.rb"])
-client = Ask::MCP::Client.new(transport, timeout: 30)
-
-# Start the session (sends initialize + receives capabilities)
-client.start
-
-# Use the client
-client.tools       # => { "tool_name" => #<Ask::MCP::Tool> }
-client.resources   # => { "resource_uri" => #<Ask::MCP::Resource> }
-client.prompts     # => { "prompt_name" => #<Ask::MCP::Prompt> }
-client.call_tool("tool_name", arg1: "value")
-client.read_resource("file:///path")
-client.get_prompt("prompt_name", arg1: "value")
-
-# Stop the session
-client.stop
+client.listen(toolsListChanged: true, resourceSubscriptions: ["file:///x"])
 ```
 
-### Tool, Resource, Prompt Objects
+Tool parameters annotated with `x-mcp-header` in the server's `inputSchema`
+are mirrored into `Mcp-Param-{Name}` headers; tool definitions with invalid
+annotations are excluded from `tools/list` on HTTP transports.
+
+## Essential API
+
+| Entry point | Purpose |
+|---|---|
+| `client.start` / `client.stop` | Negotiate the protocol (discover or handshake) and shut down |
+| `client.tools` / `client.resources` / `client.prompts` | Indexed lists exposed by the server (title/icons preserved) |
+| `client.call_tool(name, args)` | Invoke a tool; also `read_resource(uri)` and `get_prompt(name, args)` |
+| `client.on_request(method)` / `on_elicitation` / `on_sampling` | Answer server-initiated requests (MRTR) |
+| `client.listen(notifications)` | Open a `subscriptions/listen` notification stream |
+| `server.notify_*_list_changed` | Emit change notifications to clients |
+| `Ask::MCP::Adapters::AskTool.wrap(tools_hash)` | Adapter from MCP tools to `Ask::Tool` instances for ask-agent |
+| `Ask::MCP::Adapters::ToolServer` | Adapter from duck-typed tools to MCP server tools |
+| `Ask::MCP::Auth::Token.new(token)` | Token-based auth (`apply(headers)`) |
+| `Ask::MCP::Auth::OAuth.new(client_id:, ...)` | OAuth for MCP; `discover!` (OIDC), `authenticate!`, `validate_iss!`, `apply(headers)` |
+| `Ask::MCP::Auth::ClientIdMetadataDocument` | Build/validate Client ID Metadata Documents (2026-07-28 client registration) |
+| `Ask::MCP::TraceContext` | OpenTelemetry `traceparent`/`tracestate`/`baggage` extraction for `_meta` |
+| `Ask::MCP::XMcpHeader` | Validation of `x-mcp-header` tool annotations |
+
+OAuth endpoints can be discovered instead of configured:
 
 ```ruby
-# Tool
-tool = Ask::MCP::Tool.new(
-  name: "read_file",
-  description: "Read a file from disk",
-  input_schema: {
-    type: "object",
-    properties: { path: { type: "string" } },
-    required: ["path"]
-  }
-)
-tool.name         # => "read_file"
-tool.description  # => "Read a file from disk"
-tool.input_schema # => { type: "object", ... }
-
-# Resource
-resource = Ask::MCP::Resource.new(
-  uri: "file:///tmp/test.txt",
-  name: "Test File",
-  mime_type: "text/plain"
-)
-
-# Prompt
-prompt = Ask::MCP::Prompt.new(
-  name: "greet",
-  description: "Generate a greeting",
-  arguments: [{ name: "name", description: "Name to greet", required: true }]
-)
-```
-
-### Authentication
-
-```ruby
-# Token-based auth
-token = Ask::MCP::Auth::Token.new("my-api-token")
-headers = token.apply({})  # => { "Authorization" => "Bearer my-api-token" }
-
-# OAuth 2.1
-oauth = Ask::MCP::Auth::OAuth.new(
-  client_id: "my-client",
-  client_secret: "my-secret",
-  token_url: "https://auth.example.com/token",
-  scopes: ["mcp"]
-)
-oauth.authenticate!
-headers = oauth.apply({})
+oauth = Ask::MCP::Auth::OAuth.new(client_id: "my-client", issuer: "https://auth.example.com")
+oauth.discover!          # fetches /.well-known/openid-configuration
+oauth.authenticate!      # client-credentials or authorization-code flow
+client = Ask::MCP::Client.new(transport, auth: oauth)
 ```
 
 ### With ask-agent
 
 ```ruby
-require "ask/mcp"
-
 client = Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-github"])
 client.start
 
-# Convert MCP tools to Ask::Tool instances for use with Ask::Agent
-client.tools.each do |name, mcp_tool|
-  agent.register_tool(mcp_tool.to_ask_tool)
-end
-
-# Or use the adapter directly
 wrapped = Ask::MCP::Adapters::AskTool.wrap(client.tools)
 wrapped.each { |name, adapter| agent.register_tool(adapter.to_ask_tool) }
 ```
 
-## Architecture
+Expose `Ask::Tool` subclasses as an MCP server with `Ask::MCP::Server.start_stdio(name:, tools:, capabilities: { tools: {} })`; the `ToolServer` adapter handles them.
 
-```
-ask-mcp/
-├── lib/ask/mcp.rb                         # Entry point, factory methods
-├── lib/ask/mcp/client.rb                  # MCP client (connect, call_tool, etc.)
-├── lib/ask/mcp/server.rb                  # MCP server representation + Server.start_stdio entry point
-├── lib/ask/mcp/server/stdio.rb            # MCP server stdio runtime (run as server)
-├── lib/ask/mcp/tool.rb                    # MCP tool representation
-├── lib/ask/mcp/resource.rb                # MCP resource representation
-├── lib/ask/mcp/prompt.rb                  # MCP prompt representation
-├── lib/ask/mcp/native/messages.rb         # JSON-RPC message layer
-├── lib/ask/mcp/transport/
-│   ├── stdio.rb                           # stdio transport (client direction)
-│   ├── sse.rb                             # Server-Sent Events transport
-│   └── streamable_http.rb                 # Streamable HTTP transport
-├── lib/ask/mcp/auth/
-│   ├── oauth.rb                           # OAuth 2.1 for MCP
-│   └── token.rb                           # Token-based auth
-└── lib/ask/mcp/adapters/
-    ├── ask_tool.rb                        # MCP::Tool → Ask::Tool adapter
-    └── tool_server.rb                     # Duck-typed tools → MCP server adapter
-```
+## Full documentation
+
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+https://ask-rb.github.io/ask-docs/core/mcp covers ask-mcp in depth, including
+tool, resource, and prompt objects, protocol details, and auth. See also the
+[Auth Setup Guide](docs/auth-setup.md) for token and OAuth 2.1 setup with
+ask-auth, and [docs/SPEC_COMPLIANCE.md](docs/SPEC_COMPLIANCE.md) for the
+protocol compliance status. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
-# Run tests
-bundle exec rake test
-
-# Run specific tests
-bundle exec ruby -Itest test/messages_test.rb
-bundle exec ruby -Itest test/stdio_integration_test.rb
-```
+bundle install
+bundle exec rake test   # full suite + self-contained conformance (both protocol eras)
 
 ## License
 
 MIT
-
-## Authentication
-
-See the [Auth Setup Guide](docs/auth-setup.md) for detailed documentation on
-token-based and OAuth 2.1 authentication, including ask-auth integration.