lakutata 3.0.0 → 3.1.0

package/doc/en/MCP.md

@@ -0,0 +1,293 @@
+# Lakutata MCP
+
+The Model Context Protocol (MCP) lets an AI assistant use an application: call its **tools**, read its **resources**
+and fill its **prompts**. The package `@lakutata/mcp` serves controller methods as these, over the standard input and
+output of a child process or over HTTP. It is not part of `lakutata`:
+
+```bash
+npm install lakutata @lakutata/mcp
+```
+
+| Declared with | What it is | Who uses it |
+|---|---|---|
+| `@MCPTool(name)` | An action the model calls with arguments | The model, when it decides to |
+| `@MCPResource(uri)` | Data read by its URI | The client, to give it to the model |
+| `@MCPPrompt(name)` | A message template filled with arguments | The user, by choosing it in the client |
+
+## 1. A server over stdio
+
+```typescript
+import {Application, DTO, Exception} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {Prefix} from 'lakutata/decorator/ctrl'
+import {Expect} from 'lakutata/decorator/dto'
+import {Logger} from 'lakutata/com/logger'
+import {MCPPrompt, MCPResource, MCPTool, stdioMCPEntrypoint} from '@lakutata/mcp'
+
+class DeviceSnDTO extends DTO {
+    @Expect(DTO.String().required().description('The serial number of the device'))
+    public sn: string
+}
+
+class StatusDTO extends DTO {
+    @Expect(DTO.String().required())
+    public sn: string
+
+    @Expect(DTO.Boolean().required())
+    public online: boolean
+}
+
+class OfflineException extends Exception {
+    public errno: string = 'E_OFFLINE'
+}
+
+@Prefix({mcp: 'device'})
+class DeviceController extends Controller {
+    //The tool device_status
+    @MCPTool('status', DeviceSnDTO, {description: 'The online status of a device', readOnly: true, output: StatusDTO})
+    public async status(input: DeviceSnDTO): Promise<StatusDTO> {
+        return {sn: input.sn, online: input.sn !== 'off'} as StatusDTO
+    }
+
+    @MCPTool('reboot', DeviceSnDTO, {description: 'Reboot a device', destructive: true})
+    public async reboot(input: DeviceSnDTO): Promise<string> {
+        if (input.sn === 'off') throw new OfflineException('The device {sn} is offline', {sn: input.sn})
+        return `Rebooting ${input.sn}`
+    }
+
+    //The resource of each device: device://A1/status
+    @MCPResource('device://{sn}/status', DeviceSnDTO, {mimeType: 'application/json', description: 'The status of a device'})
+    public async statusResource(input: DeviceSnDTO): Promise<StatusDTO> {
+        return {sn: input.sn, online: true} as StatusDTO
+    }
+
+    //The prompt device_diagnose
+    @MCPPrompt('diagnose', DeviceSnDTO, {description: 'Diagnose the failures of a device'})
+    public async diagnose(input: DeviceSnDTO): Promise<string> {
+        return `Diagnose the device ${input.sn} from its status and its logs.`
+    }
+}
+
+Application.run(() => ({
+    id: 'devices.app',
+    name: 'Devices',
+    components: {
+        //The standard output belongs to the protocol: the logs go to the standard error
+        log: {class: Logger, destinations: [process.stderr]},
+        entrypoint: buildEntrypoints({
+            controllers: [DeviceController],
+            mcp: stdioMCPEntrypoint({instructions: 'Check the status of a device before rebooting it.'})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+- The client runs the application as its child process, with a command such as `node build/App.js`, and speaks to it
+  on its standard input and output. The application exits once the client closes its input (`exitOnClose: false`
+  keeps it running).
+- The standard output carries the messages of the protocol: write the logs to the standard error, as above, and never
+  call `console.log()`.
+- The options of `stdioMCPEntrypoint()`: `serverName` (the name of the application by default), `serverVersion`
+  (`'1.0.0'`), `instructions` for the model, `stdin` and `stdout`, `exitOnClose`, `name` and `middlewares`.
+- Over stdio, the server speaks the revisions of 2025 of the protocol.
+
+## 2. Tools
+
+```text
+@MCPTool(name, DTO?, options?)
+```
+
+| Option | Meaning |
+|---|---|
+| `description` | What the tool does, for the model; without it, the model sees `ControllerClass:method` |
+| `title` | A name to display |
+| `readOnly`, `destructive`, `idempotent`, `openWorld` | Hints for the client: the tool changes nothing, makes changes that cannot be undone, gives the same result when called again, or reaches outside systems |
+| `output` | The DTO of the result: its JSON schema is sent, and the result is given as structured content too |
+| `acl`, `rule`, `middlewares`… | The options of every action (see [Controllers](Controllers.md), section 3) |
+
+- A name has 1 to 128 letters, digits, `_`, `-` or `.`. `@Prefix({mcp: 'device'})` prefixes the names of the tools and
+  of the prompts of a controller: `status` becomes `device_status`.
+- The arguments are described by the JSON schema of the DTO; `.description()` describes an argument to the model. The
+  DTO validates them, as for every action.
+- A tool declared by two controllers is served by the one registered last, as on the other transports.
+
+What a tool returns becomes its result:
+
+| Returned | Result |
+|---|---|
+| A string | One text |
+| An object | Its JSON as a text, and the object as structured content |
+| `undefined` | No content |
+| `Result.file(buffer, {contentType})` | An image or an audio for these types, otherwise an embedded resource |
+| `Result.status(status, data)` | Its data |
+
+- A class instance (a DTO) is given as structured content only when the tool declares `output`. A tool that declares
+  `output` and returns no object fails.
+- The server does not check the structured content against `output`; the client does, and refuses a result that does
+  not match.
+- An error thrown by the tool, its validation or its access control included, is given to the model as a result
+  marked as an error, whose text is `errno: message` (`E_OFFLINE: The device off is offline`). The model can then
+  correct its call.
+
+## 3. Resources
+
+```text
+@MCPResource(uri, DTO?, options?)
+```
+
+- A URI without variables (`device://catalog`) is a resource of its own; a URI with variables
+  (`device://{sn}/status`) is a template, which the client fills. The URIs are never prefixed.
+- The variables are the input of the action. They are strings: declare them as strings, or convert them with
+  `.strict(false)`, as the query of an HTTP request.
+- The options: `resourceName` (the name listed; the name of the action by default), `title`, `mimeType`, `audience`
+  (`['user']`, `['assistant']`), `priority` (from 0 to 1), and the options of every action.
+
+| Returned | Content |
+|---|---|
+| A string | A text, of the `mimeType` (`text/plain` by default) |
+| Another value | Its JSON, of the `mimeType` (`application/json` by default) |
+| A `Buffer`, `Result.file()` | A text or a binary, by its type |
+
+An error thrown when a resource is read is answered as an error of the protocol: invalid params (`-32602`) when its
+`statusCode` is a client error (400 to 499, an invalid input among them), internal error (`-32603`) otherwise. Its
+message is `errno: message`.
+
+## 4. Prompts
+
+```text
+@MCPPrompt(name, DTO?, options?)
+```
+
+- The properties of the DTO are the arguments of the prompt, listed to the client. They are strings: declare them as
+  strings, or convert them with `.strict(false)`.
+- A string becomes one message of the user; an array, one message per item (a string, or `{role, content}`); an object
+  `{messages}` is sent as it is.
+- The option `title`, and the options of every action. The errors are answered as for the resources.
+
+## 5. The context
+
+In an MCP action, `this.context` is an `MCPContext`:
+
+| Property | What it is |
+|---|---|
+| `kind` | `'tool'`, `'resource'` or `'prompt'` |
+| `name` | The name of the tool or of the prompt, prefix included; for a resource, its URI as declared |
+| `uri` | The URI read, for a resource |
+| `data` | The arguments, before the validation (empty for a resource, whose variables are its input) |
+| `authInfo` | What `authenticate` returned (section 6) |
+| `progress(progress, total?, message?)` | Reports the progress of a long call to the client |
+
+```typescript
+import {Controller} from 'lakutata/com/entrypoint'
+import {MCPTool, type MCPContext} from '@lakutata/mcp'
+
+class ImportController extends Controller {
+    @MCPTool('import', {description: 'Import the devices'})
+    public async import(): Promise<string> {
+        const context: MCPContext = this.context as MCPContext
+        for (let step: number = 1; step <= 3; step++) {
+            //The client cancelled the call
+            if (this.signal?.aborted) return 'cancelled'
+            await context.progress(step, 3, `step ${step}`)
+        }
+        return 'imported'
+    }
+}
+```
+
+- When the client cancels a call, `this.signal` is aborted.
+- A method may serve several transports at once (`@GET` and `@MCPTool`): `this.context.type` is then `'MCP'`
+  (`MCP_CONTEXT_TYPE`) for the MCP requests.
+- The access rules of the entrypoint apply to the MCP actions declared with `acl: true` when their
+  `supportContextTypes()` include `MCP_CONTEXT_TYPE` (see [Middlewares](Middlewares.md)).
+- The server does not ask the client for anything: there is no sampling, elicitation or logging to the client.
+
+**Notifications.** `MCPNotifier`, a component to inject (`@Inject(MCPNotifier)`), tells the clients that something
+changed: `resourceUpdated(uri)`, `resourcesChanged()`, `toolsChanged()`, `promptsChanged()`. Over stdio, a resource
+update reaches the client only if it subscribed to that URI. Over HTTP, only the clients of the revision 2026-07-28
+that listen to the changes are notified.
+
+## 6. Over HTTP
+
+```typescript
+import type {IncomingMessage} from 'node:http'
+import {Application} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {httpMCPEntrypoint, MCPTool, type MCPAuthInfo} from '@lakutata/mcp'
+
+class ClockController extends Controller {
+    @MCPTool('now', {description: 'The current time of the server', readOnly: true})
+    public async now(): Promise<string> {
+        return new Date().toISOString()
+    }
+}
+
+//Throwing answers 401
+function verifyToken(request: IncomingMessage): MCPAuthInfo {
+    const token: string = request.headers.authorization?.replace(/^Bearer /, '') ?? ''
+    if (token !== process.env.MCP_TOKEN) throw new Error('Invalid token')
+    return {token: token, clientId: 'assistant', scopes: []}
+}
+
+//The clients connect to http://127.0.0.1:3000/mcp
+Application.run(() => ({
+    id: 'clock.app',
+    name: 'Clock',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [ClockController],
+            mcp: httpMCPEntrypoint({port: 3000, authenticate: verifyToken})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+| Option | Default | Meaning |
+|---|---|---|
+| `port`, `host`, `path` | `3000`, `'127.0.0.1'`, `'/mcp'` | Where it listens |
+| `authenticate` | | `(request) => MCPAuthInfo \| undefined`: the authentication of the client; throwing answers 401, returning `undefined` serves the request without one |
+| `allowedHosts`, `allowedOrigins` | the local names, on a local address | The `Host` and `Origin` headers accepted (403 otherwise); `false` checks none |
+| `legacy` | `'stateless'` | The clients of the revisions of 2025: served without sessions, or refused with `'reject'` |
+| `maxRequestBodySize` | 4 MiB | A larger body is answered with 413 |
+| `bus` | in memory | Where the notifications go, to share them between the instances of the application |
+| `listen` | `true` | `false` opens no port: the `handler` is mounted on another server |
+| `serverName`, `serverVersion`, `instructions`, `server`, `listening`, `name`, `middlewares` | | As for stdio; `server` holds the options of the `node:http` server |
+
+- It serves the protocol over Streamable HTTP: the revision 2026-07-28, and the revisions of 2025 without sessions.
+- On a local address, the `Host` and `Origin` headers are checked against the local names, which protects the server
+  from DNS rebinding: behind a proxy, list the names the clients use. On another address, nothing is checked unless you
+  list names.
+- When the application stops, the calls in progress are answered, then the port closes.
+
+**Sharing the port of the HTTP adapter.** With `listen: false`, mount the `handler` of the adapter on the Express
+application, in its `before` hook:
+
+```typescript
+import {buildEntrypoints} from 'lakutata/com/entrypoint'
+import {expressHTTPEntrypoint} from 'lakutata/adapter/express'
+import {httpMCPEntrypoint} from '@lakutata/mcp'
+
+//The names the clients connect with (http://localhost:8080/mcp)
+const mcp = httpMCPEntrypoint({listen: false, allowedHosts: ['localhost', '127.0.0.1', 'mcp.example.com']})
+
+export const entrypoint = buildEntrypoints({
+    controllers: [],
+    http: expressHTTPEntrypoint({port: 8080, before: (app): void => void app.all('/mcp', mcp.handler)}),
+    mcp: mcp
+})
+```
+
+A mounted handler checks the `Host` and `Origin` headers only against the names given, and answers 503 before the
+adapter starts and once it stops.
+
+## 7. Errors
+
+| Situation | The client receives |
+|---|---|
+| A tool fails: an exception, an invalid argument, a refused access | A result marked as an error: `errno: message` |
+| A resource or a prompt fails with a client error (400 to 499) | The protocol error `-32602`, its message `errno: message`, its data `{errno}` |
+| A resource or a prompt fails otherwise | The protocol error `-32603` |
+| An unknown tool, prompt or resource | The protocol error `-32602` (`Tool nope not found`) |
+| An invalid name of a tool or a prompt, a resource URI without scheme | A `TypeError` when the class is declared |

package/doc/en/Middlewares.md

@@ -0,0 +1,213 @@
+# Lakutata Middlewares and Access Control
+
+A middleware runs around the actions: it sees each request before the action, and its result after. The access control
+decides whether a request may reach its action. Both work the same way for every transport.
+
+## 1. Middlewares
+
+A middleware is a function `(invocation, next) => Promise<unknown>`. It calls `next()` to go on with the request, and
+returns what the request returns:
+
+```typescript
+import {type ActionInvocation, Controller, type Next} from 'lakutata/com/entrypoint'
+import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
+
+async function timing(invocation: ActionInvocation, next: Next): Promise<unknown> {
+    const started: number = Date.now()
+    try {
+        return await next()
+    } finally {
+        console.log(`${invocation.action.name} took ${Date.now() - started} ms`)
+    }
+}
+
+@UseMiddlewares(timing)
+class HealthController extends Controller {
+    @GET('/health')
+    public async health(): Promise<string> {
+        return 'ok'
+    }
+}
+```
+
+A middleware can also be a class that extends `Middleware` and implements `handle(invocation, next)`. The class is
+created for each request, in the scope of the request, so it can inject other objects:
+
+```typescript
+import {Component} from 'lakutata'
+import {type ActionInvocation, Middleware, type Next} from 'lakutata/com/entrypoint'
+import {Inject} from 'lakutata/decorator/di'
+
+class Metrics extends Component {
+    public record(name: string, milliseconds: number): void {
+        console.log(name, milliseconds)
+    }
+}
+
+export class Timing extends Middleware {
+    //The component declared as metrics in the components of the application
+    @Inject('metrics')
+    protected readonly metrics: Metrics
+
+    public async handle(invocation: ActionInvocation, next: Next): Promise<unknown> {
+        const started: number = Date.now()
+        try {
+            return await next()
+        } finally {
+            this.metrics.record(invocation.action.name, Date.now() - started)
+        }
+    }
+}
+```
+
+`invocation` describes the request:
+
+| Property | Meaning |
+|---|---|
+| `context` | The context of the request (`this.context` in the action). Its `data`, the input before validation, can be changed |
+| `action` | The action: its `name`, `description`, `groups`, its address (`route`, `command`, `pattern`) |
+| `container` | The container of the request's scope, to get the objects of the request |
+| `signal` | The `AbortSignal` of the request |
+
+- A middleware that returns without calling `next()` answers the request itself: the action does not run. A cache
+  can work this way.
+- A middleware that throws fails the request with its error, as an action that throws.
+- `next()` can be called only once: a second call throws a `MiddlewareNextCalledException`.
+- The middlewares run for every transport, the scheduled jobs included. `invocation.context.type` tells them apart.
+
+## 2. Where to declare them
+
+| Where | Applies to |
+|---|---|
+| `buildEntrypoints({middlewares})` | Every action |
+| The `middlewares` option of an adapter | The actions reached through that adapter |
+| `@UseMiddlewares(...)` on a controller class | The actions of the class and of its subclasses |
+| The `middlewares` action option | That action |
+| `@UseMiddlewares(...)` on a method | That method |
+
+They run in the order of this table, from the first row (the outermost) to the last: entrypoint, adapter, controller
+class, action option, method. On a controller, the middlewares of the parent classes run before the ones of the
+subclass. After the last middleware come the validation of the input, the access control, then the action.
+
+## 3. Passing data to the action
+
+A middleware often finds something the action needs, such as the user who sent the request. The input is the wrong
+place for it: the DTO validates the input after the middlewares, and removes the keys it does not declare. Use a
+provider of the request instead. A `@Scoped` provider has one instance per request: the middleware fills it, and the
+action injects the same instance.
+
+```typescript
+import {Exception, Provider} from 'lakutata'
+import {type ActionInvocation, Controller, type HTTPContext, Middleware, type Next} from 'lakutata/com/entrypoint'
+import {GET, UseMiddlewares} from 'lakutata/decorator/ctrl'
+import {Autoload, Inject, Scoped} from 'lakutata/decorator/di'
+
+class UnauthorizedException extends Exception {
+    public errno: string = 'E_UNAUTHORIZED'
+
+    public statusCode: number = 401
+}
+
+//One instance per request, registered the first time it is used
+@Autoload()
+@Scoped()
+export class CurrentUser extends Provider {
+    public name: string
+
+    public role: string
+}
+
+class Authenticate extends Middleware {
+    public async handle(invocation: ActionInvocation, next: Next): Promise<unknown> {
+        const token: string | undefined = (invocation.context as HTTPContext).request.headers.authorization
+        if (!token) throw new UnauthorizedException('Not logged in')
+        const user: CurrentUser = await invocation.container.get(CurrentUser)
+        //Look the token up in a real application
+        user.name = token
+        user.role = token === 'ada' ? 'admin' : 'user'
+        return await next()
+    }
+}
+
+@UseMiddlewares(Authenticate)
+class ProfileController extends Controller {
+    @Inject(CurrentUser)
+    protected readonly user: CurrentUser
+
+    @GET('/me')
+    public async me(): Promise<{ name: string, role: string }> {
+        return {name: this.user.name, role: this.user.role}
+    }
+}
+```
+
+```text
+$ curl localhost:8080/me -H 'Authorization: ada'
+{"name":"ada","role":"admin"}
+$ curl localhost:8080/me
+{"errno":"E_UNAUTHORIZED","errMsg":"Not logged in"}
+```
+
+## 4. Access control
+
+An action declared with `acl: true` is checked by the access rules of the entrypoint. A rule is a class that extends
+`AccessControlRule` and is listed in `buildEntrypoints({rules})`:
+
+```typescript
+import {Provider} from 'lakutata'
+import {AccessControlRule, ContextType, Controller, type HTTPContext} from 'lakutata/com/entrypoint'
+import {DELETE, GET} from 'lakutata/decorator/ctrl'
+import {Autoload, Inject, Scoped} from 'lakutata/decorator/di'
+
+//The provider of section 3, filled by the middleware Authenticate
+@Autoload()
+@Scoped()
+class CurrentUser extends Provider {
+    public name: string
+
+    public role: string
+}
+
+//The actions of the "admin" group are for the administrators
+export class AdminRule extends AccessControlRule<HTTPContext> {
+    @Inject(CurrentUser)
+    protected readonly user: CurrentUser
+
+    public get supportContextTypes(): ContextType[] {
+        return [ContextType.HTTP]
+    }
+
+    public async rule(): Promise<boolean> {
+        if (!this.targetAction.groups.includes('admin')) return true
+        return this.user.role === 'admin'
+    }
+}
+
+export class StatsController extends Controller {
+    @GET('/admin/stats', {acl: true, groups: ['admin']})
+    public async stats(): Promise<string> {
+        return 'stats'
+    }
+
+    //A rule of this action only; no acl needed
+    @DELETE('/drafts/:id', {rule: async (context): Promise<boolean> => (context as HTTPContext).request.headers['x-owner'] === 'yes'})
+    public async removeDraft(): Promise<void> {
+    }
+}
+
+//buildEntrypoints({controllers: [StatsController], rules: [AdminRule], httpActionGroups: {admin: 'Administration'}})
+```
+
+- A rule is created for each request, in the scope of the request: it can inject the objects of the request, such as
+  the `CurrentUser` filled by a middleware.
+- In a rule, `this.context` is the context of the request, `this.input` the validated input, `this.targetAction` the
+  action (its `name`, its `groups`), and `this.actions` all the actions of the transport.
+- `supportContextTypes` lists the transports the rule checks; it is skipped for the others.
+- The rules run in the order of the `rules` option, then the `rule` option of the action. The first one that resolves
+  `false` denies the request with an `AccessDeniedException` (errno `E_ACCESS_DENY`, status 403 over HTTP); one that
+  throws denies it with its own error (such as a 401).
+- The `rule` option of an action works on its own: without `acl`, only that rule is checked.
+- An action with neither `acl` nor `rule` is not checked. An `acl: true` action is allowed when no rule denies it.
+
+The access control runs after the middlewares and the validation of the input, just before the action. To change how
+it decides for the whole application, see [Entrypoint](Entrypoint.md), section 7.