@softure-ai/mcp-access 0.1.11 → 0.1.13

package/src/next/issue-token.ts

@@ -0,0 +1,90 @@
+// 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. Unexpected failures, the gate's included, become `safeError` codes.
+import { getCurrentUser } from "@softure-ai/auth/next";
+import { errorLogLabel, formatMessage, 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, 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;
+}
+
+/** The app's check before a token is issued: `ok()` lets it through, `err(code)` refuses with a message the page shows. */
+export type BeforeIssueGate = (input: IssueGateInput) => Ok<unknown> | Err<McpIssueRefusalCode> | Promise<Ok<unknown> | Err<McpIssueRefusalCode>>;
+
+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 { status: "error", error: gate.error };
+    }
+    // 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);
+    return {
+      status: "ok",
+      issued: {
+        id: issued.id,
+        name: issued.name,
+        canWrite: issued.canWrite,
+        expiresText: formatMessage(messages.issued.expires, { date: formatDate(config, issued.expiresAt) }),
+        setup: getMcpClientSetup({
+          serverName: getMcpAccessOptions(config).serverName,
+          endpointUrl,
+          token: issued.token,
+          promptTemplate: messages.setup.assistantPrompt,
+        }),
+      },
+    };
+  } catch (error) {
+    console.error(`@softure-ai/mcp-access: issuing a token failed: ${errorLogLabel(error)}`);
+    return { status: "error", error: safeError(error).error };
+  }
+}

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(),
 });
 
 /**
@@ -137,9 +141,9 @@ export const mcpAccessOptionsSchema = z
      */
     legacyTokenPattern: legacyTokenPatternSchema.optional(),
     /**
-     * The app origin of a request, when it is not the fixed `appOrigin`: an image built once and
-     * served under another origin, or a proxy whose `request.url` does not carry the public host.
-     * `readRequestOrigin` (`/server`) reads it from `Host`. Null keeps `appOrigin`.
+     * The app origin of a request, when the config's `origins` block (core `resolveAppOrigin`) does not
+     * answer it: prefer `origins.trustedOrigins` or `origins.trustRequestHost` there, which every
+     * module reads. `readRequestOrigin` reads it from `Host`. Null falls back to the config's rule.
      */
     resolveAppOrigin: z.custom<McpAppOriginResolver>((value) => typeof value === "function", "must be a function (request) => string | null").optional(),
     /**

package/src/origins.ts

@@ -1,11 +1,12 @@
 // The origins one request is served under: the app origin every OAuth URL is built from, and the
 // other public hosts whose root may be named as a protected resource. Pure: no config, no database.
+// Reading the request is core's rule (`readRequestHost`, `readRequestOrigin`, issue #311).
+import { readForwardedProto, readRequestHost, readRequestOrigin, type OriginRequest } from "@softure-ai/core";
+
+export { readRequestHost, readRequestOrigin };
 
 /** What the origin helpers read from a request: a Web `Request`, or Next's `headers()` with a URL. */
-export interface McpOriginRequest {
-  readonly url: string;
-  readonly headers: { get(name: string): string | null };
-}
+export type McpOriginRequest = OriginRequest;
 
 export interface McpOrigins {
   /** The issuer, and the origin of every endpoint, of `resource_metadata` and of the consent form. */
@@ -14,28 +15,6 @@ export interface McpOrigins {
   readonly resourceOrigins: readonly string[];
 }
 
-function firstValue(header: string | null): string | null {
-  const value = header?.split(",")[0]?.trim().toLowerCase();
-  return value === undefined || value === "" ? null : value;
-}
-
-/** The host the request was sent to: `Host`, else the URL's host. Behind a proxy the URL names the server's own. */
-export function readRequestHost(request: McpOriginRequest): string {
-  return firstValue(request.headers.get("host")) ?? new URL(request.url).host;
-}
-
-/**
- * The origin the request was sent to: the first `X-Forwarded-Proto` value when it is http or https
- * (else the URL's scheme) and `Host` (else the URL's host). For `resolveAppOrigin` in an app whose
- * proxy passes `Host` through and refuses hosts it does not serve.
- */
-export function readRequestOrigin(request: McpOriginRequest): string {
-  const url = new URL(request.url);
-  const proto = firstValue(request.headers.get("x-forwarded-proto"));
-  const scheme = proto === "http" || proto === "https" ? proto : url.protocol.replace(/:$/, "");
-  return new URL(`${scheme}://${readRequestHost(request)}`).origin;
-}
-
 /**
  * The resource origin the request was sent to, when its host is one of `resourceOrigins`; when two
  * share the host, the one whose scheme `X-Forwarded-Proto` names wins, else the first. Null otherwise.
@@ -43,6 +22,6 @@ export function readRequestOrigin(request: McpOriginRequest): string {
 export function findServedResourceOrigin(origins: McpOrigins, request: McpOriginRequest): string | null {
   const host = readRequestHost(request);
   const candidates = origins.resourceOrigins.filter((origin) => new URL(origin).host === host);
-  const proto = firstValue(request.headers.get("x-forwarded-proto"));
+  const proto = readForwardedProto(request);
   return candidates.find((origin) => new URL(origin).protocol === `${proto ?? ""}:`) ?? candidates[0] ?? null;
 }

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/oauth-http.ts

@@ -53,7 +53,7 @@ const CORS_HEADERS = {
 /** Responses that carry credentials must not be stored (RFC 6749 §5.1). */
 const NO_STORE = { "cache-control": "no-store", pragma: "no-cache" };
 /** Discovery documents change only with a deploy, and with the host they were asked on. */
-const DISCOVERY_CACHE = { "cache-control": "public, max-age=300", vary: "host, x-forwarded-proto" };
+const DISCOVERY_CACHE = { "cache-control": "public, max-age=300", vary: "host, x-forwarded-host, x-forwarded-proto" };
 
 function protocolJson(body: unknown, status = 200, extra: Readonly<Record<string, string>> = {}): Response {
   return Response.json(body, { status, headers: { ...CORS_HEADERS, ...NO_STORE, ...extra } });

package/src/server/origins.ts

@@ -1,6 +1,6 @@
-// The origins of one request, from the app's options: `resolveAppOrigin` when it answers, else the
-// configured `appOrigin`, plus `resourceOrigins`.
-import type { SoftureConfig } from "@softure-ai/core";
+// The origins of one request: the `resolveAppOrigin` option when it answers, else core `resolveAppOrigin` (a listed
+// origin the request was sent to, see the config's `origins`, else `appOrigin`), plus `resourceOrigins`.
+import { resolveAppOrigin, type SoftureConfig } from "@softure-ai/core";
 import { isBareOrigin } from "../options.js";
 import type { McpOriginRequest, McpOrigins } from "../origins.js";
 import { getMcpAccessOptions } from "./options.js";
@@ -11,9 +11,10 @@ import { getMcpAccessOptions } from "./options.js";
  */
 export function resolveMcpOrigins(config: SoftureConfig, request?: McpOriginRequest | null): McpOrigins {
   const options = getMcpAccessOptions(config);
-  const resolved = request === undefined || request === null || options.resolveAppOrigin === undefined ? null : options.resolveAppOrigin(request);
+  if (request === undefined || request === null) return { appOrigin: config.appOrigin, resourceOrigins: options.resourceOrigins };
+  const resolved = options.resolveAppOrigin === undefined ? null : options.resolveAppOrigin(request);
   if (resolved !== null && !isBareOrigin(resolved)) {
     throw new Error(`@softure-ai/mcp-access: resolveAppOrigin returned "${resolved.slice(0, 100)}", which is not an http(s) origin without a path`);
   }
-  return { appOrigin: new URL(resolved ?? config.appOrigin).origin, resourceOrigins: options.resourceOrigins };
+  return { appOrigin: new URL(resolved ?? resolveAppOrigin(config, request)).origin, resourceOrigins: options.resourceOrigins };
 }

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}` } };
+}