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

package/source/MCP/schema.test.ts

@@ -1,91 +0,0 @@
-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

@@ -1,94 +0,0 @@
-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.
- */
-// eslint-disable-next-line max-params
-export function input(
-  introspection: Introspection,
-  variables: string[],
-  selection: Record<string, Schema> | null
-): 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. What selects
-   * records is stated here and not in the resource's own description, where it would be the
-   * same sentence on every queryable resource there is.
-   */
-  const query = { ...introspection.query, ...selection }
-
-  if (Object.keys(query).length > 0)
-    properties.query = {
-      type: 'object',
-      description:
-        'Which records the call works on: what to match, in what order, ' +
-        'and how many at once.',
-      properties: 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

@@ -1,144 +0,0 @@
-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 { describing } from '../Introspection.js'
-import { variables } from '../RTD/segment.js'
-import type { 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, request: http.Context): Promise<Tool[]> {
-  const tools: Tool[] = []
-
-  /*
-   * A description, not 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 context = describing(request)
-
-  for (const { segments, verb, method } of tree.walk()) {
-    if (!MCP.published(method.directives.declared<Declaration>(FAMILY))) 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 params = variables(segments)
-    const introspection = await method.explain(context, params)
-
-    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,
-        params.map((param) => param.name),
-        method.endpoint?.selection() ?? null
-      ),
-      ...(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))
-
-  return false
-}
-
-function result(body: unknown): Result {
-  if (body === undefined || body === null) return { content: [] }
-
-  return {
-    content: [{ type: 'text', text: JSON.stringify(body) }],
-    structuredContent: body
-  }
-}

package/source/MCP/types.ts

@@ -1,84 +0,0 @@
-/** 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/Mapping.ts

@@ -1,101 +0,0 @@
-import { type Parameter } from './RTD/index.js'
-import { Query } from './Query.js'
-import type { Introspection, Schema } from './Introspection.js'
-import type { QueryString } from './Query.js'
-import type * as http from './HTTP/index.js'
-import type * as syntax from './RTD/syntax/index.js'
-import type * as core from '@toa.io/core/types'
-
-export abstract class Mapping {
-  protected readonly query: Query
-  public abstract readonly queryable: boolean
-
-  public constructor(query: Query) {
-    this.query = query
-  }
-
-  public static create(query?: syntax.Query | null, paged?: boolean): Mapping {
-    const q = new Query(query!, paged)
-
-    return queryable(query) ? new QueryableMapping(q) : new InputMapping(q)
-  }
-
-  public explain(introspection: Introspection): Record<string, Schema> | null {
-    return this.query.explain(introspection)
-  }
-
-  /** What picks the records a call is about; see `Query.selection`. */
-  public selection(): Record<string, Schema> | null {
-    return this.query.selection()
-  }
-
-  protected assign(input: any, qs: QueryString): void {
-    if (qs.parameters !== null) {
-      if (typeof input !== 'object' || input === null)
-        throw new Error('Input must be an object to embed query parameters')
-
-      Object.assign(input, qs.parameters)
-    }
-  }
-
-  public abstract fit(
-    input: any,
-    query: http.Query,
-    parameters: Parameter[]
-  ): core.Request
-}
-
-class QueryableMapping extends Mapping {
-  public override readonly queryable = true
-
-  public fit(input: any, query: http.Query, parameters: Parameter[]): core.Request {
-    const request: core.Request = {}
-    const qs = this.query.fit(query, parameters)
-
-    if (input === undefined && qs.parameters !== null) input = {}
-
-    this.assign(input, qs)
-
-    if (input !== undefined) request.input = input
-
-    if (qs.query !== null) request.query = qs.query
-
-    return request
-  }
-}
-
-class InputMapping extends Mapping {
-  public override readonly queryable = false
-
-  public fit(input: any, query: http.Query, parameters: Parameter[]): core.Request {
-    const request: core.Request = {}
-    const qs = this.query.fit(query, parameters)
-
-    if (
-      input === undefined &&
-      (this.query.parameterized || parameters.length > 0 || qs.parameters !== null)
-    )
-      input = {}
-
-    if (parameters.length > 0) {
-      if (typeof input !== 'object' || input === null)
-        throw new Error('Input must be an object to embed parameters')
-
-      for (const parameter of parameters) input[parameter.name] = parameter.value
-    }
-
-    this.assign(input, qs)
-
-    if (input !== undefined) request.input = input
-
-    return request
-  }
-}
-
-export function queryable(query?: syntax.Query | null): boolean {
-  if (query === undefined || query === null) return false
-
-  const keys = Object.keys(query)
-
-  return !(keys.length === 1 && keys[0] === 'parameters')
-}

package/source/Query.test.ts

@@ -1,54 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Query } from './Query.js'
-import { type Parameter, type syntax } from './RTD/index.js'
-
-it('should combine request criteria', async () => {
-  const query: syntax.Query = {
-    criteria: 'foo==1;',
-    omit: { range: [0, 1] },
-    limit: { range: [0, 1] }
-  }
-
-  const parameters: Parameter[] = [
-    { name: 'bar', value: '2' },
-    { name: 'baz', value: '3' }
-  ]
-
-  const instance = new Query(query)
-  const result = instance.fit({ criteria: 'qux==4' }, parameters)
-
-  assert.deepStrictEqual(result.query!.criteria, '(bar=="2";baz=="3");(foo==1);(qux==4)')
-})
-
-it('should quote parameter values', async () => {
-  const query: syntax.Query = {
-    omit: { range: [0, 1] },
-    limit: { range: [0, 1] }
-  }
-
-  const parameters: Parameter[] = [{ name: 'user', value: 'me"),(user=="victim' }]
-
-  const instance = new Query(query)
-  const result = instance.fit({}, parameters)
-
-  assert.deepStrictEqual(result.query!.criteria, '(user=="me\\"),(user==\\"victim")')
-})
-
-it('should set id parameter as query.id', async () => {
-  const query: syntax.Query = {
-    omit: { range: [0, 1] },
-    limit: { range: [0, 1] }
-  }
-
-  const id = '87782631058445da81cb82f78b20c223'
-
-  const parameters: Parameter[] = [{ name: 'id', value: id }]
-
-  const instance = new Query(query)
-  const result = instance.fit({}, parameters)
-
-  assert.strictEqual(result.query!.criteria, undefined)
-  assert.deepStrictEqual(result.query!.id, id)
-})