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

package/source/MCP/errors.ts

@@ -0,0 +1,81 @@
+import * as http from '../HTTP/index.js'
+import { JSONRPC, type Failure, type Response } from './types.js'
+
+/* The five JSON-RPC 2.0 fixes, which mean the same to every client. */
+export const PARSE = -32700
+export const INVALID_REQUEST = -32600
+export const METHOD_NOT_FOUND = -32601
+export const INVALID_PARAMS = -32602
+export const INTERNAL = -32603
+
+/*
+ * MCP's own. It reserves -32020 to -32099 for the specification and tells an implementation
+ * to use nothing of -32000 to -32019 at all — which is where this gateway's JSON-RPC codes
+ * sit, so none of them is answered here.
+ */
+export const HEADER_MISMATCH = -32020
+export const MISSING_CAPABILITY = -32021
+export const UNSUPPORTED_VERSION = -32022
+
+export function failure (code: number, message: string, data?: unknown): Failure {
+  const value: Failure = { code, message }
+
+  if (data !== undefined)
+    value.data = data
+
+  return value
+}
+
+export function response (id: string | number | null, error: Failure): Response {
+  return { jsonrpc: JSONRPC, id, error }
+}
+
+/**
+ * What an exception says as a JSON-RPC error.
+ *
+ * The readable text is `body`, never `message`: `http.Exception` calls `super()` with no
+ * argument, so every one of them carries an empty `message`.
+ */
+export function of (exception: unknown): Failure {
+  if (exception instanceof http.NotFound || exception instanceof http.MethodNotAllowed)
+    return failure(METHOD_NOT_FOUND, text(exception, 'Method not found'))
+
+  if (exception instanceof http.BadRequest)
+    return failure(INVALID_PARAMS, text(exception, 'Invalid params'))
+
+  return failure(INTERNAL, 'Internal error')
+}
+
+/**
+ * What the call was refused with, which a model reads and may correct itself by: what the
+ * operation said, where it said anything, and otherwise what the status means here.
+ */
+export function refusal (exception: http.ClientError): string {
+  const body = exception.body
+
+  if (typeof body !== 'object' || body === null || typeof body.code !== 'string')
+    return text(exception, REFUSALS[exception.status] ?? 'Refused')
+
+  const message = body.message as unknown
+
+  return typeof message === 'string' && message !== '' ? message : body.code as string
+}
+
+/**
+ * A refusal a model can act on, where the reply carried no words of its own. `auth` does
+ * not say which of its directives refused, and `auth:id` is what most of them are: a call
+ * naming a record that is not the caller's is the likeliest thing to have gone wrong.
+ */
+const REFUSALS: Record<number, string> = {
+  400: 'The arguments were refused',
+  403: "Not authorized. If an argument names an identity or a record, it may not be the caller's own",
+  404: 'There is nothing at that address',
+  409: 'The record changed while the call was made',
+  429: 'Too many calls'
+}
+
+function text (exception: http.Exception, fallback: string): string {
+  return typeof exception.body === 'string' && exception.body !== ''
+    ? exception.body
+    : fallback
+}

package/source/MCP/index.ts

@@ -0,0 +1 @@
+export { Server } from './Server.js'

package/source/MCP/schema.test.ts

@@ -0,0 +1,85 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { annotations, input, output } from './schema.js'
+import type { Introspection, Schema } from '../Introspection.js'
+
+const schema = (value: object): Schema => value as unknown as Schema
+
+describe('input', () => {
+  it('should ask for a route variable by the name the template gives it', () => {
+    assert.deepEqual(input({ route: { id: schema({ type: 'string' }) } }, ['id']), {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+      additionalProperties: false
+    })
+  })
+
+  it('should ask for a variable the operation does not declare', () => {
+    assert.deepEqual(input({}, ['id']), {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+      additionalProperties: false
+    })
+  })
+
+  it('should carry the querystring under a name of its own', () => {
+    const introspection: Introspection = { query: { limit: schema({ type: 'integer' }) } }
+    const { properties } = input(introspection, []) as { properties: Record<string, any> }
+
+    assert.equal(properties.query.type, 'object')
+    assert.deepEqual(properties.query.properties, { limit: { type: 'integer' } })
+  })
+
+  it('should leave a header where a call has nowhere to put one', () => {
+    const introspection: Introspection = {
+      headers: { token: { header: 'x-access-token', type: 'string' } }
+    }
+
+    assert.deepEqual(input(introspection, []),
+      { type: 'object', properties: {}, additionalProperties: false })
+  })
+
+  it('should take the body as it is, requiring what it requires', () => {
+    const introspection: Introspection = {
+      input: schema({
+        type: 'object',
+        properties: { title: { type: 'string' }, volume: { type: 'number' } },
+        required: ['title']
+      })
+    }
+
+    assert.deepEqual(input(introspection, []), {
+      type: 'object',
+      properties: { title: { type: 'string' }, volume: { type: 'number' } },
+      required: ['title'],
+      additionalProperties: false
+    })
+  })
+})
+
+describe('output', () => {
+  it('should state a schema the operation declared', () => {
+    const declared = schema({ type: 'object', properties: { id: { type: 'string' } } })
+
+    assert.deepEqual(output({ output: declared }), declared)
+  })
+
+  it('should state none where the operation declared none', () => {
+    // an operation's `output` is optional and normalizes to `{}`, which describes nothing
+    assert.equal(output({ output: schema({}) }), undefined)
+    assert.equal(output({}), undefined)
+  })
+})
+
+describe('annotations', () => {
+  it('should read what the verb says of the call', () => {
+    assert.deepEqual(annotations('GET'), { readOnlyHint: true })
+    assert.deepEqual(annotations('HEAD'), { readOnlyHint: true })
+    assert.deepEqual(annotations('DELETE'), { destructiveHint: true, idempotentHint: true })
+    assert.deepEqual(annotations('PUT'), { idempotentHint: true })
+    assert.equal(annotations('POST'), undefined)
+  })
+})

package/source/MCP/schema.ts

@@ -0,0 +1,87 @@
+import type { Introspection, Schema } from '../Introspection.js'
+import type { Annotations } from './types.js'
+
+/**
+ * What a tool takes, which is what the procedure takes: a route variable by the name the
+ * template gives it, the querystring under a name of its own, and what is left is the body.
+ *
+ * A `map:headers` property is not here: a call carries no headers of its own, so there is
+ * nowhere for a model to put one.
+ */
+export function input (introspection: Introspection, variables: string[]): object {
+  const properties: Record<string, unknown> = {}
+  const required: string[] = []
+
+  /*
+   * By the name the template gives it, which is what the tool's own name states and what
+   * resolving it consumes. A `map:segments` renaming is the gateway's, as invisible here as
+   * it is to whoever writes the path; and a variable the operation does not declare has no
+   * schema of its own, being a segment.
+   */
+  for (const variable of variables) {
+    properties[variable] = introspection.route?.[variable] ?? { type: 'string' }
+    required.push(variable)
+  }
+
+  // it is a querystring on the wire, which is nothing a model knows or needs to; what it
+  // is to a caller is the part of a call that picks what the call is about
+  if (introspection.query !== undefined)
+    properties.query = {
+      type: 'object',
+      description: 'Which records the call works on: what to match, in what order, ' +
+        'and how many at once.',
+      properties: introspection.query
+    }
+
+  const body = introspection.input as Shape | null | undefined
+
+  if (body?.properties !== undefined) {
+    Object.assign(properties, body.properties)
+    required.push(...body.required ?? [])
+  }
+
+  const schema: Record<string, unknown> = { type: 'object', properties }
+
+  if (required.length > 0)
+    schema.required = required
+
+  // what a name does not state is not a parameter, and a model should not invent one
+  schema.additionalProperties = false
+
+  return schema
+}
+
+/**
+ * What a tool answers with, where that is worth stating. An operation's `output` is optional
+ * and normalizes to `{}`, which describes nothing — and a schema the revision would have the
+ * reply validated against is worse said emptily than left unsaid.
+ */
+export function output (introspection: Introspection): object | undefined {
+  const schema = introspection.output as Shape | null | undefined
+
+  if (schema === undefined || schema === null)
+    return undefined
+
+  return Object.keys(schema).length === 0 ? undefined : schema as object
+}
+
+/** What the verb says of the call, which the revision has a client treat as a hint. */
+export function annotations (verb: string): Annotations | undefined {
+  const value: Annotations = {}
+
+  if (verb === 'GET' || verb === 'HEAD')
+    value.readOnlyHint = true
+
+  if (verb === 'DELETE')
+    value.destructiveHint = true
+
+  if (verb === 'PUT' || verb === 'DELETE')
+    value.idempotentHint = true
+
+  return Object.keys(value).length === 0 ? undefined : value
+}
+
+interface Shape {
+  properties?: Record<string, Schema>
+  required?: string[]
+}

package/source/MCP/tools.ts

@@ -0,0 +1,157 @@
+import * as http from '../HTTP/index.js'
+import { fork } from '../RPC/Context.js'
+import { address, name, split } from '../RPC/names.js'
+import { METHOD_NOT_FOUND, failure, refusal, response } from './errors.js'
+import { annotations, input, output } from './schema.js'
+import { FAMILY, MCP, type Tool as Declaration } from '../directives/mcp/index.js'
+import type { Segment } from '../RTD/segment.js'
+import type { Parameter, Tree } from '../RTD/index.js'
+import type { Params, Result, Tool } from './types.js'
+
+/**
+ * Every method this caller may reach that is published as a tool, named as the procedure
+ * it is.
+ *
+ * A method is a tool where it says so with `mcp:tool`, and a default denies: a tree holds
+ * what an application serves, and most of it is machinery a model has no business reading.
+ * What a caller may then do with one is what `auth` says. The tree is walked once and each
+ * method describes itself, which is where that is decided and where `io` and `map` say what
+ * may be sent.
+ *
+ * Sorted, because the revision asks for an order a client can cache on.
+ */
+export async function list (tree: Tree, context: http.Context): Promise<Tool[]> {
+  const tools: Tool[] = []
+
+  /*
+   * Each method is described as the procedure it would be, not as the request asking. What
+   * refuses a credentialed request at an `anonymous` route does not refuse the call a tool
+   * makes, and a list that says otherwise disagrees with what `tools/call` then does.
+   */
+  const describing: http.Context = Object.create(context,
+    { procedural: { value: true, enumerable: true } })
+
+  for (const { segments, verb, method } of tree.walk()) {
+    if (MCP.published(method.directives.declared<Declaration>(FAMILY)) === null)
+      continue
+
+    const named = name(segments, verb)
+
+    // a route a name cannot spell is a route nothing addresses, here or at `/.rpc`
+    if (named === null)
+      continue
+
+    const variables = parameters(segments)
+    const introspection = await method.explain(describing, variables)
+
+    if (introspection === null)
+      continue
+
+    const described = introspection.description
+    const schema = output(introspection)
+    const hints = annotations(verb)
+
+    // in the order the revision documents one, which is the order it is read in
+    const tool: Tool = {
+      name: named,
+      ...introspection.title === undefined ? {} : { title: introspection.title },
+      ...described === undefined ? {} : { description: described },
+      inputSchema: input(introspection, variables.map((variable) => variable.name)),
+      ...schema === undefined ? {} : { outputSchema: schema },
+      ...hints === undefined ? {} : { annotations: hints }
+    }
+
+    tools.push(tool)
+  }
+
+  return tools.sort((one, other) => one.name < other.name ? -1 : 1)
+}
+
+/**
+ * The call the tool is. Its arguments are the procedure's parameters, taken apart the way a
+ * request carries them, and what answers is the same `route` an ordinary request goes to.
+ *
+ * A name that is not a published tool is answered as no tool at all, whether or not a route
+ * would have taken it: what an application did not publish is not reachable here by guessing
+ * its name. What the caller may then do with one that is published is still `auth`'s to say.
+ */
+export async function call (scope: Scope, named: string, args: Params): Promise<Result> {
+  if (!published(scope.tree, named))
+    throw new http.NotFound(response(null,
+      failure(METHOD_NOT_FOUND, `'${named}' is not a tool this server publishes`)))
+
+  const { path, verb, variables } = address(named, args)
+  const { query, input: body } = split(args, variables)
+  const clone = fork(scope.context, path, verb, query, body)
+
+  try {
+    const message = await scope.route(clone)
+
+    // what `io:output` restricts, over this call's reply rather than the envelope
+    await http.shape(clone, message)
+
+    return result(message.body)
+  } catch (exception) {
+    /*
+     * What the route made of this call is a value a model reads and may correct itself by:
+     * an operation that refused, an argument `io:input` would not take, a record that is
+     * not there, an identity `auth` would not let it act on. A credential is none of those
+     * — that is the client's to fix and not the model's, so it is answered as it is — and
+     * neither is a fault of this server, which is a protocol error and stays one.
+     */
+    if (exception instanceof http.ClientError && !(exception instanceof http.Unauthorized))
+      return { content: [{ type: 'text', text: refusal(exception) }], isError: true }
+
+    throw exception
+  }
+}
+
+/** Everything a call needs that is not the call: the request it is of, and what answers it. */
+export interface Scope {
+  context: http.Context
+  route: http.Processor
+  tree: Tree
+}
+
+/**
+ * Whether the tree publishes this name as a tool. What `auth` makes of the caller is not
+ * asked here — the declaration is the route's and does not vary by who is calling, and the
+ * call that follows is authorized as any request to that route is.
+ */
+function published (tree: Tree, named: string): boolean {
+  for (const { segments, verb, method } of tree.walk())
+    if (name(segments, verb) === named)
+      return MCP.published(method.directives.declared<Declaration>(FAMILY)) !== null
+
+  return false
+}
+
+function result (body: unknown): Result {
+  if (body === undefined || body === null)
+    return { content: [] }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(body) }],
+    structuredContent: body
+  }
+}
+
+/**
+ * What a route template takes, by name. Describing has no values for them — a template is
+ * not a path — and nothing that describes a method reads one.
+ */
+function parameters (segments: Segment[]): Parameter[] {
+  const params: Parameter[] = []
+
+  for (const segment of segments) {
+    if (segment.fragment !== null)
+      continue
+
+    if (segment.wildcard === true)
+      params.push({ name: '**', value: '' })
+    else if (segment.placeholder !== null)
+      params.push({ name: segment.placeholder, value: '' })
+  }
+
+  return params
+}

package/source/MCP/types.ts

@@ -0,0 +1,84 @@
+/** The revision this endpoint serves, where a request carries its own metadata. */
+export const MODERN = '2026-07-28'
+
+/** The newest revision reached by an `initialize` handshake, which is what clients still send. */
+export const LEGACY = '2025-11-25'
+
+export const VERSIONS = [MODERN, LEGACY]
+
+/** The version every JSON-RPC message states, which is not the protocol's. */
+export const JSONRPC = '2.0'
+
+/** The prefix the revision reserves for itself in `_meta`. */
+export const RESERVED = 'io.modelcontextprotocol/'
+
+export const PROTOCOL_VERSION = RESERVED + 'protocolVersion'
+export const CLIENT_CAPABILITIES = RESERVED + 'clientCapabilities'
+export const SERVER_INFO = RESERVED + 'serverInfo'
+
+export type Params = Record<string, unknown>
+
+export interface Message {
+  jsonrpc: string
+  method: string
+  params?: Params
+
+  /** Absent makes this a notification, which is answered by not answering. */
+  id?: string | number
+}
+
+export interface Failure {
+  code: number
+  message: string
+  data?: unknown
+}
+
+export interface Response {
+  jsonrpc: string
+  id: string | number | null
+  result?: unknown
+  error?: Failure
+}
+
+/**
+ * How long a complete result may be held, and by whom. `private` is a result that is the
+ * caller's alone — a list `auth` filtered for their identity is not another caller's list.
+ */
+export interface Cache {
+  ttlMs: number
+  cacheScope: 'public' | 'private'
+}
+
+/** What a tool answers with: what a model reads, and the reply itself. */
+export interface Result {
+  content: Content[]
+  structuredContent?: unknown
+
+  /** The operation refused, which is something a model can read and correct. */
+  isError?: boolean
+}
+
+export interface Content {
+  type: 'text'
+  text: string
+}
+
+export interface Tool {
+  name: string
+
+  /** what a person is shown where a client lists this tool; a name is an address */
+  title?: string
+
+  /** what the route states this method is */
+  description?: string
+  inputSchema: object
+  outputSchema?: object
+  annotations?: Annotations
+}
+
+/** What the verb says about the call, which the revision asks a client to treat as a hint. */
+export interface Annotations {
+  readOnlyHint?: boolean
+  destructiveHint?: boolean
+  idempotentHint?: boolean
+}

package/source/Query.ts

@@ -4,6 +4,7 @@ import * as http from './HTTP/index.js'
 import { type Parameter } from './RTD/index.js'
 import * as schemas from './schemas.js'
 import { queryable } from './Mapping.js'
+import { take } from './Introspection.js'
 import type { Introspection, Schema } from './Introspection.js'
 import type * as syntax from './RTD/syntax/index.js'
 import type * as core from '@toa.io/core'
@@ -68,22 +69,43 @@ export class Query {
     }
   }
 
+  /**
+   * What the querystring carries: the parameters this method declares, taken out of the
+   * input because they are not the body's, and what a queryable method accepts besides.
+   *
+   * Only what it actually accepts — a criteria the declaration closes is refused, and so is
+   * a search where none was asked for.
+   */
   public explain (introspection: Introspection): Record<string, Schema> | null {
-    if (this.query?.parameters === undefined || introspection.input?.type !== 'object')
-      return null
-
     let query: Record<string, Schema> | null = null
 
-    for (const parameter of this.query.parameters) {
-      const schema = introspection.input.properties[parameter]
+    if (this.query?.parameters !== undefined)
+      for (const parameter of this.query.parameters) {
+        const schema = take(introspection, parameter)
+
+        // eslint-disable-next-line max-depth
+        if (schema === undefined)
+          continue
 
-      if (schema !== undefined) {
         query ??= {}
         query[parameter] = schema
       }
 
-      delete introspection.input.properties[parameter]
-    }
+    if (!this.queryable)
+      return query
+
+    query ??= {}
+
+    if (!this.closed)
+      query.criteria = keyword('string',
+        'What to match, in RSQL: `state==hot`, `rank=gt=5;name==*tea*`.')
+
+    query.sort = keyword('string', 'What to order by: `rank:desc`, or `rank` for ascending.')
+    query.limit = bounded('How many at once.', this.query.limit!)
+    query.omit = bounded('How many to skip.', this.query.omit!)
+
+    if (this.searchable)
+      query.search = keyword('string', 'What to search the text index for.')
 
     return query
   }
@@ -202,6 +224,24 @@ interface CriteriaGroup {
   operator: ',' | ';'
 }
 
+function keyword (type: string, description: string): Schema {
+  return { type, description } as unknown as Schema
+}
+
+function bounded (description: string, bounds: syntax.Range): Schema {
+  const schema: Record<string, unknown> = {
+    type: 'integer',
+    description,
+    minimum: bounds.range[0],
+    maximum: bounds.range[1]
+  }
+
+  if (bounds.value !== undefined)
+    schema.default = bounds.value
+
+  return schema as unknown as Schema
+}
+
 export interface QueryString {
   query: core.Query | null
   parameters: Record<string, string> | null

package/source/RPC/Context.ts

@@ -0,0 +1,78 @@
+import * as http from '../HTTP/index.js'
+import { Timing } from '../HTTP/Timing.js'
+import type { Params } from './types.js'
+
+/**
+ * One call, as a request the rest of the gateway can serve.
+ *
+ * The clone is the transport context except for what the call decides, so nothing
+ * downstream — the router, the directives, the endpoint, the mapping — knows it is one.
+ * It is derived from the context rather than built beside it, so everything not named
+ * here, `identity` included, is read through.
+ */
+// eslint-disable-next-line max-params
+export function fork (context: http.Context, path: string, verb: string,
+  query: Params | undefined, input: unknown): http.Context {
+  const url = new URL(path, context.url)
+
+  if (query !== undefined)
+    for (const [name, value] of Object.entries(query))
+      url.searchParams.set(name, String(value))
+
+  const headers = { ...context.request.headers }
+
+  // a conditional is the envelope's, and a call would answer 304 to a question nobody asked
+  delete headers['if-match']
+  delete headers['if-none-match']
+
+  const request = Object.create(context.request, {
+    method: { value: verb, enumerable: true },
+    headers: { value: headers, enumerable: true }
+  })
+
+  // its own, so an `io:output` restriction shapes this call's reply and no other
+  const pipelines: Pipelines = { body: [], response: [] }
+
+  return Object.create(context, {
+    /*
+     * A credential refuses an `anonymous` route because it would make the reply
+     * uncacheable. What a procedure answers is not a reply: it is a value in an envelope
+     * this gateway answers `no-store`, and the procedure's own headers are discarded.
+     */
+    procedural: { value: true, enumerable: true },
+    url: { value: url, enumerable: true },
+    request: { value: request, enumerable: true },
+    pipelines: { value: pipelines, enumerable: true },
+    /*
+     * Its own, so that what the stages of a call take is measured per call and stays there.
+     * `server-timing` is a header, and a request carrying thirty-two calls would otherwise
+     * write ninety-six values into one — where a trace says the same thing, per call.
+     */
+    timing: { value: new Timing(), enumerable: true },
+    body: {
+      value: async () => {
+        let value = input
+
+        for (const transform of pipelines.body)
+          value = await transform(value)
+
+        return value
+      }
+    },
+    /*
+     * The raw request is the envelope, and it has been read. `map:buffer` is the one
+     * directive that asks for it, and answering with a spent stream would hand the
+     * operation an empty string; refusing says what is actually the matter.
+     */
+    buffer: {
+      value: () => {
+        throw new http.BadRequest('`map:buffer` reads the request, which a call is not')
+      }
+    }
+  }) as http.Context
+}
+
+interface Pipelines {
+  body: Array<(input: unknown) => unknown>
+  response: Array<(output: http.OutgoingMessage) => void | Promise<void>>
+}