ask-mcp 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 909c171336e0497c2377c2f4106e1ec0314adbbbf15791819caf6be0c9d04035
-  data.tar.gz: 5a5e95508499f38e310cce0052fcd4c9dfd2c95f8a4e965621c37d35c392293d
+  metadata.gz: d73da1e33a97a8bd6825f2eb3e0f9c770ffbbc8b1a9502db612b49e71fc87193
+  data.tar.gz: 5f7cf6b4cb501db18cf5a8367215292c923cf97c078acb226e7546d86e3218a8
 SHA512:
-  metadata.gz: 52526b46e9574fb4289ddde3b7ff340945eead680763ad7ece3903a8bea89a5a535cb3b9951b0236f6749808b22254c9f4b691133eff56e24a7438eb68ae8743
-  data.tar.gz: be8c62053892b8aa52e5216fcb58c7857ecfdff12b025173d9cd1be1a384cced8dd41ef4f9e17ca531fe6d869743dbc63caad275fbccb82014ddd4d94d49c3a2
+  metadata.gz: c932454bfccb278fa718290ea84cb3e721296db46ab449c941005f363f404e5342a3836354660d525604c441088b556e938403f99c1d6c80b9066a68906ed3b0
+  data.tar.gz: c8a46f82f4f4907aed57bb1394856f9894a8d9d4bf727fc011604f0b8f68fd621ba2884d72cd194f7e30b9b4545804aba99e412ab55d0a3cbb2498f6708587a1

data/CHANGELOG.md

@@ -1,3 +1,108 @@
+## [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

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.

data/docs/SPEC_COMPLIANCE.md

@@ -0,0 +1,184 @@
+# ask-mcp — MCP Specification Compliance
+
+Status of `ask-mcp` against the Model Context Protocol specification.
+
+**Advertised versions:** `Ask::MCP::PROTOCOL_VERSION` = `2025-06-18` (legacy
+default), `Ask::MCP::LATEST_PROTOCOL_VERSION` = `2026-07-28` (stateless),
+`Ask::MCP::SUPPORTED_PROTOCOL_VERSIONS` = `[2025-06-18, 2025-11-25,
+2026-07-28]`. Clients negotiate via `server/discover` (falling back to the
+legacy `initialize` handshake); servers speak both eras on one connection.
+
+## Strategy (applies to every item below)
+
+1. **Single source of truth.** Protocol constants live on `Ask::MCP`; client
+   and server reference them. This is what the `0.1.0` bug was about — never
+   reintroduce per-class duplicates.
+2. **Dual-mode, not rewrite.** `2026-07-28` removed the `initialize`
+   handshake, but the spec *requires* backward compatibility with older peers
+   (missing `resultType` → treat as `"complete"`; `server/discover` as a
+   backward-compat probe on stdio; `UnsupportedProtocolVersionError`). The
+   gem speaks the old and new protocols at once, negotiated per peer.
+3. **Tests first, wire-level.** Where a change alters what goes over the
+   wire, assert on the wire: `RecordingTransport` (unit, no subprocess) for
+   the client, `MCPServerHarness` for the server.
+4. **Don't build on deprecated features.** Roots, Sampling, Logging, the
+   HTTP+SSE transport, and OAuth Dynamic Client Registration are deprecated
+   as of `2026-07-28` — keep existing support working, don't add new surface.
+
+---
+
+## 1. Baseline: `2025-06-18` (done)
+
+- [x] `initialize` / `notifications/initialized` handshake (client + server)
+- [x] stdio transport
+- [x] Streamable HTTP transport
+- [x] HTTP+SSE transport (legacy, deprecated)
+- [x] `tools/list`, `tools/call` (+ retry dedup, timeouts, graceful shutdown)
+- [x] `resources/list`, `resources/read`, `resources/templates/list`
+- [x] `prompts/list`, `prompts/get`
+- [x] `ping` (legacy only — removed for 2026-07-28 peers)
+- [x] OAuth resource-server authorization (`auth/oauth.rb`)
+- [x] JSON-RPC 2.0 message types, parser, error codes (`native/messages.rb`)
+- [x] Server serves tools, resources, prompts, and resource templates
+  (duck-typed serialization; `Server.start_stdio` accepts `resources`,
+  `prompts`, `resource_templates`)
+
+## 2. `2025-11-25` gap (done)
+
+- [x] **Icons + title display metadata (SEP-973)** — `title` (optional) and
+  `icons` (array of `{src, mimeType, sizes}`) on tools, resources, prompts;
+  parsed/emitted by the value objects, passed through by
+  `Adapters::ToolServer`.
+- [x] **Server serves resources & prompts** — `resources/list`,
+  `resources/read`, `resources/templates/list`, `prompts/list`, `prompts/get`
+  handlers in `Server::Stdio`; `resources/read`/`prompts/get` pull contents
+  from `content`/`read`/`messages` or return the spec error codes.
+- [x] **OIDC discovery (1.0)** — `Auth::OAuth#discover!` fetches
+  `/.well-known/openid-configuration` (derived from `issuer` per RFC 8414 or
+  an explicit `discovery_url`) and populates `token_url`, `auth_url`,
+  `issuer`; `token_url` is now optional at construction.
+- [x] **Elicitation** — client handles `elicitation/create` via
+  `on_elicitation` (schema/params passed through verbatim, so titled/untitled,
+  single/multi-select enums and defaults are supported by construction).
+- [x] **Sampling with tool calling (SEP-1577)** — client handles
+  `sampling/createMessage` via `on_sampling`, passing `tools`/`toolChoice`
+  through untouched.
+- [x] **JSON Schema 2020-12 as default dialect** — `Validator` accepts
+  schemas declaring the 2020-12 dialect (the json-schema gem lacks 2020-12,
+  so the metaschema is stripped and validation retried; shared keywords
+  including `const` are enforced).
+- [x] **Tool-name guidance** — spec is SHOULD-level; ask-mcp does not reject
+  tool names.
+- [~] **Experimental Tasks** — explicitly not implemented: deprecated in
+  2026-07-28 in favor of the `io.modelcontextprotocol/tasks` extension.
+
+## 3. `2026-07-28` (stateless revision) — done, dual-mode
+
+### 3.1 Stateless core
+
+- [x] **`server/discover`** — server advertises `protocolVersions`,
+  `capabilities`, `serverInfo`; client probes it first and falls back to the
+  legacy handshake when the method is unknown (`UnsupportedProtocolVersion`
+  semantics via negotiated version lists).
+- [x] **Remove `initialize` handshake in stateless mode** — every request
+  carries `_meta` (`io.modelcontextprotocol/protocolVersion`,
+  `clientCapabilities`, `clientInfo`); server identifies itself in results
+  via `serverInfo` (in discover) and `resultType`. Legacy handshake kept for
+  older peers; a server that supports ≤ 2025-11-25 is detected and the client
+  still handshakes with the negotiated version.
+- [x] **`resultType` on all results** — server emits `"complete"` for
+  stateless peers (and `"input_required"` on MRTR); clients treat missing as
+  `"complete"` per spec.
+- [x] **MRTR (Multi Round-Trip Requests, SEP-2322)** — client resolves
+  `inputRequests` (elicitation/sampling/roots) through the registered
+  handlers, retries with `inputResponses`, echoes `requestState` verbatim,
+  uses a fresh JSON-RPC id per retry, and caps round trips.
+- [x] **Remove `ping`, `logging/setLevel`, `notifications/roots/list_changed`**
+  — `ping` returns Method-not-found for stateless peers (`logging/setLevel`
+  and roots notifications were never implemented; nothing to remove).
+- [x] **Error-code allocation policy** — `-32020..-32099` reserved:
+  `HeaderMismatch` `-32020`, `MissingRequiredClientCapability` `-32021`,
+  `UnsupportedProtocolVersion` `-32022`; resource-not-found renumbered to
+  `-32602` for stateless peers.
+
+### 3.2 Transports
+
+- [x] **Streamable HTTP: stateless shape** — no `Mcp-Session-Id`, no GET
+  stream endpoint, no `Last-Event-ID`; one POST per message; per-response
+  Content-Type decides single JSON vs SSE stream; SSE comment (keep-alive)
+  lines ignored.
+- [x] **Required request headers** — `MCP-Protocol-Version` (matching body
+  `_meta`), `Mcp-Method`, `Mcp-Name` (`params.name`/`params.uri` for
+  `tools/call`, `resources/read`, `prompts/get`), with Base64 sentinel value
+  encoding for non-ASCII/unsafe values.
+- [x] **x-mcp-header param mirroring (SEP-2243)** — client mirrors annotated
+  tool parameters into `Mcp-Param-{Name}` headers with value encoding, and
+  validates the annotations (`Ask::MCP::XMcpHeader`): empty names, invalid
+  field-name characters, non-primitive types, case-insensitive duplicates,
+  and annotations not statically reachable via a `properties`-only chain
+  (items/composition/conditionals/$ref/$defs) all make a tool definition
+  invalid, and Streamable HTTP clients exclude such tools from `tools/list`
+  with a warning. Integer values outside the JavaScript safe range are
+  omitted from headers at call time.
+- [x] **`subscriptions/listen`** — transport opens the long-lived POST
+  response stream; `Client#listen(notifications)` convenience; delivered
+  notifications flow into the client's cache-invalidation handling.
+  Server-side emission: `Server::Stdio#notify_tools_list_changed` /
+  `notify_resources_list_changed` / `notify_prompts_list_changed` write the
+  notifications (deterministically ordered before the triggering response);
+  clients invalidate their caches on receipt (verified end-to-end).
+- [x] **HTTP+SSE transport deprecated (SEP-2596)** — marked in code/docs;
+  still functional for legacy servers.
+
+### 3.3 Results, caching, errors
+
+- [x] **`CacheableResult`** — `ttlMs` + `cacheScope` (`"private"` default,
+  configurable) emitted on `tools/list`, `resources/list`,
+  `resources/templates/list`, `resources/read`, `prompts/list` for stateless
+  peers.
+- [x] **Deterministic tool ordering** — `tools/list` order is stable (locked
+  by test) for client caching and prompt-cache hit rates.
+- [x] **`extensions` capability field** — capabilities are caller-provided
+  pass-through, so extension capabilities are supported by construction.
+
+### 3.4 Authorization
+
+- [x] **Issuer tracking** — `discover!` records the discovered `issuer`.
+- [x] **`iss` validation (RFC 9207)** — `Auth::OAuth#validate_iss!` rejects
+  an `iss` that does not match the recorded issuer.
+- [x] **Client ID Metadata Documents (SEP-991)** —
+  `Auth::ClientIdMetadataDocument` builds and validates the self-hosted JSON
+  document (required `client_id`/`client_name`/`redirect_uris`, https URL
+  client_id with a path, `client_id` matching the document URL,
+  `application_type` `native`/`web` with `native` default for CLI clients).
+  URL-based client IDs are portable across authorization servers, so no
+  re-registration is needed when the server changes.
+- [x] **Credential binding by issuer** — satisfied by construction: each
+  `OAuth` instance holds credentials for the single authorization server it
+  is configured/discovered against (no shared credential store exists).
+- [~] **`application_type` in Dynamic Client Registration** — ask-mcp has no
+  DCR implementation (it is deprecated in 2026-07-28); `application_type` is
+  supported via the Client ID Metadata Document builder.
+
+### 3.5 Deprecations (keep working, don't extend)
+
+- [x] Roots, Sampling, Logging marked deprecated (no new build-out; the
+  client still exposes `on_sampling`/elicitation handlers for MRTR).
+- [x] **OTel trace context conventions (SEP-414)** — `Ask::MCP::TraceContext`
+  extracts `traceparent`/`tracestate`/`baggage` from HTTP headers (incl.
+  Rack's `HTTP_*` convention) and from `_meta`; clients propagate configured
+  `_meta` fields (e.g. `meta: TraceContext.from_headers(rack_env)`).
+
+## 4. Conformance / verification
+
+- Unit (no subprocess): `bundle exec ruby -Itest test/client_test.rb`
+- Server (harness + subprocess): `bundle exec ruby -Itest test/server/stdio_test.rb`
+- Transports: `bundle exec ruby -Itest test/transport/`
+- Full suite: `bundle exec rake test`
+- Status: 299 runs, 686 assertions, 0 failures (green across repeated runs).
+
+Conformance: `test/conformance_test.rb` is the self-contained stand-in for the
+official MCP test suite — it runs the full lifecycle against the real server
+in both the `2025-06-18` handshake era and the `2026-07-28` stateless era, plus
+a stateless client end-to-end. Run the official MCP fixtures here too once the
+2026-07-28 fixtures are published.