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

package/source/MCP/Server.ts

@@ -0,0 +1,335 @@
+import { console } from 'openspan'
+import { BRANCH_TTL } from '../const.js'
+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 { MCP } from '../Annotation.js'
+
+/**
+ * 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

@@ -0,0 +1,51 @@
+import { readFileSync } from 'node:fs'
+import { LEGACY, MODERN, SERVER_INFO, VERSIONS } from './types.js'
+import type { MCP } from '../Annotation.js'
+
+/**
+ * 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

@@ -0,0 +1,80 @@
+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,91 @@
+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,94 @@
+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[]
+}