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

package/source/Introspection.ts

@@ -33,28 +33,40 @@ export type Schema = Awaited<ReturnType<Remote['explain']>>['input']
  * The same, in the order the shape states — whatever order the families that filled it ran
  * in. What a resource says about itself is read, so it is written the way it is documented.
  */
-export function order (introspection: Introspection): Introspection {
+export function order(introspection: Introspection): Introspection {
   const ordered: Introspection = {}
 
   for (const key of KEYS)
-    if (introspection[key] !== undefined)
-      (ordered[key] as unknown) = introspection[key]
+    if (introspection[key] !== undefined) (ordered[key] as unknown) = introspection[key]
 
   return ordered
 }
 
-const KEYS = ['title', 'description', 'route', 'query', 'headers', 'input', 'output', 'errors'] as const
+const KEYS = [
+  'title',
+  'description',
+  'route',
+  'query',
+  'headers',
+  'input',
+  'output',
+  'errors'
+] as const
 
 /**
  * The schema of one input property, taken out of it: a property another family fills is
  * not the caller's to send, and what took it says where it comes from instead.
  */
-export function take (carrier: Carrier, property: string): Schema | undefined {
+export function take(carrier: Carrier, property: string): Schema | undefined {
   const input = carrier.input as Shape | null | undefined
   const properties = input?.properties
 
-  if (input === undefined || input === null || properties === undefined ||
-    !(property in properties))
+  if (
+    input === undefined ||
+    input === null ||
+    properties === undefined ||
+    !(property in properties)
+  )
     return undefined
 
   const schema = properties[property]
@@ -72,23 +84,23 @@ export function take (carrier: Carrier, property: string): Schema | undefined {
  * describes an array. What is not an object of properties is left alone: a whitelist has
  * nothing to say about a string.
  */
-export function restrict (schema: Schema | undefined, allowed: Set<string>): Schema | undefined {
+export function restrict(
+  schema: Schema | undefined,
+  allowed: Set<string>
+): Schema | undefined {
   const shape = schema as Shape | null | undefined
 
-  if (shape === undefined || shape === null)
-    return schema
+  if (shape === undefined || shape === null) return schema
 
   if (shape.items !== undefined)
     return { ...shape, items: restrict(shape.items, allowed) } as unknown as Schema
 
-  if (shape.properties === undefined)
-    return schema
+  if (shape.properties === undefined) return schema
 
   const properties: Record<string, Schema> = {}
 
   for (const [name, property] of Object.entries(shape.properties))
-    if (allowed.has(name))
-      properties[name] = property
+    if (allowed.has(name)) properties[name] = property
 
   const restricted: Shape = { ...shape, properties }
 

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
 }