@softure-ai/mcp-access 0.1.11 → 0.1.13

package/dist/stdio/serve.js

@@ -0,0 +1,89 @@
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { users } from "@softure-ai/auth";
+import { errorLogLabel } from "@softure-ai/core";
+import { openCommandDatabase } from "@softure-ai/db";
+import { eq } from "drizzle-orm";
+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;
+/** Resolves the account, then serves the app's server for it over stdio until the client goes away. */
+export async function serveMcpStdio(options) {
+    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;
+    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 = {
+        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, requested, userIdEnv) {
+    const { db } = database.handle;
+    if (requested !== "") {
+        const unknown = { code: "mcp-access.stdio_account_unknown", message: `@softure-ai/mcp-access: ${userIdEnv} names no account` };
+        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, reason) {
+    return { ok: false, error: { code, message: `@softure-ai/mcp-access: ${reason}` } };
+}
+//# sourceMappingURL=serve.js.map

package/dist/stdio/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/stdio/serve.ts"],"names":[],"mappings":"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"}

package/dist/testing/catalog.d.ts

@@ -0,0 +1,15 @@
+import type { SoftureConfig } from "@softure-ai/core";
+import type { McpServerFactory } from "../server/endpoint.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[];
+}
+/** Every difference between the configured catalog and the server, each list in the catalog's order, then the server's. */
+export declare function getToolCatalogDifferences(config: SoftureConfig, createServer: McpServerFactory): Promise<ToolCatalogDifferences>;
+/** Throws a list of every difference, e.g. in a unit test next to the server. */
+export declare function expectToolCatalogMatchesServer(config: SoftureConfig, createServer: McpServerFactory): Promise<void>;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/testing/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/testing/catalog.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,MAAM,WAAW,sBAAsB;IACrC,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,oEAAoE;IACpE,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAKD,2HAA2H;AAC3H,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAUtI;AAED,iFAAiF;AACjF,wBAAsB,8BAA8B,CAAC,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUzH"}

package/dist/testing/catalog.js

@@ -0,0 +1,51 @@
+// 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 { getMcpAccessOptions } from "../server/options.js";
+const READER = { userId: "00000000-0000-4000-8000-000000000001", canWrite: false, tokenId: "catalog-check" };
+const WRITER = { ...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, createServer) {
+    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, createServer) {
+    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, identity) {
+    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 !== "");
+}
+/** The JSON-RPC answer, sent as JSON or as one SSE `message` event. */
+function readAnswer(body) {
+    const data = body.startsWith("event:") ? (body.split("\n").find((line) => line.startsWith("data: "))?.slice("data: ".length) ?? "null") : body;
+    return (JSON.parse(data) ?? {});
+}
+//# sourceMappingURL=catalog.js.map

package/dist/testing/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/testing/catalog.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -0,0 +1,2 @@
+export { expectToolCatalogMatchesServer, getToolCatalogDifferences, type ToolCatalogDifferences } from "./catalog.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,8BAA8B,EAAE,yBAAyB,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC"}

package/dist/testing/index.js

@@ -0,0 +1,3 @@
+// `@softure-ai/mcp-access/testing`: checks for an app's own tests.
+export { expectToolCatalogMatchesServer, getToolCatalogDifferences } from "./catalog.js";
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EAAE,8BAA8B,EAAE,yBAAyB,EAA+B,MAAM,cAAc,CAAC"}

package/module.json

@@ -1,6 +1,6 @@
 {
   "id": "mcp-access",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "dependsOn": { "security": "^0.1.0", "auth": "^0.1.0" },
   "dbSchema": "mcp",
   "tables": ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants"],

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@softure-ai/mcp-access",
-  "version": "0.1.11",
-  "description": "SOFTURE AI MCP access module: hashed, scoped, expiring access tokens, a rate-limited Bearer endpoint around the app's MCP server factory, and a token page with client setup instructions for Next.js.",
+  "version": "0.1.13",
+  "description": "SOFTURE AI MCP access module: hashed, scoped, expiring access tokens, a rate-limited Bearer endpoint around the app's MCP server factory, and a token page with client setup instructions for Next.js; tool result helpers with a safe error boundary, a stdio entry, a catalog parity check and the softure-mcp prune command.",
   "license": "MIT",
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/stdio/register.js",
+    "./src/stdio/register.ts"
+  ],
   "engines": {
     "node": ">=22"
   },
@@ -27,6 +30,9 @@
     "access": "public",
     "provenance": true
   },
+  "bin": {
+    "softure-mcp": "./dist/cli/bin.js"
+  },
   "exports": {
     ".": {
       "@softure-ai/source": "./src/index.ts",
@@ -47,6 +53,26 @@
       "@softure-ai/source": "./src/ui/index.ts",
       "types": "./dist/ui/index.d.ts",
       "default": "./dist/ui/index.js"
+    },
+    "./stdio": {
+      "@softure-ai/source": "./src/stdio/index.ts",
+      "types": "./dist/stdio/index.d.ts",
+      "default": "./dist/stdio/index.js"
+    },
+    "./stdio/register": {
+      "@softure-ai/source": "./src/stdio/register.ts",
+      "types": "./dist/stdio/register.d.ts",
+      "default": "./dist/stdio/register.js"
+    },
+    "./testing": {
+      "@softure-ai/source": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./cli": {
+      "@softure-ai/source": "./src/cli/index.ts",
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
     }
   },
   "scripts": {
@@ -54,9 +80,9 @@
   },
   "dependencies": {
     "@softure-ai/auth": "^0.1.0",
-    "@softure-ai/core": "^0.1.7",
+    "@softure-ai/core": "^0.1.9",
     "@softure-ai/db": "^0.1.0",
-    "@softure-ai/security": "^0.1.0",
+    "@softure-ai/security": "^0.1.8",
     "zod": "^4.6.5"
   },
   "peerDependencies": {

package/src/cli/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `softure-mcp` executable. All logic lives in command.ts and run.ts, which the tests call directly.
+import { runMcpAccessCommand } from "./command.js";
+
+process.exitCode = await runMcpAccessCommand({ argv: process.argv.slice(2), cwd: process.cwd() });

package/src/cli/command.ts

@@ -0,0 +1,38 @@
+// The `softure-mcp` bin. It loads the app's config through `@softure-ai/core/cli`, like `softure-mail`
+// (@softure-ai/mailing): the file must be loadable by Node itself (`.js`/`.mjs`, or `.ts` where Node
+// strips types). Anything else uses an app script with `runMcpAccessCli` instead (see run.ts).
+import { loadAppConfig, takeConfigOption } from "@softure-ai/core/cli";
+import { EXIT_FAILED, EXIT_USAGE, MCP_ACCESS_USAGE, runMcpAccessCli, type CliOutput } from "./run.js";
+
+export interface RunMcpAccessCommandOptions {
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly output?: CliOutput;
+}
+
+const APP_SCRIPT = { runner: "runMcpAccessCli", packageName: "@softure-ai/mcp-access" };
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+/** Loads the config (unless only help is asked for) and runs `runMcpAccessCli`. */
+export async function runMcpAccessCommand(options: RunMcpAccessCommandOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const taken = takeConfigOption(options.argv);
+  if (!taken.ok) {
+    output.error(`softure-mcp: ${taken.problem}`);
+    output.error(MCP_ACCESS_USAGE);
+    return EXIT_USAGE;
+  }
+  const { configPath, argv } = taken;
+  if (argv[0] !== "prune") return runMcpAccessCli({ argv, output });
+
+  const loaded = await loadAppConfig({ cwd: options.cwd, configPath, appScript: APP_SCRIPT });
+  if (!loaded.ok) {
+    output.error(`softure-mcp: ${loaded.problem}`);
+    return EXIT_FAILED;
+  }
+  return runMcpAccessCli({ config: loaded.config, argv, output });
+}

package/src/cli/index.ts

@@ -0,0 +1,3 @@
+// `@softure-ai/mcp-access/cli`: the `softure-mcp` command for app scripts and container bundles.
+export { runMcpAccessCommand, type RunMcpAccessCommandOptions } from "./command.js";
+export { EXIT_FAILED, EXIT_OK, EXIT_USAGE, MCP_ACCESS_USAGE, runMcpAccessCli, type CliOutput, type RunMcpAccessCliOptions } from "./run.js";

package/src/cli/run.ts

@@ -0,0 +1,79 @@
+// `softure-mcp`: the module's maintenance command. `prune` deletes expired access tokens and dead OAuth
+// records (`pruneMcpAccess`), for a daily job such as a deploy `maintain` hook. The app passes its
+// validated config, so the same function serves the bin and an app script a bundler packs:
+//
+//   // scripts/mcp.ts
+//   import { runMcpAccessCli } from "@softure-ai/mcp-access/cli";
+//   import config from "../softure.config";
+//   process.exitCode = await runMcpAccessCli({ config, argv: process.argv.slice(2) });
+import { errorLogLabel, systemClock, type Clock, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
+import { openCommandDatabase, type CommandDatabase } from "@softure-ai/db";
+import { pruneMcpAccess } from "../server/prune.js";
+
+export interface CliOutput {
+  readonly log: (line: string) => void;
+  readonly error: (line: string) => void;
+}
+
+export interface RunMcpAccessCliOptions {
+  /** The app's config; only help needs none. */
+  readonly config?: SoftureConfig;
+  /** The arguments after the executable, e.g. `["prune"]`. */
+  readonly argv: readonly string[];
+  readonly output?: CliOutput;
+  /** Default: the wall clock. */
+  readonly clock?: Clock;
+  /** Default: the config's `database.handle`, else a connection on `database.url`. */
+  readonly openDatabase?: (database: SoftureDatabaseConfig) => Promise<CommandDatabase>;
+}
+
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+
+export const MCP_ACCESS_USAGE = `Usage:
+  softure-mcp prune    deletes expired access tokens, authorization codes, grants and abandoned clients`;
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+/** Runs one command and answers its exit code. */
+export async function runMcpAccessCli(options: RunMcpAccessCliOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const [command, ...rest] = options.argv;
+  if (command === undefined || command === "--help" || command === "help") {
+    output.log(MCP_ACCESS_USAGE);
+    return EXIT_OK;
+  }
+  if (command !== "prune" || rest.length > 0) {
+    output.error(command === "prune" ? `softure-mcp prune: unexpected argument "${rest[0] ?? ""}"` : `softure-mcp: unknown command "${command}"`);
+    output.error(MCP_ACCESS_USAGE);
+    return EXIT_USAGE;
+  }
+  return prune(options, output);
+}
+
+async function prune(options: RunMcpAccessCliOptions, output: CliOutput): Promise<number> {
+  const database = options.config?.database ?? null;
+  if (options.config === undefined || database === null) {
+    output.error("softure-mcp prune: the config has no database; set database.url in softure.config");
+    return EXIT_FAILED;
+  }
+  let opened: CommandDatabase | undefined;
+  try {
+    opened = await (options.openDatabase ?? ((settings) => openCommandDatabase(settings, { max: 1 })))(database);
+    const removed = await pruneMcpAccess({ db: opened.handle.db, clock: options.clock ?? systemClock, config: options.config });
+    output.log(
+      `softure-mcp prune: removed ${String(removed.accessTokens)} access tokens, ${String(removed.codes)} authorization codes, ${String(removed.grants)} grants, ${String(removed.clients)} clients`,
+    );
+    return EXIT_OK;
+  } catch (error) {
+    // The kind only: a driver message can carry the database address or credentials.
+    output.error(`softure-mcp prune: failed: ${errorLogLabel(error)}`);
+    return EXIT_FAILED;
+  } finally {
+    await opened?.close();
+  }
+}

package/src/contract.ts

@@ -9,8 +9,11 @@ export type McpAccessErrorCode =
   | "mcp-access.token_not_found"
   | "mcp-access.grant_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 an app's `beforeIssue` gate may answer instead of letting a token be issued. */
+export type McpIssueRefusalCode = "mcp-access.issue_refused" | "mcp-access.write_refused";
+
+/** Every code the token page can show: its own, a gate's refusal, a missing session and the generic ones. */
+export type TokenFormErrorCode = McpAccessErrorCode | McpIssueRefusalCode | "auth.unauthenticated" | CoreErrorCode;
 
 /** What the app's MCP server factory receives for one request. */
 export interface McpServerIdentity {

package/src/index.ts

@@ -3,8 +3,10 @@
 // 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 type { RateLimitBucketInput } from "@softure-ai/security";
 import { mcpAccessMessages } from "./messages/index.js";
 import { mcpAccessOptionsSchema } from "./options.js";
+import { DEFAULT_MCP_ACCESS_ROUTES } from "./routes.js";
 import { checkAccessTokensTable } from "./server/health.js";
 import { mcpAccessPrivacyContributor } from "./server/privacy.js";
 
@@ -16,14 +18,14 @@ export const MODULE_ID = "mcp-access";
  * the traffic behind one address (several assistants share it), not for one token.
  */
 export const MCP_RATE_LIMIT_BUCKETS = {
-  mcp: { limit: 200, windowMinutes: 15 },
+  mcp: { limit: 200, windowMinutes: 15, key: "ip" },
   /**
    * OAuth registration (per address) and token requests (per address and client id), when
    * `oauth.enabled`. Enough for an assistant platform refreshing many users' tokens per client,
    * too little for a script filling the clients table.
    */
-  "mcp-oauth": { limit: 60, windowMinutes: 15 },
-} as const;
+  "mcp-oauth": { limit: 60, windowMinutes: 15, key: "ip" },
+} as const satisfies Readonly<Record<string, RateLimitBucketInput>>;
 
 /**
  * Enables MCP access in `softure.config.ts` (after `security` and `auth`):
@@ -32,20 +34,13 @@ export const MCP_RATE_LIMIT_BUCKETS = {
 export const mcpAccess = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.11",
+    version: "0.1.13",
     dependsOn: { security: "^0.1.0", auth: "^0.1.0" },
     dbSchema: "mcp",
     tables: ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants"],
     env: [],
     switches: [],
-    routes: {
-      page: "/account/mcp",
-      endpoint: "/api/mcp",
-      oauthConsent: "/oauth/authorize",
-      oauthDecision: "/api/oauth/authorize",
-      oauthToken: "/api/oauth/token",
-      oauthRegister: "/api/oauth/register",
-    },
+    routes: { ...DEFAULT_MCP_ACCESS_ROUTES },
     mount: [
       { kind: "page", path: "app/account/mcp/page.tsx", export: "McpAccessPage" },
       { kind: "route-handler", path: "app/api/mcp/route.ts", export: "createMcpRoute" },
@@ -81,6 +76,7 @@ export type {
   IssuedToken,
   IssueTokenFormState,
   McpAccessErrorCode,
+  McpIssueRefusalCode,
   McpClientSetup,
   McpServerIdentity,
   OAuthGrantView,
@@ -105,6 +101,7 @@ export {
   type McpToolDefinition,
   type McpToolDefinitionInput,
 } from "./options.js";
+export { DEFAULT_MCP_ACCESS_ROUTES } from "./routes.js";
 export { readRequestOrigin, type McpOriginRequest, type McpOrigins } from "./origins.js";
 export { accessTokens, oauthAuthorizationCodes, oauthClients, oauthGrants, type OAuthClientRow, type OAuthTokenEndpointAuthMethod } from "./schema.js";
 export { getAccessTokenStatus, type AccessTokenStatusOptions } from "./token-status.js";

package/src/messages/en.ts

@@ -92,6 +92,8 @@ export const en = {
       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.",
       grant_not_found: "This app is no longer connected.",
+      issue_refused: "Your account cannot create tokens right now.",
+      write_refused: "Your account cannot create tokens with write access. Create a read-only token instead.",
     },
     auth: {
       unauthenticated: "Your session has ended. Log in again.",

package/src/messages/pl.ts

@@ -94,6 +94,8 @@ export const pl: typeof en = {
       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.",
       grant_not_found: "Ta aplikacja nie jest już połączona.",
+      issue_refused: "Twoje konto nie może teraz tworzyć tokenów.",
+      write_refused: "Twoje konto nie może tworzyć tokenów z prawem zapisu. Utwórz token tylko do odczytu.",
     },
     auth: {
       unauthenticated: "Twoja sesja wygasła. Zaloguj się ponownie.",

package/src/next/actions.ts

@@ -4,18 +4,17 @@
 // 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 { errorLogLabel, 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, RevokeGrantFormState, RevokeTokenFormState } from "../contract.js";
 import { MAX_TOKEN_NAME_LENGTH } from "../options.js";
-import { getMcpAccessMessages, getMcpAccessOptions, getMcpAccessRoutes, getMcpEndpointUrl } from "../server/options.js";
+import { getMcpAccessRoutes } from "../server/options.js";
 import { revokeOAuthGrant } from "../server/oauth.js";
-import { issueAccessToken, revokeAccessToken } from "../server/tokens.js";
-import { getMcpAccessContext, getRequestOrigins } from "./context.js";
-import { formatDate } from "./format.js";
+import { revokeAccessToken } from "../server/tokens.js";
+import { getMcpAccessContext } from "./context.js";
+import { issueToken } from "./issue-token.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;
@@ -24,11 +23,6 @@ const text = z
   .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) {
@@ -40,40 +34,9 @@ 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 {
-    // 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: 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,
-          token: issued.token,
-          promptTemplate: messages.setup.assistantPrompt,
-        }),
-      },
-    };
-  } catch (error) {
-    return { status: "error", error: reportFailure("issuing a token", error) };
-  }
+/** Issues a token for the signed-in user and returns its plaintext with the setup snippets, once. No gate: see `issueToken`. */
+export async function issueTokenAction(previous: IssueTokenFormState, formData: FormData): Promise<IssueTokenFormState> {
+  return issueToken(previous, formData);
 }
 
 /** Revokes one of the signed-in user's tokens; another account's id matches nothing. */

package/src/next/format.ts

@@ -1,8 +1,8 @@
 // Dates on the token page, in the app's locale and time zone.
-import type { SoftureConfig } from "@softure-ai/core";
+import { formatCalendarDay, toCalendarDay, 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);
+  return formatCalendarDay(toCalendarDay(date, config.timezone), config.locale, "long");
 }
 
 export function formatDateTime(config: SoftureConfig, date: Date): string {

package/src/next/index.ts

@@ -10,6 +10,7 @@ export {
   getProtectedResourceMetadataRoute,
   registerOAuthClientRoute,
 } from "./oauth-routes.js";
-export { getMcpAccessContext } from "./context.js";
-export { McpAccessPage } from "./pages.js";
+export { getMcpAccessContext, getRequestOrigins } from "./context.js";
+export { issueToken, type BeforeIssueGate, type IssueGateInput, type IssueTokenOptions } from "./issue-token.js";
+export { McpAccessPage, type McpAccessPageProps } from "./pages.js";
 export { createMcpRoute } from "./route.js";