@toa.io/extensions.exposition 1.0.0-alpha.283 → 1.0.0-alpha.285

package/documentation/mcp.md

@@ -0,0 +1,186 @@
+# Model Context Protocol
+
+An application annotates it, and the methods it names as tools are what a model may call.
+
+```yaml
+exposition:
+  mcp:
+    name: Teapots
+    instructions: A pot is read by its id. A pot that is brewing cannot be emptied.
+    origins: [https://claude.ai]
+```
+
+<dl>
+<dt><code>name</code></dt>
+<dd>Required. What the server calls itself, which a client shows a user.</dd>
+<dt><code>instructions</code></dt>
+<dd>What a model is told before it calls anything here.</dd>
+<dt><code>origins</code></dt>
+<dd>Browser origins the endpoint answers. A request carrying an <code>Origin</code> that is not
+listed is <code>403</code>, and an empty list admits none; a request carrying none is unaffected.</dd>
+<dt><code>anonymous</code></dt>
+<dd>Whether the endpoint answers without a credential. It does not unless it says so.</dd>
+</dl>
+
+Without the annotation `/.mcp` is a path like any other, and nothing answers there. The path is
+fixed: one an application could choose is one it could collide with a route of its own.
+
+## What a tool is
+
+A tool is an RTD method that says it is one, named as the [procedure](rpc.md#the-name) it is:
+
+```yaml
+/pots:
+  GET:
+    mcp:tool: Every pot there is, newest first.
+    endpoint: enumerate
+  /hot:
+    GET:
+      query: { criteria: temperature=gt=80 }
+      mcp:tool:
+        title: Hot pots
+        description: The pots that are too hot to pour.
+      endpoint: enumerate
+```
+
+A default denies, and a tree holds everything an application serves — its identity endpoints, its
+uploads, the machinery of the authorization flow the model already came through. Publishing all of
+it would spend a model's context on what it has no business calling.
+
+The value is what the tool is, and stating it is what publishes it — there is no way to publish one
+that says nothing, because a tool a model cannot read the purpose of is one it cannot choose.
+
+A `title` is what a person is shown where a client lists what it may call. Without one a client has
+only the name, which is an address — `apps._identity._id.repos.POST` — and reads as one. A
+description alone is written as the value; a title beside it is written as a mapping.
+
+An operation [states what it is](/documentation/component/declaration.md) as well, and that is not
+this: it is written without knowledge of any route, and a tool is an operation and a route together.
+The two routes above are one operation and two tools, and one sentence is not true of both. The
+operation's own is the Introspection's to read, and the gateway does not use it.
+
+A declaration is inherited by everything below it, as every directive is, and the nearer one wins.
+Since what it carries is what one method is, it belongs on a method: a node stating one would say
+the same thing of everything under it.
+
+A route whose name a client [cannot spell](rpc.md#what-has-a-name) is refused where the directive
+is built, rather than served as a tool that is quietly never listed.
+
+`tools/list` answers every published method this caller may reach — a method whose directives refuse
+them is not listed, and a route with [no name](rpc.md#what-has-a-name) is not either. `tools/call`
+answers `404` to a name that is not published, whether or not a route would have taken it: what an
+application did not publish is not reachable by guessing what it would have been called.
+
+`annotations` are read from the verb: `GET` and `HEAD` are `readOnlyHint`, `DELETE` is
+`destructiveHint`, `PUT` and `DELETE` are `idempotentHint`.
+
+## What a tool takes
+
+`inputSchema` is the procedure's `params`, which is what the method
+[says of itself](introspection.md): a route variable by the name the template gives it, the
+querystring under `query`, and what is left is the body. `io:input` restricts it, and a property
+`map` fills is not there — a call carries no headers of its own.
+
+```yaml
+type: object
+properties:
+  id: { type: string, pattern: ^[a-fA-F0-9]{32}$ }
+  query:
+    type: object
+    properties:
+      criteria: { type: string }
+      sort: { type: string }
+      limit: { type: integer, minimum: 1, maximum: 100, default: 10 }
+      omit: { type: integer, minimum: 0, maximum: 1000, default: 0 }
+required: [id]
+additionalProperties: false
+```
+
+## What a tool answers
+
+`content` carries one `text` block holding the reply's JSON, and `structuredContent` the reply
+itself. A reply of nothing is an empty `content`.
+
+`outputSchema` is what the operation declares, restricted by `io:output`. An operation's `output` is
+optional and normalizes to `{}`, which describes nothing, and none is stated for it — an
+application that wants the schema declares the operation's `output`.
+
+An operation that refuses answers a result with `isError: true` carrying its message, not an error
+of the protocol: it is something a model reads and may correct itself by.
+
+## Two revisions
+
+Both are answered from one endpoint that remembers nothing between requests.
+[`2026-07-28`](https://modelcontextprotocol.io/specification/2026-07-28) carries the version and
+the client's capabilities in every request; `2025-11-25` opens with `initialize`. Which one a
+request is, is read from `MCP-Protocol-Version`, or from
+`_meta['io.modelcontextprotocol/protocolVersion']` where the header is absent; `initialize` is one
+by itself, and a request naming no version is of a revision that sent none.
+
+| method | |
+| --- | --- |
+| `server/discover` | what is served, and who serves it |
+| `tools/list` | every tool this caller may reach, in a stable order |
+| `tools/call` | the call the tool is |
+| `initialize` | the same as `server/discover`, in the shape a client of `2025-11-25` reads |
+| `notifications/initialized` | `202`, and nothing done |
+| `ping` | `{}` |
+
+`POST` only, one message per request; `GET` and `DELETE` are `405`. An `Mcp-Session-Id` is ignored
+and none is minted, a `Last-Event-ID` is ignored, and `accept` is negotiated as everywhere else.
+
+Of the modern revision, `MCP-Protocol-Version` and `Mcp-Method` are required, and `Mcp-Name` for a
+`tools/call`; each must say what the body says. `_meta` states the protocol version and the client's
+capabilities. Every result carries `resultType` and names the server in its own `_meta`, and a
+`server/discover` or a `tools/list` carries how long it may be held: half an hour, `public` for the
+first and `private` for the second, which is filtered by the identity that asked.
+
+Neither `listChanged` nor a subscription is declared: both are a stream held open, and this endpoint
+holds none.
+
+## Authorization
+
+The endpoint is a protected resource, and an application advertises it as one:
+
+```yaml
+exposition:
+  oauth:
+    authorize: https://app.example.com/oauth/authorize
+    resources: ['/.mcp']
+```
+
+Its RFC 9728 document is then read at `/.well-known/oauth-protected-resource/.mcp`, and the
+canonical URI of the resource is `https://api.example.com/.mcp`. See [OAuth](oauth.md).
+
+A request without a credential is `401`, carrying the challenge that names that document — which is
+where the flow starts. A call the identity is not authorized to make is `403` with
+`error="insufficient_scope"`. Each tool is authorized as the resource it is, against the path and
+the verb its name states.
+
+A route that is [`anonymous`](access.md#anonymous) is reached here whatever the client presented:
+the rule that refuses a credentialed request is about a cacheable reply, and what a tool answers is
+not one. So a resource that is public over HTTP is a public tool, and nothing in a manifest has to
+say it twice.
+
+## What refuses
+
+| | |
+| --- | --- |
+| `-32700` | the body is not readable |
+| `-32600` | the body is not one JSON-RPC message |
+| `-32601` | no method of that name, at `404` |
+| `-32602` | the arguments do not fit, or `_meta` states too little |
+| `-32603` | anything the gateway did not mean to answer |
+| `-32020` | a header says one thing and the body another |
+| `-32022` | a revision neither served, naming both |
+
+The codes MCP reserves for itself are `-32020` to `-32099`, and it has an implementation use none of
+`-32000` to `-32019` — which is where [JSON-RPC](rpc.md#what-refuses) has this gateway's own, so none
+of those is answered here.
+
+## References
+
+- [The specification](https://modelcontextprotocol.io/specification/2026-07-28)
+- [JSON-RPC](rpc.md), where a procedure gets its name
+- [Introspection](introspection.md), which is what a tool's schemas are
+- [Features](../features/mcp.feature)

package/documentation/oauth.md

@@ -11,7 +11,7 @@ exposition:
     local: api.example.com
   oauth:
     authorize: https://app.example.com/oauth/authorize
-    resources: ['/mcp/']
+    resources: ['/.mcp']
     scopes: [app:notes, app:notes:read]
     registration: closed
 ```
@@ -22,7 +22,8 @@ exposition:
 <a href="consent.md">Consent</a>.</dd>
 <dt><code>resources</code></dt>
 <dd>Paths advertised as protected resources, each with a document of its own and named by the
-challenge a request to it is refused with. A token is not yet bound to one, see
+challenge a request to it is refused with. <code>/.mcp</code> is where
+<a href="mcp.md">MCP</a> is served. A token is not yet bound to one, see
 <a href="#audience">Audience</a>.</dd>
 <dt><code>scopes</code></dt>
 <dd>Advertised as what a client may ask for. Each is a <a href="access.md#roles">role</a>, or a
@@ -56,11 +57,11 @@ authorization_response_iss_parameter_supported: true
 
 `/.well-known/oauth-protected-resource` is
 [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) metadata. Each configured resource has one of
-its own, at the path the well-known segment is followed by: `/mcp/` is read at
-`/.well-known/oauth-protected-resource/mcp`.
+its own, at the path the well-known segment is followed by: `/.mcp` is read at
+`/.well-known/oauth-protected-resource/.mcp`.
 
 ```yaml
-resource: https://api.example.com/mcp
+resource: https://api.example.com/.mcp
 authorization_servers: [https://api.example.com]
 bearer_methods_supported: [header]
 ```
@@ -72,7 +73,7 @@ A reply of `401` carries the challenge that names the document:
 
 ```http
 401 Unauthorized
-www-authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp", scope="app:notes"
+www-authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/.mcp", scope="app:notes"
 ```
 
 ## Clients
@@ -168,7 +169,7 @@ of the identity that consented, over every path that identity may reach, whichev
 asked for.
 
 Restricting it is a `permissions` argument at the `identity.tokens.issue` call in
-`identity.grants.exchange` — `{'/mcp/**': ['*']}` for a resource at `/mcp/` — enforced by
+`identity.grants.exchange` — `{'/.mcp': ['*']}` for a resource at `/.mcp` — enforced by
 `permits()`, which is already what reads a token's permissions on every request. It waits on the
 resource that will check the audience itself.
 

package/documentation/rpc.md

@@ -0,0 +1,144 @@
+# JSON-RPC
+
+An application annotates it, and every resource it exposes answers as a procedure as well.
+
+```yaml
+exposition:
+  rpc:
+    batch: 32
+```
+
+Without it `/.rpc` is a path like any other, and nothing answers there. The path is fixed:
+one an application could choose is one it could collide with a route of its own.
+
+## The name
+
+A procedure is an RTD method — a node and a verb — and its name is the route template with a
+variable marked by a leading `_` and the verb as the last segment, joined by `.`.
+
+The separator is `.` and not `/` because a name is a tool's name too, and
+[MCP](mcp.md) names the characters one may hold: letters, digits, `_`, `-` and `.`. A client that
+receives one outside that set may refuse the tool, and one that accepts it rewrites what it shows
+a model — so what is published has to be spellable as it stands.
+
+| route | verb | method |
+| --- | --- | --- |
+| `/pots` | `GET` | `pots.GET` |
+| `/pots` | `POST` | `pots.POST` |
+| `/pots/:id` | `GET` | `pots._id.GET` |
+| `/identity/tokens/:identity` | `POST` | `identity.tokens._identity.POST` |
+| `/files/**` | `GET` | `files.__.GET` |
+| `/` | `GET` | `GET` |
+
+The verb is always the last segment, so `/pots/GET` answering `POST` is `pots.GET.POST` and
+`/pots` answering `GET` is `pots.GET`. Nothing is declared to make a name: a re-mounted route is
+a renamed procedure, because the name is the address.
+
+## What has a name
+
+A segment is addressed where it holds only `A-Z`, `a-z`, `0-9` and `-`. `_` is the name's own,
+marking a variable, and `__` the rest of a path; `.` is what divides one segment from the next.
+
+A route with a segment holding anything else — a `.`, a `_`, a `*`, a variable that is not one
+word — has no name. It is served over HTTP as it always was; what it loses is the address, so
+`/.rpc` cannot call it. Each is said once at startup, naming the route and the segment.
+
+```
+Route cannot be addressed as a procedure  route=/pots/v1.0 segment=v1.0
+```
+
+## The parameters
+
+`params` is by name, and carries what a request carries.
+
+A key the template names is a route variable, and is taken by the path. `query` is the
+querystring. Whatever is left is the body.
+
+```json
+{"jsonrpc": "2.0", "id": 1, "method": "pots._id.GET", "params": {"id": "a1b2"}}
+```
+
+```json
+{"jsonrpc": "2.0", "id": 2, "method": "pots.POST",
+ "params": {"title": "Kettle", "volume": 1.7}}
+```
+
+```json
+{"jsonrpc": "2.0", "id": 3, "method": "pots.GET",
+ "params": {"query": {"criteria": "volume=gt=1", "limit": 10}}}
+```
+
+The querystring has a name of its own because an operation's input is free to have an `id` or
+a `limit`, and the two would otherwise be one object. An operation whose input has a property
+named `query` cannot be called with one.
+
+A variable stands for a single segment, so its value may not contain `/`, `?` or `#`. `__`
+stands for the rest of the path and may contain `/`; its value is read under the name `**`,
+which is what the RTD calls it wherever else it is read.
+
+## What answers
+
+The reply is the operation's, restricted by the same [`io:output`](io.md) as the resource's,
+and encoded as the request's `accept` asks. A call that returned nothing answers `result: null`
+— JSON-RPC has no 404, and nothing went wrong.
+
+A call with no `id` is a notification: it runs and answers nothing, and a request carrying only
+notifications answers `204`.
+
+## Several at once
+
+A request may carry an array of calls instead of one, and answers an array of what they
+answered — shorter than what it was given, where some were notifications.
+
+```json
+[{"jsonrpc": "2.0", "id": 1, "method": "pots._id.GET", "params": {"id": "a1b2"}},
+ {"jsonrpc": "2.0", "method": "pots._id.DELETE", "params": {"id": "c3d4"}}]
+```
+
+They run one after another, in the order given. `batch` is how many one request may carry, 32
+where the annotation does not say: a request is one authentication and one reply however many
+calls it makes, so what a caller may ask for at once is bounded.
+
+## What refuses
+
+The whole request is refused, with a status, when it is not a request this endpoint serves: a
+verb other than `POST` is `405`, an unreadable body is `400`, and an array that is empty or
+longer than `batch` is `400`.
+
+A call that is not one — a version it does not state, a method it does not name — is answered
+to nobody: `id` is `null`, because nothing about it is trustworthy enough to answer to.
+
+A credential is the request's, so a call cannot be refused for one: a request that presents
+none where the procedure requires one is `401`, and carries the challenge that says where to
+authenticate.
+
+Everything else a call runs into is a value, at `200`, because the request itself succeeded.
+
+| | |
+| --- | --- |
+| `-32601` | no route of that name, or no such verb on it |
+| `-32602` | a variable is missing, or a query is not one |
+| `-32000` | the identity is not authorized to make this call |
+| `-32001` | the operation refused, its own code in `data.code` |
+| `-32603` | anything the gateway did not mean to answer |
+| `-32002` | the request carries more calls than `batch` |
+
+The first five codes JSON-RPC states mean the same to every client. `-32000` and `-32001` are
+this gateway's, from the block the specification reserves and leaves empty, so
+`-32001` says only that an operation refused — `data.code` is the code that operation declares
+in its manifest, and is what a caller reads.
+
+## Authorization
+
+A procedure is authorized as the resource is, against the path and the verb its name states.
+A token restricted to `/pots/:id/` for `GET` authorizes `pots._id.GET` and nothing else,
+whichever way the call arrives.
+
+[`anonymous`](access.md#anonymous) is the one directive that reads a call differently from a
+request: it admits one whatever the request presented, because what refuses a credentialed request
+is that the reply would not be cacheable, and what a call answers is not a reply.
+
+## What has no procedure
+
+`map:buffer` reads the request, and a call is not the request. A resource that declares it
+answers over HTTP alone.

package/documentation/tree.md

@@ -71,6 +71,9 @@ Forwarding Route variables are mapped to the forwarded Route variables if they h
 
 ## Methods
 
+Every Method is also addressable as a procedure, where the context annotates
+[JSON-RPC](rpc.md).
+
 Methods are mappings of the HTTP methods to the corresponding operations.
 
 A Method is a key named after the corresponding HTTP method, with a value following the schema

package/features/identity.basic.feature

@@ -323,6 +323,50 @@ Feature: Basic authentication
       message: Principal username cannot be changed
       """
 
+  Scenario: A Principal incepted by its own credentials holds the role at once
+    Given the `identity.basic` database is empty
+    And the `identity.basic` configuration:
+      """yaml
+      principal:
+        authority: nex
+        username: root
+      """
+    And the annotation:
+      """yaml
+      /:
+        io:output: true
+        GET:
+          auth:role: system:stub
+          dev:stub:
+            access: granted!
+      """
+    # the token the inception replies with carries the roles the Identity has by then
+    When the following request is received:
+      """
+      POST /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic cm9vdDpzZWNyZXQjMTIzNA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      authorization: Token ${{ token }}
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+
+      access: granted!
+      """
+
   Scenario: Principal username in another authority is ordinary credentials
     Given the `identity.basic` configuration:
       """yaml

package/features/identity.federation.feature

@@ -197,16 +197,13 @@ Feature: Identity Federation
       id: ${{ root.id }}
       """
 
-    Then after 0.2 seconds
-
-    # the role is checked over the id token: a Token carries the roles held when it
-    # was issued, and this one was issued before the grant
+    # the Role is granted before the reply, so the Token that reply carries holds it
     When the following request is received:
       """
       GET /identity/ HTTP/1.1
       host: nex.toa.io
       accept: application/yaml
-      authorization: Bearer ${{ root.id_token }}
+      authorization: Token ${{ root.token }}
       """
     Then the following reply is sent:
       """