@softure-ai/mcp-access 0.1.12 → 0.1.14

package/src/next/issue-token.ts

@@ -0,0 +1,113 @@
+// Issuing a token from the token page's form, with an optional gate the app puts in front of it (a
+// billing write gate). Not a server action itself: the app calls it from its own `"use server"` file,
+// so the gate stays in the app's code and out of softure.config.ts:
+//
+//   "use server";
+//   export async function issueGatedToken(previous: IssueTokenFormState, form: FormData) {
+//     return issueToken(previous, form, { beforeIssue: checkPlan });
+//   }
+//
+// The owner comes from the session (never from a bound argument, which the client controls, docs/02 §8)
+// before the form is read. The gate refuses with a code, a code and its own text, or a thrown
+// `PublicError`; any other failure, the gate's included, becomes a `safeError` code.
+import { getCurrentUser } from "@softure-ai/auth/next";
+import { errorLogLabel, formatMessage, getPublicMessage, safeError, type Err, type Ok } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { revalidatePath } from "next/cache";
+import { z } from "zod";
+import { getMcpClientSetup } from "../client-setup.js";
+import type { IssueTokenFormState, McpIssueRefusal, McpIssueRefusalCode } from "../contract.js";
+import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
+import { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl } from "../server/options.js";
+import { issueAccessToken } from "../server/tokens.js";
+import { getMcpAccessContext, getRequestOrigins } from "./context.js";
+import { formatDate } from "./format.js";
+
+/** Longer values are cut: the server functions refuse them anyway, and nothing huge is echoed back. */
+const MAX_FIELD_LENGTH = MAX_TOKEN_NAME_LENGTH * 4;
+
+const issueInput = z.object({
+  name: z
+    .string()
+    .catch("")
+    .transform((value) => value.slice(0, MAX_FIELD_LENGTH)),
+  // A checked HTML checkbox sends "on"; an unchecked one sends nothing, which means read only.
+  canWrite: z.string().nullable().catch(null),
+});
+
+/** What the gate learns about the token about to be issued. */
+export interface IssueGateInput {
+  readonly userId: string;
+  readonly canWrite: boolean;
+}
+
+/**
+ * How the gate answers: `ok()` lets the token through, `err(code)` refuses with the code's copy,
+ * `refuseIssue(code, message)` with the app's own text.
+ */
+export type IssueGateResult = Ok<unknown> | Err<McpIssueRefusalCode> | McpIssueRefusal;
+
+/** The app's check before a token is issued. Throwing a `PublicError` refuses too, with its message. */
+export type BeforeIssueGate = (input: IssueGateInput) => IssueGateResult | Promise<IssueGateResult>;
+
+export interface IssueTokenOptions {
+  readonly beforeIssue?: BeforeIssueGate;
+}
+
+/** Issues a token for the signed-in user, after the gate, and returns its plaintext with the setup snippets, once. */
+export async function issueToken(_previous: IssueTokenFormState, formData: FormData, options: IssueTokenOptions = {}): Promise<IssueTokenFormState> {
+  const config = getSoftureConfig();
+  const user = await getCurrentUser();
+  if (user === null) return { status: "error", error: "auth.unauthenticated" };
+
+  // Every field has a `catch`, so parsing cannot fail.
+  const input = issueInput.parse({ name: formData.get("name"), canWrite: formData.get("canWrite") });
+  const canWrite = input.canWrite !== null;
+  try {
+    if (options.beforeIssue !== undefined) {
+      const gate = await options.beforeIssue({ userId: user.id, canWrite });
+      if (!gate.ok) return getRefusalState(gate.error, "message" in gate ? gate.message : undefined);
+    }
+    // Resolved before issuing: a failure afterwards would leave a token nobody received.
+    const endpointUrl = getMcpEndpointUrl(config, await getRequestOrigins(config, getMcpAccessRoutes(config).page));
+    const result = await issueAccessToken(await getMcpAccessContext(config), { userId: user.id, name: input.name, canWrite });
+    if (!result.ok) return { status: "error", error: result.error };
+    revalidatePath(getMcpAccessRoutes(config).page);
+    const issued = result.value;
+    const messages = getMcpAccessMessages(config);
+    const accessOptions = getMcpAccessOptions(config);
+    return {
+      status: "ok",
+      issued: {
+        id: issued.id,
+        name: issued.name,
+        canWrite: issued.canWrite,
+        expiresText: formatMessage(messages.issued.expires, { date: formatDate(config, issued.expiresAt) }),
+        expiresAt: issued.expiresAt.toISOString(),
+        setup: getMcpClientSetup({
+          serverName: accessOptions.clientServerName ?? accessOptions.serverName,
+          endpointUrl,
+          token: issued.token,
+          promptTemplate: messages.setup.assistantPrompt,
+        }),
+      },
+    };
+  } catch (error) {
+    // A deliberate refusal written for the user, not a failure: shown, not logged.
+    const publicMessage = getPublicMessage(error);
+    if (publicMessage !== null) return getRefusalState("mcp-access.issue_refused", publicMessage);
+    console.error(`@softure-ai/mcp-access: issuing a token failed: ${errorLogLabel(error)}`);
+    return { status: "error", error: safeError(error).error };
+  }
+}
+
+/** A gate's refusal with the app's own text, which the token page shows instead of the code's copy. */
+export function refuseIssue(code: McpIssueRefusalCode, message: string): McpIssueRefusal {
+  return { ok: false, error: code, message };
+}
+
+/** The form state for a gate's refusal; a missing or blank text falls back to the code's copy. */
+function getRefusalState(code: McpIssueRefusalCode, text: unknown): IssueTokenFormState {
+  const message = typeof text === "string" ? text.trim() : "";
+  return message === "" ? { status: "error", error: code } : { status: "error", error: code, message };
+}

package/src/next/pages.tsx

@@ -14,7 +14,7 @@ import { getLocalizedText, getMcpAccessMessages, getMcpAccessOptions, getMcpAcce
 import { listOAuthGrants } from "../server/oauth.js";
 import { listAccessTokens } from "../server/tokens.js";
 import { getAccessTokenStatus } from "../token-status.js";
-import { TokenManager, type TokenManagerGrant, type TokenManagerRow, type TokenManagerTool } from "../ui/token-manager.js";
+import { TokenManager, type IssueTokenAction, type TokenManagerGrant, type TokenManagerRow, type TokenManagerTool } from "../ui/token-manager.js";
 import { issueTokenAction, revokeGrantAction, revokeTokenAction } from "./actions.js";
 import { getMcpAccessContext } from "./context.js";
 import { formatDate, formatDateTime } from "./format.js";
@@ -64,7 +64,15 @@ function toTool(tool: McpAccessOptions["tools"][number], config: SoftureConfig,
   return { name: tool.name, description: getLocalizedText(tool.description, config.locale), accessText };
 }
 
-export async function McpAccessPage() {
+export interface McpAccessPageProps {
+  /**
+   * The app's own issue action, e.g. one that calls `issueToken` with a `beforeIssue` gate. Default:
+   * `issueTokenAction`, which issues without a gate.
+   */
+  readonly issueAction?: IssueTokenAction;
+}
+
+export async function McpAccessPage({ issueAction = issueTokenAction }: McpAccessPageProps = {}) {
   const config = getSoftureConfig();
   const user = await requireUser({ next: getMcpAccessRoutes(config).page });
   const options = getMcpAccessOptions(config);
@@ -81,7 +89,7 @@ export async function McpAccessPage() {
           tokens={tokens.map((token) => toRow(token, now, config, options, messages))}
           allowWrites={options.allowWrites}
           maxTokens={options.maxTokensPerUser}
-          issueAction={issueTokenAction}
+          issueAction={issueAction}
           revokeAction={revokeTokenAction}
           {...(grants === null ? {} : { grants: grants.map((grant) => toGrant(grant, config, options, messages)), revokeGrantAction })}
           messages={messages}

package/src/options.ts

@@ -28,6 +28,10 @@ const toolSchema = z.strictObject({
   access: z.enum(["read", "write"]),
   /** What the tool does, for the owner deciding which token to issue. */
   description: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text"),
+  /** A short display name (MCP's `title`), for clients and agent docs that show one. */
+  title: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text").optional(),
+  /** A request a person could make that uses the tool, e.g. "Show my last five orders.", for agent docs. */
+  example: localizedTextSchema.refine((text) => text.en !== undefined, "needs at least an en text").optional(),
 });
 
 /**
@@ -121,6 +125,15 @@ export const mcpAccessOptionsSchema = z
   .strictObject({
     /** The name MCP clients list the server under, e.g. "acme". Used in the setup instructions. */
     serverName: z.string().regex(SERVER_NAME_PATTERN, "must be lowercase letters, digits and inner dashes, at most 64 characters"),
+    /**
+     * The name the setup snippets register the server under in an MCP client (`claude mcp add`, the
+     * JSON configs, the assistant prompt), when it differs from `serverName`: an app keeps the entry its
+     * users already added. Unset, `serverName`.
+     */
+    clientServerName: z
+      .string()
+      .regex(SERVER_NAME_PATTERN, "must be lowercase letters, digits and inner dashes, at most 64 characters")
+      .optional(),
     /** The app's tool catalog, shown on the token page. The MCP server itself comes from the route. */
     tools: z.array(toolSchema).default([]),
     /** Lets write tokens be issued and used. Off, every token reads only, write tokens included. */

package/src/routes.ts

@@ -0,0 +1,17 @@
+// The routes the module mounts, as constants for code that cannot read the config: a proxy matcher,
+// a client, a test. The manifest declares the same object.
+
+export const DEFAULT_MCP_ACCESS_ROUTES = {
+  /** The token page. */
+  page: "/account/mcp",
+  /** `POST` MCP endpoint. */
+  endpoint: "/api/mcp",
+  /** OAuth consent page, the authorization endpoint. */
+  oauthConsent: "/oauth/authorize",
+  /** `POST` target of the consent form. */
+  oauthDecision: "/api/oauth/authorize",
+  /** `POST` OAuth token endpoint. */
+  oauthToken: "/api/oauth/token",
+  /** `POST` dynamic client registration. */
+  oauthRegister: "/api/oauth/register",
+} as const;

package/src/server/action-tool.ts

@@ -0,0 +1,64 @@
+// A server action as a write tool: the tool's arguments become the form the action reads, so the tool
+// and the form share one validation path, and the action's error state becomes a tool error.
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import { describeCode, toolError, toolResult, withToolErrors, type ToolErrorHints } from "./tools.js";
+
+/** The action, called with the form. A `useActionState` action is passed as `(form) => action(INITIAL, form)`. */
+export type FormActionHandler = (formData: FormData) => unknown;
+
+export interface ActionToolOptions {
+  /** The answer on success: a text, or a text built from the action's state. Default: the state as JSON. */
+  readonly message?: string | ((state: unknown) => string);
+  /** Texts per error code, as in `withToolErrors`. */
+  readonly hints?: ToolErrorHints;
+  /** The tool's name in the log line. */
+  readonly label?: string;
+}
+
+/** The tool callback for `server.registerTool(name, { inputSchema }, actionTool(handler))`. */
+export function actionTool(handler: FormActionHandler, options: ActionToolOptions = {}): (args: Readonly<Record<string, unknown>>) => Promise<CallToolResult> {
+  const hints = options.hints ?? {};
+  return (args) =>
+    withToolErrors(
+      async () => {
+        const state = await handler(toFormData(args));
+        const error = readErrorCode(state);
+        if (error !== null) return toolError(describeCode(error, hints));
+        if (options.message === undefined) return toolResult(state);
+        return toolResult(typeof options.message === "string" ? options.message : options.message(state));
+      },
+      { hints, ...(options.label === undefined ? {} : { label: options.label }) },
+    );
+}
+
+/**
+ * Arguments as a submitted form: strings as they are, numbers as text, `true` as `"on"` (a checked
+ * checkbox) and `false`, `null` and `undefined` left out (an unchecked one), arrays one entry per item,
+ * dates as ISO text, objects as JSON.
+ */
+export function toFormData(args: Readonly<Record<string, unknown>>): FormData {
+  const form = new FormData();
+  for (const [name, value] of Object.entries(args)) {
+    for (const item of Array.isArray(value) ? (value as unknown[]) : [value]) {
+      const field = toFieldValue(item);
+      if (field !== null) form.append(name, field);
+    }
+  }
+  return form;
+}
+
+function toFieldValue(value: unknown): string | null {
+  if (value === undefined || value === null || value === false) return null;
+  if (value === true) return "on";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return value.toString();
+  if (value instanceof Date) return value.toISOString();
+  return JSON.stringify(value);
+}
+
+/** The error code of an action state: `{ ok: false, error }` (core's result) or `{ status: "error", error }` (a form state). */
+function readErrorCode(state: unknown): string | null {
+  if (typeof state !== "object" || state === null || !("error" in state) || typeof state.error !== "string") return null;
+  const isFailure = ("ok" in state && state.ok === false) || ("status" in state && state.status === "error");
+  return isFailure ? state.error : null;
+}

package/src/server/index.ts

@@ -10,6 +10,7 @@ export {
   type McpEndpointOptions,
   type McpServerFactory,
 } from "./endpoint.js";
+export { actionTool, toFormData, type ActionToolOptions, type FormActionHandler } from "./action-tool.js";
 export { createMcpAccessContext } from "./context.js";
 export { checkAccessTokensTable } from "./health.js";
 export {
@@ -68,6 +69,7 @@ export type { OAuthClientRow, OAuthTokenEndpointAuthMethod } from "../schema.js"
 export { describeRedirectUri, isAllowedRedirectUri, MAX_CLIENT_NAME_LENGTH, parseClientRegistration, type ClientRegistrationResult, type RegistrationError } from "./oauth-validation.js";
 export { getCodeChallenge, isPkceVerifierValid, isValidCodeChallenge, PKCE_METHOD } from "./pkce.js";
 export { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl, type McpAccessRoutes } from "./options.js";
+export { pruneMcpAccess, type PrunedMcpAccessRecords } from "./prune.js";
 export {
   deleteMcpAccessUserData,
   exportMcpAccessUserData,
@@ -90,3 +92,4 @@ export {
   type RevokeAccessTokenInput,
   type VerifiedAccessToken,
 } from "./tokens.js";
+export { toolError, toolResult, withToolErrors, type ToolErrorHints, type ToolErrorOptions } from "./tools.js";

package/src/server/prune.ts

@@ -0,0 +1,14 @@
+// The module's scheduled cleanup: expired access tokens and dead OAuth records of every account, in
+// one call for a daily job (`softure-mcp prune`, a deploy `maintain` hook) instead of inline on requests.
+import { pruneOAuthRecords, type PrunedOAuthRecords } from "./oauth.js";
+import { pruneAccessTokens, type McpAccessContext } from "./tokens.js";
+
+export interface PrunedMcpAccessRecords extends PrunedOAuthRecords {
+  readonly accessTokens: number;
+}
+
+/** Runs `pruneAccessTokens`, then `pruneOAuthRecords`, and counts what each removed. */
+export async function pruneMcpAccess(ctx: McpAccessContext): Promise<PrunedMcpAccessRecords> {
+  const accessTokens = await pruneAccessTokens(ctx);
+  return { accessTokens, ...(await pruneOAuthRecords(ctx)) };
+}

package/src/server/tools.ts

@@ -0,0 +1,72 @@
+// Tool results for the app's MCP server and the boundary that keeps failures safe: the assistant gets
+// a value, a `PublicError`'s message or a hint, never a thrown error's text (a failed query carries
+// its SQL and parameters). The log gets the error's kind only (`errorLogLabel`).
+import { isCallToolResult, type CallToolResult } from "@modelcontextprotocol/server";
+import { errorLogLabel, getPublicMessage, safeError } from "@softure-ai/core";
+
+/** What the assistant reads for an error code: the app's own text per code, e.g. `{ "orders.not_found": "No order with that number." }`. */
+export type ToolErrorHints = Readonly<Record<string, string>>;
+
+export interface ToolErrorOptions {
+  /** Texts per error code; a code without one is answered as the code itself. */
+  readonly hints?: ToolErrorHints;
+  /** The tool's name in the log line. */
+  readonly label?: string;
+}
+
+/** For failures the tool did not expect: what `safeError` makes of them, unless a hint replaces it. */
+const DEFAULT_FAILURE_TEXT: ToolErrorHints = {
+  "core.database_failed": "The database could not answer; try again later.",
+  "core.unexpected": "The tool failed; try again later.",
+};
+
+/** A successful tool answer: a string as text, anything else as JSON text. */
+export function toolResult(value: unknown): CallToolResult {
+  return { content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value) ?? "null" }] };
+}
+
+/** A failed tool answer the assistant reads and may act on. */
+export function toolError(message: string): CallToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+/**
+ * Runs a tool's work and answers it safely. A `CallToolResult` passes as is; a result value is unwrapped
+ * (`{ ok: true, value }` → `toolResult(value)`, `{ ok: false, error }` → `toolError` with the hint for the
+ * code, else the code); any other value becomes `toolResult`. A thrown `PublicError` gives its message;
+ * anything else is logged by kind and answered with the hint for its `safeError` code, else a fixed text.
+ */
+export async function withToolErrors(work: () => unknown, options: ToolErrorOptions = {}): Promise<CallToolResult> {
+  try {
+    return answerValue(await work(), options.hints);
+  } catch (error) {
+    return answerFailure(error, options);
+  }
+}
+
+/** The answer for a value a tool or an action returned. */
+export function answerValue(value: unknown, hints: ToolErrorHints = {}): CallToolResult {
+  if (isCallToolResult(value)) return value;
+  if (isResult(value)) return value.ok ? toolResult(value.value) : toolError(describeCode(value.error, hints));
+  return toolResult(value);
+}
+
+function answerFailure(error: unknown, options: ToolErrorOptions): CallToolResult {
+  const publicMessage = getPublicMessage(error);
+  if (publicMessage !== null) return toolError(publicMessage);
+  console.error(`@softure-ai/mcp-access: tool ${options.label ?? "call"} failed: ${errorLogLabel(error)}`);
+  const code = safeError(error).error;
+  return toolError(options.hints?.[code] ?? DEFAULT_FAILURE_TEXT[code] ?? code);
+}
+
+/** The text for an error code: the app's hint, else the code. */
+export function describeCode(code: string, hints: ToolErrorHints): string {
+  return Object.hasOwn(hints, code) ? (hints[code] ?? code) : code;
+}
+
+/** Core's result shape: `{ ok: true, value }` or `{ ok: false, error }` with a string code. */
+function isResult(value: unknown): value is { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly error: string } {
+  if (typeof value !== "object" || value === null || !("ok" in value)) return false;
+  if (value.ok === true) return "value" in value;
+  return value.ok === false && "error" in value && typeof value.error === "string";
+}

package/src/stdio/index.ts

@@ -0,0 +1,12 @@
+// `@softure-ai/mcp-access/stdio`: the app's MCP server over stdio for a local assistant, with the
+// account from the environment. `/stdio/register` lets a factory that imports `server-only` run here.
+export {
+  DEFAULT_MCP_USER_ID_ENV,
+  serveMcpStdio,
+  STDIO_TOKEN_ID,
+  type McpStdioError,
+  type McpStdioErrorCode,
+  type McpStdioHandle,
+  type McpStdioResult,
+  type ServeMcpStdioOptions,
+} from "./serve.js";

package/src/stdio/register.ts

@@ -0,0 +1,11 @@
+// `node --import @softure-ai/mcp-access/stdio/register` (or `tsx --import …`): resolves `server-only` to
+// an empty module, so an MCP server factory written for Next (which marks its files with
+// `import "server-only"`) runs in a plain Node process. Nothing else is resolved differently; unlike
+// `--conditions=react-server`, React keeps its regular build.
+import { registerHooks } from "node:module";
+
+const EMPTY_MODULE = "data:text/javascript,export%20%7B%7D%3B";
+
+registerHooks({
+  resolve: (specifier, context, nextResolve) => (specifier === "server-only" ? { url: EMPTY_MODULE, format: "module", shortCircuit: true } : nextResolve(specifier, context)),
+});

package/src/stdio/serve.ts

@@ -0,0 +1,133 @@
+// The app's MCP server over stdio, for a local assistant (Claude Code, Claude Desktop) on the machine
+// that holds the database. There is no token: the account comes from the environment or, on a
+// database with exactly one account, is that account. The app's factory is the one the endpoint uses.
+//
+//   // scripts/mcp-stdio.ts, run with `tsx --import @softure-ai/mcp-access/stdio/register scripts/mcp-stdio.ts`
+//   const started = await serveMcpStdio({ config, createServer });
+//   if (!started.ok) { console.error(started.error.message); process.exitCode = 1; }
+import type { Transport } from "@modelcontextprotocol/server";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { users } from "@softure-ai/auth";
+import { errorLogLabel, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
+import { openCommandDatabase, type CommandDatabase } from "@softure-ai/db";
+import { eq } from "drizzle-orm";
+import type { McpServerIdentity } from "../contract.js";
+import type { McpServerFactory } from "../server/endpoint.js";
+import { getMcpAccessOptions } from "../server/options.js";
+
+/** The variable naming the account to serve, unless the entry is told another one. */
+export const DEFAULT_MCP_USER_ID_ENV = "MCP_USER_ID";
+
+/** The token id the factory receives over stdio, where there is no token. */
+export const STDIO_TOKEN_ID = "stdio";
+
+const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export type McpStdioErrorCode = "mcp-access.stdio_no_database" | "mcp-access.stdio_no_account" | "mcp-access.stdio_account_ambiguous" | "mcp-access.stdio_account_unknown";
+
+/** Why the entry did not start, with a message for the person running it (stderr: stdout is the protocol). */
+export interface McpStdioError {
+  readonly code: McpStdioErrorCode;
+  readonly message: string;
+}
+
+export interface McpStdioHandle {
+  /** Who the server runs as. */
+  readonly identity: McpServerIdentity;
+  /** Ends the connection and closes the database. Also happens when the client closes stdin. */
+  readonly close: () => Promise<void>;
+}
+
+export type McpStdioResult = { readonly ok: true; readonly value: McpStdioHandle } | { readonly ok: false; readonly error: McpStdioError };
+
+export interface ServeMcpStdioOptions {
+  readonly config: SoftureConfig;
+  readonly createServer: McpServerFactory;
+  /** The environment variable with the account's id. Default: `MCP_USER_ID`. */
+  readonly userIdEnv?: string;
+  /** Registers write tools, when the app's `allowWrites` is on too. Default: false, read only. */
+  readonly allowWrites?: boolean;
+  /** Default: `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Default: stdin and stdout of this process. */
+  readonly transport?: Transport;
+  /** Default: the config's `database.handle`, else a connection on `database.url`. */
+  readonly openDatabase?: (database: SoftureDatabaseConfig) => Promise<CommandDatabase>;
+}
+
+/** Resolves the account, then serves the app's server for it over stdio until the client goes away. */
+export async function serveMcpStdio(options: ServeMcpStdioOptions): Promise<McpStdioResult> {
+  const { config } = options;
+  if (config.database === null) return refuse("mcp-access.stdio_no_database", "softure.config.ts has no database; mcp-access needs one");
+  const userIdEnv = options.userIdEnv ?? DEFAULT_MCP_USER_ID_ENV;
+  const env = options.env ?? process.env;
+  const database = await (options.openDatabase ?? ((settings) => openCommandDatabase(settings, { max: 1 })))(config.database);
+
+  let userId: string | McpStdioError;
+  try {
+    userId = await resolveAccount(database, env[userIdEnv]?.trim() ?? "", userIdEnv);
+  } catch (error) {
+    await database.close();
+    throw new Error(`@softure-ai/mcp-access: looking up the account to serve failed: ${errorLogLabel(error)}`, { cause: error });
+  }
+  if (typeof userId !== "string") {
+    await database.close();
+    return { ok: false, error: userId };
+  }
+
+  const identity: McpServerIdentity = {
+    userId,
+    canWrite: (options.allowWrites ?? false) && getMcpAccessOptions(config).allowWrites,
+    tokenId: STDIO_TOKEN_ID,
+  };
+  let closed = false;
+  const closeDatabase = async () => {
+    if (closed) return;
+    closed = true;
+    await database.close();
+  };
+  const transport = options.transport ?? new StdioServerTransport();
+  const handle = serveStdio(() => options.createServer(identity), {
+    transport,
+    onerror: (error) => console.error(`@softure-ai/mcp-access: the stdio connection reported: ${errorLogLabel(error)}`),
+  });
+  // serveStdio has set its own handler by now; the database follows the connection, so a client that
+  // closes stdin leaves no open pool keeping the process alive.
+  const servedOnClose = transport.onclose;
+  transport.onclose = () => {
+    servedOnClose?.();
+    void closeDatabase();
+  };
+  return {
+    ok: true,
+    value: {
+      identity,
+      close: async () => {
+        await handle.close();
+        await closeDatabase();
+      },
+    },
+  };
+}
+
+/** The account id, or why there is none. Never the first of several accounts: that could be another person's data. */
+async function resolveAccount(database: CommandDatabase, requested: string, userIdEnv: string): Promise<string | McpStdioError> {
+  const { db } = database.handle;
+  if (requested !== "") {
+    const unknown = { code: "mcp-access.stdio_account_unknown", message: `@softure-ai/mcp-access: ${userIdEnv} names no account` } as const;
+    if (!UUID_SHAPE.test(requested)) return unknown;
+    const found = await db.select({ id: users.id }).from(users).where(eq(users.id, requested)).limit(1);
+    return found[0]?.id ?? unknown;
+  }
+  const accounts = await db.select({ id: users.id }).from(users).limit(2);
+  const [only, second] = accounts;
+  if (only === undefined) return { code: "mcp-access.stdio_no_account", message: "@softure-ai/mcp-access: the database has no account to serve" };
+  if (second !== undefined) {
+    return { code: "mcp-access.stdio_account_ambiguous", message: `@softure-ai/mcp-access: the database has several accounts; set ${userIdEnv} to the id of the one to serve` };
+  }
+  return only.id;
+}
+
+function refuse(code: McpStdioErrorCode, reason: string): McpStdioResult {
+  return { ok: false, error: { code, message: `@softure-ai/mcp-access: ${reason}` } };
+}

package/src/testing/catalog.ts

@@ -0,0 +1,74 @@
+// Catalog parity: the tools listed in softure.config.ts (the token page shows them, agent docs read
+// them) against the tools the app's MCP server really registers, for a read-only and a write identity.
+// Framework-free: `expectToolCatalogMatchesServer` throws, so it works in any test runner.
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import type { SoftureConfig } from "@softure-ai/core";
+import type { McpServerIdentity } from "../contract.js";
+import type { McpServerFactory } from "../server/endpoint.js";
+import { getMcpAccessOptions } from "../server/options.js";
+
+export interface ToolCatalogDifferences {
+  /** Configured tools the server does not register for the identity that should get them. */
+  readonly missing: readonly string[];
+  /** Tools the server registers that the catalog does not list. */
+  readonly unlisted: readonly string[];
+  /** Configured write tools the server gives a read-only identity. */
+  readonly writeForReaders: readonly string[];
+}
+
+const READER: McpServerIdentity = { userId: "00000000-0000-4000-8000-000000000001", canWrite: false, tokenId: "catalog-check" };
+const WRITER: McpServerIdentity = { ...READER, canWrite: true };
+
+/** Every difference between the configured catalog and the server, each list in the catalog's order, then the server's. */
+export async function getToolCatalogDifferences(config: SoftureConfig, createServer: McpServerFactory): Promise<ToolCatalogDifferences> {
+  const catalog = getMcpAccessOptions(config).tools;
+  const forReaders = await listServerTools(createServer, READER);
+  const forWriters = await listServerTools(createServer, WRITER);
+  const listed = new Set(catalog.map((tool) => tool.name));
+  return {
+    missing: catalog.filter((tool) => !(tool.access === "read" ? forReaders.includes(tool.name) && forWriters.includes(tool.name) : forWriters.includes(tool.name))).map((tool) => tool.name),
+    unlisted: [...new Set([...forReaders, ...forWriters])].filter((name) => !listed.has(name)),
+    writeForReaders: catalog.filter((tool) => tool.access === "write" && forReaders.includes(tool.name)).map((tool) => tool.name),
+  };
+}
+
+/** Throws a list of every difference, e.g. in a unit test next to the server. */
+export async function expectToolCatalogMatchesServer(config: SoftureConfig, createServer: McpServerFactory): Promise<void> {
+  const differences = await getToolCatalogDifferences(config, createServer);
+  const problems = [
+    differences.missing.length > 0 ? `missing from the server: ${differences.missing.join(", ")}` : null,
+    differences.unlisted.length > 0 ? `registered but not in the catalog: ${differences.unlisted.join(", ")}` : null,
+    differences.writeForReaders.length > 0 ? `write tools a read-only token gets: ${differences.writeForReaders.join(", ")}` : null,
+  ].filter((problem) => problem !== null);
+  if (problems.length > 0) {
+    throw new Error(`@softure-ai/mcp-access: the tool catalog in softure.config.ts does not match the MCP server: ${problems.join("; ")}`);
+  }
+}
+
+/** The tool names a fresh server lists for the identity, asked the way the endpoint serves it. */
+async function listServerTools(createServer: McpServerFactory, identity: McpServerIdentity): Promise<string[]> {
+  const handler = createMcpHandler(() => createServer(identity), { responseMode: "json" });
+  const response = await handler.fetch(
+    new Request("http://localhost/api/mcp", {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
+    }),
+  );
+  const answer = readAnswer(await response.text());
+  if (answer.result?.tools === undefined) {
+    throw new Error(`@softure-ai/mcp-access: listing the server's tools failed: ${typeof answer.error?.message === "string" ? answer.error.message : `HTTP ${String(response.status)}`}`);
+  }
+  return answer.result.tools.map((tool) => (typeof tool.name === "string" ? tool.name : "")).filter((name) => name !== "");
+}
+
+interface ToolsListAnswer {
+  readonly result?: { readonly tools?: readonly { readonly name?: unknown }[] };
+  readonly error?: { readonly message?: unknown };
+}
+
+/** The JSON-RPC answer, sent as JSON or as one SSE `message` event. */
+function readAnswer(body: string): ToolsListAnswer {
+  const data = body.startsWith("event:") ? (body.split("\n").find((line) => line.startsWith("data: "))?.slice("data: ".length) ?? "null") : body;
+  return (JSON.parse(data) ?? {}) as ToolsListAnswer;
+}

package/src/testing/index.ts

@@ -0,0 +1,2 @@
+// `@softure-ai/mcp-access/testing`: checks for an app's own tests.
+export { expectToolCatalogMatchesServer, getToolCatalogDifferences, type ToolCatalogDifferences } from "./catalog.js";

package/src/ui/token-manager.tsx

@@ -185,7 +185,7 @@ function IssueForm({
           />
           {allowWrites ? <Checkbox name="canWrite" label={messages.issue.canWrite} description={messages.issue.canWriteHint} unstyled={unstyled} /> : null}
           <p className={slot("text")}>{formatMessage(messages.issue.limit, { max: maxTokens })}</p>
-          <FormError message={state.status === "error" ? getTokenErrorMessage(messages, state.error) : undefined} unstyled={unstyled} />
+          <FormError message={state.status === "error" ? (state.message ?? getTokenErrorMessage(messages, state.error)) : undefined} unstyled={unstyled} />
           <Button type="submit" variant="primary" pending={isPending} unstyled={unstyled}>
             {isPending ? messages.issue.pending : messages.issue.submit}
           </Button>