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

package/source/MCP/tools.ts

@@ -0,0 +1,144 @@
+import * as http from '../HTTP/index.js'
+import { fork } from '../RPC/Context.js'
+import { address, name, split } from '../RPC/names.js'
+import { METHOD_NOT_FOUND, failure, refusal, response } from './errors.js'
+import { annotations, input, output } from './schema.js'
+import { FAMILY, MCP, type Tool as Declaration } from '../directives/mcp/index.js'
+import { describing } from '../Introspection.js'
+import { variables } from '../RTD/segment.js'
+import type { Tree } from '../RTD/index.js'
+import type { Params, Result, Tool } from './types.js'
+
+/**
+ * Every method this caller may reach that is published as a tool, named as the procedure
+ * it is.
+ *
+ * A method is a tool where it says so with `mcp:tool`, and a default denies: a tree holds
+ * what an application serves, and most of it is machinery a model has no business reading.
+ * What a caller may then do with one is what `auth` says. The tree is walked once and each
+ * method describes itself, which is where that is decided and where `io` and `map` say what
+ * may be sent.
+ *
+ * Sorted, because the revision asks for an order a client can cache on.
+ */
+export async function list(tree: Tree, request: http.Context): Promise<Tool[]> {
+  const tools: Tool[] = []
+
+  /*
+   * A description, not the request asking. What refuses a credentialed request at an
+   * `anonymous` route does not refuse the call a tool makes, and a list that says otherwise
+   * disagrees with what `tools/call` then does.
+   */
+  const context = describing(request)
+
+  for (const { segments, verb, method } of tree.walk()) {
+    if (!MCP.published(method.directives.declared<Declaration>(FAMILY))) continue
+
+    const named = name(segments, verb)
+
+    // a route a name cannot spell is a route nothing addresses, here or at `/.rpc`
+    if (named === null) continue
+
+    const params = variables(segments)
+    const introspection = await method.explain(context, params)
+
+    if (introspection === null) continue
+
+    const described = introspection.description
+    const schema = output(introspection)
+    const hints = annotations(verb)
+
+    // in the order the revision documents one, which is the order it is read in
+    const tool: Tool = {
+      name: named,
+      ...(introspection.title === undefined ? {} : { title: introspection.title }),
+      ...(described === undefined ? {} : { description: described }),
+      inputSchema: input(
+        introspection,
+        params.map((param) => param.name),
+        method.endpoint?.selection() ?? null
+      ),
+      ...(schema === undefined ? {} : { outputSchema: schema }),
+      ...(hints === undefined ? {} : { annotations: hints })
+    }
+
+    tools.push(tool)
+  }
+
+  return tools.sort((one, other) => (one.name < other.name ? -1 : 1))
+}
+
+/**
+ * The call the tool is. Its arguments are the procedure's parameters, taken apart the way a
+ * request carries them, and what answers is the same `route` an ordinary request goes to.
+ *
+ * A name that is not a published tool is answered as no tool at all, whether or not a route
+ * would have taken it: what an application did not publish is not reachable here by guessing
+ * its name. What the caller may then do with one that is published is still `auth`'s to say.
+ */
+export async function call(scope: Scope, named: string, args: Params): Promise<Result> {
+  if (!published(scope.tree, named))
+    throw new http.NotFound(
+      response(
+        null,
+        failure(METHOD_NOT_FOUND, `'${named}' is not a tool this server publishes`)
+      )
+    )
+
+  const { path, verb, variables } = address(named, args)
+  const { query, input: body } = split(args, variables)
+  const clone = fork(scope.context, path, verb, query, body)
+
+  try {
+    const message = await scope.route(clone)
+
+    // what `io:output` restricts, over this call's reply rather than the envelope
+    await http.shape(clone, message)
+
+    return result(message.body)
+  } catch (exception) {
+    /*
+     * What the route made of this call is a value a model reads and may correct itself by:
+     * an operation that refused, an argument `io:input` would not take, a record that is
+     * not there, an identity `auth` would not let it act on. A credential is none of those
+     * — that is the client's to fix and not the model's, so it is answered as it is — and
+     * neither is a fault of this server, which is a protocol error and stays one.
+     */
+    if (
+      exception instanceof http.ClientError &&
+      !(exception instanceof http.Unauthorized)
+    )
+      return { content: [{ type: 'text', text: refusal(exception) }], isError: true }
+
+    throw exception
+  }
+}
+
+/** Everything a call needs that is not the call: the request it is of, and what answers it. */
+export interface Scope {
+  context: http.Context
+  route: http.Processor
+  tree: Tree
+}
+
+/**
+ * Whether the tree publishes this name as a tool. What `auth` makes of the caller is not
+ * asked here — the declaration is the route's and does not vary by who is calling, and the
+ * call that follows is authorized as any request to that route is.
+ */
+function published(tree: Tree, named: string): boolean {
+  for (const { segments, verb, method } of tree.walk())
+    if (name(segments, verb) === named)
+      return MCP.published(method.directives.declared<Declaration>(FAMILY))
+
+  return false
+}
+
+function result(body: unknown): Result {
+  if (body === undefined || body === null) return { content: [] }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(body) }],
+    structuredContent: body
+  }
+}

package/source/MCP/types.ts

@@ -0,0 +1,84 @@
+/** The revision this endpoint serves, where a request carries its own metadata. */
+export const MODERN = '2026-07-28'
+
+/** The newest revision reached by an `initialize` handshake, which is what clients still send. */
+export const LEGACY = '2025-11-25'
+
+export const VERSIONS = [MODERN, LEGACY]
+
+/** The version every JSON-RPC message states, which is not the protocol's. */
+export const JSONRPC = '2.0'
+
+/** The prefix the revision reserves for itself in `_meta`. */
+export const RESERVED = 'io.modelcontextprotocol/'
+
+export const PROTOCOL_VERSION = RESERVED + 'protocolVersion'
+export const CLIENT_CAPABILITIES = RESERVED + 'clientCapabilities'
+export const SERVER_INFO = RESERVED + 'serverInfo'
+
+export type Params = Record<string, unknown>
+
+export interface Message {
+  jsonrpc: string
+  method: string
+  params?: Params
+
+  /** Absent makes this a notification, which is answered by not answering. */
+  id?: string | number
+}
+
+export interface Failure {
+  code: number
+  message: string
+  data?: unknown
+}
+
+export interface Response {
+  jsonrpc: string
+  id: string | number | null
+  result?: unknown
+  error?: Failure
+}
+
+/**
+ * How long a complete result may be held, and by whom. `private` is a result that is the
+ * caller's alone — a list `auth` filtered for their identity is not another caller's list.
+ */
+export interface Cache {
+  ttlMs: number
+  cacheScope: 'public' | 'private'
+}
+
+/** What a tool answers with: what a model reads, and the reply itself. */
+export interface Result {
+  content: Content[]
+  structuredContent?: unknown
+
+  /** The operation refused, which is something a model can read and correct. */
+  isError?: boolean
+}
+
+export interface Content {
+  type: 'text'
+  text: string
+}
+
+export interface Tool {
+  name: string
+
+  /** what a person is shown where a client lists this tool; a name is an address */
+  title?: string
+
+  /** what the route states this method is */
+  description?: string
+  inputSchema: object
+  outputSchema?: object
+  annotations?: Annotations
+}
+
+/** What the verb says about the call, which the revision asks a client to treat as a hint. */
+export interface Annotations {
+  readOnlyHint?: boolean
+  destructiveHint?: boolean
+  idempotentHint?: boolean
+}

package/source/Mapping.ts

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

package/source/Query.test.ts

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