@toa.io/extensions.exposition 1.0.0-alpha.284 → 1.0.0-alpha.286

package/source/MCP/Server.ts

@@ -42,15 +42,17 @@ export class Server {
   private readonly discovery: Discovery
   private readonly origins: Set<string>
 
-  public constructor (options: MCP, tree: Tree) {
+  public constructor(options: MCP, tree: Tree) {
     this.options = options
     this.tree = tree
     this.discovery = discovery(options)
     this.origins = new Set(options.origins ?? [])
   }
 
-  public async process (context: http.Context,
-    route: http.Processor): Promise<http.OutgoingMessage> {
+  public async process(
+    context: http.Context,
+    route: http.Processor
+  ): Promise<http.OutgoingMessage> {
     if (context.request.method !== 'POST')
       throw new http.MethodNotAllowed(new Headers({ allow: 'POST' }))
 
@@ -60,14 +62,12 @@ export class Server {
     const version = this.version(context, message)
     const modern = version === MODERN
 
-    if (modern)
-      this.mirrored(context, message)
+    if (modern) this.mirrored(context, message)
 
     const result = await this.answer({ context, route, tree: this.tree }, message, modern)
 
     // a notification is answered by not answering, and there is nothing here to remember
-    if (message.id === undefined)
-      return { status: ACCEPTED }
+    if (message.id === undefined) return { status: ACCEPTED }
 
     return {
       status: OK,
@@ -77,21 +77,24 @@ export class Server {
   }
 
   /** Who may reach the endpoint at all, before anything it carries is read. */
-  private admit (context: http.Context): void {
+  private admit(context: http.Context): void {
     const origin = context.request.headers.origin
 
     // the revision requires this against DNS rebinding; a request without one is no browser's
     if (origin !== undefined && !this.origins.has(origin))
       throw new http.Forbidden('Origin is not allowed')
 
-    if (this.options.anonymous === true)
-      return
+    if (this.options.anonymous === true) return
 
     if ((context as { identity?: unknown }).identity == null)
       throw new http.Unauthorized()
   }
 
-  private async answer (scope: Scope, message: Message, modern: boolean): Promise<unknown> {
+  private async answer(
+    scope: Scope,
+    message: Message,
+    modern: boolean
+  ): Promise<unknown> {
     const params = message.params ?? {}
 
     switch (message.method) {
@@ -99,7 +102,11 @@ export class Server {
         return this.complete(this.discovery.modern, modern, DISCOVERY_CACHE)
 
       case 'tools/list':
-        return this.complete({ tools: await list(this.tree, scope.context) }, modern, TOOLS_CACHE)
+        return this.complete(
+          { tools: await list(this.tree, scope.context) },
+          modern,
+          TOOLS_CACHE
+        )
 
       case 'tools/call':
         return this.complete(await this.tool(scope, params), modern)
@@ -115,66 +122,98 @@ export class Server {
         return {}
 
       default:
-        throw new http.NotFound(response(message.id ?? null,
-          failure(METHOD_NOT_FOUND, `'${message.method}' is not a method this server answers`)))
+        throw new http.NotFound(
+          response(
+            message.id ?? null,
+            failure(
+              METHOD_NOT_FOUND,
+              `'${message.method}' is not a method this server answers`
+            )
+          )
+        )
     }
   }
 
-  private async tool (scope: Scope, params: Params): Promise<object> {
+  private async tool(scope: Scope, params: Params): Promise<object> {
     const named = params.name
 
     if (typeof named !== 'string')
-      throw new http.BadRequest(response(null,
-        failure(INVALID_PARAMS, '`tools/call` states the tool it calls by name')))
+      throw new http.BadRequest(
+        response(
+          null,
+          failure(INVALID_PARAMS, '`tools/call` states the tool it calls by name')
+        )
+      )
 
     const args = params.arguments ?? {}
 
     if (typeof args !== 'object' || args === null || Array.isArray(args))
-      throw new http.BadRequest(response(null,
-        failure(INVALID_PARAMS, '`arguments` must be an object')))
-
-    return await console.span({ name: named },
-      async () => await call(scope, named, args as Params))
+      throw new http.BadRequest(
+        response(null, failure(INVALID_PARAMS, '`arguments` must be an object'))
+      )
+
+    return await console.span(
+      { name: named },
+      async () => await call(scope, named, args as Params)
+    )
   }
 
   /**
    * Every result of the modern revision says what kind it is, and who answered it. Where the
    * revision names the operation as one whose result may be held, it says that too, and must.
    */
-  private complete (result: object, modern: boolean, cache?: Cache): object {
+  private complete(result: object, modern: boolean, cache?: Cache): object {
     return modern
-      ? { ...result, ...cache, resultType: 'complete', _meta: { [SERVER_INFO]: this.serverInfo() } }
+      ? {
+          ...result,
+          ...cache,
+          resultType: 'complete',
+          _meta: { [SERVER_INFO]: this.serverInfo() }
+        }
       : result
   }
 
-  private serverInfo (): unknown {
-    return (this.discovery.modern as { _meta: Record<string, unknown> })._meta[SERVER_INFO]
+  private serverInfo(): unknown {
+    return (this.discovery.modern as { _meta: Record<string, unknown> })._meta[
+      SERVER_INFO
+    ]
   }
 
   /**
    * Which revision this request is of. `initialize` is one by itself; otherwise the header
    * says, and a request that names none is of a revision that did not send one.
    */
-  private version (context: http.Context, message: Message): string {
-    if (message.method === 'initialize')
-      return LEGACY
+  private version(context: http.Context, message: Message): string {
+    if (message.method === 'initialize') return LEGACY
 
     const header = context.request.headers['mcp-protocol-version']
     const stated = declared(message.params ?? {})
 
     if (header !== undefined && stated !== undefined && header !== stated)
-      throw new http.BadRequest(response(message.id ?? null, failure(HEADER_MISMATCH,
-        `'MCP-Protocol-Version' says '${String(header)}' and the body says '${stated}'`)))
+      throw new http.BadRequest(
+        response(
+          message.id ?? null,
+          failure(
+            HEADER_MISMATCH,
+            `'MCP-Protocol-Version' says '${String(header)}' and the body says '${stated}'`
+          )
+        )
+      )
 
     const value = (header as string | undefined) ?? stated
 
-    if (value === undefined)
-      return LEGACY
+    if (value === undefined) return LEGACY
 
     if (!VERSIONS.includes(value))
-      throw new http.BadRequest(response(message.id ?? null,
-        failure(UNSUPPORTED_VERSION, 'Unsupported protocol version',
-          { supported: VERSIONS, requested: value })))
+      throw new http.BadRequest(
+        response(
+          message.id ?? null,
+          failure(UNSUPPORTED_VERSION, 'Unsupported protocol version', {
+            supported: VERSIONS,
+            requested: value
+          })
+        )
+      )
 
     return value
   }
@@ -183,12 +222,19 @@ export class Server {
    * What the modern revision mirrors into headers, so that what routes a request and what
    * answers it cannot be told two different things.
    */
-  private mirrored (context: http.Context, message: Message): void {
+  private mirrored(context: http.Context, message: Message): void {
     const meta = metadata(message.params ?? {})
 
     if (meta?.[PROTOCOL_VERSION] === undefined || meta[CLIENT_CAPABILITIES] === undefined)
-      throw new http.BadRequest(response(message.id ?? null, failure(INVALID_PARAMS,
-        `'_meta' states '${PROTOCOL_VERSION}' and '${CLIENT_CAPABILITIES}'`)))
+      throw new http.BadRequest(
+        response(
+          message.id ?? null,
+          failure(
+            INVALID_PARAMS,
+            `'_meta' states '${PROTOCOL_VERSION}' and '${CLIENT_CAPABILITIES}'`
+          )
+        )
+      )
 
     const id = message.id ?? null
 
@@ -199,7 +245,7 @@ export class Server {
   }
 
   /** A body the decoder refuses is a parse error; a media type it does not know is not. */
-  private async read (context: http.Context): Promise<Message> {
+  private async read(context: http.Context): Promise<Message> {
     let body: unknown
 
     try {
@@ -211,26 +257,41 @@ export class Server {
       throw exception
     }
 
-    if (typeof body !== 'object' || body === null || Array.isArray(body) ||
-      (body as Message).jsonrpc !== JSONRPC || typeof (body as Message).method !== 'string')
-      throw new http.BadRequest(response(null,
-        failure(INVALID_REQUEST, 'A request carries one JSON-RPC message')))
+    if (
+      typeof body !== 'object' ||
+      body === null ||
+      Array.isArray(body) ||
+      (body as Message).jsonrpc !== JSONRPC ||
+      typeof (body as Message).method !== 'string'
+    )
+      throw new http.BadRequest(
+        response(null, failure(INVALID_REQUEST, 'A request carries one JSON-RPC message'))
+      )
 
     return body as Message
   }
 }
 
 /** What a header says must be what the body says, or what routes and what answers differ. */
-function mirrors (context: http.Context, mirror: Mirror): void {
+function mirrors(context: http.Context, mirror: Mirror): void {
   const { id, header, value } = mirror
   const stated = context.request.headers[header]
 
   if (stated === undefined)
-    throw new http.BadRequest(response(id, failure(HEADER_MISMATCH, `'${header}' is required`)))
+    throw new http.BadRequest(
+      response(id, failure(HEADER_MISMATCH, `'${header}' is required`))
+    )
 
   if (decode(String(stated)) !== value)
-    throw new http.BadRequest(response(id, failure(HEADER_MISMATCH,
-      `'${header}' says '${String(stated)}' and the body says '${String(value)}'`)))
+    throw new http.BadRequest(
+      response(
+        id,
+        failure(
+          HEADER_MISMATCH,
+          `'${header}' says '${String(stated)}' and the body says '${String(value)}'`
+        )
+      )
+    )
 }
 
 interface Mirror {
@@ -239,24 +300,23 @@ interface Mirror {
   value: unknown
 }
 
-function metadata (params: Params): Record<string, unknown> | undefined {
+function metadata(params: Params): Record<string, unknown> | undefined {
   const meta = params._meta
 
   return typeof meta === 'object' && meta !== null
-    ? meta as Record<string, unknown>
+    ? (meta as Record<string, unknown>)
     : undefined
 }
 
-function declared (params: Params): string | undefined {
+function declared(params: Params): string | undefined {
   const stated = metadata(params)?.[PROTOCOL_VERSION]
 
   return typeof stated === 'string' ? stated : undefined
 }
 
 /** What a header value that could not be written as ASCII was encoded as. */
-function decode (value: string): string {
-  if (!value.startsWith(SENTINEL) || !value.endsWith(TERMINATOR))
-    return value
+function decode(value: string): string {
+  if (!value.startsWith(SENTINEL) || !value.endsWith(TERMINATOR)) return value
 
   const encoded = value.slice(SENTINEL.length, -TERMINATOR.length)
 

package/source/MCP/discover.ts

@@ -15,7 +15,7 @@ export interface Discovery {
   legacy: (offered: string | undefined) => object
 }
 
-export function discovery (options: MCP): Discovery {
+export function discovery(options: MCP): Discovery {
   const info = { name: options.name, version: VERSION }
 
   // `listChanged` is a stream a client holds open, and this endpoint holds none
@@ -27,10 +27,9 @@ export function discovery (options: MCP): Discovery {
     _meta: { [SERVER_INFO]: info }
   }
 
-  if (options.instructions !== undefined)
-    modern.instructions = options.instructions
+  if (options.instructions !== undefined) modern.instructions = options.instructions
 
-  function legacy (offered: string | undefined): object {
+  function legacy(offered: string | undefined): object {
     const value: Record<string, unknown> = {
       // what the client asked for where that is served, and the newest handshake otherwise
       protocolVersion: offered !== undefined && offered !== MODERN ? offered : LEGACY,
@@ -38,8 +37,7 @@ export function discovery (options: MCP): Discovery {
       serverInfo: info
     }
 
-    if (options.instructions !== undefined)
-      value.instructions = options.instructions
+    if (options.instructions !== undefined) value.instructions = options.instructions
 
     return value
   }
@@ -49,4 +47,5 @@ export function discovery (options: MCP): Discovery {
 
 /** What this gateway is, which is what answers however an application names itself. */
 const VERSION: string = JSON.parse(
-  readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version
+  readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+).version

package/source/MCP/errors.ts

@@ -17,16 +17,15 @@ 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 {
+export function failure(code: number, message: string, data?: unknown): Failure {
   const value: Failure = { code, message }
 
-  if (data !== undefined)
-    value.data = data
+  if (data !== undefined) value.data = data
 
   return value
 }
 
-export function response (id: string | number | null, error: Failure): Response {
+export function response(id: string | number | null, error: Failure): Response {
   return { jsonrpc: JSONRPC, id, error }
 }
 
@@ -36,7 +35,7 @@ export function response (id: string | number | null, error: Failure): Response
  * 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 {
+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'))
 
@@ -50,7 +49,7 @@ export function of (exception: unknown): Failure {
  * 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 {
+export function refusal(exception: http.ClientError): string {
   const body = exception.body
 
   if (typeof body !== 'object' || body === null || typeof body.code !== 'string')
@@ -58,7 +57,7 @@ export function refusal (exception: http.ClientError): string {
 
   const message = body.message as unknown
 
-  return typeof message === 'string' && message !== '' ? message : body.code as string
+  return typeof message === 'string' && message !== '' ? message : (body.code as string)
 }
 
 /**
@@ -74,7 +73,7 @@ const REFUSALS: Record<number, string> = {
   429: 'Too many calls'
 }
 
-function text (exception: http.Exception, fallback: string): string {
+function text(exception: http.Exception, fallback: string): string {
   return typeof exception.body === 'string' && exception.body !== ''
     ? exception.body
     : fallback

package/source/MCP/schema.test.ts

@@ -38,8 +38,11 @@ describe('input', () => {
       headers: { token: { header: 'x-access-token', type: 'string' } }
     }
 
-    assert.deepEqual(input(introspection, []),
-      { type: 'object', properties: {}, additionalProperties: false })
+    assert.deepEqual(input(introspection, []), {
+      type: 'object',
+      properties: {},
+      additionalProperties: false
+    })
   })
 
   it('should take the body as it is, requiring what it requires', () => {
@@ -78,7 +81,10 @@ 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('DELETE'), {
+      destructiveHint: true,
+      idempotentHint: true
+    })
     assert.deepEqual(annotations('PUT'), { idempotentHint: true })
     assert.equal(annotations('POST'), undefined)
   })

package/source/MCP/schema.ts

@@ -8,7 +8,7 @@ import type { Annotations } from './types.js'
  * 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 {
+export function input(introspection: Introspection, variables: string[]): object {
   const properties: Record<string, unknown> = {}
   const required: string[] = []
 
@@ -28,7 +28,8 @@ export function input (introspection: Introspection, variables: string[]): objec
   if (introspection.query !== undefined)
     properties.query = {
       type: 'object',
-      description: 'Which records the call works on: what to match, in what order, ' +
+      description:
+        'Which records the call works on: what to match, in what order, ' +
         'and how many at once.',
       properties: introspection.query
     }
@@ -37,13 +38,12 @@ export function input (introspection: Introspection, variables: string[]): objec
 
   if (body?.properties !== undefined) {
     Object.assign(properties, body.properties)
-    required.push(...body.required ?? [])
+    required.push(...(body.required ?? []))
   }
 
   const schema: Record<string, unknown> = { type: 'object', properties }
 
-  if (required.length > 0)
-    schema.required = required
+  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
@@ -56,27 +56,23 @@ export function input (introspection: Introspection, variables: string[]): objec
  * 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 {
+export function output(introspection: Introspection): object | undefined {
   const schema = introspection.output as Shape | null | undefined
 
-  if (schema === undefined || schema === null)
-    return undefined
+  if (schema === undefined || schema === null) return undefined
 
-  return Object.keys(schema).length === 0 ? undefined : schema as object
+  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 {
+export function annotations(verb: string): Annotations | undefined {
   const value: Annotations = {}
 
-  if (verb === 'GET' || verb === 'HEAD')
-    value.readOnlyHint = true
+  if (verb === 'GET' || verb === 'HEAD') value.readOnlyHint = true
 
-  if (verb === 'DELETE')
-    value.destructiveHint = true
+  if (verb === 'DELETE') value.destructiveHint = true
 
-  if (verb === 'PUT' || verb === 'DELETE')
-    value.idempotentHint = true
+  if (verb === 'PUT' || verb === 'DELETE') value.idempotentHint = true
 
   return Object.keys(value).length === 0 ? undefined : value
 }

package/source/MCP/tools.ts

@@ -20,7 +20,7 @@ import type { Params, Result, Tool } from './types.js'
  *
  * Sorted, because the revision asks for an order a client can cache on.
  */
-export async function list (tree: Tree, context: http.Context): Promise<Tool[]> {
+export async function list(tree: Tree, context: http.Context): Promise<Tool[]> {
   const tools: Tool[] = []
 
   /*
@@ -28,24 +28,22 @@ export async function list (tree: Tree, context: http.Context): Promise<Tool[]>
    * 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 } })
+  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
+    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
+    if (named === null) continue
 
     const variables = parameters(segments)
     const introspection = await method.explain(describing, variables)
 
-    if (introspection === null)
-      continue
+    if (introspection === null) continue
 
     const described = introspection.description
     const schema = output(introspection)
@@ -54,16 +52,20 @@ export async function list (tree: Tree, context: http.Context): Promise<Tool[]>
     // in the order the revision documents one, which is the order it is read in
     const tool: Tool = {
       name: named,
-      ...described === undefined ? {} : { description: described },
-      inputSchema: input(introspection, variables.map((variable) => variable.name)),
-      ...schema === undefined ? {} : { outputSchema: schema },
-      ...hints === undefined ? {} : { annotations: hints }
+      ...(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)
+  return tools.sort((one, other) => (one.name < other.name ? -1 : 1))
 }
 
 /**
@@ -74,10 +76,14 @@ export async function list (tree: Tree, context: http.Context): Promise<Tool[]>
  * 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> {
+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`)))
+    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)
@@ -98,7 +104,10 @@ export async function call (scope: Scope, named: string, args: Params): Promise<
      * — 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))
+    if (
+      exception instanceof http.ClientError &&
+      !(exception instanceof http.Unauthorized)
+    )
       return { content: [{ type: 'text', text: refusal(exception) }], isError: true }
 
     throw exception
@@ -117,7 +126,7 @@ export interface Scope {
  * 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 {
+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
@@ -125,9 +134,8 @@ function published (tree: Tree, named: string): boolean {
   return false
 }
 
-function result (body: unknown): Result {
-  if (body === undefined || body === null)
-    return { content: [] }
+function result(body: unknown): Result {
+  if (body === undefined || body === null) return { content: [] }
 
   return {
     content: [{ type: 'text', text: JSON.stringify(body) }],
@@ -139,15 +147,13 @@ function result (body: unknown): Result {
  * 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[] {
+function parameters(segments: Segment[]): Parameter[] {
   const params: Parameter[] = []
 
   for (const segment of segments) {
-    if (segment.fragment !== null)
-      continue
+    if (segment.fragment !== null) continue
 
-    if (segment.wildcard === true)
-      params.push({ name: '**', value: '' })
+    if (segment.wildcard === true) params.push({ name: '**', value: '' })
     else if (segment.placeholder !== null)
       params.push({ name: segment.placeholder, value: '' })
   }

package/source/MCP/types.ts

@@ -66,7 +66,10 @@ export interface Content {
 export interface Tool {
   name: string
 
-  /** what the operation states it is; absent where it states nothing */
+  /** 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