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

package/source/MCP/Server.ts

@@ -1,335 +0,0 @@
-import { console } from 'openspan'
-import { BRANCH_TTL } from '@toa.io/definitions/extensions.exposition'
-import * as http from '../HTTP/index.js'
-import { discovery, type Discovery } from './discover.js'
-import { call, list, type Scope } from './tools.js'
-import {
-  HEADER_MISMATCH,
-  INVALID_PARAMS,
-  INVALID_REQUEST,
-  METHOD_NOT_FOUND,
-  PARSE,
-  UNSUPPORTED_VERSION,
-  failure,
-  response
-} from './errors.js'
-import {
-  CLIENT_CAPABILITIES,
-  JSONRPC,
-  LEGACY,
-  MODERN,
-  PROTOCOL_VERSION,
-  SERVER_INFO,
-  VERSIONS,
-  type Cache,
-  type Message,
-  type Params
-} from './types.js'
-import type { Tree } from '../RTD/index.js'
-import type { MCPAnnotation as MCP } from '@toa.io/definitions/extensions.exposition'
-
-/**
- * The Model Context Protocol, as one endpoint that remembers nothing between requests.
- *
- * Two revisions are answered from it. The modern one carries the version and the client's
- * capabilities in every request; the one before it opens with `initialize`, which is what
- * most clients still send. Neither needs a session, and neither needs a stream: every method
- * here answers one object, which is why this can exist in a package that serves no SSE.
- */
-export class Server {
-  private readonly options: MCP
-  private readonly tree: Tree
-  private readonly discovery: Discovery
-  private readonly origins: Set<string>
-
-  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> {
-    if (context.request.method !== 'POST')
-      throw new http.MethodNotAllowed(new Headers({ allow: 'POST' }))
-
-    this.admit(context)
-
-    const message = await this.read(context)
-    const version = this.version(context, message)
-    const modern = version === MODERN
-
-    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 }
-
-    return {
-      status: OK,
-      body: { jsonrpc: JSONRPC, id: message.id, result },
-      headers: new Headers({ 'cache-control': 'no-store' })
-    }
-  }
-
-  /** Who may reach the endpoint at all, before anything it carries is read. */
-  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 ((context as { identity?: unknown }).identity == null)
-      throw new http.Unauthorized()
-  }
-
-  private async answer(
-    scope: Scope,
-    message: Message,
-    modern: boolean
-  ): Promise<unknown> {
-    const params = message.params ?? {}
-
-    switch (message.method) {
-      case 'server/discover':
-        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
-        )
-
-      case 'tools/call':
-        return this.complete(await this.tool(scope, params), modern)
-
-      // what a client of an earlier revision opens with; no session is made and none is named
-      case 'initialize':
-        return this.discovery.legacy(declared(params))
-
-      case 'notifications/initialized':
-        return null
-
-      case 'ping':
-        return {}
-
-      default:
-        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> {
-    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')
-        )
-      )
-
-    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)
-    )
-  }
-
-  /**
-   * 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 {
-    return modern
-      ? {
-          ...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
-    ]
-  }
-
-  /**
-   * 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
-
-    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}'`
-          )
-        )
-      )
-
-    const value = (header as string | undefined) ?? stated
-
-    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
-          })
-        )
-      )
-
-    return value
-  }
-
-  /**
-   * 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 {
-    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}'`
-          )
-        )
-      )
-
-    const id = message.id ?? null
-
-    mirrors(context, { id, header: 'mcp-method', value: message.method })
-
-    if (message.method === 'tools/call')
-      mirrors(context, { id, header: 'mcp-name', value: (message.params ?? {}).name })
-  }
-
-  /** 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> {
-    let body: unknown
-
-    try {
-      body = await context.body()
-    } catch (exception) {
-      if (exception instanceof http.BadRequest)
-        throw new http.BadRequest(response(null, failure(PARSE, 'Parse error')))
-
-      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'))
-      )
-
-    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 {
-  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`))
-    )
-
-  if (decode(String(stated)) !== value)
-    throw new http.BadRequest(
-      response(
-        id,
-        failure(
-          HEADER_MISMATCH,
-          `'${header}' says '${String(stated)}' and the body says '${String(value)}'`
-        )
-      )
-    )
-}
-
-interface Mirror {
-  id: string | number | null
-  header: string
-  value: unknown
-}
-
-function metadata(params: Params): Record<string, unknown> | undefined {
-  const meta = params._meta
-
-  return typeof meta === 'object' && meta !== null
-    ? (meta as Record<string, unknown>)
-    : 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
-
-  const encoded = value.slice(SENTINEL.length, -TERMINATOR.length)
-
-  return Buffer.from(encoded, 'base64').toString('utf8')
-}
-
-/** A tool list is what the tree holds, which stands until a branch of it expires. */
-const TOOLS_CACHE: Cache = { ttlMs: BRANCH_TTL, cacheScope: 'private' }
-
-/** What the annotation says, which is the same for every caller until the application is redeployed. */
-const DISCOVERY_CACHE: Cache = { ttlMs: BRANCH_TTL, cacheScope: 'public' }
-
-const OK = 200
-const ACCEPTED = 202
-const SENTINEL = '=?base64?'
-const TERMINATOR = '?='

package/source/MCP/discover.ts

@@ -1,51 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { LEGACY, MODERN, SERVER_INFO, VERSIONS } from './types.js'
-import type { MCPAnnotation as MCP } from '@toa.io/definitions/extensions.exposition'
-
-/**
- * What a client is told before it calls anything: the revisions served, what is served, and
- * who serves it. It is a function of the annotation alone, so it is built once and answered
- * as it is.
- */
-export interface Discovery {
-  /** `server/discover`, which the modern revision has replaced the handshake with. */
-  modern: object
-
-  /** `initialize`, in the shape a client of an earlier revision reads. */
-  legacy: (offered: string | undefined) => object
-}
-
-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
-  const capabilities = { tools: {} }
-
-  const modern: Record<string, unknown> = {
-    supportedVersions: VERSIONS,
-    capabilities,
-    _meta: { [SERVER_INFO]: info }
-  }
-
-  if (options.instructions !== undefined) modern.instructions = options.instructions
-
-  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,
-      capabilities,
-      serverInfo: info
-    }
-
-    if (options.instructions !== undefined) value.instructions = options.instructions
-
-    return value
-  }
-
-  return { modern, legacy }
-}
-
-/** 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

package/source/MCP/errors.ts

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

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

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[]
-}