@toa.io/extensions.exposition 1.0.0-alpha.291 → 1.0.0-alpha.293

package/features/mcp.feature

@@ -1,753 +0,0 @@
-@security
-Feature: Model Context Protocol
-
-  A tool is a procedure a method is published as. A method says so with `mcp:tool`, and a
-  default denies: a tree holds everything an application serves and most of it is machinery
-  a model has no business reading. What the tool is called and what it is for is
-  `help:method`, which is what describes the method everywhere else as well. What a tool
-  takes and answers is what the method says of itself, and what a caller may do with it is
-  what `auth` says.
-
-  What a tool is, is stated on the route and nowhere else. The operation states what it is
-  too, and that is not this: one operation mounted on two routes is two tools. A `title`
-  beside the description is what a person is shown where a client lists what it may call.
-
-  Two revisions are answered from one endpoint that remembers nothing between requests: the
-  modern one, where every request carries its own version and capabilities, and the one
-  before it, which opens with `initialize`. Neither is given a session, and neither is given
-  a stream.
-
-  Background:
-    Given the annotation:
-      """yaml
-      mcp:
-        name: Teapots
-        instructions: A pot is read by its id.
-        anonymous: true
-      """
-    And the `pots` is running with the following manifest:
-      """yaml
-      exposition:
-        /:
-          io:output: [id, title, volume]
-          GET:
-            mcp:tool: true
-            help:method:
-              description: All the pots, newest first.
-            endpoint: enumerate
-          POST:
-            mcp:tool: true
-            help:method:
-              description: Start a new pot brewing.
-            endpoint: create
-          /:id:
-            GET:
-              mcp:tool: true
-              help:method:
-                description: One pot, by its id.
-              endpoint: observe
-          /large:
-            GET:
-              query:
-                criteria: volume>=100
-              mcp:tool: true
-              help:method:
-                title: Large pots
-                description: The pots that hold a hundred or more, newest first.
-              endpoint: enumerate
-          /unpublished:
-            GET: enumerate
-          /guarded:
-            isolated: true
-            GET:
-              auth:role: admin
-              mcp:tool: true
-              help:method:
-                description: Every pot there is, for whoever may see them all.
-              endpoint: enumerate
-      """
-    And the `pots` database contains:
-      | _id                              | title     | volume |
-      | 4c4759e6f9c74da989d64511df42d6f4 | First pot | 100    |
-
-  Scenario: What the server is
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: server/discover
-
-      {"jsonrpc": "2.0", "id": 1, "method": "server/discover",
-       "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-      cache-control: no-store
-
-      jsonrpc: '2.0'
-      id: 1
-      result:
-        supportedVersions:
-          - '2026-07-28'
-          - '2025-11-25'
-        capabilities:
-          tools: {}
-        instructions: A pot is read by its id.
-        ttlMs: 1800000
-        cacheScope: public
-        resultType: complete
-      """
-
-  Scenario: What a client of an earlier revision opens with
-    No session is made, and none is named back.
-
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-
-      {"jsonrpc": "2.0", "id": 1, "method": "initialize",
-       "params": {"protocolVersion": "2025-11-25", "capabilities": {},
-                  "clientInfo": {"name": "Inspector", "version": "2.5.0"}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      jsonrpc: '2.0'
-      id: 1
-      result:
-        protocolVersion: '2025-11-25'
-        capabilities:
-          tools: {}
-        serverInfo:
-          name: Teapots
-        instructions: A pot is read by its id.
-      """
-    And the reply does not contain:
-      """
-      mcp-session-id
-      """
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      content-type: application/json
-
-      {"jsonrpc": "2.0", "method": "notifications/initialized"}
-      """
-    Then the following reply is sent:
-      """
-      202 Accepted
-      """
-
-  Scenario: What the tools are
-    Every method that is published and the caller may reach. One the caller may not, and
-    one that is published as nothing at all, are both absent.
-
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/list
-
-      {"jsonrpc": "2.0", "id": 2, "method": "tools/list",
-       "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      jsonrpc: '2.0'
-      id: 2
-      result:
-        tools:
-          - name: pots.GET
-            description: All the pots, newest first.
-            inputSchema:
-              type: object
-              properties:
-                query:
-                  type: object
-                  properties:
-                    criteria:
-                      type: string
-                    limit:
-                      type: integer
-                      minimum: 1
-                      maximum: 100
-                      default: 10
-              additionalProperties: false
-            annotations:
-              readOnlyHint: true
-          - name: pots.POST
-            description: Start a new pot brewing.
-            inputSchema:
-              type: object
-              properties:
-                title:
-                  type: string
-                  maxLength: 64
-                volume:
-                  type: number
-              required:
-                - title
-                - volume
-              additionalProperties: false
-          - name: pots._id.GET
-            description: One pot, by its id.
-            inputSchema:
-              type: object
-              properties:
-                id:
-                  type: string
-              required:
-                - id
-              additionalProperties: false
-          - name: pots.large.GET
-            title: Large pots
-            description: The pots that hold a hundred or more, newest first.
-            annotations:
-              readOnlyHint: true
-        ttlMs: 1800000
-        cacheScope: private
-        resultType: complete
-      """
-    And the reply does not contain:
-      """
-      pots.guarded.GET
-      """
-    And the reply does not contain:
-      """
-      pots.unpublished.GET
-      """
-    And the reply does not contain:
-      """
-      Put a pot on to brew.
-      """
-
-  Scenario: A method that is published as nothing is not called by guessing its name
-    A route the application did not publish is served over HTTP exactly as before. What it
-    does not have is a name here, and naming it anyway reaches nothing.
-
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/call
-      mcp-name: pots.unpublished.GET
-
-      {"jsonrpc": "2.0", "id": 30, "method": "tools/call",
-       "params": {"name": "pots.unpublished.GET", "arguments": {},
-                  "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      404 Not Found
-
-      jsonrpc: '2.0'
-      id: null
-      error:
-        code: -32601
-      """
-
-  Scenario: A tool that takes an identity is not listed to nobody
-    `tools/list` answers what this caller may reach, and it is the description that decides
-    — the same one `OPTIONS` answers. A model is not shown a tool it would be refused.
-
-    Given the annotation:
-      """yaml
-      mcp:
-        name: Pots
-        anonymous: true
-      /:
-        anonymous: true
-        /pots/:id:
-          isolated: true
-          GET:
-            anonymous: true
-            mcp:tool: true
-            help:method: One pot, by its id.
-            dev:stub: []
-          PATCH:
-            auth:id: id
-            mcp:tool: true
-            help:method: Change your own pot.
-            dev:stub: []
-      """
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/list
-
-      {"jsonrpc": "2.0", "id": 3, "method": "tools/list",
-       "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      - name: pots._id.GET
-      """
-    And the reply does not contain:
-      """
-      pots._id.PATCH
-      """
-
-  Scenario: A credential does not hide an anonymous tool
-    A client here always presents one, and what refuses a credentialed request at an
-    `anonymous` route is that the reply would not be cacheable — which a tool's is not.
-
-    # developer:secret
-    Given the `identity.basic` database contains:
-      | _id                              | authority | username  | password                                                     |
-      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
-    And the `identity.bans` database is empty
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/list
-
-      {"jsonrpc": "2.0", "id": 20, "method": "tools/list",
-       "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      jsonrpc: '2.0'
-      id: 20
-      result:
-        tools:
-          - name: pots.GET
-      """
-
-  Scenario: A tool takes what the procedure takes
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/call
-      mcp-name: pots._id.GET
-
-      {"jsonrpc": "2.0", "id": 3, "method": "tools/call",
-       "params": {"name": "pots._id.GET",
-                  "arguments": {"id": "4c4759e6f9c74da989d64511df42d6f4"},
-                  "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      jsonrpc: '2.0'
-      id: 3
-      result:
-        structuredContent:
-          id: 4c4759e6f9c74da989d64511df42d6f4
-          title: First pot
-          volume: 100
-        resultType: complete
-      """
-
-  Scenario: What is left of the arguments is the input
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/call
-      mcp-name: pots.POST
-
-      {"jsonrpc": "2.0", "id": 4, "method": "tools/call",
-       "params": {"name": "pots.POST", "arguments": {"title": "Kettle", "volume": 1.7},
-                  "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      jsonrpc: '2.0'
-      id: 4
-      result:
-        structuredContent:
-          id:
-      """
-
-  Scenario: A name nothing answers to
-
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/call
-      mcp-name: kettles.GET
-
-      {"jsonrpc": "2.0", "id": 5, "method": "tools/call",
-       "params": {"name": "kettles.GET", "arguments": {},
-                  "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      404 Not Found
-      """
-
-  Scenario: A method this server does not answer
-    The status is what tells a client that this endpoint is here and the method is not.
-
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: prompts/list
-
-      {"jsonrpc": "2.0", "id": 6, "method": "prompts/list",
-       "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      404 Not Found
-
-      jsonrpc: '2.0'
-      id: 6
-      error:
-        code: -32601
-      """
-
-  Scenario: A header saying one thing and a body another
-    What routes a request and what answers it must not be told two different things.
-
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/call
-      mcp-name: pots.GET
-
-      {"jsonrpc": "2.0", "id": 7, "method": "tools/call",
-       "params": {"name": "pots.POST", "arguments": {},
-                  "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      400 Bad Request
-
-      jsonrpc: '2.0'
-      id: 7
-      error:
-        code: -32020
-      """
-
-  Scenario: A revision neither served
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 1900-01-01
-      mcp-method: tools/list
-
-      {"jsonrpc": "2.0", "id": 8, "method": "tools/list", "params": {}}
-      """
-    Then the following reply is sent:
-      """
-      400 Bad Request
-
-      jsonrpc: '2.0'
-      id: 8
-      error:
-        code: -32022
-        data:
-          supported:
-            - '2026-07-28'
-            - '2025-11-25'
-          requested: '1900-01-01'
-      """
-
-  Scenario: What the endpoint does not serve
-    A stream is what these were for, and this endpoint has none.
-
-    When the following request is received:
-      """
-      GET /.mcp HTTP/1.1
-      host: nex.toa.io
-      """
-    Then the following reply is sent:
-      """
-      405 Method Not Allowed
-      allow: POST
-      """
-
-  Scenario: Without the annotation nothing answers there
-    Given the annotation:
-      """yaml
-      {}
-      """
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      content-type: application/json
-
-      {"jsonrpc": "2.0", "id": 9, "method": "tools/list", "params": {}}
-      """
-    Then the following reply is sent:
-      """
-      404 Not Found
-      """
-
-  Scenario: A tool the caller may not call
-    What `auth` makes of a call is a refusal of the call, not of the credential: the model
-    named a record that is not the caller's, which it may correct itself by naming another.
-    A challenge here would send the client to ask for a scope that would not help.
-
-    # developer:secret, who is not an `admin` and so may not reach `pots.guarded.GET`
-    Given the `identity.basic` database contains:
-      | _id                              | authority | username  | password                                                     |
-      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
-    And the `identity.bans` database is empty
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/call
-      mcp-name: pots.guarded.GET
-
-      {"jsonrpc": "2.0", "id": 31, "method": "tools/call",
-       "params": {"name": "pots.guarded.GET", "arguments": {},
-                  "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      jsonrpc: '2.0'
-      id: 31
-      result:
-        isError: true
-      """
-    And the reply does not contain:
-      """
-      insufficient_scope
-      """
-
-  Scenario: An argument the schemas would not take
-    What the arguments are refused for is the model's to correct by sending others, so it
-    is a result and not an error of the protocol.
-
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/call
-      mcp-name: pots._id.GET
-
-      {"jsonrpc": "2.0", "id": 32, "method": "tools/call",
-       "params": {"name": "pots._id.GET",
-                  "arguments": {"id": "not-an-id"},
-                  "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      jsonrpc: '2.0'
-      id: 32
-      result:
-        isError: true
-      """
-
-  Scenario: What the operation refused with
-    A refusal is a value a model reads and may correct itself by, so it is a result rather
-    than an error of the protocol.
-
-    Given the `echo` is running with the following manifest:
-      """yaml
-      exposition:
-        /:
-          io:output: true
-          GET:
-            mcp:tool: true
-            help:method:
-              description: Refuses, with what it was given.
-            endpoint: error
-      """
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/call
-      mcp-name: echo.GET
-
-      {"jsonrpc": "2.0", "id": 10, "method": "tools/call",
-       "params": {"name": "echo.GET", "arguments": {},
-                  "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      jsonrpc: '2.0'
-      id: 10
-      result:
-        content:
-          - type: text
-            text: message
-        isError: true
-        resultType: complete
-      """
-
-  Scenario: An operation that declares no output
-    A schema the revision would have the reply validated against is worse said emptily than
-    left unsaid — and the reply is answered all the same.
-
-    Given the `echo` is running with the following manifest:
-      """yaml
-      exposition:
-        /:
-          io:output: true
-          GET:
-            mcp:tool: true
-            help:method:
-              description: Answers with what it was given.
-            endpoint: echo
-      """
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/call
-      mcp-name: echo.GET
-
-      {"jsonrpc": "2.0", "id": 11, "method": "tools/call",
-       "params": {"name": "echo.GET", "arguments": {"greeting": "hello"},
-                  "_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      200 OK
-
-      jsonrpc: '2.0'
-      id: 11
-      result:
-        structuredContent:
-          greeting: hello
-        resultType: complete
-      """
-
-  Scenario: An origin that is not listed
-    The revision requires this against DNS rebinding, and an empty list admits none.
-
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      origin: https://elsewhere.example
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/list
-
-      {"jsonrpc": "2.0", "id": 12, "method": "tools/list",
-       "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      403 Forbidden
-      """
-
-  Scenario: Without a credential
-    A request without one is where the authorization flow starts, so the refusal carries
-    the document that says where to get a token.
-
-    Given the annotation:
-      """yaml
-      authorities:
-        nex: nex.toa.io
-      oauth:
-        authorize: https://app.nex.toa.io/oauth/authorize
-        resources: ['/.mcp']
-      mcp:
-        name: Teapots
-      """
-    When the following request is received:
-      """
-      POST /.mcp HTTP/1.1
-      host: nex.toa.io
-      accept: application/yaml
-      content-type: application/json
-      mcp-protocol-version: 2026-07-28
-      mcp-method: tools/list
-
-      {"jsonrpc": "2.0", "id": 13, "method": "tools/list",
-       "params": {"_meta": {"io.modelcontextprotocol/protocolVersion": "2026-07-28",
-                            "io.modelcontextprotocol/clientCapabilities": {}}}}
-      """
-    Then the following reply is sent:
-      """
-      401 Unauthorized
-      www-authenticate: Bearer resource_metadata="https://nex.toa.io/.well-known/oauth-protected-resource/.mcp"
-      """