@softure-ai/mcp-access 0.0.0-stage → 0.1.5

package/src/contract.ts

@@ -0,0 +1,80 @@
+// Result types and error codes of the mcp-access module. No user-facing copy here: the UI
+// translates codes through `messages` (docs/02-module-standard.md §6).
+import type { CoreErrorCode } from "@softure-ai/core";
+
+export type McpAccessErrorCode =
+  | "mcp-access.name_required"
+  | "mcp-access.name_too_long"
+  | "mcp-access.token_limit_reached"
+  | "mcp-access.token_not_found";
+
+/** Every code the token page can show: its own, a missing session and the generic ones. */
+export type TokenFormErrorCode = McpAccessErrorCode | "auth.unauthenticated" | CoreErrorCode;
+
+/** What the app's MCP server factory receives for one request. */
+export interface McpServerIdentity {
+  /** The auth user id of the token's owner: every query of the server is scoped to it. */
+  readonly userId: string;
+  /** Whether write tools may be registered: the app allows writes and the token was issued for them. */
+  readonly canWrite: boolean;
+  /** The token's id, for the server's own logs. Never the token. */
+  readonly tokenId: string;
+}
+
+/** A stored token as its owner sees it. The hash never leaves the server functions. */
+export interface AccessTokenView {
+  readonly id: string;
+  readonly name: string;
+  /** Issued with write access (it still writes only while the app allows writes). */
+  readonly canWrite: boolean;
+  readonly createdAt: Date;
+  readonly expiresAt: Date;
+  readonly lastUsedAt: Date | null;
+}
+
+/** Where a token stands on its expiry, for the list. */
+export type AccessTokenStatus =
+  | { readonly kind: "active" }
+  /** `daysLeft`: calendar days in the app's time zone, from 0 (today) to the warning threshold. */
+  | { readonly kind: "expiring"; readonly daysLeft: number }
+  | { readonly kind: "expired" };
+
+/** Ready-to-paste setup for MCP clients, built around the plaintext token. */
+export interface McpClientSetup {
+  readonly serverName: string;
+  readonly endpointUrl: string;
+  /** `claude mcp add …` for Claude Code, with the token in it. */
+  readonly claudeCodeCommand: string;
+  /** A prompt asking the assistant to run that command and confirm the connection. */
+  readonly assistantPrompt: string;
+  /** A `claude-cli://` link that opens Claude Code with the prompt (it runs nothing by itself). */
+  readonly claudeCodeLink: string;
+  /** `mcpServers` JSON for clients configured by file (Cursor, VS Code, Windsurf). */
+  readonly jsonConfig: string;
+  /** Claude Desktop's file, bridged through `mcp-remote` (it cannot send headers itself). */
+  readonly desktopConfig: string;
+  /** The `Authorization` header value, for clients with a header field. */
+  readonly authorizationHeader: string;
+}
+
+/** A token right after it was issued: the only moment its plaintext exists outside the client. */
+export interface IssuedToken {
+  readonly id: string;
+  readonly name: string;
+  readonly canWrite: boolean;
+  /** The expiry, already formatted in the app's locale and time zone. */
+  readonly expiresText: string;
+  readonly setup: McpClientSetup;
+}
+
+/** What the issue action returns to its form (`useActionState`). */
+export type IssueTokenFormState =
+  | { readonly status: "idle" }
+  | { readonly status: "ok"; readonly issued: IssuedToken }
+  | { readonly status: "error"; readonly error: TokenFormErrorCode };
+
+/** What the revoke action returns to one token's form. */
+export type RevokeTokenFormState =
+  | { readonly status: "idle" }
+  | { readonly status: "ok" }
+  | { readonly status: "error"; readonly error: TokenFormErrorCode };

package/src/index.ts

@@ -0,0 +1,81 @@
+// Public API of @softure-ai/mcp-access: the module factory for softure.config.ts, its rate limit
+// bucket, types, messages, table and the pure helpers for token status and client setup. Database
+// work and the endpoint are in `@softure-ai/mcp-access/server`, the Next.js adapter (route, page,
+// actions) in `/next`, the token manager in `/ui`.
+import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
+import { mcpAccessMessages } from "./messages/index.js";
+import { mcpAccessOptionsSchema } from "./options.js";
+import { checkAccessTokensTable } from "./server/health.js";
+import { mcpAccessPrivacyContributor } from "./server/privacy.js";
+
+export const MODULE_ID = "mcp-access";
+
+/**
+ * The rate limit bucket of `POST /api/mcp`, to spread into `security({ buckets })`: requests per
+ * client address, counted before the token is verified. Every request counts, so the limit is for
+ * the traffic behind one address (several assistants share it), not for one token.
+ */
+export const MCP_RATE_LIMIT_BUCKETS = {
+  mcp: { limit: 200, windowMinutes: 15 },
+} as const;
+
+/**
+ * Enables MCP access in `softure.config.ts` (after `security` and `auth`):
+ * `mcpAccess({ serverName: "acme", tools: [{ name: "list_orders", access: "read", description: { en: "Lists your orders." } }] })`.
+ */
+export const mcpAccess = defineModule({
+  manifest: {
+    id: MODULE_ID,
+    version: "0.1.5",
+    dependsOn: { security: "^0.1.0", auth: "^0.1.0" },
+    dbSchema: "mcp",
+    tables: ["access_tokens"],
+    env: [],
+    switches: [],
+    routes: { page: "/account/mcp", endpoint: "/api/mcp" },
+    mount: [
+      { kind: "page", path: "app/account/mcp/page.tsx", export: "McpAccessPage" },
+      { kind: "route-handler", path: "app/api/mcp/route.ts", export: "createMcpRoute" },
+    ],
+    privacy: { exports: true, deletes: true },
+  },
+  messages: mcpAccessMessages,
+  options: mcpAccessOptionsSchema,
+  migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
+  privacy: mcpAccessPrivacyContributor,
+  health: checkAccessTokensTable,
+});
+
+export {
+  getAuthorizationHeader,
+  getClaudeCodeCommand,
+  getClaudeCodeLink,
+  getDesktopConfig,
+  getJsonConfig,
+  getMcpClientSetup,
+  type McpClientSetupInput,
+} from "./client-setup.js";
+export type {
+  AccessTokenStatus,
+  AccessTokenView,
+  IssuedToken,
+  IssueTokenFormState,
+  McpAccessErrorCode,
+  McpClientSetup,
+  McpServerIdentity,
+  RevokeTokenFormState,
+  TokenFormErrorCode,
+} from "./contract.js";
+export { getTokenErrorMessage, mcpAccessMessages, type McpAccessMessages } from "./messages/index.js";
+export {
+  MAX_TOKEN_NAME_LENGTH,
+  SERVER_NAME_PATTERN,
+  TOOL_NAME_PATTERN,
+  type McpAccessOptions,
+  type McpAccessOptionsInput,
+  type McpToolAccess,
+  type McpToolDefinition,
+  type McpToolDefinitionInput,
+} from "./options.js";
+export { accessTokens } from "./schema.js";
+export { getAccessTokenStatus, type AccessTokenStatusOptions } from "./token-status.js";

package/src/messages/en.ts

@@ -0,0 +1,76 @@
+export const en = {
+  page: {
+    title: "AI assistant access",
+    lead: "Connect an AI assistant such as Claude to your account over MCP. Each assistant gets its own token, which you can revoke at any time.",
+  },
+  tools: {
+    title: "What an assistant can do",
+    empty: "The app lists no tools yet.",
+    read: "Reads",
+    write: "Changes data",
+    writeUnavailable: "Changes data (turned off in this app)",
+  },
+  issue: {
+    title: "New token",
+    name: "Name",
+    nameHint: "Where you will use it, e.g. Laptop or Claude Desktop.",
+    canWrite: "Allow changes",
+    canWriteHint: "Without it, the assistant can only read.",
+    submit: "Create token",
+    pending: "Creating…",
+    limit: "You can hold up to {max} active tokens.",
+  },
+  issued: {
+    title: "Token created: {name}",
+    once: "Copy it now. It is shown only once; after you leave this page, only its name remains.",
+    expires: "Works until {date}.",
+    readOnly: "This token can only read.",
+    readWrite: "This token can read and change data.",
+    promptTitle: "Easiest: let Claude Code set it up",
+    promptHint: "Paste this into a conversation with Claude Code. It runs the command and checks the connection.",
+    openClaudeCode: "Open in Claude Code",
+    commandTitle: "Terminal command (Claude Code)",
+    jsonTitle: "Configuration file (Cursor, VS Code, Windsurf)",
+    desktopTitle: "Claude Desktop (claude_desktop_config.json)",
+    headerTitle: "Other clients: server address and Authorization header",
+    copy: "Copy",
+    copied: "Copied",
+    done: "Done, hide the token",
+  },
+  setup: {
+    assistantPrompt: "Connect to my {serverName} account over MCP.\nRun: {command}\nThen check /mcp and tell me whether the server \"{serverName}\" is connected.",
+  },
+  list: {
+    title: "Your tokens",
+    empty: "You have no tokens yet.",
+    readOnly: "Read only",
+    readWrite: "Read and change",
+    active: "Active",
+    expired: "Expired",
+    expiresToday: "Expires today",
+    expiresTomorrow: "Expires tomorrow",
+    expiresInDays: "Expires in {days} days",
+    expiresOn: "Valid until {date}",
+    expiredOn: "Expired on {date}",
+    createdOn: "Created {date}",
+    lastUsed: "Last used {date}",
+    neverUsed: "Not used yet",
+    revoke: "Revoke",
+    revoking: "Revoking…",
+  },
+  errors: {
+    "mcp-access": {
+      name_required: "Give the token a name, so you can tell it from the others.",
+      name_too_long: "The name is too long.",
+      token_limit_reached: "You already hold the most active tokens allowed. Revoke one before creating another.",
+      token_not_found: "This token no longer exists. It may have been revoked already.",
+    },
+    auth: {
+      unauthenticated: "Your session has ended. Log in again.",
+    },
+    core: {
+      database_failed: "Something went wrong on our side. Try again in a moment.",
+      unexpected: "Something went wrong on our side. Try again in a moment.",
+    },
+  },
+};

package/src/messages/index.ts

@@ -0,0 +1,18 @@
+import type { TokenFormErrorCode } from "../contract.js";
+import { en } from "./en.js";
+import { pl } from "./pl.js";
+
+/** Complete default dictionaries; apps pass partial overrides per locale. */
+export const mcpAccessMessages = { en, pl };
+
+export type McpAccessMessages = typeof en;
+
+/** The copy for an error code; an unknown code gets the generic failure. */
+export function getTokenErrorMessage(messages: McpAccessMessages, code: TokenFormErrorCode): string {
+  const separator = code.lastIndexOf(".");
+  const namespace = code.slice(0, separator);
+  const name = code.slice(separator + 1);
+  const groups = messages.errors as Readonly<Record<string, Readonly<Record<string, string>>>>;
+  const group = Object.hasOwn(groups, namespace) ? groups[namespace] : undefined;
+  return (group !== undefined && Object.hasOwn(group, name) ? group[name] : undefined) ?? messages.errors.core.unexpected;
+}

package/src/messages/pl.ts

@@ -0,0 +1,78 @@
+import type { en } from "./en.js";
+
+export const pl: typeof en = {
+  page: {
+    title: "Dostęp dla asystenta AI",
+    lead: "Połącz asystenta AI, na przykład Claude, ze swoim kontem przez MCP. Każdy asystent dostaje własny token, który możesz w każdej chwili unieważnić.",
+  },
+  tools: {
+    title: "Co może asystent",
+    empty: "Aplikacja nie udostępnia jeszcze żadnych narzędzi.",
+    read: "Odczyt",
+    write: "Zmienia dane",
+    writeUnavailable: "Zmienia dane (wyłączone w tej aplikacji)",
+  },
+  issue: {
+    title: "Nowy token",
+    name: "Nazwa",
+    nameHint: "Gdzie go użyjesz, na przykład Laptop albo Claude Desktop.",
+    canWrite: "Pozwól na zmiany",
+    canWriteHint: "Bez tego asystent może tylko czytać.",
+    submit: "Utwórz token",
+    pending: "Tworzenie…",
+    limit: "Możesz mieć najwyżej {max} aktywnych tokenów.",
+  },
+  issued: {
+    title: "Utworzono token: {name}",
+    once: "Skopiuj go teraz. Pokazujemy go tylko raz; gdy opuścisz tę stronę, zostanie tylko jego nazwa.",
+    expires: "Działa do {date}.",
+    readOnly: "Ten token może tylko czytać.",
+    readWrite: "Ten token może czytać i zmieniać dane.",
+    promptTitle: "Najprościej: niech Claude Code sam to skonfiguruje",
+    promptHint: "Wklej to do rozmowy z Claude Code. Wykona polecenie i sprawdzi połączenie.",
+    openClaudeCode: "Otwórz w Claude Code",
+    commandTitle: "Polecenie w terminalu (Claude Code)",
+    jsonTitle: "Plik konfiguracyjny (Cursor, VS Code, Windsurf)",
+    desktopTitle: "Claude Desktop (claude_desktop_config.json)",
+    headerTitle: "Inne klienty: adres serwera i nagłówek Authorization",
+    copy: "Kopiuj",
+    copied: "Skopiowano",
+    done: "Gotowe, ukryj token",
+  },
+  setup: {
+    assistantPrompt: "Połącz się z moim kontem {serverName} przez MCP.\nWykonaj: {command}\nPotem sprawdź /mcp i powiedz mi, czy serwer „{serverName}” jest połączony.",
+  },
+  list: {
+    title: "Twoje tokeny",
+    empty: "Nie masz jeszcze żadnych tokenów.",
+    readOnly: "Tylko odczyt",
+    readWrite: "Odczyt i zmiany",
+    active: "Aktywny",
+    expired: "Wygasł",
+    expiresToday: "Wygasa dziś",
+    expiresTomorrow: "Wygasa jutro",
+    expiresInDays: "Wygasa za {days} dni",
+    expiresOn: "Ważny do {date}",
+    expiredOn: "Wygasł {date}",
+    createdOn: "Utworzony {date}",
+    lastUsed: "Ostatnio użyty {date}",
+    neverUsed: "Jeszcze nieużywany",
+    revoke: "Unieważnij",
+    revoking: "Unieważnianie…",
+  },
+  errors: {
+    "mcp-access": {
+      name_required: "Nadaj tokenowi nazwę, żeby odróżnić go od pozostałych.",
+      name_too_long: "Nazwa jest za długa.",
+      token_limit_reached: "Masz już najwięcej aktywnych tokenów, ile można. Unieważnij któryś, zanim utworzysz nowy.",
+      token_not_found: "Ten token już nie istnieje. Mógł zostać unieważniony.",
+    },
+    auth: {
+      unauthenticated: "Twoja sesja wygasła. Zaloguj się ponownie.",
+    },
+    core: {
+      database_failed: "Coś poszło nie tak po naszej stronie. Spróbuj ponownie za chwilę.",
+      unexpected: "Coś poszło nie tak po naszej stronie. Spróbuj ponownie za chwilę.",
+    },
+  },
+};

package/src/next/actions.ts

@@ -0,0 +1,91 @@
+"use server";
+
+// The token page's server actions. The owner comes from the session (never from a bound argument,
+// which the client controls, docs/02 §8) before the form is read, and every query is scoped to
+// that owner. Unexpected failures become `safeError` codes; the token never reaches a log.
+import { getCurrentUser } from "@softure-ai/auth/next";
+import { errorLogLabel, formatMessage, safeError, type SoftureConfig } 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, RevokeTokenFormState } from "../contract.js";
+import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
+import { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl } from "../server/options.js";
+import { issueAccessToken, revokeAccessToken } from "../server/tokens.js";
+import { getMcpAccessContext } 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 text = z
+  .string()
+  .catch("")
+  .transform((value) => value.slice(0, MAX_FIELD_LENGTH));
+
+const issueInput = z.object({
+  name: text,
+  // A checked HTML checkbox sends "on"; an unchecked one sends nothing, which means read only.
+  canWrite: z.string().nullable().catch(null),
+});
+const revokeInput = z.object({ id: text });
+
+function reportFailure(operation: string, error: unknown) {
+  console.error(`@softure-ai/mcp-access: ${operation} failed: ${errorLogLabel(error)}`);
+  return safeError(error).error;
+}
+
+function refreshPage(config: SoftureConfig): void {
+  revalidatePath(getMcpAccessRoutes(config).page);
+}
+
+/** Issues a token for the signed-in user and returns its plaintext with the setup snippets, once. */
+export async function issueTokenAction(_previous: IssueTokenFormState, formData: FormData): 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") });
+  try {
+    const result = await issueAccessToken(await getMcpAccessContext(config), { userId: user.id, name: input.name, canWrite: input.canWrite !== null });
+    if (!result.ok) return { status: "error", error: result.error };
+    refreshPage(config);
+    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: getMcpEndpointUrl(config),
+          token: issued.token,
+          promptTemplate: messages.setup.assistantPrompt,
+        }),
+      },
+    };
+  } catch (error) {
+    return { status: "error", error: reportFailure("issuing a token", error) };
+  }
+}
+
+/** Revokes one of the signed-in user's tokens; another account's id matches nothing. */
+export async function revokeTokenAction(_previous: RevokeTokenFormState, formData: FormData): Promise<RevokeTokenFormState> {
+  const config = getSoftureConfig();
+  const user = await getCurrentUser();
+  if (user === null) return { status: "error", error: "auth.unauthenticated" };
+
+  const input = revokeInput.parse({ id: formData.get("id") });
+  try {
+    const result = await revokeAccessToken(await getMcpAccessContext(config), { userId: user.id, tokenId: input.id });
+    if (!result.ok) return { status: "error", error: result.error };
+    refreshPage(config);
+    return { status: "ok" };
+  } catch (error) {
+    return { status: "error", error: reportFailure("revoking a token", error) };
+  }
+}

package/src/next/context.ts

@@ -0,0 +1,14 @@
+// What the adapter hands the server functions: the registered config, the process-wide database
+// handle and the wall clock.
+import { systemClock, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { getSharedDatabase } from "@softure-ai/db";
+import type { McpAccessContext } from "../server/tokens.js";
+
+export async function getMcpAccessContext(config: SoftureConfig = getSoftureConfig()): Promise<McpAccessContext> {
+  if (config.database === null) {
+    throw new Error("@softure-ai/mcp-access: softure.config.ts has no database; mcp-access needs one");
+  }
+  const { db } = await getSharedDatabase(config.database.url);
+  return { db, clock: systemClock, config };
+}

package/src/next/format.ts

@@ -0,0 +1,10 @@
+// Dates on the token page, in the app's locale and time zone.
+import type { SoftureConfig } from "@softure-ai/core";
+
+export function formatDate(config: SoftureConfig, date: Date): string {
+  return new Intl.DateTimeFormat(config.locale, { dateStyle: "long", timeZone: config.timezone }).format(date);
+}
+
+export function formatDateTime(config: SoftureConfig, date: Date): string {
+  return new Intl.DateTimeFormat(config.locale, { dateStyle: "medium", timeStyle: "short", timeZone: config.timezone }).format(date);
+}

package/src/next/index.ts

@@ -0,0 +1,5 @@
+// The Next.js adapter of @softure-ai/mcp-access: the MCP route factory, the token page and its
+// server actions (docs/02-module-standard.md §8).
+export { issueTokenAction, revokeTokenAction } from "./actions.js";
+export { McpAccessPage } from "./pages.js";
+export { createMcpRoute } from "./route.js";

package/src/next/next-modules.d.ts

@@ -0,0 +1,16 @@
+// Next.js has no `exports` map, so NodeNext resolution (tsconfig.base.json) only finds
+// `next/navigation.js` and `next/headers.js`. The code must still import the bare specifiers:
+// Next's bundler aliases them per runtime, and the `.js` form bypasses the alias (measured:
+// `next build` failed to collect a route handler importing `next/navigation.js`, MODULE_UNPARSABLE
+// on the vendored app-router context). These declarations give the bare specifiers their types.
+declare module "next/navigation" {
+  export * from "next/navigation.js";
+}
+
+declare module "next/headers" {
+  export * from "next/headers.js";
+}
+
+declare module "next/cache" {
+  export * from "next/cache.js";
+}

package/src/next/pages.tsx

@@ -0,0 +1,80 @@
+// The token page, ready to mount with one line:
+// `export { McpAccessPage as default } from "@softure-ai/mcp-access/next"`.
+// A server component for the signed-in user; without a session it redirects to the login page and
+// back. Everything the client part shows is prepared here, so dates are formatted once, in the
+// app's locale and time zone, and never differ between the server render and hydration.
+import { requireUser } from "@softure-ai/auth/next";
+import { formatMessage, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { Card } from "@softure-ai/ui";
+import type { AccessTokenStatus, AccessTokenView } from "../contract.js";
+import type { McpAccessMessages } from "../messages/index.js";
+import type { McpAccessOptions } from "../options.js";
+import { getLocalizedText, getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes } from "../server/options.js";
+import { listAccessTokens } from "../server/tokens.js";
+import { getAccessTokenStatus } from "../token-status.js";
+import { TokenManager, type TokenManagerRow, type TokenManagerTool } from "../ui/token-manager.js";
+import { issueTokenAction, revokeTokenAction } from "./actions.js";
+import { getMcpAccessContext } from "./context.js";
+import { formatDate, formatDateTime } from "./format.js";
+
+const LAYOUT_CLASS = "sft:mx-auto sft:box-border sft:w-full sft:sm:max-w-3xl sft:px-4 sft:py-4";
+
+function describeStatus(status: AccessTokenStatus, messages: McpAccessMessages): string {
+  switch (status.kind) {
+    case "active":
+      return messages.list.active;
+    case "expired":
+      return messages.list.expired;
+    case "expiring":
+      if (status.daysLeft === 0) return messages.list.expiresToday;
+      if (status.daysLeft === 1) return messages.list.expiresTomorrow;
+      return formatMessage(messages.list.expiresInDays, { days: status.daysLeft });
+  }
+}
+
+function toRow(token: AccessTokenView, now: Date, config: SoftureConfig, options: McpAccessOptions, messages: McpAccessMessages): TokenManagerRow {
+  const status = getAccessTokenStatus(token.expiresAt, now, { timezone: config.timezone, warningDays: options.expiryWarningDays });
+  const isExpired = status.kind === "expired";
+  const expiry = formatMessage(isExpired ? messages.list.expiredOn : messages.list.expiresOn, { date: formatDate(config, token.expiresAt) });
+  const lastUse = token.lastUsedAt === null ? messages.list.neverUsed : formatMessage(messages.list.lastUsed, { date: formatDateTime(config, token.lastUsedAt) });
+  return {
+    id: token.id,
+    name: token.name,
+    scopeText: token.canWrite && options.allowWrites ? messages.list.readWrite : messages.list.readOnly,
+    statusText: describeStatus(status, messages),
+    isExpired,
+    details: [formatMessage(messages.list.createdOn, { date: formatDate(config, token.createdAt) }), expiry, lastUse],
+  };
+}
+
+function toTool(tool: McpAccessOptions["tools"][number], config: SoftureConfig, options: McpAccessOptions, messages: McpAccessMessages): TokenManagerTool {
+  const accessText = tool.access === "read" ? messages.tools.read : options.allowWrites ? messages.tools.write : messages.tools.writeUnavailable;
+  return { name: tool.name, description: getLocalizedText(tool.description, config.locale), accessText };
+}
+
+export async function McpAccessPage() {
+  const config = getSoftureConfig();
+  const user = await requireUser({ next: getMcpAccessRoutes(config).page });
+  const options = getMcpAccessOptions(config);
+  const messages = getMcpAccessMessages(config);
+  const ctx = await getMcpAccessContext(config);
+  const now = ctx.clock.now();
+  const tokens = await listAccessTokens(ctx, user.id);
+  return (
+    <main className={LAYOUT_CLASS}>
+      <Card title={messages.page.title} subtitle={messages.page.lead}>
+        <TokenManager
+          tools={options.tools.map((tool) => toTool(tool, config, options, messages))}
+          tokens={tokens.map((token) => toRow(token, now, config, options, messages))}
+          allowWrites={options.allowWrites}
+          maxTokens={options.maxTokensPerUser}
+          issueAction={issueTokenAction}
+          revokeAction={revokeTokenAction}
+          messages={messages}
+          locale={config.locale}
+        />
+      </Card>
+    </main>
+  );
+}

package/src/next/route.ts

@@ -0,0 +1,24 @@
+// `POST /api/mcp`, built around the app's MCP server factory and mounted with one line:
+// `app/api/mcp/route.ts → export const POST = createMcpRoute({ createServer });`
+// The factory lives in the app, next to its tools; the module brings the rate limit, the token
+// check and the identity the factory receives. GET and DELETE are not exported, so Next answers
+// them with 405: the endpoint is stateless and keeps no sessions.
+import { errorLogLabel } from "@softure-ai/core";
+import { createMcpEndpoint, type McpEndpointOptions } from "../server/endpoint.js";
+import { getMcpAccessContext } from "./context.js";
+
+const NO_STORE = { "cache-control": "no-store" };
+
+export function createMcpRoute(options: McpEndpointOptions): (request: Request) => Promise<Response> {
+  const endpoint = createMcpEndpoint(options);
+  return async (request) => {
+    let ctx;
+    try {
+      ctx = await getMcpAccessContext();
+    } catch (error) {
+      console.error(`@softure-ai/mcp-access: opening the database failed: ${errorLogLabel(error)}`);
+      return Response.json({ error: "temporarily_unavailable" }, { status: 503, headers: NO_STORE });
+    }
+    return endpoint(ctx, request);
+  };
+}

package/src/options.ts

@@ -0,0 +1,58 @@
+// The options an app passes to `mcpAccess({ ... })` in softure.config.ts, parsed at startup.
+import { LOCALES } from "@softure-ai/core";
+import { z } from "zod";
+
+/** The name an MCP client lists the server under: no spaces, so a shell command needs no quotes. */
+export const SERVER_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+
+/** The MCP rule for tool names: 1 to 128 of A-Z, a-z, 0-9, `_`, `-` and `.`. */
+export const TOOL_NAME_PATTERN = /^[A-Za-z0-9_.-]{1,128}$/;
+
+/** The longest token name the table takes (`access_tokens.name`). */
+export const MAX_TOKEN_NAME_LENGTH = 60;
+
+/** Copy per locale; a locale without its own text falls back to `en`. */
+const localizedTextSchema = z.partialRecord(z.enum(LOCALES), z.string().trim().min(1).max(500));
+
+const toolSchema = z.strictObject({
+  /** The tool's name as the app's MCP server registers it. */
+  name: z.string().regex(TOOL_NAME_PATTERN, "must be 1 to 128 of A-Z, a-z, 0-9, _, - and ."),
+  /**
+   * `write` tools change data: the app registers them only for a token that can write. They stay
+   * listed while `allowWrites` is off, marked as unavailable.
+   */
+  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"),
+});
+
+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 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. */
+    allowWrites: z.boolean().default(false),
+    /** How long a token works. A choice: longer than a session, never forever. */
+    tokenLifetimeDays: z.int().min(1).max(365).default(90),
+    /** How many unexpired tokens one account may hold. */
+    maxTokensPerUser: z.int().min(1).max(100).default(20),
+    /** From how many calendar days before its expiry the page warns about a token. */
+    expiryWarningDays: z.int().min(0).max(60).default(14),
+  })
+  .superRefine((options, context) => {
+    const names = new Set<string>();
+    options.tools.forEach((tool, index) => {
+      if (names.has(tool.name)) {
+        context.addIssue({ code: "custom", path: ["tools", index, "name"], message: `"${tool.name}" is listed twice` });
+      }
+      names.add(tool.name);
+    });
+  });
+
+export type McpAccessOptionsInput = z.input<typeof mcpAccessOptionsSchema>;
+export type McpAccessOptions = z.output<typeof mcpAccessOptionsSchema>;
+export type McpToolDefinitionInput = z.input<typeof toolSchema>;
+export type McpToolDefinition = z.output<typeof toolSchema>;
+export type McpToolAccess = McpToolDefinition["access"];

package/src/schema.ts

@@ -0,0 +1,19 @@
+// Drizzle view of the module's table (migrations/0001_create_access_tokens.sql). The migration is
+// the source of truth; this file only types the queries.
+import { users } from "@softure-ai/auth";
+import { boolean, pgSchema, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+export const mcpSchema = pgSchema("mcp");
+
+export const accessTokens = mcpSchema.table("access_tokens", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  userId: uuid("user_id")
+    .notNull()
+    .references(() => users.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+  tokenHash: text("token_hash").notNull().unique("access_tokens_token_hash_key"),
+  canWrite: boolean("can_write").notNull(),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull(),
+  expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+  lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+});