akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/server/mcp/McpDispatcher.ts

@@ -0,0 +1,245 @@
+import { type BaseEnv, ENDPOINT_META } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import { DictionaryLookup } from "akanjs/dictionary";
+import { NoDocumentError } from "akanjs/document";
+import type { InjectRegistry, LiveRegistry } from "akanjs/service";
+import type { Endpoint, EndpointCls } from "../../signal/endpoint";
+import type { EndpointInfo } from "../../signal/endpointInfo";
+import type { GuardCls } from "../../signal/guard";
+import {
+  McpDocument,
+  McpErrorCode,
+  type McpExposedEndpoint,
+  type McpToolResult,
+  type PromptMessage,
+} from "../../signal/mcp";
+import type { MiddlewareCls } from "../../signal/middleware";
+import { SignalContext } from "../../signal/signalContext";
+import { McpExecutionContext } from "./McpExecutionContext";
+
+/** Raised when the caller presented no credential at all, so the client should be told to authenticate. */
+export class McpAuthRequiredError extends Error {}
+
+/**
+ * A prompt failure whose message has already been through `#message` and is safe to put on the wire.
+ *
+ * It carries its JSON-RPC code because a prompt has no `isError` result to put a refusal in, so the code is the
+ * only place left to say whose fault it was. Without it a mistyped argument reads as `-32603 internal error`,
+ * while the *missing*-argument check `prompts/get` does itself answers `-32602` — the same mistake, two codes.
+ */
+export class McpPromptError extends Error {
+  readonly code: number;
+  constructor(message: string, code: number) {
+    super(message);
+    this.code = code;
+  }
+}
+
+interface McpDispatcherProps {
+  registry: InjectRegistry;
+  env: BaseEnv;
+  live: LiveRegistry;
+  middleware: Map<string, MiddlewareCls>;
+  /** The one language error text is resolved in, matching the catalogue the client was handed. */
+  language?: string;
+}
+
+/** Executes one MCP tool call or resource read through the ordinary signal pipeline. */
+export class McpDispatcher {
+  static readonly logger = new Logger("McpDispatcher");
+
+  readonly #props: McpDispatcherProps;
+  #endpoints: Map<string, { endpointInfo: EndpointInfo; endpoint: Endpoint }> | null = null;
+  /**
+   * Built on first use and then held: the merge behind it is not free, a server whose calls all succeed never
+   * needs it, and a caller that types an argument wrong drives that path as often as it likes.
+   *
+   * Not deferred for the reason the endpoint index below is. Dictionaries register at module evaluation, before
+   * any route exists — `McpRouter` builds one at boot to resolve the catalogue's own text — so a lookup made in
+   * the constructor would be correct, just paid for by every process whether or not a call ever fails.
+   */
+  #lookup: DictionaryLookup | null = null;
+
+  constructor(props: McpDispatcherProps) {
+    this.#props = props;
+  }
+
+  async call(exposed: McpExposedEndpoint, args: Record<string, unknown>, req: Request): Promise<McpToolResult> {
+    const found = this.#index().get(exposed.key);
+    if (!found) return McpDispatcher.#failure(`Tool "${exposed.key}" is declared but not mounted on this server.`);
+    try {
+      const value = await this.#exec(exposed.key, found, args, req);
+      const structuredContent = McpDocument.structuredContent(exposed.endpoint, value);
+      return {
+        content: [{ type: "text", text: McpDispatcher.#text(structuredContent, value) }],
+        ...(structuredContent === undefined ? {} : { structuredContent }),
+        isError: false,
+      };
+    } catch (error) {
+      const status = McpDispatcher.#statusOf(error);
+
+      if ((status === 401 || status === 403) && !req.headers.get("authorization")) throw new McpAuthRequiredError();
+      return McpDispatcher.#failure(this.#message(error, status, exposed.refName));
+    }
+  }
+
+  /**
+   * A prompt is user-chosen, not model-chosen, so a failure has nowhere to go but the JSON-RPC error — there is
+   * no `isError` result the model could read and recover from. Errors propagate to the router unchanged.
+   *
+   * The messages arrive already normalized: `SignalContext` does that for every `prompt`, so this route and the
+   * plain HTTP one return the same shape.
+   */
+  async prompt(exposed: McpExposedEndpoint, args: Record<string, unknown>, req: Request): Promise<PromptMessage[]> {
+    const found = this.#index().get(exposed.key);
+    if (!found)
+      throw new McpPromptError(
+        `Prompt "${exposed.key}" is declared but not mounted on this server.`,
+        McpErrorCode.internal,
+      );
+    try {
+      return (await this.#exec(exposed.key, found, args, req)) as PromptMessage[];
+    } catch (error) {
+      const status = McpDispatcher.#statusOf(error);
+      if ((status === 401 || status === 403) && !req.headers.get("authorization")) throw new McpAuthRequiredError();
+      throw new McpPromptError(this.#message(error, status, exposed.refName), McpDispatcher.#codeOf(status));
+    }
+  }
+
+  /**
+   * Drops catalogue entries whose account-scoped guards refuse this caller — an anonymous agent should not be
+   * offered a shelf of admin tools it can only fail at. Entries with no such guard are kept and stopped at call
+   * time instead, so the listing is a UX filter and never the access decision.
+   *
+   * The context is deliberately not `init()`-ed: parsing arguments that a listing does not have would throw,
+   * and a resource guard reached here reads `undefined` and fails closed, which is the behaviour we want.
+   */
+  async filterForAccount<T extends { name: string }>(items: T[], req: Request): Promise<T[]> {
+    const index = this.#index();
+
+    const ids = new Map<GuardCls, number>();
+    const idOf = (GuardCls: GuardCls) => {
+      const id = ids.get(GuardCls);
+      if (id !== undefined) return id;
+      ids.set(GuardCls, ids.size);
+      return ids.size - 1;
+    };
+    const cached = new Map<string, Promise<boolean>>();
+    const verdicts = await Promise.all(
+      items.map(async (item) => {
+        const found = index.get(item.name);
+        if (!found) return true;
+        const guards = (found.endpointInfo.signalOption.guards ?? []).filter(
+          (GuardCls) => GuardCls.scope === "account",
+        );
+        if (!guards.length) return true;
+        const key = guards
+          .map(idOf)
+          .sort((a, b) => a - b)
+          .join(",");
+        const verdict =
+          cached.get(key) ??
+          new SignalContext(item.name, req as Bun.BunRequest, {
+            ...this.#props,
+            endpointInfo: found.endpointInfo,
+            adaptor: found.endpoint,
+            ctx: new McpExecutionContext(req, {}),
+          }).canListForAccount();
+        cached.set(key, verdict);
+        return await verdict;
+      }),
+    );
+    return items.filter((_item, idx) => verdicts[idx]);
+  }
+
+  async #exec(
+    key: string,
+    { endpointInfo, endpoint }: { endpointInfo: EndpointInfo; endpoint: Endpoint },
+    args: Record<string, unknown>,
+    req: Request,
+  ) {
+
+    const context = await new SignalContext(key, req as Bun.BunRequest, {
+      ...this.#props,
+      endpointInfo,
+      adaptor: endpoint,
+      ctx: new McpExecutionContext(req, args),
+    }).init();
+    return (await context.exec()) as unknown;
+  }
+
+  /**
+   * Built on first use and kept: nothing before a `tools/call` needs it, and a router constructed to answer one
+   * request — which tests and tooling do — should not walk the whole registry to do it. Not an ordering
+   * workaround; DI has finished filling the registry long before any route is created.
+   *
+   * Keyed by endpoint key, which is globally unique and is what MCP names a tool by.
+   */
+  #index() {
+    if (this.#endpoints) return this.#endpoints;
+    const endpoints = new Map<string, { endpointInfo: EndpointInfo; endpoint: Endpoint }>();
+    for (const [endpointCls, endpoint] of this.#props.registry.endpoint.entries()) {
+      const meta = (endpointCls as EndpointCls)[ENDPOINT_META] as { [key: string]: EndpointInfo };
+      for (const [key, endpointInfo] of Object.entries(meta)) endpoints.set(key, { endpointInfo, endpoint });
+    }
+    this.#endpoints = endpoints;
+    return endpoints;
+  }
+
+  #message(error: unknown, status: number | undefined, refName: string): string {
+
+    if (error instanceof NoDocumentError) return `No ${refName} found for the arguments given.`;
+    if (status && status < 500) {
+      const raw = error instanceof Error ? error.message : String(error);
+      
+      this.#lookup ??= new DictionaryLookup(this.#props.language);
+      const text = this.#lookup.text(raw);
+      if (text) return text;
+
+      if (status === 401 || status === 403) return "You are not permitted to perform this action.";
+      return raw;
+    }
+
+    McpDispatcher.logger.error(`MCP call failed: ${error instanceof Error ? (error.stack ?? error.message) : error}`);
+    return "The server failed to complete this request.";
+  }
+
+  /**
+   * Anything without a status is treated as a crash, so the two failures an agent can trigger at will carry one:
+   * `McpArgumentError` (400) and `NoDocumentError` (404). Without them a mistyped id logged a stack and answered
+   * "the server failed", which is both a lie and a log-spam path any caller could drive.
+   */
+  static #statusOf(error: unknown): number | undefined {
+    const status = (error as { statusCode?: unknown } | null)?.statusCode;
+    return typeof status === "number" ? status : undefined;
+  }
+
+  /**
+   * The same split `#message` makes, in the currency a prompt reports failures in. `-32602` covers a not-found
+   * as well as a bad argument: this revision retired `-32002` and points resource-does-not-exist at invalid
+   * params, so the two caller mistakes share one code by the spec's own choice rather than for want of another.
+   */
+  static #codeOf(status: number | undefined) {
+    return status && status < 500 ? McpErrorCode.invalidParams : McpErrorCode.internal;
+  }
+
+  /**
+   * The text block every result carries, whether or not a structured one goes with it.
+   *
+   * A structured result is mirrored as its JSON, which is what the spec asks for so a client with no structured
+   * support still reads the payload. A scalar return has no structured half to mirror, and encoding one as JSON
+   * spent the block on syntax: a tool returning an id answered `"507f…"`, quotes included, which a model then has
+   * to know to strip. Numbers and booleans read the same either way; only a string differs.
+   *
+   * `JSON.stringify(undefined)` is `undefined` rather than a string, so a void return would otherwise ship a
+   * content block with no `text` at all.
+   */
+  static #text(structuredContent: unknown, value: unknown) {
+    if (structuredContent === undefined && typeof value === "string") return value;
+    return JSON.stringify(structuredContent ?? value) ?? "null";
+  }
+
+  static #failure(message: string): McpToolResult {
+    return { content: [{ type: "text", text: message }], isError: true };
+  }
+}

package/server/mcp/McpEventStream.ts

@@ -0,0 +1,76 @@
+/**
+ * One `text/event-stream` response carrying the notifications a single request produced, ending with that
+ * request's own result.
+ *
+ * This is the only channel a server has for pushing anything: `2026-07-28` removed the GET stream, session
+ * resumption and server-initiated requests, so nothing may be sent that is not related to a request in flight.
+ * Closing the stream is also how the client cancels — `notifications/cancelled` is stdio-only — which is why
+ * `cancel` is a constructor argument rather than something a caller could forget to wire.
+ */
+export class McpEventStream {
+  /** Below any common proxy idle timeout, so a slow tool does not have its connection reaped mid-work. */
+  static readonly keepAliveMs = 15_000;
+
+  readonly #encoder = new TextEncoder();
+  readonly #stream: ReadableStream<Uint8Array>;
+  #controller: ReadableStreamDefaultController<Uint8Array> | null = null;
+  #keepAlive: ReturnType<typeof setInterval> | null = null;
+
+  constructor(onCancel: () => void) {
+    this.#stream = new ReadableStream<Uint8Array>({
+      start: (controller) => {
+        this.#controller = controller;
+        this.#keepAlive = setInterval(() => this.#enqueue(":\r\n"), McpEventStream.keepAliveMs);
+        
+        this.#keepAlive.unref?.();
+      },
+      cancel: () => {
+        this.#stopKeepAlive();
+        this.#controller = null;
+        onCancel();
+      },
+    });
+  }
+
+  response() {
+    return new Response(this.#stream, {
+      headers: {
+        "content-type": "text/event-stream",
+
+        "cache-control": "no-cache, no-transform",
+        connection: "keep-alive",
+        "x-accel-buffering": "no",
+      },
+    });
+  }
+
+  write(message: object) {
+    this.#enqueue(`data: ${JSON.stringify(message)}\n\n`);
+  }
+
+  close() {
+    this.#stopKeepAlive();
+    const controller = this.#controller;
+    this.#controller = null;
+    try {
+      controller?.close();
+    } catch {
+    }
+  }
+
+  #enqueue(chunk: string) {
+    if (!this.#controller) return;
+    try {
+      this.#controller.enqueue(this.#encoder.encode(chunk));
+    } catch {
+      
+      this.#stopKeepAlive();
+      this.#controller = null;
+    }
+  }
+
+  #stopKeepAlive() {
+    if (this.#keepAlive) clearInterval(this.#keepAlive);
+    this.#keepAlive = null;
+  }
+}

package/server/mcp/McpExecutionContext.ts

@@ -0,0 +1,105 @@
+import { type Cls, PrimitiveRegistry, type PrimitiveScalar } from "akanjs/base";
+import { isMcpDescribableArg } from "akanjs/common";
+import { deserialize, serialize } from "akanjs/constant";
+import type { EndpointInfo } from "../../signal/endpointInfo";
+import { HttpExecutionContext } from "../../signal/signalContext";
+
+type McpArg = EndpointInfo["args"][number];
+
+/**
+ * An argument the caller can fix, carrying a 400 so the dispatcher reports it as a tool error rather than as a
+ * server failure. Everything that rejects an argument — the nullable check, `ID._parse`, a scalar's own
+ * validator — throws a bare `Error`, and a bare `Error` is indistinguishable from a crash.
+ */
+export class McpArgumentError extends Error {
+  readonly statusCode = 400;
+}
+
+/**
+ * Runs an endpoint for an MCP call while staying an HTTP context.
+ *
+ * MCP arrives over HTTP and the whole authorization stack reads the request through this context —
+ * `AccountMiddleware` resolves the bearer token off `getHttpContext().req`, and `Self`/`Me` and every guard read
+ * what it left there. A transport of its own would not adapt that stack, it would bypass it.
+ */
+export class McpExecutionContext extends HttpExecutionContext {
+  readonly #arguments: Record<string, unknown>;
+
+  constructor(req: Request, args: Record<string, unknown>) {
+    
+    super(req as Bun.BunRequest);
+    this.#arguments = args;
+  }
+
+  /**
+   * MCP passes one flat named object, so `param`/`search`/`body` all resolve by name from the same place. An
+   * absent value becomes `null` to match what a missing query string yields, letting `deserialize` apply the
+   * same nullability rules an HTTP call gets.
+   *
+   * A name nobody declared is the caller's mistake and is reported as one. `additionalProperties: false` travels
+   * in the published schema, but this server does not validate against it and plenty of clients do not either —
+   * so reading only the declared names dropped the rest in silence: `{ category, status }` on a slice that takes
+   * only `category` came back as a successful, unfiltered list, which a model reads as the filter having applied.
+   *
+   * "Declared" means what the *published schema* declares, which is why an `Any` argument counts as absent here.
+   * It is deliberately left out of that schema — the empty schema tells a model nothing — and the root list's raw
+   * `query` descriptor is the one that matters: read as sent, an agent could hand any model exposed through
+   * `mcp: { list: true }` an arbitrary query, which is precisely the narrowing a named filter slice exists to make
+   * deliberate. `additionalProperties: false` was never going to stop that on its own.
+   */
+  override async getArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
+    const declared = new Set(endpointInfo.args.filter(McpExecutionContext.#describable).map((arg) => arg.name));
+    const undeclared = Object.keys(this.#arguments).find((name) => !declared.has(name));
+    if (undeclared) throw new McpArgumentError(`Unknown argument "${undeclared}".`);
+    return endpointInfo.args.map((arg) => {
+      const value = McpExecutionContext.#lift(arg, this.#arguments[arg.name] ?? null);
+      try {
+        return deserialize(arg.argRef, arg.arrDepth, value, { key: arg.name, nullable: arg.option?.nullable });
+      } catch {
+
+        throw new McpArgumentError(McpExecutionContext.#argumentMessage(arg, value));
+      }
+    });
+  }
+
+  /**
+   * Returns the serialized value rather than a `Response`, so the router can put it straight into a JSON-RPC
+   * result. The `Response` in the signature is the base class's; `WebSocketExecutionContext` widens it the same
+   * way, and `SignalContext` only ever hands this value back to its caller.
+   */
+  override makeResponse(result: unknown, endpointInfo: EndpointInfo) {
+    if (endpointInfo.returns.arrDepth === 0 && PrimitiveRegistry.has(endpointInfo.returns.returnRef as Cls))
+      return result as unknown as Response;
+    return serialize(endpointInfo.returns.returnRef, endpointInfo.returns.arrDepth, result, "object", {
+      nullable: endpointInfo.returns.nullable,
+    }) as unknown as Response;
+  }
+
+  /**
+   * One value where a list was declared becomes a one-element list. Both callers produce it: form-style uri
+   * expansion writes `?tags=a` for a single tag, and a model routinely types a bare string for an array field.
+   * The http context never meets this because `searchParams.getAll` always returns an array, and `deserialize`
+   * hands a lone scalar straight back instead of lifting it — so the endpoint would receive a string where it
+   * iterates a list.
+   */
+  static #lift(arg: McpArg, value: unknown) {
+    return arg.arrDepth && value !== null && !Array.isArray(value) ? [value] : value;
+  }
+
+  /** The same rule `McpDocument` builds `properties` from, so what is refused is exactly what was not published. */
+  static #describable(arg: McpArg) {
+    const refName = PrimitiveRegistry.has(arg.argRef as Cls)
+      ? PrimitiveRegistry.getName(arg.argRef as typeof PrimitiveScalar)
+      : "";
+    return isMcpDescribableArg({ refName });
+  }
+
+  static #argumentMessage(arg: McpArg, value: unknown) {
+    if (value === null) return `Missing required argument "${arg.name}".`;
+    const primitive = PrimitiveRegistry.has(arg.argRef as Cls)
+      ? PrimitiveRegistry.getName(arg.argRef as typeof PrimitiveScalar)
+      : undefined;
+    const expected = primitive ? `${primitive}${"[]".repeat(arg.arrDepth)}` : undefined;
+    return `Invalid argument "${arg.name}"${expected ? `: expected ${expected}` : ""}.`;
+  }
+}